fix(agent-presence): keep remote, mobile and CLI views on host ownership (step 3/3)

[brennanb2025]

	Files	Added	Deleted	Net
Test	12	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1232	0	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1232
Prod	36	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​754	$\color{#cf222e}{\Huge{\mathbf{−}}}$​276	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​478

What this fixes

The phone app, a paired desktop/web client, and the command line (orca terminal show, worktree ps, orchestration dispatch) could each disagree with the computer that actually runs the agent. A running Claude disappeared from them when its terminal title looked like a plain shell (for example while Claude sat idle), and an agent that had provably exited kept its icon and its Chat button on the phone. After a reconnect to a remote host, a pane could keep showing the agent that ran before the disconnect instead of the one running now.

Who hits it: anyone watching or driving Claude from the phone, a paired client or the CLI, when Claude runs on macOS or Linux, either locally or on an SSH host. Those are the panes whose owner a hook already identifies by its process (steps 1 and 2).

What is NOT affected: hookless agents (aider, goose, crush and similar), agents whose hooks carry no process identity (Codex, Cursor and others), and everything on native Windows keep today's behaviour on every surface, including when one of them starts in a pane right after an identified Claude exited there. Capturing their process was part of an earlier draft of this PR and has moved to a separate follow-up, because it needs its own design (see Notes). The host desktop's own tab icon, sidebar and Chat already read this record since step 2 and are unchanged here.

ELI5

A terminal title is a label, not proof that an agent is there. The computer running the agent keeps one record per terminal pane of which agent process owns it and whether that process has exited. Until now only the desktop app on that computer read the record; the phone, paired clients and the command line still guessed from titles. After this PR they all read the same record, so they agree with each other.

What Changed

This PR is step 3 of 3, stacked on #24175 (brennanb2025/agent-presence-step2, step 2), which now targets main; step 1 (#23947) has already merged into main. The whole plan: (1) the execution host records which agent process owns each pane and checks that exact process; (2) the desktop's icons, Chat and sidebar read that record; (3) the phone, paired clients, the CLI and SSH reconnects read the same record, and mixed versions keep working. This PR is step 3 of 3.

Before, as the user sees it: on the phone and on a paired client, an idle Claude under a shell-looking title showed as a plain shell with no Chat; an exited Claude could keep its icon and Chat; after an SSH reconnect the pane could still show the old agent; if that agent was waiting for permission when you disconnected, then exited and a new Claude started, the pane kept showing the dead agent's permission prompt. orca terminal show and dispatch decided "is an agent running" from the title and the foreground process, so an idle Claude under a shell title could read as "no agent".

After: those surfaces show the owner the host recorded. A live identified owner counts as present under any title for display, while sends and dispatch only go to it when it is the program in front. Once it has provably exited, its own leftovers (its hook row, launch intent, title and process name) no longer bring it back, while any other agent started in that pane shows exactly as it does today. After a reconnect the pane shows the agent the remote host says is running now (see the SSH note below).

Mechanism, phone and paired clients: for clients that advertise the new agent-process-presence.v1 capability (negotiated per connection; the paired desktop, the browser web client and the phone advertise it, the CLI does not, and the desktop's own renderer keeps reading presence from its main process), the host adds its owner record to the status each terminal tab already publishes, so the tab keeps its activity history, unread count, prompt search, orchestration labels and title corrections. Only when a pane published no status at all (Claude idle under a shell title) does the host's own row stand in, and for an exited owner that row carries identity only, never the exited agent's session, model or type. Older clients receive exactly the previous row, and advertising the capability alone never marks a row as identified. The paired client takes the record from each host snapshot as published, in snapshot order (never by the status clock, which the host does not keep monotonic): a row without a process identity, or the pane published without status, drops the record instead of hiding the next agent; an older snapshot is never applied, so it cannot bring an exited owner back; closing the tab on the host clears it; routine status pings do not rewrite it or re-sort the sidebar. After an owner exits, the paired client sets aside only statuses that name that agent, so a later agent's status in the pane still shows, the same rule as the phone and the host desktop. Host-local rows keep their local attribution, as today.

Mechanism, command line: presence proves the agent exists; the owner answers for the keyboard only when the program in front is that agent. terminal show, the send guard and dispatch's "is an agent running" check therefore keep main's foreground rules: a shell, any other program (for example ssh, vim or less after Ctrl-Z suspends Claude), or a foreground read that fails all answer exactly as on main, so nothing is typed into that program. The one change is that a fresh hook status is no longer hidden by a shell-like title when the process in front is recognised as the owner's own agent. An owner recorded on another host (a WSL guest or an SSH relay) cannot be checked here, so those panes keep main's rules entirely. The permission checks (a live permission title, an approval menu on screen) and the claude agents management screen stay ahead of it in their previous order, so a Cursor-style approval menu still reads as "waiting for permission" and the management screen never reads as a task agent. Once the owner has exited, these checks fall back to today's title and foreground rules with only the evidence naming that exited agent set aside; this is the same rule step 2 applies on the desktop, now moved to shared code so the desktop, phone and CLI use one implementation. worktree ps and terminal summaries take the agent type from the identified owner.

Mechanism, remote hosts: the relay on the execution host stamps every owner it publishes with an ordering marker (a random id per relay process plus an increasing number). The desktop accepts that stamp only on its authenticated remote channel, so local hooks, client publications and terminal output cannot claim it, and it rejects older deliveries. The provenance this earns ("the execution host decided this owner") is used only for that admission and is never stored on the row; the marker itself is stored with the owner record (see Known weaknesses). When a stamped frame names an owner process different from the one the desktop remembered, it replaces that stale row outright: the new agent's state is not held by the old agent's permission prompt, and an agent that started and exited while you were disconnected replaces the old one. Deciding that "the relay chose the owner" now happens in one place on the desktop. Relays from older builds send no marker and keep the previous behaviour. This PR also makes the SSH session forward the relay's whole hook envelope to the desktop, the way the WSL link already does (the desktop re-validates every field). Before, the SSH path copied a fixed field list that left out the owner record, so this turns the step 1/2 owner paths on for SSH for the first time.

Why

The bug is several readers guessing presence from different signals (titles, launch intent, the foreground process) and disagreeing. The fix gives every reader the one record the execution host already keeps, reusing its storage, cleanup and publication rather than adding a second store. That removes the class of "surfaces disagree about whether an agent is there" for identified owners, instead of patching each title rule.

Alternatives rejected: sending the whole host store to clients (larger wire change, and older clients would need a second path anyway); letting each client recompute ownership from its own evidence (that is the bug); and capturing every agent's process in this PR. The last one was built and reviewed, and it made things worse than today in three ways: a working hookless agent showed as Done, every command in a plain shell pane started a machine-wide process scan, and on native Windows an exited agent never left the tab because Windows cannot yet prove a process has gone. So it moved to a follow-up with a design that avoids all three.

The paired-client fix removes a latch rather than adding a guard: presence is re-derived from each host snapshot, so no stale record can outlive what the host says. The reconnect fix makes the remote host's word final for its own panes instead of having the desktop re-decide it from a copy that belonged to a dead process.

How this differs from the reference designs we compared against:

• Intended: readers on the phone and the CLI project the host's record only for identified rows; unidentified rows keep today's title and launch-hint rules. Safe because a row is identified only by a process the host captured, and the approved compatibility rule is that unidentified rows keep existing behaviour.
• Temporary: hookless agents, agents without process capture and native Windows are not identified yet. Follow-up: the planned hookless/Windows capture PR (not yet opened), which records identity without inventing a turn state, runs only on agent evidence, and leaves Windows uncovered until an exit can be proven on a real Windows machine.
• Temporary: the relay's ordering marker is a stale-delivery fence on its per-pane replay, not a resume cursor with a full snapshot and removals, and in practice nothing reorders these frames, so its real job is marking a new relay. It costs a field persisted with the owner record and published to every client. Follow-up: replace it with a relay capability marker and drop the stored field (not yet opened).
• Intended: for a live (not replayed) exit, the desktop still checks the exit comes from the owner process it holds, instead of adopting the host's exit outright. Safe because the relay forwards in order, so a connected exit always names the owner the desktop holds; live owners, replayed exits and owner replacements are adopted from the host.
• Intended: the host carries its record to the per-client projection on a private field that JSON cannot carry, instead of passing capabilities into the projection. Safe because no client publication can supply it; it is an extra moving part, not a behaviour difference.
• Intended: the paired client and the phone both take each host snapshot's owner as published, in snapshot order; neither re-orders owners by a clock.

Linked Issue

Partly addresses the inconsistent icon/Chat presence reported in #23638 (STA-8819); the reported freeze was not reproduced and this PR does not claim to close it. STA-8862/#23753 restart rebinding and STA-7949/#22727 turn cancellation remain separate. No Linear ticket is claimed closed.

Visual Proof

Live QA ran on remote machines from dev builds of this branch (M4Air macOS: desktop, CLI, phone and a real SSH host; Windows high-spec: native Windows), with isolated homes and an unauthenticated Claude so only its hooks and process mattered.

Phone (round 1, head 20c3343): Claude idle under a zsh title keeps its icon and the "Switch to chat view" entry; after /exit both clear within 5 s. The final-head phone run was blocked because another session held the shared Android emulator for the whole window; the phone-facing code changed after round 1 (published status kept, presence added), and that path is covered by the unit tests listed below.

SSH (final head): the desktop now receives the remote Claude's process identity. Claude replaced on the remote while the client was disconnected: after reconnect the pane shows the new Claude live and a terminal send lands in its input. Claude killed while disconnected: after reconnect worktree ps, the CLI and the sidebar clear.

CLI (final head): worktree ps and terminal show/list show Claude while it idles under a zsh title and are empty within 3 s of /exit.

Native Windows (final head): unchanged from main, as intended: the sidebar row and worktree ps clear within about a second of Claude exiting (3/3), and a plain PowerShell pane shows no agent.

Not this PR's (reproduced identically on step 2 and on main): after /exit the host desktop's tab icon can stay on Claude and the macOS sidebar can keep a "shell - Claude" row, because the desktop's sleeping-session and retained-row records survive the exit; on the final head the macOS tab sparkle clears but the sidebar row stays. These are desktop readers outside this PR's diff.

Testing

• Manually tested on remote QA machines (M4Air macOS + SSH, Windows high-spec)
• Automated tests added/updated

On macOS, at the merged head: 63 named root Vitest files (this PR's own plus neighbours that import changed modules, including orca-runtime.test.ts, step 2's desktop presence and relay handover tests, the send and dispatch tests, the capability-list tests and the mobile publication-cost test) passed, 2206 tests; the SSH and remote-ingress set (every ssh-relay-session* test including the integration file run by name, remote replay, relay handover, remote ingest and the WSL relay tests) passed 23 files, 237 tests; mobile's own Vitest passed 4 files, 36 tests; the 12 cross-version wire fixtures passed 78 tests. New cases cover: an idle owner under a shell title, a proven exit on the phone, per-connection capability negotiation, client-published presence rejected as host evidence, the Cursor approval menu and the claude agents screen with an identified owner, a hookless agent started after the owner exited (phone and CLI) next to the exited Claude's own title, process and launch hint staying hidden, a suspended (Ctrl-Z) owner with a shell, ssh, vim, python3, less or tmux in front, or a failed foreground read, answering exactly as main (the send guard refuses), the owner itself in front under a shell title still reading as running, a WSL-style owner behind wsl.exe reading exactly as main, a replayed old exit leaving a later unidentified row alone, a newer snapshot's owner winning over an older status clock (exit and relaunch), a later agent's status kept after the owner exited on a paired client, the SSH session forwarding the relay's owner record (agent, process and ordering) to the desktop row while keeping the host-set run capability, a later unidentified agent after an exit on a paired client, the host retracting a tab, the published status keeping its history and labels for capable clients, an exited owner projected as identity only, host-local rows keeping their local attribution, a pane published without status, a status ping that must not republish presence, host provenance kept off stored rows, offline exit plus replacement plus replay, and a dead owner's permission prompt after reconnect.

Red proof: with each of the eleven main review fixes temporarily undone, its new tests fail on assertions (approval menu read as working and management screen read as an agent; the exited record kept and leaked on the paired client; the dead Claude shown waiting on permission after reconnect; a hookless successor hidden on the phone and read as not running by the CLI; a suspended owner read as running with a shell in front, in both the running check and the status query; the published status replaced and its history lost; a host-local row rewritten to the paired environment; a WSL owner read as running behind wsl.exe; a live owner answering for a program that is not the agent; a relaunch or exit ignored on an older status clock and a later agent's status dropped on the paired client; the SSH owner record dropped by the old field-by-field copy), and pass again once restored. The changed-code-quality gate against step 2 reports no new findings and oxlint is clean on every changed file. The node, web and CLI typechecks and the mobile test-typecheck ratchet passed on the merged head (run through the gated tsc); an app build is left to CI.

Review

The only protected hook-server file edited is server-status-update.ts: a host-stamped frame for a different owner process replaces the stored row, a host-stamped replay of the relay's own exit is accepted next to step 2's relay-owner adoption (so the shared transition is back to step 2's version), and the host-provenance tag is removed before the row is written. Remote ingress, the internal host-provenance tag, the relay projection and the SSH session's hook forwarding (ssh-relay-session.ts, now forwarding the envelope like the WSL link) are the other approved edits. One separate refactor commit moves three browser capability constants out of protocol-version.ts into their own module, with the same values, only to keep that file within its line limit after merging step 2. No changes to #22727's branch or to turn-state semantics. Step 2 is merged in at its latest head, including main with step 1 (per-pane presence resolution, no polling of identified owners, owner release on terminal teardown, the answered-shell exit confirmation, and one owner-handover rule for every host).

Agent skill upstream boundary

• Not applicable; no upstream skill content copied or translated.

Notes

Known weaknesses

• Right after Claude exits, relaunching Claude in the same pane reads as "no agent" on the phone and in the CLI until the new Claude's first hook arrives (usually at startup), because its title and process name name the exited owner. The desktop behaves the same since step 2. It fails closed: nothing is typed into a shell.
• A live owner is trusted until an event proves otherwise; there are no sweeps. A silent kill with no later title change, command end or hook stays "present" until the next such event.
• Temporary: the relay's ordering marker (a relay id plus a counter) is stored with the owner record in the last-status file and published to every client. It is optional and dies with the row, but it is delivery metadata, not state, and does not fence across relay restarts. Follow-up: a relay capability marker instead (not yet opened).
• Not exercised live: a paired web client, mixed-version apps across a real connection (covered by unit tests and the cross-version wire fixtures), Codex rows on Windows (real Codex is not allowed in a QA rig pane), and the phone on the final head (emulator held by another session; it passed on an earlier head).
• Windows, WSL, hookless agents and agents without process capture keep today's behaviour and today's limitations, including known false exits from title changes.

Author: @BrennanKB5.

Checklist

• This PR is small and focused (cross-surface step 3; 46 files)
• I explained what changed and why
• Before/after screenshots attached (remote QA)
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered
• Full lint/typecheck/test/build pass (CI green on e6353da: all unit shards, typecheck, package mac + Windows, cross-version wire, Mobile Checks)

[brennanb2025]

Review status — PR #24184 (step 3 of 3), head 351af5a

The problem: the phone app, a paired desktop/web client and the CLI each guessed whether an agent was in a terminal from its title. A running Claude idling under a shell-like title disappeared from them; an exited Claude could keep its icon and Chat on the phone; and after an SSH reconnect a pane could keep showing the agent that ran before the disconnect.

What changes for users: for Claude on macOS/Linux (local or SSH), the phone, paired clients, orca worktree ps / terminal show and SSH reconnects now show the agent the execution host recorded: an idle Claude stays shown under any title, an exited one clears, and an agent replaced while you were disconnected shows correctly after reconnect. Sends and dispatch still only go to an agent that is actually in front. Hookless agents, Codex/Cursor and native Windows keep today's behaviour on every surface.

Scope change during review: the first draft also captured process identity for hookless agents and on native Windows. Review proved that made things worse than main (a working hookless agent showed Done; every shell command started a machine-wide process scan; on Windows an exited agent never left the tab), so that part was removed and redesigned as a separate follow-up.

Fixed in review (each with a test that fails without the fix):

• Sends to an identified agent skipped the permission and claude agents checks, so a note could be typed into Cursor's "Run this command?" menu; those checks run first again.
• A Ctrl-Z-suspended Claude counted as ready, so sends could be typed into bash, ssh, vim or python3; the agent now answers for the keyboard only when it is the program in front, otherwise main's rules apply.
• WSL/SSH-recorded agents can't be checked locally, so those panes keep main's send rules.
• After an agent exited, a different agent started in the same pane was hidden on the phone, the CLI and paired clients; only the exited agent's own leftovers are set aside now.
• Paired clients lost Activity history, unread counts, prompt search and orchestration labels because the host's status was replaced instead of extended; host presence is now added to the published status.
• Paired clients dropped host-local rows from the palette, could keep a stale exited record, ignored a relaunch with an older clock, and re-sorted the sidebar on every status ping.
• SSH reconnect: an agent replaced while disconnected kept the old agent shown; a replayed old exit could delete a later agent's row.
• SSH never forwarded the agent's process record to the desktop (a field omission present since step 1); the SSH link now forwards the relay's message like WSL, which turns the step 1/2 owner handling on for SSH for the first time.
• CI: two capability-list tests, the browser web client not advertising the capability, and a publication-cost regression that rebuilt every worktree on each republish.

Deferred (P3, no user-visible harm proven):

• The relay's ordering marker is stored and published though only its "new relay" meaning is needed; follow-up: a relay capability marker.
• "Owner is in front" is decided by process name, not pid (a different claude process in front of a suspended one counts); same looseness main already has without a fresh hook status.
• One extra foreground read on explicit status requests for a live local owner.
• A hostile relay sending a non-string version makes that frame throw and be dropped (WSL already behaves so).
• worktree ps reports the owner's agent type in a pane with a nested agent.

Verified:

• Node, web and CLI typechecks and the mobile test-typecheck ratchet pass on the merged head; CI is green on 351af5a (all unit shards, typecheck, mac + Windows packages, cross-version wire, Mobile Checks ran and passed).
• 63 root test files (2206 tests), the SSH/remote set (23 files, 237 tests), mobile (36 tests) and 12 cross-version wire fixtures pass; old phone + new host gets byte-identical rows, new phone + old host keeps today's behaviour.
• Live on the M4Air: CLI shows idle Claude under a zsh title and clears within 3 s of /exit; over a real SSH host the desktop receives the remote Claude's process, a replaced agent shows live after reconnect and a send lands in it, and a killed agent clears from worktree ps, CLI and sidebar.
• Live phone (earlier head 20c3343): Claude icon and "Switch to chat view" while idle under a shell title, both cleared within 5 s of /exit.
• Live native Windows: unchanged from main (sidebar and worktree ps clear within about a second, plain PowerShell pane shows no agent).

Not verified:

• The phone on the final head (the shared emulator was held by another session for the whole window).
• A live paired web client and mixed-version apps over a real connection (unit tests and wire fixtures only).
• Codex rows on Windows (real Codex is not allowed in a QA rig).

Seen in QA but not caused by this PR: after /exit, the native-Windows tab icon can stay on Claude and the macOS sidebar keeps a "shell - Claude" row; both reproduce identically on step 2 and on main, because the desktop's sleeping-session and retained-row records survive the exit (on this PR's final head the macOS tab sparkle clears; the sidebar row remains). The same sleeping-session record also kept the tab icon on an SSH pane after a disconnected kill; that case was not re-run on main.

Base update: step 2's sleep/teardown fixes and its merge of current main (step 2 @85f4d2c52e6) are merged in as 351af5a; neither touches this PR's code. Node and web typechecks and all named suites pass, and CI on 351af5a is fully green (unit shards, typecheck, static analysis, packages, cross-version wire, Mobile Checks, computer-use smoke on mac/Ubuntu/Windows). Live QA ran on e6353da, before those merges. The PR stays a draft.

[greptile-apps]

Confidence Score: 3/5

[High risk] Adds agent process presence tracking across remote, mobile, and CLI views.

The PR should not merge until terminal status stops reporting an exited owner from its stale permission title and mobile Chat keeps provider sessions aligned with the host owner.

Findings

1.  New owner inherits old conversation ▶

Summary

The PR carries execution-host agent ownership to mobile and paired-client tab snapshots, uses it in terminal and CLI readers, and forwards SSH relay presence through remote ingress.

• Capability-gated projections preserve the legacy view for clients that do not opt in.
• Two reader paths still need attention: an exited owner's permission title can remain authoritative in the CLI, and a new owner's mobile Chat identity can be paired with an old provider session.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  H[Execution-host hook owner] --> R[Host status row]
  R --> P[Capability-gated tab projection]
  P --> M[Mobile icon and Chat]
  P --> W[Paired-client mirror]
  R --> C[CLI terminal status]
  S[SSH relay] --> R

Loading

_{Reviews (1) · Last reviewed commit: "Merge remote-tracking branch 'origin/bre..."}

[greptile-apps]

New owner inherits old conversation When the host records a new live agent before the renderer replaces the previous agent's published status, this merge puts the new owner's presence on a status that can still contain the old agent's session ID and transcript path. Mobile Chat selects the new agent but uses that old conversation identity, so it can open or attempt to open the wrong conversation. Keep the published session only when it belongs to the recorded owner.

Knowledge Base Used: Agent integrations and hooks

[greptile-apps]

Comments Outside Diff

These findings could not be posted inline.

•  Exited agent still appears waiting src/main/runtime/runtime-terminal-agent-status-query.ts:93 ▶

  When the host has proved an agent exited but its last terminal title still says it is waiting for permission, this return reports it as running before checking the exit record. terminal show can therefore keep showing the dead agent as waiting. Filter the exited owner's title before accepting it as permission evidence.

[pullfrog]

✅ No new issues found.

Reviewed changes — read the complete diff against brennanb2025/agent-presence-step2, traced the owner-record flow end to end, and ran the new/changed tests for the presence, projection, remote-replay, and paired-client paths (all pass).

• One shared owner/evidence rule — new src/shared/ended-agent-owner-evidence.ts extracts the ended-owner helpers out of renderer/.../agent-presence-selectors.ts (which now re-exports them); mobile, the CLI status query, and the desktop dispatch/terminal paths all call the shared functions so a live identified owner wins, an exited owner's own title/launch/process evidence is history, and other agents still show.
• Keyboard routing separated from presence — runtime-terminal-agent-status-query.ts and runtime-terminal-agent-presence.ts only let the owner answer for keyboard input when it is the program in front, keep permission/management checks ahead, and leave main's rules untouched for owners recorded on another host (selectKeyboardAgentPresence downsamples a remote live owner to {agent}).
• Relay ordering + admission — new relay-agent-presence-observation.ts stamps each forwarded owner with an epoch/sequence; new server-remote-agent-presence.ts fences stale deliveries and sets the internal agentPresenceFromExecutionHost flag, which server-status-update.ts uses to adopt host-stamped owner replacements/replayed exits and then strips before storing. ssh-relay-session.ts now forwards the whole envelope (WSL-style) so presence reaches main, with host-set capabilities applied last.
• Capability-gated client projection — session-tab-presence-projection.ts attaches the owner record to the published tab only for agent-process-presence.v1 clients, via a module-private Symbol so it cannot arrive over JSON; web-session-tabs-sync re-derives the paired-client mirror per snapshot, keeps a later agent's status after an exit, releases on retraction, and does not republish presence for a same-owner ping.

No inline comments. The base is the stacked agent-presence-step2 branch rather than main (the author documents the 3-step plan), so merge ordering is a reviewer/process decision, not a code concern here.

Default format / metadata

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[brennanb2025]

Close this older stacked implementation while preserving the work to make phone, desktop and command-line agent identity agree. Build it around the computer that now owns each terminal.