[euclodius]

ELI5

#14624 fixes the normal detach/reattach path by lifting pane-retirement fences when a live PTY binds again. This PR adds the secondary safety net: if that attach signal was not observed on both sides, a real live new turn can reclaim the retired pane. Replays, malformed relay metadata, invalid payloads, declared-source mismatches, and closed-tab events remain blocked.

What Changed

• Reuse the shared source-aware new-turn classifier so Pi/OMP/Prime before_agent_start can identify a legitimate fallback restart.
• Preserve mixed-version relay compatibility: source remains optional, and a source-less legacy event is classified only after deriving a valid source from the canonical normalized payload.
• Reject a present invalid relay source; a malformed declaration cannot fall through to source-less authority.
• Require a declared relay source to match the normalized payload's agent type.
• Carry a one-shot authorityRestart signal from main to renderer and clear only the matching retired-pane tombstone.
• Reuse fix(agents): lift the pane retirement fence when a live PTY re-attaches (STA-4114) #14624's restorePaneAuthority fence restoration before emitting restart authority; closed-tab fences remain stronger.
• Retain exact closed-tab pane provenance beyond tab-ID LRU eviction so a late new turn cannot revive a pane from a closed tab.
• Move remote observation rebind and authority mutation after replay, metadata, payload, and source validation.
• Strip restart authority from persistence, startup snapshots, listener replay, and hydration.
• Preserve raw SSH relay replay metadata through mux routing so main remains the trust boundary.

Relationship to #14624

#14624 is the primary contract: authoritative PTY attach restores pane authority immediately, including idle and mid-turn reattach. This PR is complementary, not a replacement: it covers live-new-turn recovery when a remote relay or process restart did not produce an attach observation on both sides.

Linked Issue

Related to #14236; complements the merged fix in #14624.

Visual Proof

N/A — no UI layout changed. The behavior is an agent-hook authority transition. It was exercised through the real loopback HTTP server plus remote relay ingestion in the runtime smoke described below.

Testing

• Automated tests added/updated
• corepack pnpm exec vitest run --config config/vitest.config.ts src/main/agent-hooks/server-*.test.ts src/main/ssh/ssh-relay-session-agent-hooks.integration.test.ts src/renderer/src/hooks/useIpcEvents-agent-status-*.test.ts src/renderer/src/store/slices/agent-pane-authority.test.ts — 46 files, 415 tests passed
• corepack pnpm run typecheck:node — passed
• corepack pnpm run typecheck:web — passed
• corepack pnpm run check:code-quality:changed -- upstream/main — 0 new code-quality, type-aware, or React Doctor findings across 12 files
• oxfmt --check on all 12 changed files — passed
• Repository pre-commit hooks (oxlint, React Doctor oxlint, oxfmt) — passed
• Standalone AgentHookServer runtime smoke using the real HTTP listener and relay ingestion:
  • local OMP live new turn restored working and emitted authorityRestart
  • source-less validated relay restart restored working
  • malformed declared source remained suppressed
  • closed-tab restart remained suppressed
• Independent trust-boundary review found one malformed-source fallback defect; it was fixed and the re-review returned no blockers.
• Full project-wide lint, test, and build suites were not run locally; focused checks cover the changed contracts and CI can cover the remainder.

AI Disclosure

OpenAI Codex GPT-5.6 Sol via OMP was used to investigate, implement, rebase, test, review, and prepare this PR. CodeRabbit and a separate reviewer were used for review. All review-found trust-boundary defects were fixed before this update.

Review

• Security: restart authority is one-shot, removed from persistence/replay, committed only after validation, and denied to malformed, replayed, source-mismatched, or closed-tab events.
• Cross-platform: shared lifecycle logic is not path- or platform-specific.
• Remote/SSH: optional-source mixed-version behavior is preserved without treating invalid declared metadata as absent; fake relay/mux integration verifies raw replay metadata reaches main.
• Mobile: no mobile or layout surface changed.
• Backwards compatibility: source remains optional and authorityRestart is additive; existing valid status events retain their previous behavior.
• Performance: extra work is limited to rare retired-pane restart and tab-close paths; ordinary status handling is unchanged.

Checklist

• This PR is small and focused
• I explained what changed and why, including its relationship to fix(agents): lift the pane retirement fence when a live PTY re-attaches (STA-4114) #14624
• Visual proof is marked N/A with runtime verification rationale
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and backwards-compatibility impact considered
• Full pnpm lint, pnpm test, and pnpm build pass locally — focused checks passed; remaining coverage is left to CI

Author

• X / Twitter: not provided

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8bf9320d-2213-4217-9b69-dfe352e54825

📥 Commits

Reviewing files that changed from the base of the PR and between 81b7ca3cbe75999ae41faea5a1693e2902176b61 and bd9ad06.

📒 Files selected for processing (2)

• src/main/agent-hooks/server-closed-tab-suppression.test.ts
• src/main/agent-hooks/server.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• src/main/agent-hooks/server-closed-tab-suppression.test.ts
• src/main/agent-hooks/server.ts

Included review availability: Your plan includes up to 10 reviews per rolling hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds source-aware authority restart classification for agent hook events. Local and remote ingestion validate restart metadata, reopen eligible retired panes, and exclude the marker from persistence and replay. Main-process status events forward the marker to the renderer. Renderer state accepts only live authority restarts through retirement tombstones while preserving closed-tab suppression. Tests cover local, remote, SSH, and renderer restart flows.

Merge Risk: ⚪ Minimal · up to bd9ad

The PR adds narrowly scoped restart recovery while preserving validation and closed-tab protections; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary change: reviving retired panes during live new turns.
Description check	✅ Passed	The description covers the required sections, explains the change and rationale, links the related issue, and documents testing and scope.
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.

---

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

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8b2f77a4-015c-4948-accd-f94093eff121

📥 Commits

Reviewing files that changed from the base of the PR and between 2f0f9a8 and 81b7ca3cbe75999ae41faea5a1693e2902176b61.

📒 Files selected for processing (12)

• src/main/agent-hooks/server-closed-tab-suppression.test.ts
• src/main/agent-hooks/server.ts
• src/main/index.ts
• src/main/ssh/ssh-relay-session-agent-hooks.integration.test.ts
• src/main/ssh/ssh-relay-session.ts
• src/renderer/src/hooks/ipc-events-agent-status-store-test-fixtures.ts
• src/renderer/src/hooks/useIpcEvents-agent-status-pane-teardown.test.ts
• src/renderer/src/hooks/useIpcEvents.ts
• src/renderer/src/store/slices/agent-pane-authority.test.ts
• src/renderer/src/store/slices/agent-status.ts
• src/shared/agent-hook-listener.ts
• src/shared/agent-status-types.ts

🚧 Files skipped from review as they are similar to previous changes (10)

• src/main/ssh/ssh-relay-session-agent-hooks.integration.test.ts
• src/main/ssh/ssh-relay-session.ts
• src/renderer/src/store/slices/agent-pane-authority.test.ts
• src/renderer/src/hooks/useIpcEvents-agent-status-pane-teardown.test.ts
• src/renderer/src/hooks/ipc-events-agent-status-store-test-fixtures.ts
• src/main/index.ts
• src/shared/agent-status-types.ts
• src/renderer/src/hooks/useIpcEvents.ts
• src/renderer/src/store/slices/agent-status.ts
• src/shared/agent-hook-listener.ts

Included review availability: Your plan includes up to 10 reviews per rolling hour; 9 remain after this review.

[euclodius]

Follow-up on the scope of this pane-recovery safety net, based on current released builds rather than a new run of this PR.

With Windows Orca 1.4.224 paired to Linux headless Orca Server 1.4.224, a fresh OMP 18.10.4 turn running only sleep 45 lost its accepted working hook entry after a pane split. Later tool/turn completion hooks still received HTTP 204, but the host hook cache remained empty. Inspection of the installed runtime shows both unconditional command-finished launch-retirement paths.

This makes the distinction important: recovering a legitimately live new turn after retirement is complementary to preventing a false retirement during an existing turn. Accepting a future before_agent_start does not recover the already-running turn's suppressed completion or other status events. The current-turn trigger is covered by #24436/#26933 and the proposed #24732/#24196 fixes; remote client park/reveal retention is tracked separately in #15442/#15443.

I have not rebased or tested this branch against current main during this investigation and am not extending its fix claim. Any updated validation should preserve its replay/source/closed-tab fences and test the new-turn fallback separately from mid-turn authority retention.

Detailed isolated reproduction: comment on #24436.

---

AI assistance disclosure: prepared with an OpenAI coding assistant via OMP, using my reported behavior and local runtime diagnostics/source inspection. Reproduction and validation limits are stated above.