Skip to content

Stop retrying final native agent startup refusals - #37213

Merged
brennanb2025 merged 28 commits into
mainfrom
brennanb2025/sta-12982-start-refusal
Nov 3, 2026
Merged

brennanb2025 merged 28 commits into
mainfrom
brennanb2025/sta-12982-start-refusal

Conversation

@brennanb2025

@brennanb2025 brennanb2025 commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 31 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​2860 $\color{#cf222e}{\Huge{\mathbf{−}}}$​111 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​2749
Prod 80 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​2873 $\color{#cf222e}{\Huge{\mathbf{−}}}$​977 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​1896

Problem

When an agent refused to start or resume a native chat with an answer it gives every time, Orca restarted it up to five times before showing the failure. The reported case was resuming a Codex conversation whose saved file had been copied under a non-canonical name: Codex answers "does not have a canonical rollout filename" on every attempt, and the user waited through five restarts before seeing it.

The cause was structural. A shared start rule guessed, from broad classes of provider errors, whether a failed start was worth retrying. When the agent process exited at about the same moment it answered, that rule also tried to reconstruct the outcome from the exit and the half-finished open together. Each fix to that guessing left the next case open.

What changes for users

  • A refusal the agent will repeat ends the start or resume on the first attempt. The user sees the existing failure card naming the agent once, and the message is not delivered.
  • Failures the provider itself marks as temporary still retry, up to five attempts within the original start deadline, and deliver the queued message once the agent is up. Examples: Codex "Server overloaded; retry later.", server shutting down, a thread still closing, a workspace change in progress or a cloud-config timeout; OpenCode server unavailable or catalog not ready.
  • An agent process that dies before answering still recovers, with up to five attempts as before.
  • A missing agent CLI, a request that ran out of time, or Orca's own refusal stays a single final failure with its specific message, whatever order the process exit arrives in.
  • Stop while an agent is starting cancels the start; nothing restarts behind it.
  • An OpenCode saved session whose reopen gets a temporary answer keeps the saved conversation instead of silently starting a new one.
  • No new screens, settings, saved data or protocol changes.

How it works

Each agent integration (Claude, Codex, Pi and ACP agents such as OpenCode) now owns its own startup. It spawns the agent, initializes, opens or resumes the conversation, runs the required startup requests, and returns one completed verdict: ready, or a failure marked final or safe to retry. Only the integration can read its own protocol, so only it decides what an answer means.

A small shared policy picks the failure that verdict reports. It keeps the most specific cause available: Orca's own refusal, a missing executable or folder, a request deadline, the agent's answer, Orca's own record of the process exit, and only then a generic exit summary. Any final fact forbids a retry, whichever explanation is shown.

The shared start owner keeps what it always owned: the queued message, Stop, the original start deadline, at most five attempts, and settling the request exactly once. It reads only the verdict. It retries only a safe failure, and only after the previous process is proven gone.

When an agent exits or stops reading its input while a request is still outstanding, Codex, ACP and Pi keep reading its output until that output ends or one second passes. An answer the agent wrote just before dying is still honoured.

If an integration ever fails to report after its process has exited, a five-second guard settles the start as a final failure, so the user is never left waiting on bookkeeping.

Differences from the common pattern

  • Intended — startup authority and failure precedence: each adapter owns acquisition, open and required startup requests, then returns one completed final or safe-to-retry verdict.
    • A single pure policy keeps the most specific available cause, in this order: installation or refusal, missing executable or folder, launch preparation, request deadline, provider answer, Orca's own exit record, then an SDK-only exit summary or unknown failure.
    • Final facts veto replay independently of which explanation is shown, and completed verdicts are never reopened.
    • This accommodates Orca's supervised spawn evidence, which an SDK exit summary can omit, without moving provider decoding back into the host.
  • Intended — bounded safe recovery: Orca keeps at most five fresh attempts, under the original whole-start deadline, for provider-declared temporary answers, unanswered exits and eligible host resource failures.
    • The common pattern may retry a narrow request on the same connection, or retry failed effects more broadly.
    • Orca respawns only after the previous owner is proven released. An active writer remains an ownership refusal under Orca's multi-host rules.
    • Unknown or final answers never gain replay permission from a later exit.
  • Intended — response preservation and SDK observation:
    • Codex, ACP and Pi keep outstanding replies decodable until output ends, or a one-second drain expires, after a spontaneous termination, including write-side termination. Duplicate stream end/close reports finish a single wait.
    • Claude keeps its bounded failed-result observer, and a finite two-second observation of initialize after exit (or of Orca's exit record after an SDK-only exit report), so a missing CLI or a final answer is not lost to cleanup. The observer stops its extra parsing after capture while still forwarding output.
    • These adapter observations replace no caller deadline and are not a generic host exit join.
  • Intended — starting ownership and readiness:
    • Orca keeps an indexed starting child for Stop, status, streamed history and persisted crash ownership.
    • Delivery waits for a successful open plus the required provider and local settlement, then rechecks the current generation before readiness.
    • Late, cancelled or replaced results cannot promote another child.
    • This uses the common pattern's pending-operation ownership shape.
  • Intended — attempt and time bounds: the five-attempt limit and the original ten-minute whole-start ceiling survive retries and required settlement. Per-request deadlines stay their own final outcomes, never replaced by process death or another startup request. These bounds are existing Orca recovery and liveness requirements.
  • Intended, Orca-only — exit receipt and contract guard:
    • An exact acquisition's ending stays readable after its live route is removed, until its startup owner retires it.
    • Separately, the first positive spontaneous root-exit observation arms a final five-second adapter-contract bound, capped by the original deadline. It keeps callers responsive when cleanup or bookkeeping is blocked, and never grants replay.
    • Receipts and listeners retire with their owner. No saved or wire field is added.
  • Intended — direct attach and presentation:
    • Direct attach keeps its early starting acknowledgement, cancellation and streaming, and one generation-keyed failure row. That row rejects the oldest queued message when there is one, and stands alone when there is none.
    • An exit-first direct attach keeps its existing exit wording, unless a request timeout gives the more specific explanation.
    • Elsewhere a specific provider answer, refusal or deadline stays ahead of a generic exit. An otherwise unexplained failure may use the existing "stopped before it finished starting" sentence without becoming retryable.
  • Intended — saved-session fallback and replacement safety:
    • A temporary ACP reopen answer keeps the saved identity.
    • An ACP load timeout stays final, with its original method and duration, whether the process is alive or exiting. An already exited or abandoned start cannot fall through to opening a new session.
    • The existing permitted restore-failed and unsaved-session replacements remain.
    • Any process respawn still separately requires the previous exact owner's exit and lease proof.

Verification

  • CI: green on eeac0fc, with all checks passing. A timing flake in an unrelated ACP perf test was rerun once; it passes locally.
  • Named tests: fed recorded real outputs where they exist (the Codex refusal wire capture, Claude's exit-127 and SDK exit captures, an OpenCode reply). They cover:
    • each adapter's final answer, declared-temporary answer, and unanswered exit, in both arrival orders, including an exit seen before the last output chunk and a write-side close;
    • the shared precedence policy;
    • Stop, deadline, stale-generation and blocked-bookkeeping cases;
    • direct attach with and without a queued message;
    • N/10N performance contracts for the start owner, receipts, drains and the Claude output watcher.
  • Real-app QA on macOS (M4Air), head eeac0fc, real Claude and Codex CLIs:
    • The ticket's reproduction: resuming a Codex conversation from Session History after its rollout was renamed made one start and showed one Codex notice, with no repeat. After the repair, the same thread replied.
    • A Codex child and a Claude child killed during startup each recovered with one retry and delivered the message once.
    • Claude: a new chat, then a resume after a graceful restart.
    • Stop while starting, for Claude and Codex: no restart, and the next send worked.
    • A Codex "conversation open elsewhere" refusal: one start.
  • Real-app QA on Windows: OpenCode (an ACP agent) and Pi on head eeac0fc, with real CLIs: a new chat and a resume after a graceful restart for each, one start per open, the same saved conversation kept, and no "starting a new one" notice. An OpenCode chat with 41 turns resumed in about 9 seconds.

Linear: STA-12982

🤖 Generated with Claude Code

…ders

- A start flight cancels its outstanding provider open on every ended path; a direct attach keeps the child-bound abort.
- The post-exit answer join is bounded by the remaining startup ceiling.
- An elapsed initialize deadline keeps its words when the exit wins the race.
- Codex cloud config temporary declarations retry on thread/resume as on thread/start.
- A Claude exit before acquisition publishes waits briefly for initialize's answer, so a rejected initialize stays final.
- The Claude startup stdout observer parses only failed root results, within the shared line budget, and detaches once it has one.
The exit path skipped saving the resume cursor whenever Orca had not
dispatched a message, but turns can settle without an Orca dispatch and an
already-started idle session still owns its exit save. Only a start that
died before initialize answered and before any turn now skips the save and
gets the short cleanup bound. A failed result captured before the first send
counts as a startup failure only when no turn ran in that process.
@brennanb2025
brennanb2025 marked this pull request as ready for review November 1, 2026 23:51
@coderabbitai

coderabbitai Bot commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review

No actionable comments were generated in the recent review.

Walkthrough

This change adds provider-specific startup failure classification and shared structured-session failure verdicts. ACP, Claude, Codex, and Pi connections now preserve startup errors, process exits, response data, and generation-scoped endings. Provider peers defer request settlement while output may still contain a response. Structured startup attempts now track ownership, root exits, bounded grace periods, contract breaches, and retry outcomes. Tests cover these races and classifications.

Merge Risk: Low · up to 97042

The change makes native-agent startup retry only for temporary answers and for processes that exit without answering. It treats other refusals as final, and the supplied context shows no defect that would block merge. One test title may misdescribe what it covers, which is worth a quick fix but does not affect behavior.

Pre-merge checks: Passed 4 · Inconclusive 1

Failed Failed checks: 1 inconclusive

Check name Status Explanation Resolution
Docstring Coverage Inconclusive Docstring coverage is 48.89% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title "Stop retrying final native agent startup refusals" matches the main change: the shared start-retry rule was replaced so that only provider-declared temporary answers retry, while final refu…
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.
Description check Passed The description is substantive and follows the template's main sections. It covers the problem, user-visible changes, mechanism, and differences from the common pattern. Verification and QA are descri…
Full details: Title check

Explanation

The title "Stop retrying final native agent startup refusals" matches the main change: the shared start-retry rule was replaced so that only provider-declared temporary answers retry, while final refusals end the start on the first attempt. The summary also covers the Codex, Claude, ACP, and Pi classifiers, the 2-second post-exit answer wait, and the startup-failure handling, which the title does not mention, but these are supporting parts of the same change. The title is specific and short.

Full details: Description check

Explanation

The description is substantive and follows the template's main sections. It covers the problem, user-visible changes, mechanism, and differences from the common pattern. Verification and QA are described in detail, and the Linear ticket is referenced. Several template items are missing or incomplete: the ELI5 section is absent, the Linked Issue section has only a Linear reference rather than a GitHub issue ('Fixes #' is unfilled), the Visual Proof section has no before/after attachments or N/A statement, the Risk section lacks an explicit Level value and a rollback plan, the AI Disclosure section is blank, the Review and Agent skill upstream boundary sections are unaddressed, and the checklist is not ticked. The description is largely complete in substance, so it passes, but these template gaps should be fixed.

Full details: Docstring Coverage

Explanation

Docstring coverage is 48.89% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 45 functions across 67 files. (29 skipped: 29 over the file limit.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches
Generate docstrings
  • Commit to this branch
  • Create a new PR
  • Autofix · 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

CodeRabbit Verify

  • Run CodeRabbit Verify to test the changes in this pull request.
Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 3fe969e7-c5c3-4a45-9a39-bd0a99b7a4c2
Commits

Reviewing files that changed from the base of the PR and between 8117c12 and 9704293.

Files selected for processing: 81
  • src/main/acp/acp-agent-connection.test.ts
  • src/main/acp/acp-agent-connection.ts
  • src/main/acp/acp-errors.ts
  • src/main/acp/acp-json-rpc-peer.test.ts
  • src/main/acp/acp-json-rpc-peer.ts
  • src/main/acp/acp-peer-reply.ts
  • src/main/acp/acp-scripted-connection.test-fixture.ts
  • src/main/acp/acp-session-reopen-failure.test.ts
  • src/main/acp/acp-session-reopen-failure.ts
  • src/main/acp/acp-session-runtime.ts
  • src/main/acp/acp-startup-outcome.ts
  • src/main/acp/acp-structured-adapter.test-support.ts
  • src/main/acp/acp-structured-child-lifecycle.ts
  • src/main/acp/acp-structured-session-adapter.ts
  • src/main/acp/acp-structured-start-open.ts
  • src/main/claude/claude-startup-failure.ts
  • src/main/claude/claude-stream-json-connection.test.ts
  • src/main/claude/claude-stream-json-exit-error.test.ts
  • src/main/claude/structured/claude-structured-session-acquisition.ts
  • src/main/claude/structured/claude-structured-session-adapter.ts
  • src/main/claude/structured/claude-structured-session-exit-lifecycle.ts
  • src/main/claude/structured/claude-structured-session-startup-exit.ts
  • src/main/claude/structured/claude-structured-session-startup-failure.test.ts
  • src/main/claude/structured/claude-structured-session-startup.test.ts
  • src/main/claude/structured/claude-structured-start-ending.ts
  • src/main/codex/app-server/codex-app-server-connection-exit-order.test.ts
  • src/main/codex/app-server/codex-app-server-connection.ts
  • src/main/codex/app-server/codex-app-server-exit-error.ts
  • src/main/codex/app-server/codex-startup-outcome.ts
  • src/main/codex/codex-scripted-child.test-fixture.ts
  • src/main/codex/codex-structured-session-acquire.ts
  • src/main/codex/codex-structured-session-adapter-fixture.ts
  • src/main/codex/codex-structured-session-adapter.ts
  • src/main/codex/codex-structured-session-state.ts
  • src/main/codex/codex-structured-start-verdict.ts
  • src/main/jsonl-rpc/agent-connection.test.ts
  • src/main/jsonl-rpc/agent-connection.ts
  • src/main/jsonl-rpc/peer-reply.ts
  • src/main/jsonl-rpc/peer.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-adapter-router.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-adapter.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-agent-start.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-append-delivery.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-attach-failure.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-attach-publish.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-child-exit.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-conversation-lifetime.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-dead-generation-settlement.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-event-recovery.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-event-sink.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-exit-observation.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-held-start.test-support.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-host-runtime-state.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-host.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-provider-open.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-provider-open.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-provider-started-outcome.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-provider-started.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-rewind.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-attempts.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-failure-writer.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-failure.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-provider-answer.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-retry-recorded.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-retry.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-settlement-host.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-startup-attempt-contract.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-startup-attempt-host-test-support.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-startup-attempt-host.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-startup-attempt.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-startup-tracking.ts
  • src/main/opencode/opencode-acp-connection.ts
  • src/main/pi/pi-scripted-child.test-fixture.ts
  • src/main/pi/rpc-session-adapter.ts
  • src/main/pi/rpc-session-startup.test.ts
  • src/main/pi/rpc-session.ts
  • src/main/pi/rpc-startup-open.ts
  • src/main/pi/rpc-startup-outcome.ts
  • src/main/provider-process/provider-exit-output-drain.ts
  • src/main/provider-process/provider-output-end.ts
  • src/main/runtime/rpc/methods/agent-launch-at-rest.test.ts
Files with no reviewable changes: 2
  • src/main/native-chat/agent-session-wire/structured-agent-session-host.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-retry.ts

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

brennanb2025 and others added 2 commits November 1, 2026 15:57
…d refusals final

Exit-time cursor writes and the short close bound now key on the host-awaited
open actually returning, so a resume that exits while transcript catch-up is
pending publishes ended at once instead of waiting on a cursor write. The
startup observer no longer reads an answer from an oversized line's prefix.
A typed acquisition refusal without a dedicated failure kind keeps its
refusal marker, so an exit-only start stays final.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpick comments: 1
src/main/runtime/agent-session/structured-agent-session-adapter-start-failure.test.ts: 1

145-147: Trivial · Maintainability & Code Quality · Quick win

Cover the unanswered Claude exit in the adapter-start test, or rename the test if that coverage is not intended.

failedStart('claude', claudeScriptedChild()) selects failHandshake, so the test does not exercise an unanswered child exit. The separate Claude startup test covers adapter behavior only; it does not cover this host retry and spawn-count path. Add an exitHandshake to claudeScriptedChild and pass true here if unanswered Claude retries are part of this suite. Otherwise, rename the test to describe the answered failed-start retry.

Proposed rename when no coverage change is intended
-it('Claude keeps unanswered early exits within five attempts', async () => {
+it('Claude retries a failed start within five attempts', async () => {
   await failedStart('claude', claudeScriptedChild())
 })

Review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: e6313603-fd9b-4c5c-a611-ef50bd4830c1
Commits

Reviewing files that changed from the base of the PR and between 7f9940e and 8bc59be.

Files selected for processing: 39
  • src/main/acp/acp-session-reopen-failure.test.ts
  • src/main/acp/acp-session-reopen-failure.ts
  • src/main/acp/acp-startup-failure.ts
  • src/main/acp/acp-structured-handshake.ts
  • src/main/claude/claude-agent-sdk-control-requests.ts
  • src/main/claude/claude-agent-sdk-process-spawn.ts
  • src/main/claude/claude-startup-answer-observation.ts
  • src/main/claude/claude-startup-failure.ts
  • src/main/claude/claude-stream-json-connection.ts
  • src/main/claude/fixtures/startup-sdk-process-exit.json
  • src/main/claude/structured/claude-structured-resume-point.ts
  • src/main/claude/structured/claude-structured-session-acquisition.ts
  • src/main/claude/structured/claude-structured-session-exit-lifecycle.ts
  • src/main/claude/structured/claude-structured-session-open.ts
  • src/main/claude/structured/claude-structured-session-startup-exit.ts
  • src/main/claude/structured/claude-structured-session-startup-failure.test.ts
  • src/main/claude/structured/claude-structured-session-startup.ts
  • src/main/claude/structured/claude-structured-session-state.ts
  • src/main/codex/app-server/codex-app-server-record-dispatch.ts
  • src/main/codex/app-server/codex-app-server-request-error.ts
  • src/main/codex/app-server/codex-startup-failure.ts
  • src/main/codex/app-server/fixtures/start-resume-canonical-filename-refusal.json
  • src/main/codex/codex-scripted-child.test-fixture.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-claude-resume-exit-start.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-failure-text.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-provider-open.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-provider-started.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-attempts.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-retry-recorded.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-retry.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-start-settlement-host.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-startup-attempt-host-test-support.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-startup-attempt-host.test.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-startup-attempt-mint.ts
  • src/main/native-chat/agent-session-wire/structured-agent-session-startup-attempt.ts
  • src/main/pi/pi-scripted-child.test-fixture.ts
  • src/main/runtime/agent-session/structured-agent-session-adapter-start-failure.test.ts
  • src/main/runtime/structured-agent-scripted-child.test-fixture.ts
  • src/shared/main-process-ndjson-framer.ts
Files with no reviewable changes: 1
  • src/main/acp/acp-structured-handshake.ts

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

brennanb2025 and others added 6 commits November 1, 2026 19:59
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Drive the startup observer through the shared framer at 100 and 1000
irrelevant hook and assistant records, and assert that only the failed
root result is parsed, one capture happens, the data listener retires,
and no parse follows capture or finish, with identical counts at both
populations.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Held opens in the launch test now reject when their child exits, as a
real connection does, and the temporary open failures use the provider's
actual overload envelope. Also fixes the test-only type errors CI found.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@brennanb2025

brennanb2025 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

Review loop status: ready for merge review (architecture rework)

Problem. When an agent refused to start or resume a native chat with an answer it gives every time, Orca restarted it up to five times before showing the failure. The reported case was a Codex conversation whose saved file had a non-canonical name. The cause was a shared start rule that guessed retry-worthiness from broad classes of provider errors, and that rebuilt the outcome from the process exit and the half-finished open whenever the two raced. Each earlier fix left the next case open.

What users get. A refusal the agent will repeat ends after one attempt and shows the existing failure card once. Provider-declared temporary failures and agents that die before answering still recover, with up to five attempts within the original start deadline. A missing CLI, a request that ran out of time, or Orca's own refusal stays one final failure with its specific message, whatever order the exit arrives in. Stop while starting cancels the start. There are no new screens, settings, saved data or protocol changes.

What changed in this round. On Brennan's direction, the fix was rebuilt so that each agent integration owns its startup and returns one verdict, final or safe to retry. The shared owner keeps the queued message, Stop, the deadline, the five-attempt bound and exactly-once settlement, and it no longer decodes provider errors.

  • The architecture went through the three-model design panel.
  • Review found and fixed, each with a test that fails without the fix:
    • final answers lost to a later exit (Claude, ACP and Pi, including write-side termination);
    • startup records that leaked across sessions;
    • Orca's own handle or rewind refusals overridden by a racing exit;
    • waiters blocked behind stalled bookkeeping;
    • a missing Claude CLI on Linux shown as a crash and retried about ten times (caught by CI's WSL lane);
    • an ACP load deadline consumed by the fallback that opens a new session.
  • One shared policy now chooses the failure from everything the integration saw.
  • Performance contracts pin the start owner, startup records, drains and the Claude output watcher at N and 10N.
  • The size tripwire fired once, at about 2x the forecast. The panel re-planned and ruled to continue unchanged; the growth is what the bug class requires.

Deferred: none. Main was synced once before final QA (#37543 and the OMP prompt fix conflicted in two ACP files; both sides were kept).

Verified

  • CI: green on eeac0fc. One unrelated ACP perf test timed out once on CI load; it was rerun and passes locally.
  • Real-app QA on macOS (M4Air), head eeac0fc, real Claude and Codex:
    • The ticket's refused resume: one start and one Codex notice, with no repeat. After the repair, the same thread replied.
    • Codex and Claude children killed inside the startup window each recovered with one retry, delivered once.
    • Claude: a new chat, then a resume after a graceful restart.
    • Stop while starting for Claude and Codex: no restart.
    • A Codex "open elsewhere" refusal: one start.
  • Real-app QA on Windows, head eeac0fc: OpenCode (ACP) and Pi, real CLIs. New chat and resume, one start each, the same conversation kept. A 41-turn OpenCode chat resumed in about 9 s.
  • Final reference comparison: clean, and every difference is labelled in the PR description.

Noticed, outside this PR (also on main):

  • A Codex chat created in Orca whose saved rollout later goes missing silently continues on a brand-new Codex thread, so earlier context is lost (codex-structured-launch-resolution.ts supersedeIfUnsaved). The ticket's route, an adopted conversation, refuses correctly.
  • The Codex refusal card says "Send your message to try again" for a refusal that will repeat, and each resend adds another identical card. Its Details show Codex's raw message, including a local file path.
  • New OpenCode and Pi chats default to a model that isn't usable on the machine.

For Brennan's review

Codex: ticket refusal, one start, one card Codex: after repair, same thread replies
codex-refusal-details.png codex-recovered.png
Codex: killed during startup, recovered once Claude: killed during startup, recovered once
codex-transient-recovered.png claude-transient-recovered.png
Claude: Stop while starting Codex: Stop while starting
claude-stop-while-starting.png codex-stop-while-starting.png
Claude: resume after restart OpenCode: long chat resume
claude-resume.png acp-long-resume.png
OpenCode: resume, same conversation Pi: resume, same conversation
acp-resume.png pi-resume.png

Spots where judgment matters:

brennanb2025 and others added 8 commits November 1, 2026 22:06
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Resolve the conflict with the saved-conversation startup outcome: the
session's open completion is now read from that outcome instead of a
separate opened flag, and an unexpected exit ends the start only after
any initialize answer it races has been delivered.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…eneric results

An exit with no stderr leaves the start to Claude's buffered result, so that result is the start's one failure. A generic startup failure result is final after one start; only an unanswered exit retries, and the recovery case now recovers from such an exit.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ported fault-first

The connection reports one physical root exit through onFault and then
onExit. It now marks that error as an observed exit before either
callback, and acquisition's onFault leaves a proven exit to onExit's
bounded initialize join, so a final initialize rejection that arrives
just after the exit owns the start instead of a retryable bare exit.
Typed refusals, live-root faults and processless spawn faults still end
the start at once.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…er start test

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…otation and guard

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Resolve the stdout tap conflict with #37246: the startup answer observer
becomes a chunk feeder behind the single reader-safe onStdout tap, which
feeds it until its first capture, send or close and then the connection's
own onStdout handler.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@brennanb2025
brennanb2025 marked this pull request as draft November 2, 2026 23:49
…the start one owner

A start that the agent refused could still be replayed: the host joined a
child's exit with its open's error and rebuilt the meaning from provider error
classes, and an answer written just before exit could lose to the exit itself.

Each adapter now answers its own acquire, open and required startup reads with
one typed result (final, or safe to run once more), keeping a final answer
beneath the exit proofs cleanup adds. Transports keep reading answers already
written after the agent stops reading or exits, within the existing one-second
drain, and only a drained exit of the agent's own process counts as unanswered.

The child's open is the single owner of the start's outcome: it awaits the
adapter's result and required settlement, records the verdict once, writes a
direct attach's failure row, and stops the child. The start flight reads that
verdict instead of joining exit and open. A start whose adapter gives no outcome
within five seconds of its own process exit fails through a timer that no
bookkeeping can hold, and the original start deadline stays in force until the
start is decided.

Tracked in STA-12982.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@brennanb2025
brennanb2025 marked this pull request as ready for review November 3, 2026 10:09
@brennanb2025
brennanb2025 marked this pull request as draft November 3, 2026 10:25
@brennanb2025
brennanb2025 marked this pull request as ready for review November 3, 2026 10:25
brennanb2025 and others added 2 commits November 3, 2026 03:00
…wn refusals final

- A start's ending is kept only while its owner can read it: admitted when the
  acquisition starts, retired when the owner finishes, the acquisition fails, or
  the session is released or closed. An exit after ready records nothing.
- Codex takes its own exit as the start's wake from the moment the process is
  seen, before spawn bookkeeping, and a failed acquire keeps that exit as cause.
- Once the handle or rewind write began, an unanswered death no longer decides
  the start: the write's refusal stays final, and the exit grace bounds the wait.
- Stop, the deadline and the exit grace release the start's callers at once; the
  failure row is queued first but never awaited by them.
- An ACP connection Orca closed before the exit keeps that cause, so cleanup's
  exit is not read as the agent ending unanswered.
- A request deadline keeps its words when an exit is seen around it.
- A direct attach whose exit settled first keeps the exit's words.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… retire its ending

Exit acknowledgment drops a session's route while the start's owner may
still be reading how its acquisition ended, so the router now reaches the
adapters by exact generation for both the read and the retirement. Claude
admits its acquisition before publication can observe an exit.

An ACP start Orca refused before the agent exited now fails with that
original refusal as the adapter's final verdict, through every cleanup
wrapper, instead of a generic closed-while-starting error.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
brennanb2025 and others added 6 commits November 3, 2026 04:01
Keeps main's prompt-close handling and input admission next to this
branch's typed start outcome in the ACP runtime and adapter, and trims one
line from the Codex adapter to stay within the file-length limit.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…yped start verdict

The host now reads only the adapter's verdict on a failed start, so the
fake open rejects with the verdict the Codex adapter returns for its
declared overload instead of the raw request error.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…DK reports as exited

A Claude CLI missing from the launch PATH makes the supervisor exit 127 with the spawn error on
stderr. The SDK rejects initialize with only "process exited with code 127", and the start took
that report as its cause, so the missing CLI was lost: the chat said Claude stopped before it
finished starting and the start was retried as an unanswered exit. The SDK's exit report is no
answer; the start now reads Orca's own record of that exit, which carries the missing CLI.

Also brings two ACP tests in line with the typed start verdict (a signed-out open rejects with
the adapter's notSignedIn verdict) and the bounded drain after the agent stops reading.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ilure is captured, and pin start and drain work at N and 10N

A failed root result captured mid-chunk still let the rest of that chunk be framed and parsed;
nothing reads those records once the start has its answer. The observer now accepts no further
line once it has captured the failure, and drops what that chunk left in its framing state.

Two contract tests drive the production start owner and transports at N and 10N:
- starts through the host, router and Codex adapter (ready, final refusal, safe replay, deadline
  expiry): each start's owner, abort handles, tracked attempt, flight, buffered exits, adapter
  receipts, root-exit subscription and deadline timer return to baseline, a waiting start holds
  a fixed set, and spawns, opens, router reads and retirements, timers and failure rows grow
  exactly linearly;
- ACP, JSON-lines and Codex connections with a pending call, answered at exit or abandoned after
  the agent stops reading (with duplicate terminal signals): each call settles once, each output
  drain finishes once and leaves no listener or timer;
- an ACP start refused at sign-in keeps its own first cause and leaves no receipt or child.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…apter saw

A failed start was decided from whichever error reached the decision first, so a later or
poorer report could replace the one that explained it: the SDK's exit report hid the missing
CLI Orca's own exit record carried, and an output drain let a load deadline give way to an
unanswered exit. One shared rule now weighs every observation an adapter kept. The start may
run again only if every observation allows it, and the most specific one explains it: what the
user can act on, then a request deadline, then the agent's answer, then Orca's record of its
exit, then an SDK's report of that exit. Claude, Codex and Pi pass their exit records alongside
the operation's error instead of choosing between them.

An ACP agent that exited while its output drained no longer gets a replacement session after
its load fails. JSON-lines output that reports both its end and its close now starts one wait,
so the agent's exit can always cancel it.

Contracts at N and 10N: JSON-lines output ending while its root lives, real Claude and Pi
adapters retiring every start's receipt, and a user Stop whose cleanup is held then released.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…g a replacement

A live agent that let session/load run past its deadline fell through to the
takeover path, and the replacement session/new answer then replaced the
deadline the user had to see. The takeover predicate now propagates any
provider request deadline unchanged, read through the existing typed timeout.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@brennanb2025
brennanb2025 merged commit d1d4ac3 into main Nov 3, 2026
101 of 104 checks passed
audichuang pushed a commit to audichuang/orca that referenced this pull request Nov 4, 2026
* Stop retrying final native agent startup refusals

* Retire startup opens after exit and keep final answers across exit orders

- A start flight cancels its outstanding provider open on every ended path; a direct attach keeps the child-bound abort.
- The post-exit answer join is bounded by the remaining startup ceiling.
- An elapsed initialize deadline keeps its words when the exit wins the race.
- Codex cloud config temporary declarations retry on thread/resume as on thread/start.
- A Claude exit before acquisition publishes waits briefly for initialize's answer, so a rejected initialize stays final.
- The Claude startup stdout observer parses only failed root results, within the shared line budget, and detaches once it has one.

* Keep saving the last turn when a Claude process exits after startup

The exit path skipped saving the resume cursor whenever Orca had not
dispatched a message, but turns can settle without an Orca dispatch and an
already-started idle session still owns its exit save. Only a start that
died before initialize answered and before any turn now skips the save and
gets the short cleanup bound. A failed result captured before the first send
counts as a startup failure only when no turn ran in that process.

* Merge duplicate test imports

* Bound resumed Claude starts that exit during catch-up and keep untyped refusals final

Exit-time cursor writes and the short close bound now key on the host-awaited
open actually returning, so a resume that exits while transcript catch-up is
pending publishes ended at once instead of waiting on a cursor write. The
startup observer no longer reads an answer from an oversized line's prefix.
A typed acquisition refusal without a dedicated failure kind keeps its
refusal marker, so an exit-only start stays final.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test: pin the fake clock in the resumed-exit start test

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test: bound startup answer parsing by candidates at N and 10N records

Drive the startup observer through the shared framer at 100 and 1000
irrelevant hook and assistant records, and assert that only the failed
root result is parsed, one capture happens, the data listener retires,
and no parse follows capture or finish, with identical counts at both
populations.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test: shape startup fixtures like the real providers

Held opens in the launch test now reject when their child exits, as a
real connection does, and the temporary open failures use the provider's
actual overload envelope. Also fixes the test-only type errors CI found.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test: use the real Codex canonical-filename refusal wire capture

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(claude): align merged startup tests with answer-wins and final generic results

An exit with no stderr leaves the start to Claude's buffered result, so that result is the start's one failure. A generic startup failure result is final after one start; only an unanswered exit retries, and the recovery case now recovers from such an exit.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(claude): let a final initialize answer outrank a physical exit reported fault-first

The connection reports one physical root exit through onFault and then
onExit. It now marks that error as an observed exit before either
callback, and acquisition's onFault leaves a proven exit to onExit's
bounded initialize join, so a final initialize rejection that arrives
just after the exit owns the start instead of a retryable bare exit.
Typed refusals, live-root faults and processless spawn faults still end
the start at once.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(claude): await a macrotask instead of real time in the exit-answer start test

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(claude): replace casts in the exit-answer start test with an annotation and guard

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(agent-session): let each adapter decide a failed start, and give the start one owner

A start that the agent refused could still be replayed: the host joined a
child's exit with its open's error and rebuilt the meaning from provider error
classes, and an answer written just before exit could lose to the exit itself.

Each adapter now answers its own acquire, open and required startup reads with
one typed result (final, or safe to run once more), keeping a final answer
beneath the exit proofs cleanup adds. Transports keep reading answers already
written after the agent stops reading or exits, within the existing one-second
drain, and only a drained exit of the agent's own process counts as unanswered.

The child's open is the single owner of the start's outcome: it awaits the
adapter's result and required settlement, records the verdict once, writes a
direct attach's failure row, and stops the child. The start flight reads that
verdict instead of joining exit and open. A start whose adapter gives no outcome
within five seconds of its own process exit fails through a timer that no
bookkeeping can hold, and the original start deadline stays in force until the
start is decided.

Tracked in STA-12982.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(agent-session): bound a failed start's lifetime and keep Orca's own refusals final

- A start's ending is kept only while its owner can read it: admitted when the
  acquisition starts, retired when the owner finishes, the acquisition fails, or
  the session is released or closed. An exit after ready records nothing.
- Codex takes its own exit as the start's wake from the moment the process is
  seen, before spawn bookkeeping, and a failed acquire keeps that exit as cause.
- Once the handle or rewind write began, an unanswered death no longer decides
  the start: the write's refusal stays final, and the exit grace bounds the wait.
- Stop, the deadline and the exit grace release the start's callers at once; the
  failure row is queued first but never awaited by them.
- An ACP connection Orca closed before the exit keeps that cause, so cleanup's
  exit is not read as the agent ending unanswered.
- A request deadline keeps its words when an exit is seen around it.
- A direct attach whose exit settled first keeps the exit's words.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(agent-session): let a start's owner, not its live route, keep and retire its ending

Exit acknowledgment drops a session's route while the start's owner may
still be reading how its acquisition ended, so the router now reaches the
adapters by exact generation for both the read and the retirement. Claude
admits its acquisition before publication can observe an exit.

An ACP start Orca refused before the agent exited now fails with that
original refusal as the adapter's final verdict, through every cleanup
wrapper, instead of a generic closed-while-starting error.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(agent-session): give the worker retry fake the Codex adapter's typed start verdict

The host now reads only the adapter's verdict on a failed start, so the
fake open rejects with the verdict the Codex adapter returns for its
declared overload instead of the raw request error.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(agent-session): let Claude's own exit record decide a start the SDK reports as exited

A Claude CLI missing from the launch PATH makes the supervisor exit 127 with the spawn error on
stderr. The SDK rejects initialize with only "process exited with code 127", and the start took
that report as its cause, so the missing CLI was lost: the chat said Claude stopped before it
finished starting and the start was retried as an unanswered exit. The SDK's exit report is no
answer; the start now reads Orca's own record of that exit, which carries the missing CLI.

Also brings two ACP tests in line with the typed start verdict (a signed-out open rejects with
the adapter's notSignedIn verdict) and the bounded drain after the agent stops reading.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* perf(agent-session): stop parsing Claude's startup output once its failure is captured, and pin start and drain work at N and 10N

A failed root result captured mid-chunk still let the rest of that chunk be framed and parsed;
nothing reads those records once the start has its answer. The observer now accepts no further
line once it has captured the failure, and drops what that chunk left in its framing state.

Two contract tests drive the production start owner and transports at N and 10N:
- starts through the host, router and Codex adapter (ready, final refusal, safe replay, deadline
  expiry): each start's owner, abort handles, tracked attempt, flight, buffered exits, adapter
  receipts, root-exit subscription and deadline timer return to baseline, a waiting start holds
  a fixed set, and spawns, opens, router reads and retirements, timers and failure rows grow
  exactly linearly;
- ACP, JSON-lines and Codex connections with a pending call, answered at exit or abandoned after
  the agent stops reading (with duplicate terminal signals): each call settles once, each output
  drain finishes once and leaves no listener or timer;
- an ACP start refused at sign-in keeps its own first cause and leaves no receipt or child.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(agent-session): decide a failed start once from everything its adapter saw

A failed start was decided from whichever error reached the decision first, so a later or
poorer report could replace the one that explained it: the SDK's exit report hid the missing
CLI Orca's own exit record carried, and an output drain let a load deadline give way to an
unanswered exit. One shared rule now weighs every observation an adapter kept. The start may
run again only if every observation allows it, and the most specific one explains it: what the
user can act on, then a request deadline, then the agent's answer, then Orca's record of its
exit, then an SDK's report of that exit. Claude, Codex and Pi pass their exit records alongside
the operation's error instead of choosing between them.

An ACP agent that exited while its output drained no longer gets a replacement session after
its load fails. JSON-lines output that reports both its end and its close now starts one wait,
so the agent's exit can always cancel it.

Contracts at N and 10N: JSON-lines output ending while its root lives, real Claude and Pi
adapters retiring every start's receipt, and a user Stop whose cleanup is held then released.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(acp): keep a missed saved-session load deadline instead of opening a replacement

A live agent that let session/load run past its deadline fell through to the
takeover path, and the replacement session/new answer then replaced the
deadline the user had to see. The takeover predicate now propagates any
provider request deadline unchanged, read through the existing typed timeout.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
(cherry picked from commit d1d4ac3)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant