fix(native-chat): never drop an agent process end Orca could not confirm

[brennanb2025]

	Files	Added	Deleted	Net
Test	9	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1111	$\color{#cf222e}{\Huge{\mathbf{−}}}$​3	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1108
Prod	18	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​381	$\color{#cf222e}{\Huge{\mathbf{−}}}$​73	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​308

ELI5

Sometimes Orca has to end a Claude or Codex process behind a chat because of a problem on Orca's side, for example when it can't save the chat's history. After ending it, Orca checks that the process really stopped. If that check can't finish in time (a busy machine, say), Orca used to say nothing at all. The chat went on believing the old process was alive, so every later message was aimed at a process that wasn't listening: each one showed "Message delivery is unconfirmed." and never reached the agent. Even when the old process did exit later, Orca didn't hear it, and the turn just stopped with no explanation.

With this change, Orca never drops an end it couldn't confirm. Messages are refused clearly while the old process might still be running, the old process's exit is always heard, and the turn says what went wrong.

What Changed

The problem

• Orca ends an agent process itself in three cases:
  • the chat's history can't be saved;
  • Codex sends something Orca can't record;
  • Orca's own bookkeeping for the chat fails.
• After ending it, Orca waits for proof that the process exited. When that proof didn't come in time, four places said nothing:
  • Claude's handling of the fault (claude-structured-session-exit-lifecycle.ts);
  • Codex's forced close (codex-structured-session-teardown.ts);
  • the recovery after a failed history write (structured-agent-session-event-recovery.ts);
  • and, for Claude, the old process's later exit. Once Claude's adapter (the per-provider code that runs the process) had let the chat go, that exit was ignored.
• The "host" (the Orca process that runs the agent: the local app, or Orca on another machine for a chat over SSH) kept treating the process as alive. Every later message failed inside Orca, was marked "Message delivery is unconfirmed." (Orca's state for a message it can't tell whether the agent got), and was never retried. The turn kept reading "Working…".
• fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862 (now on main) makes every process exit reach one handler, keeps an unconfirmed stop on the process's record, and makes later sends and Stops retry it. But nothing ever starts that stop for these faults, so on main with fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862 alone the bug still reproduces. The regression test below fails there with that unconfirmed state.

What is different for the user

• While the old process might still be running:
  • A new message first retries killing the old process.
  • If its exit still can't be confirmed, the message is refused with fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862's wording, "Couldn't stop Claude from before.", and can be sent again. It is never marked "Message delivery is unconfirmed." and never written to the old process.
• When the old process exits: Orca hears it at once.
  • The turn ends with "Orca ran into a problem, so this didn't go through. Try again.", the same row a fault with a confirmed exit already writes.
  • The next message goes to a fresh process.
• Stop or close after one of these faults:
  • Stop, or closing the chat, retries the kill (fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862's mechanism).
  • The end is recorded as the user's Stop or close, and the turn still gets the fault's explanation row.
  • An approval or question left open after the turn had finished doesn't count as interrupted work, so it gets no fault row. This is the same rule a confirmed exit uses.
• A message, or /compact, sent in the moment after the adapter let the old process go:
  • It is rejected with the real reason instead of "Message delivery is unconfirmed.": for example "Claude stopped before it finished starting. Send your message to try again." for a start that died, or the "Orca ran into a problem…" sentence for a fault.
  • Codex sends and /compact behave the same way. Codex is said to have stopped only when its exit was actually seen. For a connection that broke while the process may still be running, the rejection reads "Orca couldn't hand this message to the agent, so it was not sent."
  • A /compact rejected this way keeps that reason on its row, instead of reading only "Compaction failed."
• After a failed start whose close couldn't be confirmed: the messages waiting on that start are rejected with the start's real failure.

The mechanism

1. Adapters report every end.
   • Where a close couldn't confirm the exit, Claude's fault handling and Codex's forced close now send the host a new internal event, end-unproven, carrying the reason and the failure.
   • When the old Claude process later exits, its connection reports the exit inside the close Orca began (fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862's behaviour). The adapter now routes that report to the exit it kept, so it reaches the host as the process's end.
2. The host records it (structured-agent-session-unproven-end.ts, -event-recovery.ts).
   • On end-unproven, or a failed-history-write stop that couldn't confirm the exit, the host keeps the process on record and marks it as closing. This uses fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862's in-memory close record. The reported reason and failure are stored with it, along with whether work was running when the fault came.
   • From then on, every send, start or Stop joins that close and retries the kill, exactly as after an unconfirmed Stop on fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862.
3. The exit ends the record as the fault it was (-child-exit.ts).
   • fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862's one exit handler settles a close that carries a reported fault as that fault: cause "exit", the fault's failure, and the explanation row when work was running.
   • This PR adds a clause to fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862's stop function (stopStructuredAgentSessionAgentUnderSerialize in -host-lifetime.ts): a Stop, chat close or quit asked for after the fault takes over the fault's close, because the fault started no one's stop. The end is recorded with the user's (or Orca's) cause and keeps the fault's failure and explanation row. Like any stop that joins a close already begun, it writes no Stop event, so the turn reads "interrupted" with the fault's row, never as the user's cancellation.
4. Sending to a process the adapter has let go of returns "rejected" with the end's reason. Before, it threw, and the host could only record a throw as unconfirmed. This covers both adapters, for messages and /compact. Claude keeps a failed start's wording.
5. end-unproven is handled on its chat's own queue, off the exit queue all chats share.

The event stays inside the host. Nothing Orca sends to other windows, the mobile app or remote clients changes, and no saved data changes. The record of the reported fault lives in memory only.

Why

This is part of the rework of how Orca owns agent processes. #24862 owns the stop and close half: one exit handler, and an unconfirmed stop that later sends and Stops join. This PR owns the other half: no end is ever dropped, and a send to a process that's gone is answered rather than lost.

The fix is made where the ends were being dropped:

• each silent branch now reports;
• the host reuses fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862's close record instead of adding new state.

Alternatives considered:

• The earlier version of this PR held messages under a waiting note until the old process exited. fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862 replaced that model with "join the close and refuse readably", so this PR was rebuilt on fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862 and keeps none of that machinery.
• fix(native-chat): a message waiting on an unconfirmed stop goes out as soon as the old process exits #24362's second "exit after close" callback (closed) only fixed the late exit. fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862's single exit report covers it, and this PR adds the routing it still lacked for a Claude chat the adapter had already let go.
• Starting a new process right away after an unconfirmed fault was rejected: the old one might still be writing to the same conversation.

How this compares with the common pattern (every process end reaches the one owner exactly once; a send to a process the owner no longer holds fails visibly instead of hanging):

• Intended: an end Orca can't confirm keeps the chat from starting a second process on the same conversation. Messages are refused readably until the exit is confirmed. This is Orca's stricter "confirmed exited" rule, the same one its SSH/remote design uses, where losing contact is never treated as proof a process died.
• Temporary: there is no time limit on how long an unconfirmed process can block new starts. In practice it's seconds, because the kill sequence ends the process and its exit is now always heard; the limit matters only for a process the OS can't kill. The next phase of this agent-process lifecycle rework adds a bound. No ticket exists for it yet.
• Temporary: a refused or rejected message is never retried automatically; the user sends it again. The common pattern retries a message that never reached the agent automatically, after 15 seconds, 1 minute and 5 minutes. fix(native-chat): a failed start is shown on its message and retried, and later messages go ahead #24340's retry doesn't cover these: it retries only messages Orca had not yet recorded as handed over to the agent, and these were recorded as handed over, though never written to the process. No follow-up is filed yet.
• Temporary: an exit Orca didn't ask for still goes through the single exit queue shared by all chats. Only end-unproven and the end of a close the host asked for run on the chat's own queue. Per-chat queues for all exits land in the next phase of this rework. No ticket exists for it yet.

How these rejections are shown (checked against #24710, now on main): every rejection this PR records is a host-recorded rejection with a typed reason ("Orca ran into a problem…", "Claude stopped before it finished starting…", "Couldn't stop Claude from before.", "Orca couldn't hand this message to the agent…", or closed with the chat). On desktop, #24710 draws such a message as "Not sent" with that reason, where it was rejected, with no Retry; the user sends it again. None of these reasons is a Stop withdrawal or a command, so none is hidden. A rejected /compact stays hidden as #24710 decided, and the command's own row carries the reason, which this PR keeps (the round-3 compaction fix). No conflict found; no change was needed.

Open check: #25028 (client-only, still a draft) will show host-recorded rejections through its new "sent from somewhere else" state (undeliveredSentElsewhere). Once it lands, check that each rejection here is shown once, with its own sentence. Not verified yet.

Linked Issue

None (maintainer change; no pre-existing issue). Builds on #24862 (merged).

Visual Proof

N/A. No new UI. The refusal, the rejection reasons and the "Orca ran into a problem…" row are existing chat rows that now appear where a message used to end as "Message delivery is unconfirmed." On desktop, a rejected message is drawn by #24710's existing "Not sent" row with its reason. Verified through host-level tests that drive the real Claude and Codex adapters and the real host against scripted processes. No app run.

Testing

• I manually tested these changes locally
• Automated tests added/updated, or explained why not below

Head f5e48b6f2c5 targets main and includes main up to 4de9f9f85a8. Its diff against main is this PR's own 27 files (+1492/−76). The main merges needed hand resolution in four places. A Codex adapter test, where main had replaced one assertion. The Stop-event line in the stop function, where main now resolves with null. The Codex lifecycle routing, which moved with main's new agent registrations into structured-agent-runtime-registrations.ts. A compaction test file, where both sides added a test. Three of this PR's test files were also updated to main's new host construction (agents from a registry) and provider-handle shape. Rows marked "earlier head" below were run before the latest merge.

New and rewritten tests:

• structured-agent-session-claude-unproven-fault-send.test.ts, the main regression test:
  • After a history-write fault whose close can't be confirmed, a message is refused readably and never written to the old process. Stop retries the kill. When the old process exits, the record ends with the fault's row and the next message goes to a new process and is accepted.
  • A message sent while the first close is still running is rejected with its reason.
  • A failed history write whose stop can't be confirmed leaves the process on record, closing, with the fault.
  • A turn cut short reads the same (turn "interrupted", one fault row) whether the exit was confirmed at once or only later.
  • A user's Stop, or a chat close, before the late exit: the turn still reads "interrupted" (never the user's cancellation) with one fault row, and the end keeps the user's cause.
• structured-agent-session-codex-forced-close-unproven.test.ts: the same for a Codex forced close, including a chat close or an Orca eviction before the late exit (no Stop event written, turn "interrupted", one fault row), and a stale exit from an old process being ignored.
• Claude and Codex takeover tests (added in 96416f316aa): a message accepted while a fault's close is unproven, then a chat close that takes that close over (with the close's own clearing of the queue failing), then the exit's proof. The child's end is stamped where the close was asked, so the message is rejected as closed with the chat and no new agent starts. If the takeover keeps the fault's old position instead, both tests fail: the message is not closed and a new agent is started for it.
• structured-agent-session-unproven-end.test.ts: an open approval left after a finished turn is not interrupted work; a running turn is.
• claude-structured-startup-fault-is-not-an-exit.test.ts: a failed start with an unconfirmed close rejects the waiting messages with the start's real failure.
• structured-conversation-compaction.test.ts: a /compact whose agent was already gone keeps that reason on its row.
• Adapter tests:
  • a send or /compact to a Claude process the adapter let go of is rejected, not thrown;
  • Codex sends to an ended session or a broken connection are rejected with the right reason.
• structured-agent-session-lifecycle-delivery.test.ts: end-unproven does not wait behind other chats' exits.

Results:

• Fails on fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862, passes here:
  • The main regression file was run with the changed source files swapped back to fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862's versions (temporary local commit, then restored; done on the earlier head baf85fcc958). 5 of 6 tests failed. The first failure is the bug itself: expected "unknown" to be "rejected", meaning the message was marked "Message delivery is unconfirmed."
  • With this change, the file passes in full.
• Removal checks (each fix taken out temporarily, then restored):
  • Writing the Stop event again when a close takes over a fault's close fails three tests: the Claude chat close (turn read as the user's cancellation), the Codex chat close and the Codex eviction.
  • Treating every rejected /compact as "Compaction failed." fails the new compaction test.
  • Keeping the fault's old position when a chat close takes over its close fails both takeover tests: the message is rejected as a failed restart (a new agent was started for it) instead of as closed with the chat.
• On f5e48b6f2c5: every test file that imports a changed module, 170 files, 1600 passed, 1 skipped (run with 2 workers).
• On the earlier head bea13c490fb: that set plus the shared-harness tests, fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862's stop and close suites, and the tests added or changed by fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held #24862, fix(native-chat): show a message Orca accepted and then failed to deliver as "Not sent" in the chat #24710, fix(native-chat): show "Sending…" on a message until the host confirms it #24606 or Fix admission of later Claude question rows and real CLI verification #25119: 307 files, 2782 passed, 1 skipped.
• Earlier heads: 244 files, 2172 passed, 1 skipped on b9c4247a6d9; the two takeover test files plus the stop and close suites, 11 files, 153 passed, on 96416f316aa.
• Mixed-version check: tests/e2e/cross-version-wire/cross-version-agent-session-wire.unit.test.ts 19/19 on f5e48b6f2c5.
• Real Claude CLI (claude-structured-real-cli.test.ts, claude-structured-real-cli-fold.test.ts): run once on baf85fcc958, 8 of 8 passed. Not re-run since: the later commits change host code and tests only, and the merge brings in main.
• Checks on f5e48b6f2c5: CI's pnpm run typecheck (all three projects, from a clean build cache) clean; the type-aware code-quality audit clean; oxlint on the whole repo clean (including max-lines); changed-code quality gate passed; lockfiles equal main's.
• Skipped: codex-app-server-teardown.integration.test.ts, which times out on the unchanged base too on this machine.
• Platforms: macOS only, unit level. Windows, Linux and SSH were not exercised; no platform-specific code changed, and the kill sequences are untouched.

AI Disclosure

Review

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Security: no new inputs or permissions.
• Cross-platform: the change is platform-neutral; the kill sequences are unchanged.
• SSH and remote: the new event never leaves the machine running the agent, and an end that can't be confirmed is never treated as an exit.
• Mobile and backwards compatibility: nothing sent between Orca processes changes and no saved data changes; clients see only existing rejection reasons and chat rows.
• Performance: one extra comparison per adapter event, and nothing per message frame.

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

[coderabbitai]

📝 Walkthrough

Walkthrough

Claude and Codex adapters now report unproven session ends and return classified rejections for dispatch or compaction on detached sessions. The host records the reported failure and interruption state, and reconciles it with later stop and exit events. Runtime delivery routes unproven-end events, and Codex journal and command handling process the related outcomes. Tests cover provider exits, host recovery, interruption state, and close races.

Priority: ➖ Normal

Merge Risk: 🔵 Low · up to f5e48

Run the required real Claude CLI tests on this head before merging to validate the changed session behavior.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 4453a

The change blocks further work while a previous process may still be running and preserves the failure for later resolution. Reviewed paths retain process-ownership checks. No introduced security weakness was established, but restart recovery and some dependents remain incompletely verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The inspected lifecycle mutation is scoped to the named session and matching provider child. Its immediate effects are work admission, close retries, ownership release, and journal settlement for that child. Export and dependent counts alone do not establish a broader attacker-reachable boundary.

Trust Boundaries and Controls

• observed — Both acquisition generation and fence must match before a lifecycle report can mutate the current child. Claude additionally matches the retained connection before processing a late exit. These controls prevent an old child's report from settling a replacement child.

Resilience and Maintainability Implications

• observed — Unproven-end delivery queues on its session's serialized path rather than waiting behind unrelated exit recovery. Pending handlers remain tracked by drain, preserving teardown's ability to await lifecycle work. The inspected test specifically covers cross-session progress and drain waiting.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.59% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 54 functions across 28 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: preserving and reporting agent-process ends that Orca could not confirm.
Description check	✅ Passed	The description covers the required explanation, changes, rationale, issue context, visual proof, and testing. It also documents limitations and cross-platform considerations. The maintainer-specific …

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pullfrog]

✅ No new issues found.

Reviewed changes

This PR makes an agent-process end that Orca could not confirm impossible to drop, building on #24862's close record. I read the full 27-file diff, traced both adapter paths into the host, and ran the changed suites (82 tests, all green).

• New internal end-unproven event (structured-agent-session-adapter.ts) — emitted by Claude's reportClaudeUnprovenEnd and Codex's forceCloseUnexpected when a stop cannot prove the root gone; it stays inside main and never reaches clients, other windows, or saved data.
• Host records the unproven end (structured-agent-session-unproven-end.ts, wired in -event-recovery.ts) — keeps the child on record, closing, writes no Stop event, precomputes interruptedWork under the same rule an observed exit uses, and republishes status.
• The late exit settles as the reported end (-child-exit.ts) — expected yields to reported, the fault's failure is preserved, endedAt stands where the close was asked, and a Stop/close that took over keeps its own cause while the fault's row is still written.
• Stop takeover (-host-lifetime.ts) — the first Stop/chat-close/quit after a fault adopts the fault's reported details and writes no Stop event.
• Sends/compaction answered instead of thrown — Claude withClaudeSessionOrRejected, Codex detachedRejection, and structured-agent-session-command-turn.ts keep the agent-gone reason rather than reading as "Compaction failed."
• Delivery routing — end-unproven takes the session's own lane and is tracked for drain; Codex routing extracted to structured-codex-lifecycle-event.ts.

Two independent specialist passes found no re-entrant-lane deadlock (all producers fire-and-forget onEvent; the one in-lane path uses the …UnderSerialize variant) and no dropped fault failure/row. The documented open items (no time bound on the blocking process, no auto-retry of refused messages, single shared exit queue, #25028 rendering check) are pre-existing/sequenced trade-offs already stated in the PR body.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 867c1c89-ffe7-4071-988d-50cdd332e8a4

📥 Commits

Reviewing files that changed from the base of the PR and between 4453a86 and f5e48b6.

📒 Files selected for processing (13)

• src/main/claude/claude-structured-session-adapter.ts
• src/main/codex/codex-structured-session-adapter-lifecycle.test.ts
• src/main/codex/codex-structured-session-adapter.test.ts
• src/main/codex/codex-structured-session-state.ts
• src/main/native-chat/agent-session-wire/structured-agent-session-adapter.ts
• src/main/native-chat/agent-session-wire/structured-agent-session-claude-unproven-fault-send.test.ts
• src/main/native-chat/agent-session-wire/structured-agent-session-codex-forced-close-unproven.test.ts
• src/main/native-chat/agent-session-wire/structured-agent-session-command-turn.ts
• src/main/native-chat/agent-session-wire/structured-agent-session-host-types.ts
• src/main/native-chat/agent-session-wire/structured-agent-session-unproven-end.test.ts
• src/main/native-chat/agent-session-wire/structured-conversation-compaction.test.ts
• src/main/runtime/structured-agent-runtime-registrations.ts
• src/main/runtime/structured-claude-runtime-adapter.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🔎 Supported by static analysis

🏁 Script executed:

git diff --name-only baf85fcc958c9cf108f9d76bec45c1e69be1c87d f5e48b6f2c539e5a0f5b6d4b0e9fee782c21ebd8 -- 'src/main/claude/claude-structured-*'
rg -n 'Real Claude CLI|ORCA_REAL_CLAUDE_CLI_TEST|Verifying Changes' AGENTS.md src/main/claude package.json 2>/dev/null | head -65

Repository: stablyai/orca

Length of output: 3035

---

Run the required real Claude CLI tests on this head.

The reported 8/8 pass predates changes to Claude structured-session code, and the PR says the tests were not rerun. The project requires this run when that code changes:

ORCA_REAL_CLAUDE_CLI_TEST=1 pnpm test src/main/claude/claude-structured-real-cli.test.ts src/main/claude/claude-structured-real-cli-fold.test.ts