Skip to content

fix(agent-status): settle killed Claude background helpers - #35930

Merged
brennanb2025 merged 15 commits into
mainfrom
brennanb2025/lu-claude-helper-kill
Oct 30, 2026
Merged

brennanb2025 merged 15 commits into
mainfrom
brennanb2025/lu-claude-helper-kill

Conversation

@brennanb2025

@brennanb2025 brennanb2025 commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 9 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​2597 $\color{#cf222e}{\Huge{\mathbf{−}}}$​2 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​2595
Prod 16 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​1144 $\color{#cf222e}{\Huge{\mathbf{−}}}$​25 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​1119

Problem and result

Claude can kill a background helper without sending a hook, leaving Orca showing Working. Orca now reads Claude’s own lifecycle evidence on the execution host and settles that helper through the existing status store. Surviving shells, parent results and unrelated waits remain intact.

Tracked in STA-10196.

Implementation

The passive observer reads transcripts asynchronously in bounded forward chunks. One semantic decoder validates complete records before applying lifecycle facts and retains validated records and prepared operation progress until acknowledgement. Genuine generation evidence protects newer work from older kill records. Missing or unreadable evidence never proves death.

Observation follows admitted runtime hooks and starts when the existing host is ready. Valid recovered hooks retain their original admission boundary; status snapshots alone do not recreate observation. Native Windows failed HTTP deliveries have no saved-hook spool, unchanged by this PR. Independent provider scheduler instances prevent another provider from evicting Claude observations. Retirement releases observation and scheduler resources.

There are no new saved or wire fields, settings, reader caches or reader precedence. Desktop integration is additive in the existing retries seam; server-claude-status-rules.ts is unchanged. The common pattern derives provider-owned work from provider lifecycle evidence. Intended differences preserve user-typed commands and aliases, independently updated hosts and guest-only file access; updated hosts publish the existing status event shape.

Verification

Full path: lifecycle, ownership, recovery, ordering and cross-host publication. Six behavioral rounds ended with a three-seat DESIGN-READY / KEEP decision and the final decoder/checkpoint repair accepted at production head 4b7d728dbf3bf853f87fe578cf47d768b213ba96. The panel explicitly settled the test-growth tripwire. Final independent source, whole-mechanism reference and performance audits found no new proven defect. Optional test consolidation and diagnostic improvements remain deferred.

  • Implementation validation passed 73 distinct tests across seven named files; independent final repair review passed 16 overlapping checkpoint tests. Production-loop tests cover complete-record validation, generation ordering, wait/debt settlement, retry, readiness and cleanup. Fixtures include scrubbed real Claude Code 2.1.310 output.
  • Test-only commit 9ee31b446cc19805ade25a3f80a070177688b6a7 repairs two CI test-code errors. Its 21 targeted tests passed, and independent verification confirmed unchanged production and test behavior. Current-head CI completed with 51 checks passed and 13 skipped. Skipped e2e and real-WSL jobs are not app evidence. Main was synced once before final QA.
  • Final-production SSH QA used real Claude 2.1.314 and Codex 0.165.0: previous-build conversation through graceful desktop quit and same-session restoration; verified activation of the branch execution server and a normal saved-session resume with a real reply; authentic helper kill with no second kill, surviving root and independent shell, and a real follow-up; independent Claude/Codex panes simultaneously Working and returning real replies; live helper work between Disconnect/Connect click starts 56.206 seconds apart, unchanged process identities, reconnect and natural settlement. The lead’s transcript extraction counted 27 helper tool calls in that interval; exported first/last tool times corroborate continued work. Codex waited for approval until reconnect.
  • Retained Windows/WSL evidence covers unchanged platform flows: genuine guest/native helper kills, root/shell preservation, real follow-ups, graceful upgrade and a distinct stop-all action. Stop-all required temporarily correcting a conflicting shortcut through Settings in the disposable profile, then restoring it. This does not claim the default shortcut was fixed. Those earlier runs do not independently validate the final decoder.

Not exercised: real failed-hook ordering R<K<S could not be reached through the tested supported controls. Normal quit removes the supported input route, and the bounded real TaskStop probe emitted no agents_killed record; no failed-hook recovery pass is claimed. Deterministic recovery/order tests remain the evidence for that branch. Same-ID helper continuation was refused by the real provider and is separately not exercisable. Neither case used fabricated live records.

SSH parent status can remain Working after a reply: pre-existing on main; tracked in STA-13015. Branch host settlement was verified; the actual killed-helper removal reached the client. No pass is claimed for that separate parent-display gap. Baseline also settled helpers, so QA did not reproduce the original stale-helper symptom.

N/10N contracts measure decoder/admission/cleanup work and retained dimensions, without claiming fixed total heap, five-second backlog catch-up, infinite-writer completion or naturally persistent failure recovery. The existing notification wakeup held final shared aggregate status for about 60 seconds before both providers settled. QA deviations and cleanup are recorded in the private evidence reports.

Visual proof

The loop’s single status comment contains baseline and branch captures for upgrade, helper settlement, shared status, reconnect and retained Windows flows. The change uses existing status UI and adds no visible control or message.

Agent skill upstream boundary

  • Not applicable; this change copies or mechanically translates no upstream skill-installer material.

@brennanb2025
brennanb2025 marked this pull request as ready for review October 29, 2026 12:09
@greptile-apps

greptile-apps Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 4/5

[Medium impact] The change affects Claude status reporting on desktop and WSL guest execution hosts.

The PR should not merge while an unfinished transcript record can cause a live helper to disappear.

Findings

  1. P1 Live helper can disappear ▶
  2. P2 Helper history keeps growing ▶

Summary

The PR reads Claude’s transcript evidence on the execution host to settle killed background helpers through existing status updates.

  • Claude’s killed helpers stop keeping Orca’s status in Working.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Accepted local Claude hook] --> B[Capture session observation]
  B --> C{Host ready and helper working?}
  C -->|Yes| D[Read parent transcript]
  D --> E{Kill evidence found?}
  E -->|Yes| F[Read child generation evidence]
  F --> G{Child generation predates kill?}
  G -->|Yes| H[Settle child and publish status]
  G -->|No| I[Keep child working]
Loading

Reviews (8) · Last reviewed commit: "test(agent-status): consolidate listener..." · Reviewed by Greptile

@coderabbitai

coderabbitai Bot commented Oct 29, 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.

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: 609adaea-64b5-4cbc-98ea-ca8f4e19330e
Commits

Reviewing files that changed from the base of the PR and between 8513170 and 390c508.

Files selected for processing: 2
  • src/main/agent-hooks/claude-helper-scheduler-coexistence.test.ts
  • src/main/agent-hooks/server-claude-helper-recovery.test.ts

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

Walkthrough

Adds a Claude helper poller that reads local parent and child transcripts and applies qualifying kill evidence to pane state. Desktop and WSL schedulers route Claude events to the poller and clear its polls with transcript polling. Tests cover helper retirement, parent state preservation, notification and wait updates, scheduler coexistence, replay, persistence, and renderer projections.

Merge Risk: Low · up to 390c5

Large transcripts may leave terminated helpers showing Working longer than expected, and relay recovery may lose useful environment diagnostics. These are bounded follow-up risks rather than release-blocking failures.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 12.50% 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 accurately and concisely describes the primary change: settling killed Claude background helpers.
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 detailed and covers the problem, implementation, rationale, linked issue, testing evidence, limitations, visual impact, and upstream-boundary declaration. It does not reproduce ever…
Full details: Description check

Explanation

The description is detailed and covers the problem, implementation, rationale, linked issue, testing evidence, limitations, visual impact, and upstream-boundary declaration. It does not reproduce every template heading or checklist item, and the visual section does not use the exact N/A wording, but the required information is mostly present.

Full details: Docstring Coverage

Explanation

Docstring coverage is 12.50% 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 16 functions across 18 files.

Resolution

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

Finishing Touches: 💡 1
📝 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

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

@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.

Actionable comments posted: 2


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: 2a7b7479-5436-4bce-8461-2c3a34f5796e
Commits

Reviewing files that changed from the base of the PR and between 43ed987 and e812b91.

Files selected for processing: 10
  • src/main/agent-hooks/claude-helper-scheduler-coexistence.test.ts
  • src/main/agent-hooks/server-claude-helper-kill.test.ts
  • src/main/agent-hooks/server/server-status-retries.ts
  • src/shared/__fixtures__/claude-helper-kill-2.1.310.json
  • src/shared/agent-hook-listener/providers/claude-helper-kill-poller.ts
  • src/shared/agent-hook-listener/providers/claude-helper-kill.test.ts
  • src/shared/agent-hook-listener/providers/claude-helper-transcript-evidence.ts
  • src/shared/agent-hook-listener/providers/claude-transcript-cursor.ts
  • src/shared/claude-owed-task-notifications.ts
  • src/wsl-guest/agent-hook-result-retry-scheduler.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 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.

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (1)

Minor · Keep the stored env and version when the… · agent-hook-result-retry-scheduler.ts:57-59

src/wsl-guest/agent-hook-result-retry-scheduler.ts:57-59
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Keep the stored env and version when the helper-kill poller publishes.

The poller's publish calls host.applyEvent(event, 'claude') without env or version. applyRelayHookEvent then replaces the pane's metadata entry with { source, env: undefined, version: undefined, claudeSettledRequests }. The expiry, transcript-poll, and assistant-message publishes pass env and version, so this publish is the only one that clears them.

After a helper kill settles, two outputs lose the values:

  • the forwarded envelope built by buildRelayHookEnvelope;
  • every later cached replay, because buildCachedPaneReplayEnvelope reads meta.env and meta.version.

Desktop ingest passes envelope.version and envelope.env to warnOnHookEnvOrVersionMismatch. The body of that function was not inspected, so the effect of the cleared values there is not established.

Pass the stored metadata through the publish. Add an optional lookup to the host type and supply it from the relay server:

Proposed fix (host lookup)
 export type AgentHookResultRetryHost = {
   state: HookListenerState
   env: string
   isListening: () => boolean
+  getEnvelopeMeta?: (paneKey: string) => { env?: string; version?: string } | undefined
   applyEvent: (
@@
       publish: (event) => {
-        host.applyEvent(event, 'claude')
+        const meta = host.getEnvelopeMeta?.(event.paneKey)
+        host.applyEvent(event, 'claude', meta?.env, meta?.version)
       },

In RelayAgentHookServer, add getEnvelopeMeta: (paneKey) => this.lastEnvelopeMetaByPaneKey.get(paneKey) to the retry host object.


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: 58855f72-c8bd-411b-9518-760d09536ace
Commits

Reviewing files that changed from the base of the PR and between 764ab81 and 0ea20ea.

Files selected for processing: 12
  • src/main/agent-hooks/claude-helper-scheduler-coexistence.test.ts
  • src/main/agent-hooks/server-claude-helper-recovery.test.ts
  • src/main/agent-hooks/server/server-ingest-normalization.ts
  • src/main/agent-hooks/server/server-lifecycle.ts
  • src/main/agent-hooks/server/server-status-hook-lifecycle.ts
  • src/main/agent-hooks/server/server-status-retries.ts
  • src/shared/agent-hook-listener/providers/claude-helper-kill-poller.ts
  • src/wsl-guest/agent-hook-event-admission.ts
  • src/wsl-guest/agent-hook-request.ts
  • src/wsl-guest/agent-hook-result-retry-scheduler.ts
  • src/wsl-guest/agent-hook-server.ts
  • src/wsl-guest/agent-hook-spool-ingest.ts

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

@brennanb2025

brennanb2025 commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor Author

Review status: complete — six rounds, scoped real-provider QA and current-head CI verified.

Claude can kill a background helper without sending a hook, leaving Orca showing Working. This patch derives helper settlement from Claude’s lifecycle evidence on the execution host, through the existing status store, while preserving parent results, independent shells and unrelated waits.

Six behavioral rounds ended with the final three-seat DESIGN-READY / KEEP ruling and C9 repaired at production head 4b7d728dbf3bf853f87fe578cf47d768b213ba96. Complete-record validation and acknowledged application progress cover partial input, newer generations and recoverable rejection. No new saved/wire field, reader cache or permanent unknown state was added. The final source/reference/performance audits found no new proven defect; optional test consolidation and diagnostic improvements remain deferred.

Implementation validation passed 73 distinct tests across seven named files; independent repair review passed 16 overlapping checkpoint tests. The later test-only commit 9ee31b446cc19805ade25a3f80a070177688b6a7 repaired two CI test-code errors, passed 21 targeted tests and leaves production unchanged. Current-head CI finished: 51 passed, 13 skipped, including configured e2e/real-WSL skips. Main was synced once before final QA. All five review threads are resolved.

Real final-production SSH QA with Claude 2.1.314 and Codex 0.165.0 verified:

  • A previous-build conversation survived graceful desktop quit and branch-client restoration to the same session with a real reply. Normal terminal exit/reconnect activated the branch server, verified by running process, active slot and bundle hash; normal saved-session resume produced another real reply.
  • An authentic Working helper was killed with one provider kill record and no second kill. Its removal reached the client; the root and independent shell survived, and a real follow-up succeeded.
  • Independent Claude/Codex panes were simultaneously Working and both returned real replies. Disconnect and Connect click starts were 56.206 seconds apart. The lead’s transcript extraction counted 27 helper tool calls in that interval, with exported first/last tool times corroborating continued work; process identities stayed unchanged and reconnect showed it alive. Codex waited for approval during the outage and completed after it was answered. Natural completion settled through host-authored status; the existing notification wakeup held the aggregate for about 60 seconds before both providers showed Done.

Retained Windows/WSL QA covers unchanged platform flows: genuine guest/native helper kills, root/shell preservation, follow-ups, graceful upgrade and distinct stop-all. Stop-all required a temporary Settings shortcut correction in the disposable profile, restored afterward; no default-shortcut fix is claimed. Earlier Windows runs do not independently validate the final decoder. Baseline also settled helpers, so the reported stale-helper symptom was not reproduced.

Not exercised: real failed-hook R<K<S was unreachable through the tested supported route: normal quit removes supported terminal input, and the bounded real TaskStop probe emitted no agents_killed. Deterministic production-loop recovery/order tests cover that branch; no real recovery pass is claimed. Same-ID helper continuation was separately refused by the real provider and remains not exercisable. No fabricated live hook or transcript was used.

SSH parent status can remain Working after a reply: pre-existing on main; tracked in STA-13015. Branch host settlement and actual killed-helper removal were verified; this does not pass the separate parent-display gap. Finite-backlog latency, fixed aggregate heap, infinite-writer completion and naturally persistent failure recovery are not claimed.

QA evidence: private report ~/orca-qa/pr-35930/qa3624-final-report.md, independently checked exports/audit in ~/orca-qa/pr-35930/final-qa-evidence-audit.md. All owned test processes and disposable runtime resources were cleaned up; retained build/evidence worktrees remain available. The report records procedural deviations and a changed real Claude-config hash; config contents were not read.

For Brennan’s review

Previous-build reply, carried through graceful upgrade and normal resume:

Previous-build Claude reply
Branch server normal saved-session resume and reply

Final branch: helper Working, then killed with shell and parent preserved:

SSH helper Working
SSH helper removed and shell alive

Independent shared-provider work and reconnect while the helper remained live:

Claude and Codex Working
SSH reconnect with live helper

Retained native Windows kill and distinct stop-all evidence, scoped to unchanged platform flows:

Native Windows helper removed
Distinct stop-all outcome

Retained WSL baseline and branch helper settlement (the baseline also settled):

WSL baseline after helper kill
WSL branch helper removed and shell alive

Human judgment spots: complete-record validation and acknowledgement, semantic completion, exact helper settlement and publication.

QA’d production head: 4b7d728dbf3bf853f87fe578cf47d768b213ba96. Later commit 9ee31b446cc19805ade25a3f80a070177688b6a7 changes only two test files; CI passed on that current head.

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