Troubleshooting

Confirm you opened the expected Tallpine data home. All state defaults under ~/.tallpine; an TALLPINE_DATA_DIR or TALLPINE_RUN_FILE override can point a development launch at a different daemon instance.

Open the desktop app first. Product CLI commands are thin clients and need the app-owned daemon. A stale ~/.tallpine/running.json is not enough; Tallpine also verifies the recorded process.

The primary daemon uses loopback port 3101 by default and fails fast if it cannot bind. Stop the conflicting local process or use a deliberate development TALLPINE_PORT override. Never change the bind host to expose the daemon.

Leave the app open briefly so its SSE connection can reconnect and invalidate current queries. If it does not recover, restart the desktop app. The event stream supports replay, but a full app restart is the safest user-level recovery.

Install the harness, run it once to authenticate, and restart Tallpine. The desktop daemon inherits a login-shell environment and reuses each provider's installed binary and authentication.

Confirm the selected harness supports native Chat and its binary is authenticated. Chat support depends on the harness and installed version; see the agent capability catalog. Check Settings → Harness and provider version/permission requirements. Choose Terminal UI when the harness lacks Chat support or preflight cannot connect.

New macOS/Linux sessions use detached native PTY hosts. Packaged builds bundle tmux for old sessions/fallback; macOS still validates it. For source runs check configured/system tmux and the native-host launch error. Windows uses ConPTY. See Runtime.

Open the session and answer the pending approval or permission prompt. Tallpine deliberately does not inject lifecycle messages while a controller is blocked.

Status is derived from activity, termination, controller, and pull-request facts. A failed runtime probe is not treated as death. Reopen the session and inspect its Chat or terminal before killing it.

Use the desktop restore action or tallpine session restore <session-id>. Restore reuses the same session and worktree when the selected adapter supports recovery. Check that the harness remains installed and authenticated. For a stopped controller on a non-terminated session use tallpine session resume-agent <id> instead. A disabled interface switch can indicate unavailable native history, an unsupported direction, or pending recovery; inspect its reason before retrying.

Run gh auth status and confirm the active account can access the repository. GitHub authentication is lazy so an auth failure does not need to block unrelated local session work. For GitLab check token/glab authentication and self-managed-host configuration in SCM setup.

Claim it from the session UI or, inside the worker, run tallpine session claim-pr <pr-number-or-url>; Tallpine reads the worker from TALLPINE_SESSION_ID. From another shell, use tallpine session claim-pr <session-id> <pr-number-or-url>.

The SCM observer polls GitHub and respects rate limits and ETags. Check gh auth status, wait for another observation cycle, and open the pull request directly for full raw logs or comment bodies.

Open the review run and use its send action. Reviewer execution and delivery are separate operations so you can inspect findings before changing the worker conversation.

Select a target explicitly with tallpine preview <url>, or use tallpine preview start when the worktree contains a valid .ao/launch.json. Tallpine does not auto-discover a preview for every new worker.

Run tallpine preview start <configuration> and inspect the returned error. Verify the command and working directory in the session's .ao/launch.json, then run the same command in its worktree shell.

Select the correct session and browser tab. Commands are authorized for the selected session. Temporary profiles are isolated; named profiles deliberately reuse saved browser state. Check the selected profile, and refresh snapshots after navigation. Keep the panel visible for screenshots/human pointer actions. Profile imports have platform-dependent cookie support; a missing login may require signing in again.

Confirm Connect Mobile is enabled and the QR is ready, then use the latest offer/password. Direct LAN needs the same trusted network; remote access needs an advertised, ready secure endpoint. Inspect connector/Tailscale setup failures, and update both apps for identity/contract mismatches. Rotating the password invalidates old credentials.

The current QR carries the host identity, available endpoints, and connection password in a v2 pairing link. Treat it as a bearer credential: do not share the QR or screenshots of it. Rotate the connection password in desktop settings if it may have been exposed.

Do not use a plaintext LAN endpoint on an untrusted network. Use an available secure endpoint from Connect Mobile. Keep the primary daemon private. If mobile push is missing, check phone notification permission, that the phone is still listed under Connected devices, and daemon connectivity.