From 9dc54a59ebd1a2454c62bf9a4ef6bc8947bb68c3 Mon Sep 17 00:00:00 2001 From: Merge Sim Date: Tue, 8 Sep 2026 22:39:16 -0700 Subject: [PATCH 1/9] refactor(agent-status): publish structured sessions into the hook server store Structured (native chat) sessions have no PTY and no hook script, so their status never reached the hook server's store; #19217 gave `worktree ps` its own adapter over the structured feed instead. The feed now writes every projection into that store through a status sink the runtime wires, drops the row when the host closes the session, and `worktree ps` reads the one snapshot like every other agent. Rows carry a `structuredHost` marker and the journal clock; they are never persisted to last-status.json, and the main process does not forward them to the renderer yet, whose feed bridge still owns them until it is retired. Design and the two follow-ups: docs/reference/agent-status-store.md. --- .gitignore | 1 + AGENTS.md | 4 + docs/reference/agent-status-store.md | 216 +++++++++++++++++ pnpm-lock.yaml | 19 ++ .../server-ingest-structured-status.test.ts | 219 ++++++++++++++++++ .../server/server-ingest-remote.ts | 4 +- .../server/server-ingest-structured.ts | 62 +++++ .../server/server-persistence-validation.ts | 4 + .../agent-hooks/server/server-persistence.ts | 5 + src/main/agent-hooks/server/server-state.ts | 6 +- .../server/server-status-application.ts | 9 +- .../server/server-status-identity.ts | 1 + .../server/server-status-update.ts | 7 +- src/main/ipc/agent-hooks.ts | 10 +- .../structured-agent-session-host-types.ts | 4 + .../structured-agent-session-host.ts | 9 +- ...ructured-agent-session-status-feed.test.ts | 75 +++++- .../structured-agent-session-status-feed.ts | 53 +++-- .../runtime/orca-runtime-get-worktree-ps.ts | 7 +- .../orca-runtime-preserved-branch-cleanup.ts | 3 + src/main/runtime/orca-runtime-state-fields.ts | 5 + ...time-structured-status-sink-wiring.test.ts | 44 ++++ .../worktree-ps-structured-host.spec.ts | 171 ++++---------- ...ime-worktree-agent-rows-structured.test.ts | 53 +++-- .../runtime/runtime-worktree-agent-rows.ts | 9 +- .../runtime/runtime-worktree-agent-source.ts | 5 +- .../runtime/runtime-worktree-agent-sources.ts | 11 +- .../runtime-worktree-pty-agent-sources.ts | 9 +- ...ree-structured-agent-rows-liveness.test.ts | 97 +++++--- .../runtime-worktree-structured-agent-rows.ts | 48 ---- .../structured-agent-session-runtime.ts | 3 + .../startup/main-process-runtime-service.ts | 6 + src/main/startup/main-window-agent-status.ts | 8 +- .../agent-hook-listener/listener-event.ts | 5 + src/shared/agent-status-ipc-payload.ts | 4 + src/shared/agent-status-observation.ts | 4 +- src/shared/runtime-worktree-contracts.ts | 3 + 37 files changed, 909 insertions(+), 294 deletions(-) create mode 100644 docs/reference/agent-status-store.md create mode 100644 src/main/agent-hooks/server-ingest-structured-status.test.ts create mode 100644 src/main/agent-hooks/server/server-ingest-structured.ts create mode 100644 src/main/runtime/orca-runtime-structured-status-sink-wiring.test.ts delete mode 100644 src/main/runtime/runtime-worktree-structured-agent-rows.ts diff --git a/.gitignore b/.gitignore index 6722fc5ae54a..913dfc4a0459 100644 --- a/.gitignore +++ b/.gitignore @@ -103,6 +103,7 @@ docs/** !docs/agent-skill-sharing-implementation-checklist.md !docs/mobile-terminal-shortcut-bar.md !docs/reference/ +!docs/reference/agent-status-store.md !docs/reference/git-compatibility.md !docs/reference/headless-linux-server.md !docs/reference/ime-regression-checklist.md diff --git a/AGENTS.md b/AGENTS.md index b0947da0c2fe..5ff66b95b0f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,6 +68,10 @@ All changes must consider the SSH use case. Don't assume local-only execution. B All changes must consider folder workspaces as well as git worktrees. Don't assume every workspace is a git worktree. +## Agent Status + +The execution host owns agent status in one store, the hook server's, and every reader (sidebar, `worktree ps`, mobile, dashboard) subscribes to it. Before adding a producer, a cache, or a reader-side precedence rule, read [`docs/reference/agent-status-store.md`](./docs/reference/agent-status-store.md): new producers write into that store, and readers keep only presentation policy. + ## Remote Wire Compatibility Clients and remote Orca servers update independently, so mixed versions are the normal state. Before changing anything a paired client and host exchange — RPC params, stream frames, or the content either side publishes over them — follow [`docs/reference/remote-wire-compatibility.md`](./docs/reference/remote-wire-compatibility.md). A new optional field is safe; a new stream opcode must be capability-negotiated because decoders drop unknown opcodes silently; and changing what the host publishes reaches old clients even with no wire change. diff --git a/docs/reference/agent-status-store.md b/docs/reference/agent-status-store.md new file mode 100644 index 000000000000..f202b4fe3335 --- /dev/null +++ b/docs/reference/agent-status-store.md @@ -0,0 +1,216 @@ +# Agent status store + +## Status + +Proposed on 2026-09-09 as the follow-up to #19217. It lands in three PRs, in +this order, each independently shippable: + +1. main-only: every producer writes into one store and `worktree ps` reads it; +2. renderer: the sidebar becomes a subscriber and stops re-deriving rows; +3. shared: one worktree-status rollup and one freshness rule for every reader. + +The PR that carries this document is PR 1. + +## The problem this solves + +Orca shows "what is this agent doing" in four places: the desktop sidebar, the +`orca worktree ps` command, the mobile app, and the agent dashboard. Before +#19217 those readers did not even share their inputs. After #19217 they share +the structured-session mapping and nothing else. + +An audit on 2026-09-09 found six producers and three consumers, and three +separate copies of the same row inside the main process alone: + +| Main-process copy | Keyed by | Owned by | Persisted | Evicted | +| -------------------------------------- | --------- | ---------------------------------------------------------- | ------------------- | ----------------------------- | +| hook server `lastStatusByPaneKey` | paneKey | `src/main/agent-hooks/server.ts` | `last-status.json` | tab close, pty exit, hydrate | +| runtime `RuntimeAgentRowStore` | paneKey | `src/main/runtime/runtime-agent-row-store.ts` | no | pty exit only | +| structured feed `published` | sessionId | `src/main/native-chat/agent-session-wire/structured-agent-session-status-feed.ts` | no | never (a broadcast cache) | + +The second copy is a duplicate write: the OSC status parsed in main is +forwarded to the hook server _and_ retained in the runtime store from the same +call (`orca-runtime-create-terminal-side-effect-command-code-detector.ts`). +The third copy is keyed differently and never reaches the hook server at all, +which is why `worktree ps` grew its own adapter for it in #19217. + +Each reader then applies its own precedence and freshness rules, so the same +pane can legitimately read differently on the desktop, on the phone, and in +the CLI. + +## The rule + +**The execution host owns agent status, in one store, and every reader +subscribes to it.** This follows the boundary in +[`ssh-execution-boundary.md`](./ssh-execution-boundary.md): the host that runs +the process is the only party that can observe it, and the client is never +authoritative for execution state. + +Three consequences: + +- One store per execution host. A remote host keeps its own store and the + client mirrors it down, as the web-session mirror already does. Mirroring is + not merging: a client never writes its observations back to a host. +- Precedence is decided once, at write time, with provenance recorded on the + row. Readers never re-adjudicate hook versus terminal versus structured. +- Readers keep only presentation policy and user facts: the 30-minute display + decay, acknowledgements, dismissals, unread. Those stay reader-side but + become one shared implementation (PR 3). + +## The store already exists + +The hook server's state is that store today for every PTY-based agent. The +audit established: + +- hook HTTP posts, the WSL and SSH relay receivers, and main's own OSC parse + all converge on the same `applyNormalizedStatus` path, stamped with the + authority id `main-agent-hooks`; +- it alone holds pane authority: launch tokens and their hashed commitments, + retired-pane fences, pane-key aliases, per-connection ordering watermarks, + and the evidence-age map that must outlive a transport clear; +- it alone persists, with a seven-day hydrate window and the + `restoredUnconfirmed` stamp that keeps a hydrated row from ever reading as + live truth; +- it already fans out to both renderer windows over `agentStatus:set` and + `agentStatus:clear`, and serves `agentStatus:getSnapshot`. + +Nothing else in main carries those guarantees, and building a second store +with them would be the wrong direction. So the design is not "add a store". It +is: **route the two producers that bypass the hook server through it, then +delete the copies.** + +## PR 1: main only + +No renderer behavior changes. The sidebar keeps receiving the same IPC events +it receives today, plus structured-session rows it currently derives itself. + +### Structured sessions publish into the hook server + +The structured feed keeps its job of projecting a session's journal into a +summary and streaming it to subscribers. On every publish it additionally +ingests the summary into the hook server as a status row: + +| Row field | From | +| ----------------- | ------------------------------------------------------------- | +| `paneKey` | `structuredAgentSessionPaneKey(tabId, sessionId)`, the key the renderer already uses; its leaf is UUID-shaped so pane-key validation accepts it | +| `tabId` | `structuredAgentSessionTabId(sessionId)` | +| `worktreeId` | `summary.workspaceId` (a folder workspace id is a valid value) | +| `state` | `structuredAgentSessionStatusState(summary.status)`, the mapping #19217 shared | +| `source` | `'structured-host'` | +| `structuredHostOwned` | present while `summary.hostExecutionOwned` is present | +| prompt, tool, last message, model, provider session | the summary's fields | + +Sessions with no persisted turn (`status === null`) produce no row, matching +what the chat shows. When the host revokes live ownership the row is re-set +without the flag; when the host closes or evicts the session the row is +dropped. Both already exist as feed events (`revokeLive` and the roster +filter in `liveSessionSummaries`); PR 1 turns them into store writes. + +Two rules the ingest must keep: + +- **Never persist a structured row.** The journal is the durable truth for a + structured session and the host republishes on restore. A structured row in + `last-status.json` would hydrate as `restoredUnconfirmed` and then fight the + live republish. The serializer skips rows whose source is `structured-host`. +- **Never let it fight a hook row.** A structured session has no PTY, so no + hook or OSC event carries its pane key. The ingest still goes through the + disposition gate so a retired pane key is refused like any other. + +The ingest lives in the feed, not in `structured-agent-session-host.ts`, which +sits at the file-length cap. + +### The runtime's retained row store is deleted + +`RuntimeAgentRowStore` keeps the same payload the hook server already holds. +Its only extra is the pty id, used to clear rows on exit and as a fallback key +for the mobile projection. PR 1 stamps `terminalHandle` on OSC-ingested rows +from the runtime event's `ptyId`, and rewrites the three readers over the hook +server's snapshot: + +- `worktree ps` reads `getStatusSnapshot()` directly; +- `getFreshExplicit` already consults hook rows; it drops the retained input; +- `getFreshForMobile` matches on pane key, then on `terminalHandle`. + +One behavior change follows and is intended: a row the user dismisses on the +desktop disappears from `worktree ps` and the phone at the same time, instead +of lingering until the pty exits. + +### `worktree ps` becomes a reader + +`collectRuntimeWorktreePtyAgentSources` loses its retained-versus-hook +reconciliation, because there is one row per pane. The structured adapter +added in #19217 is deleted. What remains is one adapter from the store's +snapshot to `RuntimeWorktreeAgentSource`, plus the admission gate that decides +which rows a worktree listing may show: + +- a hook or OSC row needs its tab mirrored or a connected pty, as today, and + SSH rows stay exempt because their tabs may exist only remotely; +- a `structured-host` row is admitted while the host holds the session, and + the host's drop on close is what removes it; no tab-mirror requirement, + because headless serve has no renderer to mirror tabs from. + +The freshness bypass for host-owned structured rows already exists in +`isFreshNonDoneAgentStatus`; with the flag now on the row it becomes the only +path, and the hand-rolled check in `runtime-worktree-agent-rows.ts` goes. + +### Wire compatibility + +`AgentStatusIpcPayload` gains one optional field, `structuredHost`, and the +`worktree ps` row gains `structuredHostOwned`. Under rule 1 of +[`remote-wire-compatibility.md`](./remote-wire-compatibility.md) both are safe: +an old client ignores them. `worktree ps` rows keep their shape and vocabulary, +so the mobile app sees no change. + +Until PR 2 the main process does not forward structured rows to the renderer +over `agentStatus:set` or `agentStatus:getSnapshot`. The renderer's feed +bridge still writes those rows itself, and forwarding them too would give one +pane key two writers. Removing that filter is the first step of PR 2. + +## PR 2: the renderer subscribes + +With structured rows arriving over `agentStatus:set`, the renderer's +`StructuredAgentSessionStatusBridge` no longer needs to write status; its +unmount cleanup becomes a tab-close signal to the host. The IPC applicator is +the single writer for observed status. The 2026-09-09 audit sorted the other +writers: + +| Writer | Disposition | +| --------------------------------------------------------------- | -------------------------------------------------- | +| Command Code output seeds, parked-pane seeds, pty-exit removal | delete; main already emits the same facts | +| structured bridge status writes | delete; main now publishes the row | +| launch placeholder seeds (a user launched an agent with a prompt) | keep for now; main holds the launch config and can seed later | +| dismissal, acknowledgement, unmount | keep; user facts and component lifecycle | +| remote-runtime OSC parse (bytes never transit local main) | keep, fenced behind the host's published row once the host is new enough; rule 3 of the wire doc applies | +| web-session mirror receipt clock | keep; the decay rule needs both clocks from one machine | + +The Command Code done-settle window is renderer policy with no main +equivalent. PR 2 either moves it into main's detector or leaves it, and says +which. + +## PR 3: one rollup, one clock + +The worktree card status is derived three times: `lib/worktree-status.ts` in +the renderer, `runtime-worktree-status-projection.ts` in main, and +`agent-row-display.ts` in mobile, which hand-copies the 30-minute constant. +PR 3 moves the rollup and the decay into `src/shared` and makes all three +call it. + +## What does not change + +- The hook scripts, the OSC 9999 wire format, and the relay protocol. +- The status vocabulary. `working / blocked / done` for rows, + `working / attention / idle` for structured summaries, mapped once. +- The `live / unverifiable / exited` verdicts for remote work. Loss of contact + clears nothing; the SSH exemptions in the admission gate stay. +- Hydration honesty: a restored non-done row is `restoredUnconfirmed` and is + never fresh. + +## Verification + +- Unit: ingest a structured summary and read it back through + `getStatusSnapshot`, `worktree ps`, and the mobile projection; assert the + serializer never writes a `structured-host` row; assert a hydrated file that + somehow contains one is dropped. +- Unit: the existing `worktree ps` suites pass unchanged, which is the + characterization that deleting the retained store changed no listing. +- Live: the parity check from #19217 (working, done, close, reload) repeated + against the merged store, with both surfaces read from the one row. diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 7add63b397bc..baf05a740844 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -6,6 +6,9 @@ importers: .: configDependencies: {} packageManagerDependencies: + '@pnpm/exe': + specifier: 12.0.0 + version: 12.0.0 pnpm: specifier: 12.0.0 version: 12.0.0 @@ -56,6 +59,11 @@ packages: cpu: [x64] os: [win32] + '@pnpm/exe@12.0.0': + resolution: {integrity: sha512-405vw2qYPPghNxoPRt2cvkGtGNU5gnInDcIe5TztQxe73yUZLqFJN/jCJFGs1xbVaIWDXEVuQ71P8npFZeatZQ==} + engines: {node: '>=18.*'} + hasBin: true + pnpm@12.0.0: resolution: {integrity: sha512-ni49w5EZlYaNyUuBdcIXwn6VQI+gO0oidJd48rNPdzt3zdOznt6BcbIvzVO+ajU0Lp+smUimjvWN9kiM6Jp+Zw==} engines: {node: '>=18.*'} @@ -87,6 +95,17 @@ snapshots: '@pnpm/exe.win32-x64@12.0.0': optional: true + '@pnpm/exe@12.0.0': + optionalDependencies: + '@pnpm/exe.darwin-arm64': 12.0.0 + '@pnpm/exe.darwin-x64': 12.0.0 + '@pnpm/exe.linux-arm64': 12.0.0 + '@pnpm/exe.linux-arm64-musl': 12.0.0 + '@pnpm/exe.linux-x64': 12.0.0 + '@pnpm/exe.linux-x64-musl': 12.0.0 + '@pnpm/exe.win32-arm64': 12.0.0 + '@pnpm/exe.win32-x64': 12.0.0 + pnpm@12.0.0: optionalDependencies: '@pnpm/exe.darwin-arm64': 12.0.0 diff --git a/src/main/agent-hooks/server-ingest-structured-status.test.ts b/src/main/agent-hooks/server-ingest-structured-status.test.ts new file mode 100644 index 000000000000..0dd648235770 --- /dev/null +++ b/src/main/agent-hooks/server-ingest-structured-status.test.ts @@ -0,0 +1,219 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import type { AgentSessionStatusSummary } from '../../shared/agent-session-wire' +import { + structuredAgentSessionPaneKey, + structuredAgentSessionTabId +} from '../../shared/structured-agent-session-projection' +import { AgentHookServer, _internals } from './server' +import { PANE } from './server.test-fixtures' + +const { getCohortAtEmitMock, trackMock } = vi.hoisted(() => ({ + getCohortAtEmitMock: vi.fn(), + trackMock: vi.fn() +})) + +vi.mock('../telemetry/client', () => ({ + track: trackMock +})) + +vi.mock('../telemetry/cohort-classifier', () => ({ + getCohortAtEmit: getCohortAtEmitMock +})) + +const SESSION = 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d' +const TAB = structuredAgentSessionTabId(SESSION) +const STRUCTURED_PANE = structuredAgentSessionPaneKey(TAB, SESSION) +const OBSERVED_AT = 1_757_030_400_000 + +function summary(over: Partial = {}): AgentSessionStatusSummary { + return { + sessionId: SESSION, + workspaceId: 'repo-1::/workspace/app', + agent: 'codex', + status: 'working', + hostExecutionOwned: true, + latestPrompt: 'ship the thing', + model: 'gpt-6-astra', + toolName: 'shell', + toolInput: 'sleep 30', + lastAssistantMessage: 'on it', + updatedAt: OBSERVED_AT, + ...over + } +} + +beforeEach(() => { + _internals.resetCachesForTests() + trackMock.mockReset() + getCohortAtEmitMock.mockReset() + getCohortAtEmitMock.mockReturnValue({ nth_repo_added: 2 }) +}) + +afterEach(() => { + vi.restoreAllMocks() +}) + +describe('AgentHookServer ingestStructuredStatus', () => { + it('stores the projection as a row under the pane key the renderer derives', () => { + const server = new AgentHookServer() + server.ingestStructuredStatus(summary()) + + expect(server.getStatusSnapshot()).toEqual([ + expect.objectContaining({ + paneKey: STRUCTURED_PANE, + tabId: TAB, + worktreeId: 'repo-1::/workspace/app', + connectionId: null, + state: 'working', + agentType: 'codex', + prompt: 'ship the thing', + model: 'gpt-6-astra', + toolName: 'shell', + toolInput: 'sleep 30', + lastAssistantMessage: 'on it', + structuredHost: 'owned', + // The journal clock, not the ingest clock: a restart's republish is not new evidence. + evidenceObservedAt: OBSERVED_AT, + stateStartedAt: OBSERVED_AT + }) + ]) + expect(server.getStatusSnapshot()[0]?.observation?.origin).toBe('structured') + }) + + // The same mapping the sidebar applies, so the two surfaces cannot disagree about one session. + it('maps attention to blocked and idle to done', () => { + const server = new AgentHookServer() + server.ingestStructuredStatus(summary({ status: 'attention' })) + expect(server.getStatusSnapshot()[0]?.state).toBe('blocked') + server.ingestStructuredStatus(summary({ status: 'idle', updatedAt: OBSERVED_AT + 1 })) + expect(server.getStatusSnapshot()[0]?.state).toBe('done') + }) + + it('marks a session whose provider child is gone as held, not owned', () => { + const server = new AgentHookServer() + server.ingestStructuredStatus(summary({ hostExecutionOwned: undefined })) + expect(server.getStatusSnapshot()[0]?.structuredHost).toBe('held') + }) + + it('keeps the state start while later evidence of the same state arrives', () => { + const server = new AgentHookServer() + server.ingestStructuredStatus(summary()) + server.ingestStructuredStatus(summary({ toolName: 'read', updatedAt: OBSERVED_AT + 5_000 })) + + expect(server.getStatusSnapshot()[0]).toMatchObject({ + toolName: 'read', + evidenceObservedAt: OBSERVED_AT + 5_000, + stateStartedAt: OBSERVED_AT + }) + }) + + // Null status means no turn has been persisted; the chat shows nothing, so neither does this. + it('holds no row for a session without a persisted turn, and drops one that regresses to none', () => { + const server = new AgentHookServer() + server.ingestStructuredStatus(summary({ status: null })) + expect(server.getStatusSnapshot()).toEqual([]) + + server.ingestStructuredStatus(summary()) + server.ingestStructuredStatus(summary({ status: null })) + expect(server.getStatusSnapshot()).toEqual([]) + }) + + it('drops the row when the host stops holding the session', () => { + const server = new AgentHookServer() + server.ingestStructuredStatus(summary()) + server.dropStructuredStatus(SESSION) + expect(server.getStatusSnapshot()).toEqual([]) + }) + + it('leaves a hook-reported pane alone', () => { + const server = new AgentHookServer() + server.ingestTerminalStatus({ + paneKey: PANE, + connectionId: null, + payload: { state: 'working', prompt: 'watch the build', agentType: 'claude' } + }) + server.ingestStructuredStatus(summary()) + + const byPane = new Map(server.getStatusSnapshot().map((row) => [row.paneKey, row])) + expect(byPane.get(PANE)?.structuredHost).toBeUndefined() + expect(byPane.get(STRUCTURED_PANE)?.structuredHost).toBe('owned') + }) +}) + +describe('structured rows and last-status.json', () => { + let userDataPath: string + + beforeEach(() => { + userDataPath = mkdtempSync(join(tmpdir(), 'orca-structured-status-')) + }) + + afterEach(() => { + rmSync(userDataPath, { recursive: true, force: true }) + }) + + function lastStatusPath(): string { + return join(userDataPath, 'agent-hooks', 'last-status.json') + } + + // The journal is the durable truth and the host republishes on restore; a persisted copy would + // hydrate as unconfirmed and fight that republish. + it('are never written, while hook rows still are', async () => { + const server = new AgentHookServer() + await server.start({ env: 'production', userDataPath }) + try { + server.ingestTerminalStatus({ + paneKey: PANE, + connectionId: null, + payload: { state: 'working', prompt: 'watch the build', agentType: 'claude' } + }) + server.ingestStructuredStatus(summary()) + server.flushStatusPersistSync() + } finally { + server.stop() + } + + const file = JSON.parse(readFileSync(lastStatusPath(), 'utf8')) as { + entries: Record + } + expect(Object.keys(file.entries)).toEqual([PANE]) + + const restored = new AgentHookServer() + await restored.start({ env: 'production', userDataPath }) + try { + expect(restored.getStatusSnapshot().map((row) => row.paneKey)).toEqual([PANE]) + } finally { + restored.stop() + } + }) + + it('are dropped on hydrate if some other writer put one on disk', async () => { + mkdirSync(join(userDataPath, 'agent-hooks'), { recursive: true }) + writeFileSync( + lastStatusPath(), + JSON.stringify({ + version: 2, + entries: { + [STRUCTURED_PANE]: { + paneKey: STRUCTURED_PANE, + tabId: TAB, + connectionId: null, + receivedAt: Date.now(), + stateStartedAt: Date.now(), + structuredHost: 'owned', + payload: { state: 'working', prompt: 'ship the thing', agentType: 'codex' } + } + } + }) + ) + const server = new AgentHookServer() + await server.start({ env: 'production', userDataPath }) + try { + expect(server.getStatusSnapshot()).toEqual([]) + } finally { + server.stop() + } + }) +}) diff --git a/src/main/agent-hooks/server/server-ingest-remote.ts b/src/main/agent-hooks/server/server-ingest-remote.ts index 18b0a837c322..fae24c93b411 100644 --- a/src/main/agent-hooks/server/server-ingest-remote.ts +++ b/src/main/agent-hooks/server/server-ingest-remote.ts @@ -17,9 +17,9 @@ import { launchTokenHash } from '../../../shared/agent-hook-spool' import { parsePaneKey } from '../../../shared/stable-pane-id' import type { AgentHookEventPayload } from '../../../shared/agent-hook-listener/listener-event' import { isValidPiProviderSessionOnly } from './server-status-identity' -import { AgentHookServerIngestTerminal } from './server-ingest-terminal' +import { AgentHookServerIngestStructured } from './server-ingest-structured' -export abstract class AgentHookServerIngestRemote extends AgentHookServerIngestTerminal { +export abstract class AgentHookServerIngestRemote extends AgentHookServerIngestStructured { /** Ingest a payload from the relay JSON-RPC channel (not the local HTTP server); connectionId is stamped here. Main is still the SSH trust boundary, so re-run the canonical normalizer before caching. */ ingestRemote( envelope: { diff --git a/src/main/agent-hooks/server/server-ingest-structured.ts b/src/main/agent-hooks/server/server-ingest-structured.ts new file mode 100644 index 000000000000..81555dea3b74 --- /dev/null +++ b/src/main/agent-hooks/server/server-ingest-structured.ts @@ -0,0 +1,62 @@ +import type { AgentSessionStatusSummary } from '../../../shared/agent-session-wire' +import type { ParsedAgentStatusPayload } from '../../../shared/agent-status-types' +import { + structuredAgentSessionPaneKey, + structuredAgentSessionStatusState, + structuredAgentSessionTabId +} from '../../../shared/structured-agent-session-projection' +import { AgentHookServerIngestTerminal } from './server-ingest-terminal' + +/** + * Structured (native chat) sessions have no PTY and no hook script, so nothing else reaches this + * store for them. The host projects each session's journal into a summary; this is where that + * summary becomes the same row every other agent has, keyed by the pane key the renderer derives. + */ +export abstract class AgentHookServerIngestStructured extends AgentHookServerIngestTerminal { + ingestStructuredStatus(summary: AgentSessionStatusSummary): void { + const paneKey = structuredStatusPaneKey(summary.sessionId) + // No persisted turn yet: the chat shows nothing, so neither does any status reader. + if (!summary.status) { + this.dropStructuredStatus(summary.sessionId) + return + } + if (this.getAgentStatusDisposition(paneKey) !== 'accept') { + return + } + const payload: ParsedAgentStatusPayload = { + state: structuredAgentSessionStatusState(summary.status), + prompt: summary.latestPrompt, + agentType: summary.agent, + ...(summary.model ? { model: summary.model } : {}), + ...(summary.toolName ? { toolName: summary.toolName } : {}), + ...(summary.toolInput ? { toolInput: summary.toolInput } : {}), + ...(summary.lastAssistantMessage + ? { lastAssistantMessage: summary.lastAssistantMessage } + : {}) + } + // The journal clock stamps the evidence so a restart's republish does not read as fresh work. + this.applyNormalizedStatus( + { + paneKey, + tabId: structuredAgentSessionTabId(summary.sessionId), + worktreeId: summary.workspaceId, + connectionId: null, + structuredHost: summary.hostExecutionOwned ? 'owned' : 'held', + ...(summary.providerSession ? { providerSession: summary.providerSession } : {}), + payload + }, + undefined, + 'structured', + summary.updatedAt + ) + } + + /** The host no longer holds the session; its last projection is history the journal keeps. */ + dropStructuredStatus(sessionId: string): void { + this.clearPaneState(structuredStatusPaneKey(sessionId)) + } +} + +function structuredStatusPaneKey(sessionId: string): string { + return structuredAgentSessionPaneKey(structuredAgentSessionTabId(sessionId), sessionId) +} diff --git a/src/main/agent-hooks/server/server-persistence-validation.ts b/src/main/agent-hooks/server/server-persistence-validation.ts index 061646731ee5..6c0136aaa512 100644 --- a/src/main/agent-hooks/server/server-persistence-validation.ts +++ b/src/main/agent-hooks/server/server-persistence-validation.ts @@ -43,6 +43,10 @@ export function sanitizeHydratedEntry( if (record.paneKey !== paneKey) { return null } + // Why: structured rows are never written; the host republishes the live projection on restore. + if (record.structuredHost !== undefined) { + return null + } const tabId = record.tabId if (tabId !== undefined && (typeof tabId !== 'string' || tabId.length === 0)) { return null diff --git a/src/main/agent-hooks/server/server-persistence.ts b/src/main/agent-hooks/server/server-persistence.ts index ecb33c44d37e..f5b66222d6d8 100644 --- a/src/main/agent-hooks/server/server-persistence.ts +++ b/src/main/agent-hooks/server/server-persistence.ts @@ -27,6 +27,11 @@ export abstract class AgentHookServerPersistence extends AgentHookServerHydratio continue } const enrichedPayload = payload as EnrichedAgentHookEventPayload + // Why: the session journal is the durable truth for a structured row and the host republishes + // it on restore; a persisted copy would hydrate unconfirmed and fight that republish. + if (enrichedPayload.structuredHost) { + continue + } const childOnlyBoundary = enrichedPayload.claudeLeadBoundaryChildOnly === true const { claudeRunningNonAgentTask: _claudeRunningNonAgentTask, diff --git a/src/main/agent-hooks/server/server-state.ts b/src/main/agent-hooks/server/server-state.ts index 7dc8125576e6..b18677689d07 100644 --- a/src/main/agent-hooks/server/server-state.ts +++ b/src/main/agent-hooks/server/server-state.ts @@ -137,7 +137,8 @@ export abstract class AgentHookServerState { protected abstract markPaneClosedForAgentStatus(paneKey: string): void protected abstract attachStatusTiming( payload: AgentHookEventPayload, - now?: number + now?: number, + observedAt?: number ): EnrichedAgentHookEventPayload protected abstract hashPromptForTelemetryDedupe(prompt: string): string protected abstract maybeTrackAgentPromptSent( @@ -152,7 +153,8 @@ export abstract class AgentHookServerState { protected abstract applyNormalizedStatus( payload: AgentHookEventPayload, onAccepted?: () => void, - origin?: AgentStatusObservationOrigin + origin?: AgentStatusObservationOrigin, + observedAt?: number ): EnrichedAgentHookEventPayload protected abstract emitEnrichedStatus(enriched: EnrichedAgentHookEventPayload): void protected abstract clearAssistantMessageRetry(paneKey: string): void diff --git a/src/main/agent-hooks/server/server-status-application.ts b/src/main/agent-hooks/server/server-status-application.ts index f7e1126d11be..025c431dff66 100644 --- a/src/main/agent-hooks/server/server-status-application.ts +++ b/src/main/agent-hooks/server/server-status-application.ts @@ -17,9 +17,12 @@ import { AgentHookServerStatusDisposition } from './server-status-disposition' const MAX_REMEMBERED_EVIDENCE_OBSERVATIONS = 1024 export abstract class AgentHookServerStatusApplication extends AgentHookServerStatusDisposition { + /** `observedAt` is the producer's own clock for evidence that has one (a session journal); it + * stamps the evidence and state-start times while `receivedAt` keeps delivery order. */ protected attachStatusTiming( payload: AgentHookEventPayload, - now = Date.now() + now = Date.now(), + observedAt?: number ): EnrichedAgentHookEventPayload { const previous = this.state.lastStatusByPaneKey.get(payload.paneKey) as | EnrichedAgentHookEventPayload @@ -39,12 +42,12 @@ export abstract class AgentHookServerStatusApplication extends AgentHookServerSt const stateStartedAt = previous && previous.payload.state === payload.payload.state && !commandCodeNewTurn ? previous.stateStartedAt - : now + : (observedAt ?? now) // Why: `stateStartedAt` tracks the current state, while `receivedAt` tracks every arrival. return { ...payload, receivedAt: now, - evidenceObservedAt: this.resolveEvidenceObservedAt(payload, previous, now), + evidenceObservedAt: observedAt ?? this.resolveEvidenceObservedAt(payload, previous, now), stateStartedAt } } diff --git a/src/main/agent-hooks/server/server-status-identity.ts b/src/main/agent-hooks/server/server-status-identity.ts index a4ee28f1bb83..4f6e920d86e5 100644 --- a/src/main/agent-hooks/server/server-status-identity.ts +++ b/src/main/agent-hooks/server/server-status-identity.ts @@ -68,6 +68,7 @@ export function toAgentStatusIpcPayload( ...(entry.promptInteractionKey ? { promptInteractionKey: entry.promptInteractionKey } : {}), ...(entry.restoredUnconfirmed ? { restoredUnconfirmed: true } : {}), ...(entry.observation ? { observation: entry.observation } : {}), + ...(entry.structuredHost ? { structuredHost: entry.structuredHost } : {}), ...entry.payload } } diff --git a/src/main/agent-hooks/server/server-status-update.ts b/src/main/agent-hooks/server/server-status-update.ts index 981da873e3dc..dff0bd40e9dd 100644 --- a/src/main/agent-hooks/server/server-status-update.ts +++ b/src/main/agent-hooks/server/server-status-update.ts @@ -23,7 +23,8 @@ export abstract class AgentHookServerStatusUpdate extends AgentHookServerStatusA protected applyNormalizedStatus( payload: AgentHookEventPayload, onAccepted?: () => void, - origin: AgentStatusObservationOrigin = 'hook' + origin: AgentStatusObservationOrigin = 'hook', + observedAt?: number ): EnrichedAgentHookEventPayload { if (payload.hookEventName === 'UserPromptSubmit') { // Why: the prompt boundary is authoritative even when text is unchanged; its next OSC working row must not inherit the prior cron/background turn stamp. @@ -179,8 +180,8 @@ export abstract class AgentHookServerStatusUpdate extends AgentHookServerStatusA this.maybeTrackAgentPromptSent(effectivePayload, previous) } const enriched = { - ...this.attachStatusTiming(boundaryAwarePayload, now), - observation: this.stampObservation(boundaryAwarePayload, origin, now) + ...this.attachStatusTiming(boundaryAwarePayload, now, observedAt), + observation: this.stampObservation(boundaryAwarePayload, origin, observedAt ?? now) } if ( typeof enriched.payload.turnCompletedAt === 'number' && diff --git a/src/main/ipc/agent-hooks.ts b/src/main/ipc/agent-hooks.ts index ee858e3cca84..f460be06b5fe 100644 --- a/src/main/ipc/agent-hooks.ts +++ b/src/main/ipc/agent-hooks.ts @@ -49,9 +49,13 @@ export function registerAgentHookHandlers( // Why: the renderer pulls this after workspace hydration, so startup cannot // lose replayed statuses while its local store is still empty. Match the // live push enrichment in main/index.ts so parent/child rows survive replay. - return agentHookServer - .getStatusSnapshot() - .map((entry) => enrichAgentStatusIpcPayload(entry, runtime)) + return ( + agentHookServer + .getStatusSnapshot() + // Same rule as the live push: the renderer's feed bridge owns structured rows for now. + .filter((entry) => entry.structuredHost === undefined) + .map((entry) => enrichAgentStatusIpcPayload(entry, runtime)) + ) }) ipcMain.handle('agentStatus:inferInterrupt', (_event, request: unknown): boolean => { if (typeof request !== 'object' || request === null) { diff --git a/src/main/native-chat/agent-session-wire/structured-agent-session-host-types.ts b/src/main/native-chat/agent-session-wire/structured-agent-session-host-types.ts index 7a321668c468..9aa87d21b3c9 100644 --- a/src/main/native-chat/agent-session-wire/structured-agent-session-host-types.ts +++ b/src/main/native-chat/agent-session-wire/structured-agent-session-host-types.ts @@ -8,6 +8,7 @@ import type { AgentSessionJournal } from '../agent-session-journal/journal-store import type { StructuredAgentSessionAdapter } from './structured-agent-session-adapter' import type { AgentSessionAttachParams } from './structured-agent-session-attach' import type { StructuredAgentSessionHandoffTransport } from './structured-agent-session-handoff-types' +import type { StructuredAgentSessionStatusSink } from './structured-agent-session-status-feed' export type StructuredAgentSessionCaller = { callerKey: string } @@ -69,5 +70,8 @@ export type StructuredAgentSessionHostDeps = { summary: AgentSessionStatusSummary, options: { replay: boolean } ) => void + /** The agent-status store every held session's projection is written to and, on close, + * removed from. Absent only in tests that read the feed directly. */ + statusSink?: StructuredAgentSessionStatusSink handoffTransport?: StructuredAgentSessionHandoffTransport } diff --git a/src/main/native-chat/agent-session-wire/structured-agent-session-host.ts b/src/main/native-chat/agent-session-wire/structured-agent-session-host.ts index 2df2fdf54124..e20a636ae184 100644 --- a/src/main/native-chat/agent-session-wire/structured-agent-session-host.ts +++ b/src/main/native-chat/agent-session-wire/structured-agent-session-host.ts @@ -68,7 +68,8 @@ export class StructuredAgentSessionHost { sessions: this.sessions, getRecord: (sessionId) => this.deps.store.getRecord(sessionId), now: () => this.now(), - onStatusChanged: (summary, options) => this.deps.onSessionStatusChanged?.(summary, options) + onStatusChanged: (summary, options) => this.deps.onSessionStatusChanged?.(summary, options), + statusSink: () => this.deps.statusSink }) private readonly subscribers = new AgentSessionSubscribers({ readCommands: (sessionId) => this.deps.adapter.readCommands?.(sessionId), @@ -200,7 +201,7 @@ export class StructuredAgentSessionHost { return this.serialize(sessionId, async () => { await this.handoffs.closeRetainedTuiOwner(sessionId) await evictHeldStructuredAgentSession(this.lifetimeContext(), sessionId) - this.statusFeed.revokeLive(sessionId) + this.statusFeed.close(sessionId) // Whoever asked for the close, the surfaces that were holding this session are looking at a // session that no longer exists. A failed eviction throws above and keeps them. this.holds.forget(sessionId) @@ -212,10 +213,6 @@ export class StructuredAgentSessionHost { listSessionTabs = () => listStructuredAgentSessionTabs(this.sessions) - /** Last projected status for every structured session this host still holds, for non-subscribing - * readers. The retained projections of forgotten sessions are deliberately not included. */ - readonly liveSessionStatusSummaries = () => this.statusFeed.liveSessionSummaries() - getPersistedVisibleSessionTabIndex = () => this.deps.store.getVisibleSessionTabIndex() setSessionTabVisibility = (sessionId: string, visible: boolean): Promise => diff --git a/src/main/native-chat/agent-session-wire/structured-agent-session-status-feed.test.ts b/src/main/native-chat/agent-session-wire/structured-agent-session-status-feed.test.ts index 1e3b9bb25a34..35837cb9debd 100644 --- a/src/main/native-chat/agent-session-wire/structured-agent-session-status-feed.test.ts +++ b/src/main/native-chat/agent-session-wire/structured-agent-session-status-feed.test.ts @@ -3,14 +3,18 @@ import { tmpdir } from 'node:os' import { join } from 'node:path' import { afterEach, beforeEach, describe, expect, it } from 'vitest' import type { AgentSessionRecord } from '../../../shared/agent-session-record' -import type { AgentSessionStatusEvent } from '../../../shared/agent-session-wire' +import type { + AgentSessionStatusEvent, + AgentSessionStatusSummary +} from '../../../shared/agent-session-wire' import { createClaudeJournalTranslator } from '../../claude/claude-structured-journal-translation' import { publishCodexTurnLifecycle } from '../../codex/codex-structured-journal-translation-turns' import { createDeferredStructuredAgentSessionEventSink } from './structured-agent-session-event-sink' import { createTrackedJournalOpener } from '../agent-session-journal/journal-store-test-open' import { StructuredAgentSessionStatusFeed, - type StructuredAgentSessionStatusFeedDeps + type StructuredAgentSessionStatusFeedDeps, + type StructuredAgentSessionStatusSink } from './structured-agent-session-status-feed' const SESSION = 'status-session' @@ -72,11 +76,13 @@ function feedFor( { journal: Awaited>; hasProviderChild?: boolean } >, record: Partial | null = null, - onStatusChanged?: StructuredAgentSessionStatusFeedDeps['onStatusChanged'] + onStatusChanged?: StructuredAgentSessionStatusFeedDeps['onStatusChanged'], + statusSink?: StructuredAgentSessionStatusSink ) { let now = 1_000 const feed = new StructuredAgentSessionStatusFeed({ ...(onStatusChanged ? { onStatusChanged } : {}), + ...(statusSink ? { statusSink: () => statusSink } : {}), sessions: { get: (sessionId: string) => { const session = sessions.get(sessionId) @@ -574,23 +580,46 @@ describe('StructuredAgentSessionStatusFeed', () => { * it lists every session this host has ever opened. Eviction's `forget-session` step deletes the * session from the live map and touches nothing else, so a poller has to intersect with that map. */ -describe('the polling reader answers from the live sessions, not the retained cache', () => { - it('drops an evicted session from the poll while a late subscriber still sees it', async () => { +describe('the status sink sees the roster the broadcast cache deliberately lacks', () => { + function sinkFor() { + const published: AgentSessionStatusSummary[] = [] + const forgotten: string[] = [] + const sink: StructuredAgentSessionStatusSink = { + publish: (summary) => published.push(summary), + forget: (sessionId) => forgotten.push(sessionId) + } + return { sink, published, forgotten } + } + + it('receives every change once, ownership revocation, and the forget edge', async () => { const journal = await openJournal() - const sessions = new Map([[SESSION, { journal }]]) - const { feed } = feedFor(sessions) + const sessions = new Map([[SESSION, { journal, hasProviderChild: true }]]) + const { sink, published, forgotten } = sinkFor() + const { feed } = feedFor(sessions, null, undefined, sink) await journal.appendItem( USER_IDENTITY, { kind: 'message', role: 'user', blocks: [{ type: 'text', text: 'hello' }] }, { fence: 1 } ) feed.publish(SESSION, journal) - expect(feed.liveSessionSummaries().map((summary) => summary.sessionId)).toEqual([SESSION]) + // A second identical publication is deduped for the sink exactly as for subscribers, so the + // sink saw two writes: the opening projection the harness's subscriber triggered, then this. + feed.publish(SESSION, journal) + expect(published.map((summary) => summary.status)).toEqual([null, 'idle']) + expect(published.at(-1)).toMatchObject({ + sessionId: SESSION, + status: 'idle', + hostExecutionOwned: true + }) - // Exactly what eviction's `forget-session` step does; nothing else touches the feed. - sessions.delete(SESSION) + feed.revokeLive(SESSION) + expect(published.at(-1)).toMatchObject({ sessionId: SESSION, status: 'idle' }) + expect(published.at(-1)?.hostExecutionOwned).toBeUndefined() - expect(feed.liveSessionSummaries()).toEqual([]) + // Exactly what `close` does after eviction: the cache keeps the projection, the sink does not. + sessions.delete(SESSION) + feed.forget(SESSION) + expect(forgotten).toEqual([SESSION]) const late: AgentSessionStatusEvent[] = [] feed.subscribe({ id: 'list-2', emit: (event) => late.push(event) }) expect(late).toEqual([ @@ -600,4 +629,28 @@ describe('the polling reader answers from the live sessions, not the retained ca } ]) }) + + it('keeps publishing to subscribers when the sink throws', async () => { + const journal = await openJournal() + const sink: StructuredAgentSessionStatusSink = { + publish: () => { + throw new Error('store down') + }, + forget: () => { + throw new Error('store down') + } + } + const { feed, events } = feedFor(new Map([[SESSION, { journal }]]), null, undefined, sink) + await journal.appendItem( + USER_IDENTITY, + { kind: 'message', role: 'user', blocks: [{ type: 'text', text: 'hello' }] }, + { fence: 1 } + ) + feed.publish(SESSION, journal) + expect(() => feed.forget(SESSION)).not.toThrow() + expect(events.at(-1)).toMatchObject({ + type: 'status', + session: expect.objectContaining({ sessionId: SESSION, status: 'idle' }) + }) + }) }) diff --git a/src/main/native-chat/agent-session-wire/structured-agent-session-status-feed.ts b/src/main/native-chat/agent-session-wire/structured-agent-session-status-feed.ts index 61d9649587e0..348c28ee8c6b 100644 --- a/src/main/native-chat/agent-session-wire/structured-agent-session-status-feed.ts +++ b/src/main/native-chat/agent-session-wire/structured-agent-session-status-feed.ts @@ -33,6 +33,14 @@ type StatusFeedSession = { hasProviderChild?: boolean } +/** Where the host's projections land for readers that see every agent alike (`worktree ps`, + * mobile, the hook store's own fanout). `forget` is the roster edge the broadcast cache + * deliberately never has. */ +export type StructuredAgentSessionStatusSink = { + publish: (summary: AgentSessionStatusSummary) => void + forget: (sessionId: string) => void +} + export type StructuredAgentSessionStatusFeedDeps = { sessions: ReadonlyMap getRecord: (sessionId: string) => AgentSessionRecord | null @@ -40,6 +48,9 @@ export type StructuredAgentSessionStatusFeedDeps = { /** Every projection change, whether or not anyone is subscribed. `replay` marks a re-projection * of state the host already knew (restore, an arriving subscriber) rather than a journal edge. */ onStatusChanged?: (summary: AgentSessionStatusSummary, options: { replay: boolean }) => void + /** Resolved on every call: the host builds this feed in a field initializer, before its own + * deps are assigned. */ + statusSink?: () => StructuredAgentSessionStatusSink | undefined } function summariesEqual(a: AgentSessionStatusSummary, b: AgentSessionStatusSummary): boolean { @@ -78,25 +89,20 @@ export class StructuredAgentSessionStatusFeed { return () => this.unsubscribe(subscriber.id) } - /** - * Summaries for the sessions this host still holds, for readers that poll instead of subscribing. - * - * `published` never retracts, so it is a broadcast cache and not a roster: enumerating it lists - * every session ever opened here. A caller asking what is running gets the live intersection, - * while the retained view a subscriber opens on stays whole. - * - * Deliberately does NOT re-project: a subscriber's snapshot is the live read, and re-running the - * journal reduction per caller would make an enumerating command pay for every session it lists. - */ - liveSessionSummaries(): AgentSessionStatusSummary[] { - const summaries: AgentSessionStatusSummary[] = [] - for (const [sessionId] of this.deps.sessions) { - const summary = this.published.get(sessionId) - if (summary) { - summaries.push(summary) - } + /** The host stopped holding the session: ownership leaves the retained projection, and the + * row leaves the sink. `published` keeps the projection for reload history. */ + close(sessionId: string): void { + this.revokeLive(sessionId) + this.forget(sessionId) + } + + /** The sink lists what is running; a forgotten session must not be in it. */ + forget(sessionId: string): void { + try { + this.deps.statusSink?.()?.forget(sessionId) + } catch (error) { + console.warn('[structured-session-status] status sink forget failed', error) } - return summaries } unsubscribe(id: string): void { @@ -124,6 +130,7 @@ export class StructuredAgentSessionStatusFeed { type: 'status', session: retained }) + this.sink(retained) } /** Re-projects one session after its journal changed; equal projections are not re-sent. */ @@ -139,6 +146,7 @@ export class StructuredAgentSessionStatusFeed { } this.published.set(sessionId, summary) this.broadcast({ type: 'status', session: summary }) + this.sink(summary) try { this.deps.onStatusChanged?.(summary, { replay: options?.replay === true }) } catch (error) { @@ -174,6 +182,15 @@ export class StructuredAgentSessionStatusFeed { } } + /** A failing sink must never cost the subscribers their status event. */ + private sink(summary: AgentSessionStatusSummary): void { + try { + this.deps.statusSink?.()?.publish(summary) + } catch (error) { + console.warn('[structured-session-status] status sink publish failed', error) + } + } + private broadcast(event: AgentSessionStatusEvent): void { // A Map skips entries deleted mid-iteration, so a failing subscriber can drop itself here. for (const subscriber of this.subscribers.values()) { diff --git a/src/main/runtime/orca-runtime-get-worktree-ps.ts b/src/main/runtime/orca-runtime-get-worktree-ps.ts index 3dbd88090188..ade25ad19751 100644 --- a/src/main/runtime/orca-runtime-get-worktree-ps.ts +++ b/src/main/runtime/orca-runtime-get-worktree-ps.ts @@ -10,7 +10,6 @@ import { applyRuntimeWorktreePsTerminalActivity } from './runtime-worktree-ps-activity' import { attachRuntimeWorktreeAgentRows } from './runtime-worktree-agent-rows' -import { getStructuredAgentSessionHost } from '../native-chat/agent-session-wire/structured-agent-session-registry' import { compareWorktreePs } from './runtime-worktree-status-projection' import type { AgentSessionRecord } from '../../shared/agent-session-record' import type { Repo } from '../../shared/repo-types' @@ -109,9 +108,8 @@ export class OrcaRuntimeWithGetWorktreePs extends OrcaRuntimeWithStructuredAgent mirroredWorktreeIdByTabId, connectedPtyEvidence, retainedSnapshots: this.agentRows.values(), - hookSnapshots: this.getAgentStatusSnapshotFn?.() ?? [], - // Broadcast history outlives closed sessions; only the host roster is eligible. - structuredSummaries: getStructuredAgentSessionHost()?.liveSessionStatusSummaries() ?? [] + // Structured sessions are in here too: the host publishes them into the same store. + hookSnapshots: this.getAgentStatusSnapshotFn?.() ?? [] }), orchestrationByPaneKey: this.agentOrchestrationProjection.buildByPaneKey(), getSummary: (summaryMap, pathIndex, missingIds, worktreeId) => @@ -173,6 +171,7 @@ export class OrcaRuntimeWithGetWorktreePs extends OrcaRuntimeWithStructuredAgent firstWorkRenameDeps(this.requireStore(), this) ) }, + ...(this.structuredAgentStatusSinkFn ? { statusSink: this.structuredAgentStatusSinkFn } : {}), handoffTransport: this.createStructuredAgentSessionHandoffTransport() }) } diff --git a/src/main/runtime/orca-runtime-preserved-branch-cleanup.ts b/src/main/runtime/orca-runtime-preserved-branch-cleanup.ts index 2e1357e34507..33b4ace77720 100644 --- a/src/main/runtime/orca-runtime-preserved-branch-cleanup.ts +++ b/src/main/runtime/orca-runtime-preserved-branch-cleanup.ts @@ -10,6 +10,7 @@ import type { } from './runtime-terminal-contracts' import type { TerminalSideEffectBatch } from '../../shared/terminal-side-effect-facts' import type { AgentStatusIpcPayload } from '../../shared/agent-status-types' +import type { StructuredAgentSessionStatusSink } from '../native-chat/agent-session-wire/structured-agent-session-status-feed' import type { ObservedAgentStatusPaneIdentity } from '../ipc/agent-status-ipc-boundary' import type { AgentHookAuthorityAttestation } from '../agent-hooks/server' import type { RuntimeDesktopWindowStatus } from '../../shared/runtime-types' @@ -66,6 +67,8 @@ export class OrcaRuntimeWithPreservedBranchCleanup extends OrcaRuntimeWithTermin protected readonly getAgentStatusSnapshotFn: (() => AgentStatusIpcPayload[]) | null + protected readonly structuredAgentStatusSinkFn: StructuredAgentSessionStatusSink | null + protected readonly readObservedAgentStatusPaneIdentityFn: ( paneKey: string ) => ObservedAgentStatusPaneIdentity diff --git a/src/main/runtime/orca-runtime-state-fields.ts b/src/main/runtime/orca-runtime-state-fields.ts index 1884df7ed12b..876de03fe76c 100644 --- a/src/main/runtime/orca-runtime-state-fields.ts +++ b/src/main/runtime/orca-runtime-state-fields.ts @@ -6,6 +6,7 @@ import type { IPtyProvider } from '../providers/types' import type { RuntimeTerminalAgentStatusEvent } from './runtime-terminal-contracts' import type { TerminalSideEffectBatch } from '../../shared/terminal-side-effect-facts' import type { AgentStatusIpcPayload } from '../../shared/agent-status-types' +import type { StructuredAgentSessionStatusSink } from '../native-chat/agent-session-wire/structured-agent-session-status-feed' import type { ObservedAgentStatusPaneIdentity } from '../ipc/agent-status-ipc-boundary' import type { AgentHookAuthorityAttestation } from '../agent-hooks/server' import type { @@ -49,6 +50,9 @@ export class OrcaRuntimeWithStateFields extends OrcaRuntimeWithLinearCommands { // terminal output. worktree.ps reads this at query time so mobile shows the // same inline agent rows the desktop sidebar does — same source, 1:1. getAgentStatusSnapshot?: () => AgentStatusIpcPayload[] + /** Where structured (native chat) sessions publish into that same store, so the snapshot + * above lists them like every other agent. */ + structuredAgentStatusSink?: StructuredAgentSessionStatusSink /** The identity the runtime resolved for a pane as each status arrived. Without it the * fleet path reminted cached rows against whatever the pane owns now. */ readObservedAgentStatusPaneIdentity?: (paneKey: string) => ObservedAgentStatusPaneIdentity @@ -188,6 +192,7 @@ export class OrcaRuntimeWithStateFields extends OrcaRuntimeWithLinearCommands { this.stats = stats } this.getAgentStatusSnapshotFn = deps?.getAgentStatusSnapshot ?? null + this.structuredAgentStatusSinkFn = deps?.structuredAgentStatusSink ?? null this.readObservedAgentStatusPaneIdentityFn = deps?.readObservedAgentStatusPaneIdentity ?? (() => ({ kind: 'unobserved' })) this.getAgentProviderSessionSnapshotFn = diff --git a/src/main/runtime/orca-runtime-structured-status-sink-wiring.test.ts b/src/main/runtime/orca-runtime-structured-status-sink-wiring.test.ts new file mode 100644 index 000000000000..baf0e4c27dd5 --- /dev/null +++ b/src/main/runtime/orca-runtime-structured-status-sink-wiring.test.ts @@ -0,0 +1,44 @@ +import { describe, expect, it, vi } from 'vitest' + +const installed = vi.hoisted(() => ({ deps: null as Record | null })) + +vi.mock('electron', () => ({ + BrowserWindow: { fromId: vi.fn(() => null) }, + webContents: { fromId: vi.fn(() => null) }, + ipcMain: { on: vi.fn(), removeListener: vi.fn() }, + app: { getPath: vi.fn(() => '/tmp') } +})) + +vi.mock('./structured-agent-session-runtime', () => ({ + ensureStructuredAgentSessionHost: vi.fn(async (deps: Record) => { + installed.deps = deps + }) +})) + +import { OrcaRuntimeService } from './orca-runtime' +import type { StructuredAgentSessionStatusSink } from '../native-chat/agent-session-wire/structured-agent-session-status-feed' + +/** The runtime class this wiring lives on does not typecheck its own `this` calls, so a misnamed + * field here would install a host that never writes to the agent-status store — and every reader + * of that store would simply list no structured sessions. Pin it behaviourally. */ +describe('structured status sink wiring', () => { + it('hands the host the sink the runtime was constructed with', async () => { + installed.deps = null + const sink: StructuredAgentSessionStatusSink = { publish: vi.fn(), forget: vi.fn() } + const runtime = new OrcaRuntimeService(null, undefined, { structuredAgentStatusSink: sink }) + + await runtime.ensureStructuredAgentSessionHost() + + expect(installed.deps?.['statusSink']).toBe(sink) + }) + + it('installs without a sink when none was provided', async () => { + installed.deps = null + const runtime = new OrcaRuntimeService() + + await runtime.ensureStructuredAgentSessionHost() + + expect(installed.deps).not.toBeNull() + expect('statusSink' in (installed.deps ?? {})).toBe(false) + }) +}) diff --git a/src/main/runtime/orca-runtime-tests/worktree-ps-structured-host.spec.ts b/src/main/runtime/orca-runtime-tests/worktree-ps-structured-host.spec.ts index 58e7de1b6746..e6db4b6af0aa 100644 --- a/src/main/runtime/orca-runtime-tests/worktree-ps-structured-host.spec.ts +++ b/src/main/runtime/orca-runtime-tests/worktree-ps-structured-host.spec.ts @@ -1,146 +1,75 @@ -import { afterEach, describe, expect, it, vi } from 'vitest' +import { beforeEach, describe, expect, it, vi } from 'vitest' import { OrcaRuntimeService } from '../orca-runtime-test-mocks.spec' import { TEST_WORKTREE_ID, store } from '../orca-runtime-test-fixtures.spec' -import type { AgentJournalRenderItem } from '../../../shared/agent-session-journal-types' -import type { - AgentSessionStatusEvent, - AgentSessionStatusSummary -} from '../../../shared/agent-session-wire' -import type { AgentSessionJournal } from '../../native-chat/agent-session-journal/journal-store' -import type { StructuredAgentSessionHost } from '../../native-chat/agent-session-wire/structured-agent-session-host' -import { - getStructuredAgentSessionHost, - setStructuredAgentSessionHost -} from '../../native-chat/agent-session-wire/structured-agent-session-registry' -import { StructuredAgentSessionStatusFeed } from '../../native-chat/agent-session-wire/structured-agent-session-status-feed' +import { AgentHookServer, _internals } from '../../agent-hooks/server' + +vi.mock('../../telemetry/client', () => ({ track: vi.fn() })) +vi.mock('../../telemetry/cohort-classifier', () => ({ + getCohortAtEmit: vi.fn(() => ({ nth_repo_added: 2 })) +})) /** - * The production wiring, not the projection. Both structured-row suites call - * `attachRuntimeWorktreeAgentRows` directly with summaries they built themselves, so nothing - * executed `getWorktreePs`'s own `getStructuredAgentSessionHost()?.liveSessionStatusSummaries()` - * — and that file carries `@ts-nocheck`, so renaming the accessor stayed green in typecheck AND - * in the suite while `orca worktree ps` and mobile's poll would throw for every user. + * The production read, not the projection. The structured-row suites feed + * `attachRuntimeWorktreeAgentRows` a snapshot they built themselves; this executes `getWorktreePs` + * in `orca-runtime-get-worktree-ps.ts`, which is `@ts-nocheck`, so a renamed dependency there stays + * green in typecheck while `orca worktree ps` and mobile's poll would list nothing. */ +const SESSION = 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d' -const HELD_SESSION = 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d' -const FORGOTTEN_SESSION = 'b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e' -const OBSERVED_AT = 1_757_030_400_000 - -function runningTurn(prompt: string): AgentJournalRenderItem[] { - return [ - { - itemId: 'user-1', - sequence: 1, - revision: 1, - observedAt: OBSERVED_AT, - body: { kind: 'message', role: 'user', blocks: [{ type: 'text', text: prompt }] } - }, - { - itemId: 'turn-1', - sequence: 2, - revision: 1, - observedAt: OBSERVED_AT, - body: { - kind: 'status', - text: 'Working', - turnLifecycle: { turnId: 'turn-1', state: 'running' } - } - } - ] -} - -function journalWith(prompt: string): AgentSessionJournal { - return { - isReadOnly: false, - lastActivityAt: () => OBSERVED_AT, - snapshot: () => ({ items: runningTurn(prompt) }) - } as unknown as AgentSessionJournal -} - -/** A real feed the host still holds one session on, having forgotten the other. Its `published` - * cache never retracts, so the two views genuinely differ. */ -function statusFeed(): StructuredAgentSessionStatusFeed { - const session = (prompt: string) => ({ - journal: journalWith(prompt), - params: { location: { workspaceId: TEST_WORKTREE_ID }, provider: 'claude' as const } - }) - const sessions = new Map([ - [HELD_SESSION, session('ship the thing')], - [FORGOTTEN_SESSION, session('rm the branch')] - ]) - const feed = new StructuredAgentSessionStatusFeed({ - sessions, - getRecord: () => null, - now: () => OBSERVED_AT - }) - feed.publish(HELD_SESSION) - feed.publish(FORGOTTEN_SESSION) - // `forget-session`, the last eviction step, drops the session and leaves the feed alone. - sessions.delete(FORGOTTEN_SESSION) - return feed -} - -/** Everything the feed retained, read through the snapshot a subscriber opens on. No production - * code reads this; it is here so swapping the call site back to a whole-cache read is a one-line - * edit that this suite must catch. */ -function retainedSummaries(feed: StructuredAgentSessionStatusFeed): AgentSessionStatusSummary[] { - let retained: AgentSessionStatusSummary[] = [] - feed.subscribe({ - id: 'retained-probe', - emit: (event: AgentSessionStatusEvent) => { - if (event.type === 'snapshot') { - retained = event.sessions - } - } - })() - return retained -} - -function installHost(feed: StructuredAgentSessionStatusFeed) { - const liveSessionStatusSummaries = vi.fn(() => feed.liveSessionSummaries()) - const retainedSessionStatusSummaries = vi.fn(() => retainedSummaries(feed)) - // Typed against the real host, so renaming the accessor on the class reddens `tc` here — the - // caller cannot, because `orca-runtime-get-worktree-ps.ts` is `@ts-nocheck`. - const host: Pick & { - retainedSessionStatusSummaries: () => AgentSessionStatusSummary[] - } = { liveSessionStatusSummaries, retainedSessionStatusSummaries } - setStructuredAgentSessionHost(host as unknown as StructuredAgentSessionHost) - return { liveSessionStatusSummaries, retainedSessionStatusSummaries } -} - -describe('worktree ps reads the installed structured host', () => { - afterEach(() => { - setStructuredAgentSessionHost(null) - }) +beforeEach(() => { + _internals.resetCachesForTests() +}) - it('reports the held session and asks the host for its live summaries', async () => { - const feed = statusFeed() - const { liveSessionStatusSummaries } = installHost(feed) +describe('worktree ps reads structured sessions from the agent-status store', () => { + it('lists a host-held structured session with no terminal behind it', async () => { + const statusStore = new AgentHookServer() + statusStore.ingestStructuredStatus({ + sessionId: SESSION, + workspaceId: TEST_WORKTREE_ID, + agent: 'claude', + status: 'working', + hostExecutionOwned: true, + latestPrompt: 'ship the thing', + updatedAt: 1_757_030_400_000 + }) + const getAgentStatusSnapshot = vi.fn(() => statusStore.getStatusSnapshot()) - const { worktrees } = await new OrcaRuntimeService(store).getWorktreePs() + const { worktrees } = await new OrcaRuntimeService(store, undefined, { + getAgentStatusSnapshot + }).getWorktreePs() const worktree = worktrees.find((entry) => entry.worktreeId === TEST_WORKTREE_ID) expect(worktree).toBeDefined() - // Exactly one: the forgotten session is still in the feed's retained cache, so a call site - // that enumerated that cache instead would report two. expect(worktree?.agents).toHaveLength(1) expect(worktree?.agents[0]).toMatchObject({ state: 'working', agentType: 'claude', - prompt: 'ship the thing' + prompt: 'ship the thing', + structuredHostOwned: true }) - // Pins the call site to the live-intersecting accessor, not merely to some accessor. - expect(liveSessionStatusSummaries).toHaveBeenCalledTimes(1) + expect(worktree?.status).toBe('working') + expect(getAgentStatusSnapshot).toHaveBeenCalledTimes(1) }) - it('succeeds with no structured rows when no host is installed', async () => { - // Guard the guard: these specs share one module registry, so state the premise. - expect(getStructuredAgentSessionHost()).toBeNull() + it('lists nothing once the host has dropped the session', async () => { + const statusStore = new AgentHookServer() + statusStore.ingestStructuredStatus({ + sessionId: SESSION, + workspaceId: TEST_WORKTREE_ID, + agent: 'claude', + status: 'attention', + latestPrompt: 'rm the branch', + updatedAt: 1_757_030_400_000 + }) + statusStore.dropStructuredStatus(SESSION) - const { worktrees } = await new OrcaRuntimeService(store).getWorktreePs() + const { worktrees } = await new OrcaRuntimeService(store, undefined, { + getAgentStatusSnapshot: () => statusStore.getStatusSnapshot() + }).getWorktreePs() const worktree = worktrees.find((entry) => entry.worktreeId === TEST_WORKTREE_ID) expect(worktree).toBeDefined() expect(worktree?.agents).toEqual([]) + expect(worktree?.status).not.toBe('permission') }) }) diff --git a/src/main/runtime/runtime-worktree-agent-rows-structured.test.ts b/src/main/runtime/runtime-worktree-agent-rows-structured.test.ts index 84966846be7b..83b3d651642b 100644 --- a/src/main/runtime/runtime-worktree-agent-rows-structured.test.ts +++ b/src/main/runtime/runtime-worktree-agent-rows-structured.test.ts @@ -1,5 +1,5 @@ import { collectRuntimeWorktreeAgentSources } from './runtime-worktree-agent-sources' -import { describe, expect, it } from 'vitest' +import { beforeEach, describe, expect, it, vi } from 'vitest' import { attachRuntimeWorktreeAgentRows } from './runtime-worktree-agent-rows' import { structuredAgentSessionPaneKey, @@ -7,17 +7,24 @@ import { } from '../../shared/structured-agent-session-projection' import type { AgentSessionStatusSummary } from '../../shared/agent-session-wire' import type { RuntimeWorktreePsSummary } from '../../shared/runtime-types' +import { AgentHookServer, _internals } from '../agent-hooks/server' + +vi.mock('../telemetry/client', () => ({ track: vi.fn() })) +vi.mock('../telemetry/cohort-classifier', () => ({ + getCohortAtEmit: vi.fn(() => ({ nth_repo_added: 2 })) +})) /** - * A structured session has no PTY, so it reaches none of the hook or retained snapshots that every - * other row comes from. Before this, `worktree ps` reported a worktree running one as idle while - * the sidebar showed it working — the CLI, which is the agent-facing surface, was the blind one. + * A structured session has no PTY and no hook script, so the host publishes its projection into + * the agent-status store itself. This walks that store into `worktree ps` rows: before it, the CLI + * reported a worktree running one as idle while the sidebar showed it working. */ const WORKTREE_ID = 'repo-1::/workspace/app' +const SESSION = 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d' function summary(over: Partial = {}): AgentSessionStatusSummary { return { - sessionId: 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d', + sessionId: SESSION, workspaceId: WORKTREE_ID, agent: 'claude', status: 'working', @@ -29,6 +36,10 @@ function summary(over: Partial = {}): AgentSessionSta } function attach(summaries: AgentSessionStatusSummary[]): RuntimeWorktreePsSummary { + const store = new AgentHookServer() + for (const entry of summaries) { + store.ingestStructuredStatus(entry) + } const row = { worktreeId: WORKTREE_ID, status: 'inactive', @@ -45,8 +56,7 @@ function attach(summaries: AgentSessionStatusSummary[]): RuntimeWorktreePsSummar mirroredWorktreeIdByTabId: new Map(), connectedPtyEvidence: { tabIds: new Set(), paneKeys: new Set(), ptyIds: new Set() }, retainedSnapshots: [], - hookSnapshots: [], - structuredSummaries: summaries + hookSnapshots: store.getStatusSnapshot() }), orchestrationByPaneKey: null, getSummary: (map, _p, _m, id) => map.get(id) ?? null @@ -54,6 +64,10 @@ function attach(summaries: AgentSessionStatusSummary[]): RuntimeWorktreePsSummar return row } +beforeEach(() => { + _internals.resetCachesForTests() +}) + describe('worktree ps reports structured sessions', () => { it('a busy structured session is not reported idle', () => { const row = attach([summary()]) @@ -61,6 +75,7 @@ describe('worktree ps reports structured sessions', () => { expect(row.agents[0]?.state).toBe('working') expect(row.agents[0]?.agentType).toBe('claude') expect(row.agents[0]?.prompt).toBe('ship the thing') + expect(row.status).toBe('working') }) // The same projection the sidebar applies, so the two surfaces cannot disagree about one session. @@ -77,9 +92,8 @@ describe('worktree ps reports structured sessions', () => { it('reports the DERIVED pane key, never an orchestration credential', () => { const row = attach([summary()]) - const sessionId = 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d' expect(row.agents[0]?.paneKey).toBe( - structuredAgentSessionPaneKey(structuredAgentSessionTabId(sessionId), sessionId) + structuredAgentSessionPaneKey(structuredAgentSessionTabId(SESSION), SESSION) ) }) @@ -87,6 +101,12 @@ describe('worktree ps reports structured sessions', () => { it('omits a session with no projected status', () => { expect(attach([summary({ status: null })]).agents).toHaveLength(0) }) + + it('keeps the journal clock on the row, so a restart republish is not new activity', () => { + const row = attach([summary()]) + expect(row.agents[0]?.updatedAt).toBe(1_757_030_400_000) + expect(row.agents[0]?.stateStartedAt).toBe(1_757_030_400_000) + }) }) /** @@ -95,11 +115,10 @@ describe('worktree ps reports structured sessions', () => { * refresh check goes permanently true and pins shipped clients to a fast cadence with no exit, and * the plugin projection has no field that can carry `writable: false`. Every SAFE consumer of a * terminal summary checks `ptyId`; the breaking ones key off `connected` or mere row presence, - * which no added field can qualify. A separate change publishes an honest partial-listing count - * there instead. This pins that only `worktree ps` gained the enumerator. + * which no added field can qualify. This pins that the listing never reads the status store. */ describe('terminal listing is deliberately left alone', () => { - it('only worktree ps consumes the structured status summaries', async () => { + it('never reads the agent-status store that now carries structured rows', async () => { const { readFile } = await import('node:fs/promises') // orca-runtime-subscribe-to-terminal-resize.ts owns listTerminals. const listing = await readFile( @@ -108,13 +127,7 @@ describe('terminal listing is deliberately left alone', () => { ) // Guard the guard: an empty read would make every assertion below vacuously true. expect(listing).toContain('async listTerminals(') - expect(listing).not.toContain('liveSessionStatusSummaries') - expect(listing).not.toContain('structuredSummaries') - - const worktreePs = await readFile( - new URL('./orca-runtime-get-worktree-ps.ts', import.meta.url), - 'utf8' - ) - expect(worktreePs).toContain('liveSessionStatusSummaries') + expect(listing).not.toContain('getAgentStatusSnapshotFn') + expect(listing).not.toContain('structuredHost') }) }) diff --git a/src/main/runtime/runtime-worktree-agent-rows.ts b/src/main/runtime/runtime-worktree-agent-rows.ts index 80802cf11a3e..da145b67091c 100644 --- a/src/main/runtime/runtime-worktree-agent-rows.ts +++ b/src/main/runtime/runtime-worktree-agent-rows.ts @@ -61,7 +61,8 @@ export function attachRuntimeWorktreeAgentRows(args: { toolInput: source.toolInput, interrupted: source.interrupted, stateStartedAt: source.stateStartedAt, - updatedAt: source.updatedAt + updatedAt: source.updatedAt, + ...(source.structuredHost === 'owned' ? { structuredHostOwned: true as const } : {}) } const rows = rowsByWorktree.get(summary.worktreeId) if (rows) { @@ -80,15 +81,13 @@ export function attachRuntimeWorktreeAgentRows(args: { let hasForegroundWorkingAgent = false const monitoringSources: RuntimeWorktreeAgentSource[] = [] for (const row of rows) { - const source = rowSources.get(row.paneKey) - const hostHeldStructuredSession = - source?.authority === 'structured-host' && row.state !== 'done' - if (!hostHeldStructuredSession && !isFreshNonDoneAgentStatus(row, now)) { + if (!isFreshNonDoneAgentStatus(row, now)) { continue } summary.hasHostSidebarActivity = true if (row.state === 'working') { if (row.workingMode === 'monitoring') { + const source = rowSources.get(row.paneKey) if (source) { monitoringSources.push(source) } diff --git a/src/main/runtime/runtime-worktree-agent-source.ts b/src/main/runtime/runtime-worktree-agent-source.ts index 2e8bc833b239..984f20e09553 100644 --- a/src/main/runtime/runtime-worktree-agent-source.ts +++ b/src/main/runtime/runtime-worktree-agent-source.ts @@ -1,3 +1,4 @@ +import type { StructuredHostStatus } from '../../shared/agent-hook-listener/listener-event' import type { ParsedAgentStatusPayload } from '../../shared/agent-status-types' export type RuntimeWorktreeAgentSource = { @@ -16,6 +17,6 @@ export type RuntimeWorktreeAgentSource = { interrupted: boolean stateStartedAt: number updatedAt: number - /** Structured host projections remain authoritative after PTY freshness expiry. */ - authority?: 'structured-host' + /** Projected by the structured session host; `owned` rows stay fresh past the staleness window. */ + structuredHost?: StructuredHostStatus } diff --git a/src/main/runtime/runtime-worktree-agent-sources.ts b/src/main/runtime/runtime-worktree-agent-sources.ts index 44ce7848960c..9015b4bb0fb4 100644 --- a/src/main/runtime/runtime-worktree-agent-sources.ts +++ b/src/main/runtime/runtime-worktree-agent-sources.ts @@ -1,22 +1,13 @@ -import type { AgentSessionStatusSummary } from '../../shared/agent-session-wire' import { collectRuntimeWorktreePtyAgentSources } from './runtime-worktree-pty-agent-sources' -import { structuredRuntimeWorktreeAgentSources } from './runtime-worktree-structured-agent-rows' import type { RuntimeWorktreeAgentSource } from './runtime-worktree-agent-source' /** One admitted roster for row and worktree-status projection. */ export function collectRuntimeWorktreeAgentSources( - args: Parameters[0] & { - structuredSummaries: readonly AgentSessionStatusSummary[] - } + args: Parameters[0] ): ReadonlyMap { const sources = new Map() for (const source of collectRuntimeWorktreePtyAgentSources(args)) { sources.set(source.paneKey, source) } - for (const source of structuredRuntimeWorktreeAgentSources(args.structuredSummaries)) { - if (!sources.has(source.paneKey)) { - sources.set(source.paneKey, source) - } - } return sources } diff --git a/src/main/runtime/runtime-worktree-pty-agent-sources.ts b/src/main/runtime/runtime-worktree-pty-agent-sources.ts index 04e8dffc04e3..9f297d7edf7d 100644 --- a/src/main/runtime/runtime-worktree-pty-agent-sources.ts +++ b/src/main/runtime/runtime-worktree-pty-agent-sources.ts @@ -94,7 +94,11 @@ export function collectRuntimeWorktreePtyAgentSources(args: { toolInput: entry.toolInput ?? null, interrupted: entry.interrupted ?? false, stateStartedAt: entry.stateStartedAt, - updatedAt: entry.receivedAt + // A structured row's clock is its journal, so a restart's republish does not read as new. + updatedAt: entry.structuredHost + ? (entry.evidenceObservedAt ?? entry.receivedAt) + : entry.receivedAt, + ...(entry.structuredHost ? { structuredHost: entry.structuredHost } : {}) }) } const sources: RuntimeWorktreeAgentSource[] = [] @@ -104,7 +108,10 @@ export function collectRuntimeWorktreePtyAgentSources(args: { parsePaneKey(source.paneKey)?.tabId ?? parseLegacyNumericPaneKey(source.paneKey)?.tabId const mirroredWorktreeId = tabId ? args.mirroredWorktreeIdByTabId.get(tabId) : undefined + // Why a structured row skips the connected-process gate: it has no PTY, and the host that + // holds the session drops the row itself on close, so its presence is the liveness evidence. if ( + source.structuredHost === undefined && tabId !== undefined && mirroredWorktreeId === undefined && (source.connectionId === null || isWslHookRelayConnectionId(source.connectionId)) && diff --git a/src/main/runtime/runtime-worktree-structured-agent-rows-liveness.test.ts b/src/main/runtime/runtime-worktree-structured-agent-rows-liveness.test.ts index 063ee0b36cf6..519b9026f178 100644 --- a/src/main/runtime/runtime-worktree-structured-agent-rows-liveness.test.ts +++ b/src/main/runtime/runtime-worktree-structured-agent-rows-liveness.test.ts @@ -2,19 +2,27 @@ import { collectRuntimeWorktreeAgentSources } from './runtime-worktree-agent-sou import { mkdtemp, rm } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' -import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' import { StructuredAgentSessionStatusFeed } from '../native-chat/agent-session-wire/structured-agent-session-status-feed' import { createTrackedJournalOpener } from '../native-chat/agent-session-journal/journal-store-test-open' +import type { AgentSessionStatusSummary } from '../../shared/agent-session-wire' import type { RuntimeWorktreePsSummary } from '../../shared/runtime-types' +import { AgentHookServer, _internals } from '../agent-hooks/server' import { attachRuntimeWorktreeAgentRows } from './runtime-worktree-agent-rows' +vi.mock('../telemetry/client', () => ({ track: vi.fn() })) +vi.mock('../telemetry/cohort-classifier', () => ({ + getCohortAtEmit: vi.fn(() => ({ nth_repo_added: 2 })) +})) + /** - * The whole chain `worktree ps` walks: journal -> status feed -> agent rows -> worktree status. + * The whole chain `worktree ps` walks: journal -> status feed -> agent-status store -> agent rows + * -> worktree status. * - * The feed's `published` map never retracts, so reading it as a roster reports every session the - * app has ever opened. A closed chat that was waiting on an approval is the sharp edge: deliberate - * close does not settle a pending prompt, so the retained summary stays `attention`, which maps to - * a `blocked` row and merges the worktree to `permission` for the 30-minute freshness window. + * The feed's `published` map never retracts, so it cannot be the roster. A closed chat that was + * waiting on an approval is the sharp edge: deliberate close does not settle a pending prompt, so + * the retained summary stays `attention`, which maps to a `blocked` row and would merge the + * worktree to `permission`. The store is the roster: the host drops the row on close. */ const WORKTREE_ID = 'repo-1::/workspace/app' const SESSION = 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d' @@ -29,6 +37,7 @@ let root: string const journals = createTrackedJournalOpener() beforeEach(async () => { + _internals.resetCachesForTests() root = await mkdtemp(join(tmpdir(), 'orca-structured-ps-liveness-')) }) @@ -68,22 +77,32 @@ async function awaitingApproval() { const sessions = new Map([ [ SESSION, - { journal, params: { location: { workspaceId: WORKTREE_ID }, provider: 'codex' as const } } + { + journal, + hasProviderChild: true, + params: { location: { workspaceId: WORKTREE_ID }, provider: 'codex' as const } + } ] ]) + const store = new AgentHookServer() + const published: AgentSessionStatusSummary[] = [] const feed = new StructuredAgentSessionStatusFeed({ sessions, getRecord: () => null, - now: () => Date.now() + now: () => Date.now(), + statusSink: () => ({ + publish: (summary) => { + published.push(summary) + store.ingestStructuredStatus(summary) + }, + forget: (sessionId) => store.dropStructuredStatus(sessionId) + }) }) feed.publish(SESSION, journal) - return { feed, sessions } + return { feed, sessions, store, published } } -function worktreeFor( - feed: StructuredAgentSessionStatusFeed, - summaries = feed.liveSessionSummaries() -): RuntimeWorktreePsSummary { +function worktreeFor(store: AgentHookServer): RuntimeWorktreePsSummary { const row = { worktreeId: WORKTREE_ID, status: 'inactive', @@ -98,8 +117,7 @@ function worktreeFor( mirroredWorktreeIdByTabId: new Map(), connectedPtyEvidence: { tabIds: new Set(), paneKeys: new Set(), ptyIds: new Set() }, retainedSnapshots: [], - hookSnapshots: [], - structuredSummaries: summaries + hookSnapshots: store.getStatusSnapshot() }), orchestrationByPaneKey: null, getSummary: (map, _paths, _missing, id) => map.get(id) ?? null @@ -109,49 +127,62 @@ function worktreeFor( describe('worktree ps and a closed structured chat', () => { it('reports the blocked row while the session is still held', async () => { - const { feed } = await awaitingApproval() - const row = worktreeFor(feed) + const { store } = await awaitingApproval() + const row = worktreeFor(store) expect(row.agents).toHaveLength(1) expect(row.agents[0]?.state).toBe('blocked') expect(row.status).toBe('permission') }) - it('stops reporting it once eviction forgets the session', async () => { - const { feed, sessions } = await awaitingApproval() - // `forget-session`, the last eviction step, does exactly this and nothing to the feed. + it('stops reporting it once close forgets the session', async () => { + const { feed, sessions, store } = await awaitingApproval() + // What the host does after eviction: the feed keeps its projection, the store drops the row. sessions.delete(SESSION) + feed.close(SESSION) - const row = worktreeFor(feed) + const row = worktreeFor(store) expect(row.agents).toHaveLength(0) expect(row.status).toBe('inactive') }) it('keeps an aged host-held working state authoritative', async () => { - const { feed } = await awaitingApproval() - const aged = feed.liveSessionSummaries().map((summary) => ({ - ...summary, + const { store, published } = await awaitingApproval() + const aged = { + ...published.at(-1)!, hostExecutionOwned: true as const, updatedAt: Date.now() - 30 * 60 * 1000 - 1, status: 'working' as const - })) - const row = worktreeFor(feed, aged) + } + store.ingestStructuredStatus(aged) + const row = worktreeFor(store) expect(row.agents).toHaveLength(1) expect(row.agents[0]?.state).toBe('working') expect(row.status).toBe('working') - expect(row.agents[0]?.updatedAt).toBe(aged[0]?.updatedAt) + expect(row.agents[0]?.updatedAt).toBe(aged.updatedAt) }) it('keeps an aged host-held approval state authoritative', async () => { - const { feed } = await awaitingApproval() - const aged = feed.liveSessionSummaries().map((summary) => ({ - ...summary, + const { store, published } = await awaitingApproval() + const aged = { + ...published.at(-1)!, hostExecutionOwned: true as const, updatedAt: Date.now() - 30 * 60 * 1000 - 1 - })) - const row = worktreeFor(feed, aged) + } + store.ingestStructuredStatus(aged) + const row = worktreeFor(store) expect(row.agents).toHaveLength(1) expect(row.agents[0]?.state).toBe('blocked') expect(row.status).toBe('permission') - expect(row.agents[0]?.updatedAt).toBe(aged[0]?.updatedAt) + expect(row.agents[0]?.updatedAt).toBe(aged.updatedAt) + }) + + it('lets an aged approval decay once the host no longer owns the child', async () => { + const { store, published } = await awaitingApproval() + const { hostExecutionOwned: _owned, ...held } = published.at(-1)! + store.ingestStructuredStatus({ ...held, updatedAt: Date.now() - 30 * 60 * 1000 - 1 }) + const row = worktreeFor(store) + expect(row.agents).toHaveLength(1) + expect(row.agents[0]?.state).toBe('blocked') + expect(row.status).toBe('inactive') }) }) diff --git a/src/main/runtime/runtime-worktree-structured-agent-rows.ts b/src/main/runtime/runtime-worktree-structured-agent-rows.ts deleted file mode 100644 index c4d075fbd9c5..000000000000 --- a/src/main/runtime/runtime-worktree-structured-agent-rows.ts +++ /dev/null @@ -1,48 +0,0 @@ -import type { AgentSessionStatusSummary } from '../../shared/agent-session-wire' -import { - structuredAgentSessionPaneKey, - structuredAgentSessionStatusState, - structuredAgentSessionTabId -} from '../../shared/structured-agent-session-projection' -import type { RuntimeWorktreeAgentSource } from './runtime-worktree-agent-source' - -/** - * Row sources for the structured (non-PTY) sessions a host still holds. - * - * A structured session reaches none of the hook or retained snapshots every other row comes from, - * so `worktree ps` projects it from the host's status feed instead. The feed's retained - * projections are not a roster — the caller passes only sessions the host still holds. - */ -export function structuredRuntimeWorktreeAgentSources( - summaries: readonly AgentSessionStatusSummary[] -): RuntimeWorktreeAgentSource[] { - const sources: RuntimeWorktreeAgentSource[] = [] - for (const summary of summaries) { - // No turn has been persisted yet, so there is nothing to report - the same read the chat shows. - if (!summary.status) { - continue - } - const tabId = structuredAgentSessionTabId(summary.sessionId) - // The DERIVED pane key the renderer already publishes, never the orchestration bearer handle - // or the minted worker pane key: both of those are credentials. - sources.push({ - paneKey: structuredAgentSessionPaneKey(tabId, summary.sessionId), - tabId, - worktreeId: summary.workspaceId, - connectionId: null, - // The shared mapping the sidebar applies, so the CLI and the GUI cannot disagree about one - // session. No hook payload: nothing reads one off a structured row. - state: structuredAgentSessionStatusState(summary.status), - agentType: summary.agent, - prompt: summary.latestPrompt, - lastAssistantMessage: summary.lastAssistantMessage ?? null, - toolName: summary.toolName ?? null, - toolInput: summary.toolInput ?? null, - interrupted: false, - stateStartedAt: summary.updatedAt, - updatedAt: summary.updatedAt, - ...(summary.hostExecutionOwned ? { authority: 'structured-host' as const } : {}) - }) - } - return sources -} diff --git a/src/main/runtime/structured-agent-session-runtime.ts b/src/main/runtime/structured-agent-session-runtime.ts index d9b3e59186ab..36890dcc2874 100644 --- a/src/main/runtime/structured-agent-session-runtime.ts +++ b/src/main/runtime/structured-agent-session-runtime.ts @@ -82,6 +82,8 @@ export type StructuredAgentSessionRuntimeDeps = { /** Every structured-session status projection, for host-side reactions such as the first-work * workspace rename that CLI agents get from their hooks. */ onSessionStatusChanged?: StructuredAgentSessionHostDeps['onSessionStatusChanged'] + /** The agent-status store; see `StructuredAgentSessionHostDeps.statusSink`. */ + statusSink?: StructuredAgentSessionHostDeps['statusSink'] handoffTransport?: StructuredAgentSessionHandoffTransport reapOrphanChildren?: typeof stopOrphanAgentSessionChildren } @@ -298,6 +300,7 @@ async function install(deps: StructuredAgentSessionRuntimeDeps): Promise { await store.transitionHandoff(sessionId, (record) => recordAgentSessionProviderHandle({ record, fence: record.lease.runtimeFence, link, now }) diff --git a/src/main/startup/main-process-runtime-service.ts b/src/main/startup/main-process-runtime-service.ts index 1b7f69213adf..8af5630e02b1 100644 --- a/src/main/startup/main-process-runtime-service.ts +++ b/src/main/startup/main-process-runtime-service.ts @@ -87,6 +87,12 @@ export function initializeMainProcessRuntime(): OrcaRuntimeService { // Why: worktree.ps pulls hook-reported agent status (same source as the desktop sidebar) at query time so mobile shows the same agents. getAgentStatusSnapshot: () => agentHookServer.getStatusSnapshot().filter((entry) => entry.providerSessionOnly !== true), + // Why: structured chats have no hooks, so the host writes their projections here itself; the + // snapshot above then lists them for the CLI and mobile without a second store. + structuredAgentStatusSink: { + publish: (summary) => agentHookServer.ingestStructuredStatus(summary), + forget: (sessionId) => agentHookServer.dropStructuredStatus(sessionId) + }, // Why captured rather than resolved at read: the fleet snapshot remints cached rows on every // read, so a row observed under one process otherwise acquires whatever the pane owns now. readObservedAgentStatusPaneIdentity: (paneKey) => observedPaneIdentities.read(paneKey), diff --git a/src/main/startup/main-window-agent-status.ts b/src/main/startup/main-window-agent-status.ts index 3b2ba9cbd714..0f10a373bf97 100644 --- a/src/main/startup/main-window-agent-status.ts +++ b/src/main/startup/main-window-agent-status.ts @@ -43,11 +43,17 @@ export function installMainWindowAgentStatusListeners(options: MainWindowAgentSt promptInteractionKey, restoredUnconfirmed, observation, - isReplay + isReplay, + structuredHost }) => { if (state.mainWindow?.isDestroyed()) { return } + // Why: the renderer still derives structured rows from its own feed subscription; forwarding + // these too would give one pane key two writers until that bridge is retired. + if (structuredHost) { + return + } if (providerSessionOnly) { // Why: session_start just refreshes durable resume identity while Pi is idle; forward it without titles, telemetry, or status UI. state.mainWindow?.webContents.send('agentStatus:set', { diff --git a/src/shared/agent-hook-listener/listener-event.ts b/src/shared/agent-hook-listener/listener-event.ts index 3dd8291d6738..9bca14cc857e 100644 --- a/src/shared/agent-hook-listener/listener-event.ts +++ b/src/shared/agent-hook-listener/listener-event.ts @@ -41,8 +41,13 @@ export type AgentHookEventPayload = { isReplay?: boolean /** Transport-only Claude background-work evidence used to reject false input-based interrupts. */ claudeRunningNonAgentTask?: boolean + /** Row projected from a structured session the host holds: `owned` while its provider child + * runs here, `held` once the child is gone but the session is still open. Never persisted. */ + structuredHost?: StructuredHostStatus payload: ParsedAgentStatusPayload } + +export type StructuredHostStatus = 'held' | 'owned' export type ToolSnapshot = { toolName?: string toolInput?: string diff --git a/src/shared/agent-status-ipc-payload.ts b/src/shared/agent-status-ipc-payload.ts index 09d8eb284ac5..5c462f5afe2a 100644 --- a/src/shared/agent-status-ipc-payload.ts +++ b/src/shared/agent-status-ipc-payload.ts @@ -3,6 +3,7 @@ // (states, entries, normalization) and the transport envelopes live next to each // other. Re-exported from agent-status-types, so existing import sites are unchanged. +import type { StructuredHostStatus } from './agent-hook-listener/listener-event' import type { AgentProviderSessionMetadata } from './agent-session-resume' import type { WithAgentStatusObservation } from './agent-status-observation' import type { @@ -49,6 +50,9 @@ export type AgentStatusIpcPayload = ParsedAgentStatusPayload & { promptInteractionKey?: string /** See AgentStatusEntry.restoredUnconfirmed — hydrated nonterminal provenance. */ restoredUnconfirmed?: boolean + /** Present on rows the structured session host projects; `owned` keeps them fresh past the + * staleness window because the host still runs the provider child. */ + structuredHost?: StructuredHostStatus } & WithAgentStatusObservation /** Identity used by UI-only cleanup to evict exactly the status it cleared. diff --git a/src/shared/agent-status-observation.ts b/src/shared/agent-status-observation.ts index 2b3064aca296..b106e43fe63d 100644 --- a/src/shared/agent-status-observation.ts +++ b/src/shared/agent-status-observation.ts @@ -21,7 +21,9 @@ export const AGENT_STATUS_OBSERVATION_ORIGINS = [ /** Seeded when Orca launched the agent itself, before any provider signal. */ 'launch', /** Stamped by orchestration dispatch rather than by the agent. */ - 'orchestration' + 'orchestration', + /** Projected by the structured session host from a session's journal; no PTY, no hook. */ + 'structured' ] as const export type AgentStatusObservationOrigin = (typeof AGENT_STATUS_OBSERVATION_ORIGINS)[number] diff --git a/src/shared/runtime-worktree-contracts.ts b/src/shared/runtime-worktree-contracts.ts index df0d4c687421..c56bc3a17e6f 100644 --- a/src/shared/runtime-worktree-contracts.ts +++ b/src/shared/runtime-worktree-contracts.ts @@ -25,6 +25,9 @@ export type RuntimeWorktreeAgentRow = { stateStartedAt: number updatedAt: number restoredUnconfirmed?: boolean + /** The structured session host still runs this row's provider child, so it is fresh regardless + * of age. Optional on the wire: old hosts never send it. */ + structuredHostOwned?: true } export type RuntimeWorktreePsSummary = { From 79fdccf66d2d7821709af0657d749fc7c5cf74fa Mon Sep 17 00:00:00 2001 From: Merge Sim Date: Tue, 8 Sep 2026 22:53:38 -0700 Subject: [PATCH 2/9] chore: drop stray @pnpm/exe lockfile entry An unrelated local pnpm run added @pnpm/exe as a packageManagerDependency with no package.json change, so CI's --frozen-lockfile install failed before any job ran. --- pnpm-lock.yaml | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index baf05a740844..7add63b397bc 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -6,9 +6,6 @@ importers: .: configDependencies: {} packageManagerDependencies: - '@pnpm/exe': - specifier: 12.0.0 - version: 12.0.0 pnpm: specifier: 12.0.0 version: 12.0.0 @@ -59,11 +56,6 @@ packages: cpu: [x64] os: [win32] - '@pnpm/exe@12.0.0': - resolution: {integrity: sha512-405vw2qYPPghNxoPRt2cvkGtGNU5gnInDcIe5TztQxe73yUZLqFJN/jCJFGs1xbVaIWDXEVuQ71P8npFZeatZQ==} - engines: {node: '>=18.*'} - hasBin: true - pnpm@12.0.0: resolution: {integrity: sha512-ni49w5EZlYaNyUuBdcIXwn6VQI+gO0oidJd48rNPdzt3zdOznt6BcbIvzVO+ajU0Lp+smUimjvWN9kiM6Jp+Zw==} engines: {node: '>=18.*'} @@ -95,17 +87,6 @@ snapshots: '@pnpm/exe.win32-x64@12.0.0': optional: true - '@pnpm/exe@12.0.0': - optionalDependencies: - '@pnpm/exe.darwin-arm64': 12.0.0 - '@pnpm/exe.darwin-x64': 12.0.0 - '@pnpm/exe.linux-arm64': 12.0.0 - '@pnpm/exe.linux-arm64-musl': 12.0.0 - '@pnpm/exe.linux-x64': 12.0.0 - '@pnpm/exe.linux-x64-musl': 12.0.0 - '@pnpm/exe.win32-arm64': 12.0.0 - '@pnpm/exe.win32-x64': 12.0.0 - pnpm@12.0.0: optionalDependencies: '@pnpm/exe.darwin-arm64': 12.0.0 From 9141524f8faad9af1fbed60deceda1d01093343a Mon Sep 17 00:00:00 2001 From: Merge Sim Date: Tue, 8 Sep 2026 23:06:53 -0700 Subject: [PATCH 3/9] docs(agent-status): describe the step that actually landed The design record claimed PR 1 deletes RuntimeAgentRowStore, drops the retained-versus-hook reconciliation, stamps terminalHandle on OSC rows, and tags rows with a source field of 'structured-host'. None of that is true of the shipped code: the retained store and its reconciliation are still in place, and the row field is structuredHost: 'held' | 'owned'. AGENTS.md points every future contributor here before they touch agent status, so split the roadmap into the 1a that landed and the 1b that has not, and name the fields the code actually writes. --- docs/reference/agent-status-store.md | 71 +++++++++++++++------------- 1 file changed, 39 insertions(+), 32 deletions(-) diff --git a/docs/reference/agent-status-store.md b/docs/reference/agent-status-store.md index f202b4fe3335..74e9a21f0677 100644 --- a/docs/reference/agent-status-store.md +++ b/docs/reference/agent-status-store.md @@ -2,14 +2,17 @@ ## Status -Proposed on 2026-09-09 as the follow-up to #19217. It lands in three PRs, in +Proposed on 2026-09-09 as the follow-up to #19217. It lands in four steps, in this order, each independently shippable: -1. main-only: every producer writes into one store and `worktree ps` reads it; +1. main-only: every producer writes into one store and `worktree ps` reads it, + split into 1a (structured sessions join the store) and 1b (the runtime's + duplicate retained store is deleted); 2. renderer: the sidebar becomes a subscriber and stops re-deriving rows; 3. shared: one worktree-status rollup and one freshness rule for every reader. -The PR that carries this document is PR 1. +The PR that carries this document is PR 1a. Sections below are grouped under +the step that delivers them; only PR 1a has landed. ## The problem this solves @@ -78,7 +81,7 @@ with them would be the wrong direction. So the design is not "add a store". It is: **route the two producers that bypass the hook server through it, then delete the copies.** -## PR 1: main only +## PR 1a: structured sessions publish into the store No renderer behavior changes. The sidebar keeps receiving the same IPC events it receives today, plus structured-session rows it currently derives itself. @@ -95,8 +98,7 @@ ingests the summary into the hook server as a status row: | `tabId` | `structuredAgentSessionTabId(sessionId)` | | `worktreeId` | `summary.workspaceId` (a folder workspace id is a valid value) | | `state` | `structuredAgentSessionStatusState(summary.status)`, the mapping #19217 shared | -| `source` | `'structured-host'` | -| `structuredHostOwned` | present while `summary.hostExecutionOwned` is present | +| `structuredHost` | `'owned'` while `summary.hostExecutionOwned` is set, otherwise `'held'`; `worktree ps` derives its row's `structuredHostOwned` from it | | prompt, tool, last message, model, provider session | the summary's fields | Sessions with no persisted turn (`status === null`) produce no row, matching @@ -110,7 +112,8 @@ Two rules the ingest must keep: - **Never persist a structured row.** The journal is the durable truth for a structured session and the host republishes on restore. A structured row in `last-status.json` would hydrate as `restoredUnconfirmed` and then fight the - live republish. The serializer skips rows whose source is `structured-host`. + live republish. The serializer skips rows carrying `structuredHost`, and + hydrate drops any such row found on disk. - **Never let it fight a hook row.** A structured session has no PTY, so no hook or OSC event carries its pane key. The ingest still goes through the disposition gate so a retired pane key is refused like any other. @@ -118,33 +121,17 @@ Two rules the ingest must keep: The ingest lives in the feed, not in `structured-agent-session-host.ts`, which sits at the file-length cap. -### The runtime's retained row store is deleted - -`RuntimeAgentRowStore` keeps the same payload the hook server already holds. -Its only extra is the pty id, used to clear rows on exit and as a fallback key -for the mobile projection. PR 1 stamps `terminalHandle` on OSC-ingested rows -from the runtime event's `ptyId`, and rewrites the three readers over the hook -server's snapshot: - -- `worktree ps` reads `getStatusSnapshot()` directly; -- `getFreshExplicit` already consults hook rows; it drops the retained input; -- `getFreshForMobile` matches on pane key, then on `terminalHandle`. - -One behavior change follows and is intended: a row the user dismisses on the -desktop disappears from `worktree ps` and the phone at the same time, instead -of lingering until the pty exits. - ### `worktree ps` becomes a reader -`collectRuntimeWorktreePtyAgentSources` loses its retained-versus-hook -reconciliation, because there is one row per pane. The structured adapter -added in #19217 is deleted. What remains is one adapter from the store's -snapshot to `RuntimeWorktreeAgentSource`, plus the admission gate that decides -which rows a worktree listing may show: +The structured adapter added in #19217 is deleted, and structured rows reach +`worktree ps` through the same snapshot as every other row. The +retained-versus-hook reconciliation in `collectRuntimeWorktreePtyAgentSources` +stays until PR 1b removes the store that feeds it. What this step settles is +the admission gate that decides which rows a worktree listing may show: - a hook or OSC row needs its tab mirrored or a connected pty, as today, and SSH rows stay exempt because their tabs may exist only remotely; -- a `structured-host` row is admitted while the host holds the session, and +- a row carrying `structuredHost` is admitted while the host holds the session, and the host's drop on close is what removes it; no tab-mirror requirement, because headless serve has no renderer to mirror tabs from. @@ -165,6 +152,25 @@ over `agentStatus:set` or `agentStatus:getSnapshot`. The renderer's feed bridge still writes those rows itself, and forwarding them too would give one pane key two writers. Removing that filter is the first step of PR 2. +## PR 1b: the runtime's retained row store is deleted + +Not yet implemented; `RuntimeAgentRowStore` and the retained-versus-hook +reconciliation it feeds are both still in place after PR 1a. + +`RuntimeAgentRowStore` keeps the same payload the hook server already holds. +Its only extra is the pty id, used to clear rows on exit and as a fallback key +for the mobile projection. PR 1b will stamp `terminalHandle` on OSC-ingested +rows from the runtime event's `ptyId`, and rewrite the three readers over the +hook server's snapshot: + +- `worktree ps` reads `getStatusSnapshot()` directly; +- `getFreshExplicit` already consults hook rows; it drops the retained input; +- `getFreshForMobile` matches on pane key, then on `terminalHandle`. + +One behavior change will follow and is intended: a row the user dismisses on +the desktop disappears from `worktree ps` and the phone at the same time, +instead of lingering until the pty exits. + ## PR 2: the renderer subscribes With structured rows arriving over `agentStatus:set`, the renderer's @@ -208,9 +214,10 @@ call it. - Unit: ingest a structured summary and read it back through `getStatusSnapshot`, `worktree ps`, and the mobile projection; assert the - serializer never writes a `structured-host` row; assert a hydrated file that - somehow contains one is dropped. + serializer never writes a row carrying `structuredHost`; assert a hydrated + file that somehow contains one is dropped. - Unit: the existing `worktree ps` suites pass unchanged, which is the - characterization that deleting the retained store changed no listing. + characterization that will show PR 1b's deletion of the retained store + changed no listing. - Live: the parity check from #19217 (working, done, close, reload) repeated against the merged store, with both surfaces read from the one row. From 201b34926422d550cd8a10cd95b4c9db23fd5acc Mon Sep 17 00:00:00 2001 From: Merge Sim Date: Tue, 8 Sep 2026 23:45:20 -0700 Subject: [PATCH 4/9] fix(agent-status): pair session removal with the status-row forget A session dropped from the host's map without an explicit forget left its row in the store forever: `structuredHostOwned` bypasses the staleness check, so a failed re-attach (the Claude rewind path reaches one) stranded a permanently working agent in `worktree ps` and on mobile with no UI able to clear it. Deletion and forget are now one operation both callers route through. --- ...structured-agent-session-attach-context.ts | 3 + ...ured-agent-session-attach-orchestration.ts | 4 +- ...ructured-agent-session-close-retry.test.ts | 3 +- ...ctured-agent-session-forget-status.test.ts | 162 ++++++++++++++++++ .../structured-agent-session-host-lifetime.ts | 18 +- .../structured-agent-session-host.ts | 3 +- 6 files changed, 185 insertions(+), 8 deletions(-) create mode 100644 src/main/native-chat/agent-session-wire/structured-agent-session-forget-status.test.ts diff --git a/src/main/native-chat/agent-session-wire/structured-agent-session-attach-context.ts b/src/main/native-chat/agent-session-wire/structured-agent-session-attach-context.ts index 986fcefadbfe..4b9b46716cb2 100644 --- a/src/main/native-chat/agent-session-wire/structured-agent-session-attach-context.ts +++ b/src/main/native-chat/agent-session-wire/structured-agent-session-attach-context.ts @@ -38,5 +38,8 @@ export type StructuredAgentSessionAttachContext = { reconcileLeases: (sessionId: string) => Promise serialize: (sessionId: string, task: () => Promise) => Promise now: () => number + /** Paired with `sessions.delete` by `forgetStructuredAgentSession`; a failed attach that only + * deleted would leave the store's row behind. */ + forgetStatus: (sessionId: string) => void publishStatus?: (sessionId: string) => void } diff --git a/src/main/native-chat/agent-session-wire/structured-agent-session-attach-orchestration.ts b/src/main/native-chat/agent-session-wire/structured-agent-session-attach-orchestration.ts index 3a58d71b625e..6ef39c853726 100644 --- a/src/main/native-chat/agent-session-wire/structured-agent-session-attach-orchestration.ts +++ b/src/main/native-chat/agent-session-wire/structured-agent-session-attach-orchestration.ts @@ -23,6 +23,7 @@ import { import { refuseAgentSessionMutation } from './structured-agent-session-mutation-admission' import { retryPendingStructuredAgentSessionSettlement } from './structured-agent-session-settlement-retry' import type { StructuredAgentSessionAttachContext } from './structured-agent-session-attach-context' +import { forgetStructuredAgentSession } from './structured-agent-session-host-lifetime' import type { DeferredStructuredAgentSessionEventSink } from './structured-agent-session-event-sink' import { agentSessionJournalCloseRetries } from '../agent-session-journal/journal-close-retry' import type { AgentSessionJournal } from '../agent-session-journal/journal-store' @@ -90,8 +91,7 @@ export function attachStructuredAgentSession( // Site 9: this closes the PRIOR map entry it drops, never the provisional // journal — it has no reference to that one. `onAttached` owns that. onAttachFailed: async () => { - await context.sessions.get(sessionId)?.journal.close() - context.sessions.delete(sessionId) + await forgetStructuredAgentSession(context, sessionId) eventSink.close() context.runtimeState.discardEventSink(sessionId) }, diff --git a/src/main/native-chat/agent-session-wire/structured-agent-session-close-retry.test.ts b/src/main/native-chat/agent-session-wire/structured-agent-session-close-retry.test.ts index a4666b4f045e..b79091c7f9fa 100644 --- a/src/main/native-chat/agent-session-wire/structured-agent-session-close-retry.test.ts +++ b/src/main/native-chat/agent-session-wire/structured-agent-session-close-retry.test.ts @@ -131,7 +131,8 @@ function attachContext( tasks: { trackAttach: (task: Promise) => task }, reconcileLeases: async () => null, serialize: (_sessionId: string, task: () => Promise) => task(), - now: () => 1 + now: () => 1, + forgetStatus: () => undefined } as unknown as StructuredAgentSessionAttachContext } diff --git a/src/main/native-chat/agent-session-wire/structured-agent-session-forget-status.test.ts b/src/main/native-chat/agent-session-wire/structured-agent-session-forget-status.test.ts new file mode 100644 index 000000000000..d74a729dc2ff --- /dev/null +++ b/src/main/native-chat/agent-session-wire/structured-agent-session-forget-status.test.ts @@ -0,0 +1,162 @@ +// Removing a session from the host's map and removing its status row are ONE operation. +// +// The store keeps a row until told to drop it, and `structuredHostOwned` bypasses the staleness +// check in `agent-status-freshness.ts` — so a deletion path that skipped the forget leaves a +// permanently `working` agent in `worktree ps` and on mobile, with no UI able to clear it. +// +// This drives the real orchestration closure for the failed attach, against the real store. + +import { mkdtemp, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import type { AgentSessionJournalIdentity } from '../../../shared/agent-session-journal-types' +import { AgentHookServer } from '../../agent-hooks/server' +import type { AgentSessionJournal } from '../agent-session-journal/journal-store' +import { createTrackedJournalOpener } from '../agent-session-journal/journal-store-test-open' +import { attachStructuredAgentSession } from './structured-agent-session-attach-orchestration' +import type { StructuredAgentSessionAttachContext } from './structured-agent-session-attach-context' +import type { StructuredAgentSessionHostSession } from './structured-agent-session-host-types' +import { StructuredAgentSessionStatusFeed } from './structured-agent-session-status-feed' + +// Everything before the journal is out of scope here; what matters is that the orchestration's +// own `onAttachFailed` runs, which is the real one. +vi.mock('./structured-agent-session-attach-flow', () => ({ + performAttach: async (input: { onAttachFailed?: () => Promise }) => { + await input.onAttachFailed?.() + throw new Error('attach failed after acquisition') + } +})) + +const SESSION = '019fd532-7c11-7a90-b6de-4e1a2c3d5f60' +const TURN = { provider: 'codex', threadId: 'thread-1', turnId: 'turn-1', ordinal: 0 } as const +const PROMPT = { ...TURN, ordinal: 1 } + +const IDENTITY: AgentSessionJournalIdentity = { + sessionId: SESSION, + workspaceId: 'repo-1::/workspace/app', + hostId: 'host-1', + agent: 'codex', + providerHandle: { kind: 'codex', threadId: SESSION } +} + +let root: string +const journals = createTrackedJournalOpener() + +beforeEach(async () => { + root = await mkdtemp(join(tmpdir(), 'orca-forget-status-')) +}) + +afterEach(async () => { + await journals.closeAll() + await rm(root, { recursive: true, force: true }) +}) + +/** A session the store already lists as a host-owned working agent. */ +async function workingSession(): Promise<{ + server: AgentHookServer + feed: StructuredAgentSessionStatusFeed + sessions: Map + journal: AgentSessionJournal +}> { + const journal = await journals.open({ identity: IDENTITY, journalDir: join(root, SESSION) }) + await journal.appendItem( + PROMPT, + { kind: 'message', role: 'user', blocks: [{ type: 'text', text: 'ship it' }] }, + { fence: 1 } + ) + await journal.appendItem( + TURN, + { kind: 'status', text: 'Working', turnLifecycle: { turnId: 'turn-1', state: 'running' } }, + { fence: 1 } + ) + const sessions = new Map([ + [ + SESSION, + { + journal, + params: { location: { workspaceId: IDENTITY.workspaceId }, provider: 'codex' }, + fence: 1, + hasProviderChild: true, + acquisitionGeneration: null + } as unknown as StructuredAgentSessionHostSession + ] + ]) + const server = new AgentHookServer() + const feed = new StructuredAgentSessionStatusFeed({ + sessions, + getRecord: () => null, + now: () => 1, + statusSink: () => ({ + publish: (summary) => server.ingestStructuredStatus(summary), + forget: (sessionId) => server.dropStructuredStatus(sessionId) + }) + }) + feed.publish(SESSION, journal) + expect(server.getStatusSnapshot()).toEqual([ + expect.objectContaining({ state: 'working', structuredHost: 'owned' }) + ]) + return { server, feed, sessions, journal } +} + +function attachContext( + sessions: Map, + feed: StructuredAgentSessionStatusFeed +): StructuredAgentSessionAttachContext { + const eventSink = { + sink: {}, + drained: async () => ({ ok: true }) as const, + unbind: () => undefined, + bind: () => undefined, + close: () => undefined + } + return { + deps: { store: { getRecord: () => null }, claimKeyId: 'key-1', journalRoot: root }, + runtimeState: { + resolveRecovery: async () => undefined, + eventSinkFor: () => eventSink, + probeOwner: async () => ({ outcome: 'pid-absent' }), + discardEventSink: () => undefined + }, + sessions, + subscribers: { reset: () => undefined, snapshot: () => undefined, publish: () => undefined }, + tasks: { trackAttach: (task: Promise) => task }, + reconcileLeases: async () => null, + serialize: (_sessionId: string, task: () => Promise) => task(), + now: () => 1, + forgetStatus: (sessionId: string) => feed.forget(sessionId) + } as unknown as StructuredAgentSessionAttachContext +} + +const attachParams = { + envelope: { sessionId: SESSION, clientOperationId: 'op-1' } +} as unknown as Parameters[2] + +describe('a session that leaves the host without an explicit close', () => { + it('leaves the agent-status store with it when an attach fails', async () => { + const { server, feed, sessions } = await workingSession() + + await expect( + attachStructuredAgentSession(attachContext(sessions, feed), 'caller-1', attachParams) + ).rejects.toThrow('attach failed after acquisition') + + expect(sessions.has(SESSION)).toBe(false) + expect(server.getStatusSnapshot()).toEqual([]) + }) + + // The feed's own cache deliberately retains the projection for reload history; only the store + // is a roster, which is why the forget has to be explicit rather than derived from the cache. + it('keeps the projection a reloading renderer still needs', async () => { + const { feed, sessions } = await workingSession() + + await expect( + attachStructuredAgentSession(attachContext(sessions, feed), 'caller-1', attachParams) + ).rejects.toThrow('attach failed after acquisition') + + const events: unknown[] = [] + feed.subscribe({ id: 'list-late', emit: (event) => events.push(event) }) + expect(events).toEqual([ + { type: 'snapshot', sessions: [expect.objectContaining({ sessionId: SESSION })] } + ]) + }) +}) diff --git a/src/main/native-chat/agent-session-wire/structured-agent-session-host-lifetime.ts b/src/main/native-chat/agent-session-wire/structured-agent-session-host-lifetime.ts index d1664bc985b3..e2f75297a5a2 100644 --- a/src/main/native-chat/agent-session-wire/structured-agent-session-host-lifetime.ts +++ b/src/main/native-chat/agent-session-wire/structured-agent-session-host-lifetime.ts @@ -27,6 +27,19 @@ export type StructuredAgentSessionLifetimeContext = { runtimeState: StructuredAgentSessionHostRuntimeState sessions: Map now: () => number + /** Drops the session's row from the agent-status store; see `forgetStructuredAgentSession`. */ + forgetStatus: (sessionId: string) => void +} + +/** Dropping a session and dropping its status row are ONE operation: the store keeps the row until + * told, so a caller that only deletes strands a live-looking row no reader can ever decay. */ +export async function forgetStructuredAgentSession( + context: StructuredAgentSessionLifetimeContext, + sessionId: string +): Promise { + await context.sessions.get(sessionId)?.journal.close() + context.sessions.delete(sessionId) + context.forgetStatus(sessionId) } function hasProviderChild( @@ -50,10 +63,7 @@ export async function evictHeldStructuredAgentSession( hasProviderChild: hasProviderChild(context, sessionId), eventSink: context.runtimeState.eventSinkFor(sessionId), adapter: context.deps.adapter, - forget: async () => { - await context.sessions.get(sessionId)?.journal.close() - context.sessions.delete(sessionId) - }, + forget: () => forgetStructuredAgentSession(context, sessionId), discardSink: () => context.runtimeState.discardEventSink(sessionId), releaseLease: () => releaseStoredStructuredAgentSessionOwner({ diff --git a/src/main/native-chat/agent-session-wire/structured-agent-session-host.ts b/src/main/native-chat/agent-session-wire/structured-agent-session-host.ts index e20a636ae184..e41c738d01d2 100644 --- a/src/main/native-chat/agent-session-wire/structured-agent-session-host.ts +++ b/src/main/native-chat/agent-session-wire/structured-agent-session-host.ts @@ -180,7 +180,8 @@ export class StructuredAgentSessionHost { deps: this.deps, runtimeState: this.runtimeState, sessions: this.sessions, - now: () => this.now() + now: () => this.now(), + forgetStatus: (sessionId) => this.statusFeed.forget(sessionId) } } From 7d4739cb130798a6664fecbb3dc83af8517b49a1 Mon Sep 17 00:00:00 2001 From: Merge Sim Date: Tue, 8 Sep 2026 23:45:30 -0700 Subject: [PATCH 5/9] fix(agent-status): give orcad the store worktree ps reads from `orcad` constructed its runtime with neither `getAgentStatusSnapshot` nor `structuredAgentStatusSink`, so once `worktree ps` sourced rows only from that snapshot the headless host published nowhere and listed nothing. The hook server's store is a module singleton whose import tree never reaches Electron, and its file paths come from `start()`, which orcad never calls. --- src/main/orcad/orcad-entry.ts | 13 ++++- ...time-structured-status-sink-wiring.test.ts | 49 +++++++++++++++++++ 2 files changed, 61 insertions(+), 1 deletion(-) diff --git a/src/main/orcad/orcad-entry.ts b/src/main/orcad/orcad-entry.ts index 3b10ca985e9a..65d1b712051e 100644 --- a/src/main/orcad/orcad-entry.ts +++ b/src/main/orcad/orcad-entry.ts @@ -146,6 +146,9 @@ async function startOrcadRuntime( const { startOrcadDaemon, stopOrcadDaemon } = await import('./orcad-daemon-supervision') const { daemonOwnsFreshPersistentPtys } = await import('../daemon/daemon-init') const { collectOrcadHealth } = await import('./orcad-health') + // Why importable here: the store is an in-memory singleton whose module tree never reaches + // Electron, and its file paths come from `start()`, which orcad never calls. + const { agentHookServer } = await import('../agent-hooks/server') const runtimeUserDataPath = getAppEnvironment().getPath('userData') initOrcaProfilePaths() @@ -180,7 +183,15 @@ async function startOrcadRuntime( // Why 'blocked': `'openable'` means a desktop window can be opened here, which is // what powers serve→desktop promotion. A Node host can never do that, and the // constructor's default would advertise it. - getDesktopWindowStatus: () => 'blocked' + getDesktopWindowStatus: () => 'blocked', + // Why here too and not only on the desktop: orcad serves `worktree.ps` and `agentSession.*`, + // so without these a headless host publishes its structured chats nowhere and lists no agents. + getAgentStatusSnapshot: () => + agentHookServer.getStatusSnapshot().filter((entry) => entry.providerSessionOnly !== true), + structuredAgentStatusSink: { + publish: (summary) => agentHookServer.ingestStructuredStatus(summary), + forget: (sessionId) => agentHookServer.dropStructuredStatus(sessionId) + } }) // Why the headless entry point rather than registerPtyHandlers directly: this is the diff --git a/src/main/runtime/orca-runtime-structured-status-sink-wiring.test.ts b/src/main/runtime/orca-runtime-structured-status-sink-wiring.test.ts index baf0e4c27dd5..decaa5cc5994 100644 --- a/src/main/runtime/orca-runtime-structured-status-sink-wiring.test.ts +++ b/src/main/runtime/orca-runtime-structured-status-sink-wiring.test.ts @@ -15,12 +15,61 @@ vi.mock('./structured-agent-session-runtime', () => ({ }) })) +import { readFileSync } from 'node:fs' +import { join } from 'node:path' import { OrcaRuntimeService } from './orca-runtime' import type { StructuredAgentSessionStatusSink } from '../native-chat/agent-session-wire/structured-agent-session-status-feed' +type OrcaRuntimeDeps = NonNullable[2]> + +/** Renaming either option reddens this list, and dropping either from a host's construction + * reddens the assertion below. Both are needed: the runtime class does not typecheck its own + * `this` calls, and each entry point wires the store separately. */ +const AGENT_STATUS_STORE_DEPS = [ + 'getAgentStatusSnapshot', + 'structuredAgentStatusSink' +] as const satisfies readonly (keyof OrcaRuntimeDeps)[] + +const MAIN_ROOT = join(import.meta.dirname, '..') + +/** The text of the `new OrcaRuntimeService(...)` call in one entry point. */ +function runtimeConstruction(relativePath: string): string { + const source = readFileSync(join(MAIN_ROOT, relativePath), 'utf8') + const start = source.indexOf('new OrcaRuntimeService(') + expect(start).toBeGreaterThanOrEqual(0) + let depth = 0 + for (let index = source.indexOf('(', start); index < source.length; index += 1) { + const character = source[index] + if (character === '(') { + depth += 1 + } else if (character === ')') { + depth -= 1 + if (depth === 0) { + return source.slice(start, index + 1) + } + } + } + throw new Error(`unbalanced OrcaRuntimeService construction in ${relativePath}`) +} + /** The runtime class this wiring lives on does not typecheck its own `this` calls, so a misnamed * field here would install a host that never writes to the agent-status store — and every reader * of that store would simply list no structured sessions. Pin it behaviourally. */ +/** `worktree ps` reads structured rows only from the agent-status store, so an entry point that + * constructs a runtime without these lists no agents at all — and `orcad` serves `worktree.ps` + * and `agentSession.*` exactly like the desktop does. */ +describe('every host that constructs a runtime wires the agent-status store', () => { + it.each([['orcad/orcad-entry.ts'], ['startup/main-process-runtime-service.ts']])( + '%s passes both store deps', + (relativePath) => { + const construction = runtimeConstruction(relativePath) + for (const dep of AGENT_STATUS_STORE_DEPS) { + expect(construction).toContain(`${dep}:`) + } + } + ) +}) + describe('structured status sink wiring', () => { it('hands the host the sink the runtime was constructed with', async () => { installed.deps = null From 5d4e3f4319508a3c09800da1a41a1e07b47d47c9 Mon Sep 17 00:00:00 2001 From: Merge Sim Date: Tue, 8 Sep 2026 23:45:38 -0700 Subject: [PATCH 6/9] fix(agent-status): drop a structured row without a renderer clear `dropStructuredStatus` went through `clearPaneState`, which fans a pane clear out to the renderer for a pane key the renderer's own feed bridge still writes - so 'exactly one writer per pane key' held for writes and not for deletes. `dropStatusEntry` routes through the status-drop tap instead, and skips the resume-identity remnant: a structured session has no pane to resume into, and every null-status publish would otherwise re-mint one. --- src/main/agent-hooks/server/server-cleanup.ts | 10 ++++++++-- .../agent-hooks/server/server-ingest-structured.ts | 8 ++++++-- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/src/main/agent-hooks/server/server-cleanup.ts b/src/main/agent-hooks/server/server-cleanup.ts index 4fcd0b5e58e3..d7669c7449fe 100644 --- a/src/main/agent-hooks/server/server-cleanup.ts +++ b/src/main/agent-hooks/server/server-cleanup.ts @@ -22,12 +22,18 @@ export abstract class AgentHookServerCleanup extends AgentHookServerAuthorityFen } /** Drop only the status row (user dismissal); do NOT wipe prompt/tool caches since the pane's agent may still be alive. Use clearPaneState for PTY-teardown. */ - dropStatusEntry(paneKey: string): void { + dropStatusEntry( + paneKey: string, + /** Defaults to true: a dismissed pane can still be resumed in place. A structured session has + * no pane to resume into and its record store owns resume identity, so it passes false. */ + options?: { preserveResumeIdentity?: boolean } + ): void { const deleted = this.deleteStatusEntry(paneKey, { preserveAuthority: true }) if (!deleted) { return } - const retained = this.toRetainedProviderSessionRow(deleted) + const retained = + options?.preserveResumeIdentity === false ? null : this.toRetainedProviderSessionRow(deleted) if (retained) { this.state.lastStatusByPaneKey.set(deleted.paneKey, retained) } diff --git a/src/main/agent-hooks/server/server-ingest-structured.ts b/src/main/agent-hooks/server/server-ingest-structured.ts index 81555dea3b74..45b0e5c0015d 100644 --- a/src/main/agent-hooks/server/server-ingest-structured.ts +++ b/src/main/agent-hooks/server/server-ingest-structured.ts @@ -51,12 +51,16 @@ export abstract class AgentHookServerIngestStructured extends AgentHookServerIng ) } - /** The host no longer holds the session; its last projection is history the journal keeps. */ + /** The host no longer holds the session; its last projection is history the journal keeps. + * `dropStatusEntry`, not `clearPaneState`: the renderer's own bridge still owns this pane key, + * so a pane-status-clear would make main a second writer for it. */ dropStructuredStatus(sessionId: string): void { - this.clearPaneState(structuredStatusPaneKey(sessionId)) + this.dropStatusEntry(structuredStatusPaneKey(sessionId), { preserveResumeIdentity: false }) } } +// The DERIVED pane key the renderer publishes, never the orchestration bearer handle or the minted +// worker pane key: both of those are credentials. function structuredStatusPaneKey(sessionId: string): string { return structuredAgentSessionPaneKey(structuredAgentSessionTabId(sessionId), sessionId) } From 889acf1c1d0d0c8762002ef35cf7044a6c25f3d5 Mon Sep 17 00:00:00 2001 From: Merge Sim Date: Tue, 8 Sep 2026 23:45:51 -0700 Subject: [PATCH 7/9] test(agent-status): pin both half-migration structured-row filters MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Neither the `agentStatus:getSnapshot` filter nor the main-window listener's had a single assertion, so deleting either — the first step of PR 2 — was green everywhere. Also covers the perf skip and the drop's lack of a renderer clear. --- .../server-ingest-structured-status.test.ts | 58 ++++++++++++ .../server/server-status-update.ts | 6 +- src/main/ipc/agent-hooks.test.ts | 31 +++++++ ...in-window-structured-status-filter.test.ts | 90 +++++++++++++++++++ 4 files changed, 184 insertions(+), 1 deletion(-) create mode 100644 src/main/startup/main-window-structured-status-filter.test.ts diff --git a/src/main/agent-hooks/server-ingest-structured-status.test.ts b/src/main/agent-hooks/server-ingest-structured-status.test.ts index 0dd648235770..5b43cc10bce5 100644 --- a/src/main/agent-hooks/server-ingest-structured-status.test.ts +++ b/src/main/agent-hooks/server-ingest-structured-status.test.ts @@ -128,6 +128,64 @@ describe('AgentHookServer ingestStructuredStatus', () => { expect(server.getStatusSnapshot()).toEqual([]) }) + // The resume-identity remnant a dismissed PTY pane keeps exists so the agent can be resumed in + // that pane. A structured session has no pane, and the record store owns its resume identity — + // so a remnant here would be an unclearable row that every null-status publish re-minted. + it('leaves no resume-identity remnant behind, even carrying a provider session', () => { + const server = new AgentHookServer() + const withProviderSession = summary({ + providerSession: { key: 'session_id', id: 'codex-thread-1' } + }) + server.ingestStructuredStatus(withProviderSession) + expect(server.getStatusSnapshot()[0]?.providerSession).toEqual({ + key: 'session_id', + id: 'codex-thread-1' + }) + + server.dropStructuredStatus(SESSION) + expect(server.getStatusSnapshot()).toEqual([]) + }) + + // Structured rows are never serialized, so persisting one could only rewrite the file already + // on disk — once per debounce window for the whole of every streaming chat. + // "Exactly one writer per pane key" has to hold for deletes too: the renderer's feed bridge owns + // this pane, so a pane-status-clear would be main reaching into a row it does not write. + it('drops the row without sending the renderer a clear for a pane it does not write', () => { + const server = new AgentHookServer() + const cleared: unknown[] = [] + const dropped: string[] = [] + server.setPaneStatusClearListener((clear) => cleared.push(clear)) + server.subscribeStatusDrop((paneKey) => dropped.push(paneKey)) + + server.ingestStructuredStatus(summary()) + server.dropStructuredStatus(SESSION) + + expect(server.getStatusSnapshot()).toEqual([]) + expect(cleared).toEqual([]) + expect(dropped).toEqual([STRUCTURED_PANE]) + }) + + it('schedules no persist for a structured row, while a hook row still does', () => { + const server = new AgentHookServer() + const persists: number[] = [] + const scheduled = server as unknown as { scheduleStatusPersist: () => void } + const original = scheduled.scheduleStatusPersist.bind(server) + scheduled.scheduleStatusPersist = () => { + persists.push(1) + original() + } + + server.ingestStructuredStatus(summary()) + expect(persists).toHaveLength(0) + + server.ingestTerminalStatus({ + paneKey: PANE, + connectionId: null, + payload: { state: 'working', prompt: 'watch the build', agentType: 'claude' } + }) + expect(persists).toHaveLength(1) + }) + it('leaves a hook-reported pane alone', () => { const server = new AgentHookServer() server.ingestTerminalStatus({ diff --git a/src/main/agent-hooks/server/server-status-update.ts b/src/main/agent-hooks/server/server-status-update.ts index dff0bd40e9dd..1a3798efe478 100644 --- a/src/main/agent-hooks/server/server-status-update.ts +++ b/src/main/agent-hooks/server/server-status-update.ts @@ -199,7 +199,11 @@ export abstract class AgentHookServerStatusUpdate extends AgentHookServerStatusA this.runtimeObservedStatusPaneKeys.add(enriched.paneKey) } this.state.lastStatusByPaneKey.set(enriched.paneKey, enriched) - this.scheduleStatusPersist() + // Why skipped for structured rows: the serializer drops them, so the whole walk and stringify + // can only ever reproduce the last file — once per debounce window for a streaming chat. + if (!enriched.structuredHost) { + this.scheduleStatusPersist() + } this.notifyStatusChangeListeners() this.emitEnrichedStatus(enriched) return enriched diff --git a/src/main/ipc/agent-hooks.test.ts b/src/main/ipc/agent-hooks.test.ts index 411a6084124f..001380e934d7 100644 --- a/src/main/ipc/agent-hooks.test.ts +++ b/src/main/ipc/agent-hooks.test.ts @@ -152,6 +152,37 @@ describe('agentStatus:getSnapshot IPC', () => { expect(handler!({})).toEqual(snapshot) }) + // The half-migration seam: until PR 2 retires the renderer's own feed bridge, main must not + // publish structured rows to the renderer at all — one pane key, one writer. + it('omits structured rows the renderer feed bridge still owns', async () => { + getStatusSnapshot.mockReturnValue([ + { + paneKey: PANE_KEY, + state: 'done', + prompt: 'hook row', + agentType: 'claude', + connectionId: null, + receivedAt: 1_700_000_000_000, + stateStartedAt: 1_699_999_999_000 + }, + { + paneKey: CHILD_PANE_KEY, + state: 'working', + prompt: 'native chat row', + agentType: 'codex', + connectionId: null, + structuredHost: 'owned', + receivedAt: 1_700_000_001_000, + stateStartedAt: 1_700_000_000_500 + } + ]) + const { registerAgentHookHandlers } = await import('./agent-hooks') + registerAgentHookHandlers() + + const rows = handleHandlers.get('agentStatus:getSnapshot')!({}) as { paneKey: string }[] + expect(rows.map((row) => row.paneKey)).toEqual([PANE_KEY]) + }) + it('enriches the hook cache snapshot with runtime lineage metadata', async () => { const snapshot = [ { diff --git a/src/main/startup/main-window-structured-status-filter.test.ts b/src/main/startup/main-window-structured-status-filter.test.ts new file mode 100644 index 000000000000..a3cd1bfdf0ac --- /dev/null +++ b/src/main/startup/main-window-structured-status-filter.test.ts @@ -0,0 +1,90 @@ +// The renderer half of the half-migration seam. +// +// Until PR 2 retires `StructuredAgentSessionStatusBridge`, the renderer writes structured rows +// itself. Main forwarding them too would give one pane key two writers, so the window listener +// drops them — a filter nothing else asserts, which makes deleting it green everywhere. + +import { beforeEach, describe, expect, it, vi } from 'vitest' +import type { EnrichedAgentHookEventPayload } from '../agent-hooks/server' + +const hooks = vi.hoisted(() => ({ + listener: null as ((payload: EnrichedAgentHookEventPayload) => void) | null +})) + +vi.mock('electron', () => ({ + app: { getPath: () => '', on: vi.fn(), isReady: () => true } +})) +vi.mock('../agent-hooks/server', () => ({ + agentHookServer: { + setListener: (listener: ((payload: EnrichedAgentHookEventPayload) => void) | null) => { + hooks.listener = listener + }, + setPaneStatusClearListener: vi.fn() + } +})) +vi.mock('../agent-hooks/migration-unsupported-pty-state', () => ({ + setMigrationUnsupportedPtyListener: vi.fn() +})) +vi.mock('../window/dashboard-popout-window', () => ({ + getDashboardPopoutWindow: () => null +})) +vi.mock('./synthetic-title-runtime', () => ({ + driveSyntheticTitleFromHook: vi.fn(), + shouldSuppressCodexAutoApprovalSyntheticTitleFromHook: () => false, + stopAllSyntheticTitleSpinners: vi.fn() +})) + +import { installMainWindowAgentStatusListeners } from './main-window-agent-status' +import { mainProcessState } from './main-process-state' + +const sent: { channel: string; event: { paneKey: string } }[] = [] + +function statusPayload( + over: Partial +): EnrichedAgentHookEventPayload { + return { + paneKey: 'pane-1', + tabId: 'tab-1', + worktreeId: 'repo::/wt', + connectionId: null, + receivedAt: 1, + stateStartedAt: 1, + payload: { state: 'working', prompt: 'ship it', agentType: 'codex' }, + ...over + } as EnrichedAgentHookEventPayload +} + +beforeEach(() => { + sent.length = 0 + hooks.listener = null + mainProcessState.runtime = null + mainProcessState.mainWindow = { + isDestroyed: () => false, + webContents: { + send: (channel: string, event: { paneKey: string }) => sent.push({ channel, event }) + } + } as unknown as typeof mainProcessState.mainWindow + installMainWindowAgentStatusListeners({ + window: mainProcessState.mainWindow!, + maybeAutoRenameBranchOnFirstWork: vi.fn(), + onRecordAgentState: vi.fn() + }) +}) + +describe('the main-window agent-status listener', () => { + it('forwards a hook row but never a structured one', () => { + expect(hooks.listener).not.toBeNull() + + hooks.listener!(statusPayload({ paneKey: 'hook-pane' })) + hooks.listener!( + statusPayload({ + paneKey: 'structured-agent-session-s1:leaf', + structuredHost: 'owned' + }) + ) + + expect(sent.map((entry) => `${entry.channel}:${entry.event.paneKey}`)).toEqual([ + 'agentStatus:set:hook-pane' + ]) + }) +}) From 3a379826626a5363a36da8142e5edfcce5d6fce2 Mon Sep 17 00:00:00 2001 From: Merge Sim Date: Tue, 8 Sep 2026 23:46:01 -0700 Subject: [PATCH 8/9] docs(agent-status): correct three statements this PR made false The sink JSDoc claimed only tests construct a host without one; `orcad` did. The doc argued a structured row needs no tab mirror 'because headless serve has no renderer', reasoning about exactly the topology the wiring had not reached. The deleted runtime adapter's warning that the pane key must be the DERIVED one - never a bearer handle or minted worker key - was lost with it. --- docs/reference/agent-status-store.md | 38 +++++++++++++++++-- .../structured-agent-session-host-types.ts | 3 +- 2 files changed, 37 insertions(+), 4 deletions(-) diff --git a/docs/reference/agent-status-store.md b/docs/reference/agent-status-store.md index 74e9a21f0677..f1068a0d9937 100644 --- a/docs/reference/agent-status-store.md +++ b/docs/reference/agent-status-store.md @@ -107,17 +107,42 @@ without the flag; when the host closes or evicts the session the row is dropped. Both already exist as feed events (`revokeLive` and the roster filter in `liveSessionSummaries`); PR 1 turns them into store writes. +Dropping the session from the host's map and dropping its row are one +operation, `forgetStructuredAgentSession`. The store keeps a row until told, +and a host-owned row bypasses the staleness check, so a deletion path that +forgot the row would strand a permanently working-looking agent. + Two rules the ingest must keep: - **Never persist a structured row.** The journal is the durable truth for a structured session and the host republishes on restore. A structured row in `last-status.json` would hydrate as `restoredUnconfirmed` and then fight the live republish. The serializer skips rows carrying `structuredHost`, and - hydrate drops any such row found on disk. + hydrate drops any such row found on disk. Applying one therefore also skips + the persist schedule: the walk and stringify could only reproduce the file + that is already on disk, once per debounce window for every streaming chat. - **Never let it fight a hook row.** A structured session has no PTY, so no hook or OSC event carries its pane key. The ingest still goes through the disposition gate so a retired pane key is refused like any other. +Applying one does still run both status fan-outs, and that is intended rather +than incidental. `notifyStatusChangeListeners` is what feeds +`agentAwakeService`'s power-save blocker, and `subscribeEnrichedStatus` is what +feeds `AgentSessionTransitionRecorder`'s stats, so joining the store enrolls +native chats in both. A working native chat is real work and should hold the +machine awake exactly like a PTY agent does. + +The drop side routes through `dropStatusEntry`, not `clearPaneState`: a +pane-status-clear reaches the renderer, and until PR 2 the renderer's own feed +bridge is that pane key's writer. It also passes `preserveResumeIdentity: +false` — the `providerSessionOnly` remnant a dismissed pane keeps exists so the +agent can be resumed in that pane, and a structured session has no pane and +keeps its resume identity in the record store. Like every other +`dropStatusEntry` caller, it emits no pane clear, so a session dropped +mid-`working` leaves `AgentSessionTransitionRecorder` holding an open stats +session until its LRU evicts it; that gap is shared with the user-dismissal +path and is not specific to structured rows. + The ingest lives in the feed, not in `structured-agent-session-host.ts`, which sits at the file-length cap. @@ -132,8 +157,15 @@ the admission gate that decides which rows a worktree listing may show: - a hook or OSC row needs its tab mirrored or a connected pty, as today, and SSH rows stay exempt because their tabs may exist only remotely; - a row carrying `structuredHost` is admitted while the host holds the session, and - the host's drop on close is what removes it; no tab-mirror requirement, - because headless serve has no renderer to mirror tabs from. + the host's drop on close is what removes it. No tab-mirror requirement: a + structured session's tab lives in the renderer's own tab state, and a + headless host has no renderer to mirror it from. That argument only holds if + the headless host is itself wired to the store, which is a separate + obligation per entry point: the Electron hosts (desktop and `orca serve`) + share `main-process-runtime-service.ts`, and `orcad` constructs its own + runtime in `src/main/orcad/orcad-entry.ts`. A host missing that wiring lists + no agents at all, not just no structured ones, because `worktree ps` reads + the same snapshot for every row. The freshness bypass for host-owned structured rows already exists in `isFreshNonDoneAgentStatus`; with the flag now on the row it becomes the only diff --git a/src/main/native-chat/agent-session-wire/structured-agent-session-host-types.ts b/src/main/native-chat/agent-session-wire/structured-agent-session-host-types.ts index 9aa87d21b3c9..50b913ee8bd4 100644 --- a/src/main/native-chat/agent-session-wire/structured-agent-session-host-types.ts +++ b/src/main/native-chat/agent-session-wire/structured-agent-session-host-types.ts @@ -71,7 +71,8 @@ export type StructuredAgentSessionHostDeps = { options: { replay: boolean } ) => void /** The agent-status store every held session's projection is written to and, on close, - * removed from. Absent only in tests that read the feed directly. */ + * removed from. Both production hosts pass one — the desktop and headless `orcad`; absent, + * every reader of that store simply lists no structured session. */ statusSink?: StructuredAgentSessionStatusSink handoffTransport?: StructuredAgentSessionHandoffTransport } From e791513d5e9f6d9e7156cdb80de51bebd32ca5f1 Mon Sep 17 00:00:00 2001 From: Merge Sim Date: Tue, 8 Sep 2026 23:56:43 -0700 Subject: [PATCH 9/9] test(agent-status): declare orcad in the hook-row producer census Wiring the hook store into the orcad runtime added a production site that hands hook rows to a consumer, which the census ratchet pins deliberately. --- .../worker/agent-status-producer-census.test.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/main/runtime/rpc/methods/orchestration/worker/agent-status-producer-census.test.ts b/src/main/runtime/rpc/methods/orchestration/worker/agent-status-producer-census.test.ts index 48fa39f5a31a..61a28f4612c2 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/agent-status-producer-census.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/agent-status-producer-census.test.ts @@ -94,6 +94,11 @@ const CENSUS: readonly CensusRow[] = [ kind: 'wiring', role: 'binds the hook server snapshot into the runtime deps' }, + { + path: 'main/orcad/orcad-entry.ts', + kind: 'wiring', + role: 'binds the same snapshot and structured sink into the headless orcad runtime deps' + }, { path: 'main/runtime/orca-runtime-state-fields.ts', kind: 'wiring',