Skip to content

fix(terminal): reconcile restored dock tabs with the backend at hydrate - #11133

Merged
iamwhatever merged 1 commit into
mainfrom
fix/hydrate-reconcile-terminal-tabs-10977
Sep 16, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/hydrate-reconcile-terminal-tabs-10977

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

What

On reload, the dock terminal store now settles its restored tab list against the backend before any terminal view mounts. Restored tabs whose session GET /api/terminal/sessions omits, or reports alive: false, are dropped once a second, uncached look after the opening grace still misses them; the trimmed list is persisted and focus moves to a surviving tab. Tabs minted after boot are never candidates.

Why

loadPersisted (website/src/hooks/useBottomTerminal.ts) restored persisted tab ids without asking the backend which PTYs still exist. A tab leaked by a "Run in terminal" dispatch whose page closed before its rollback deadline (#10822, fixed in-page by #10859), or one whose shell the orphan reaper has since killed, came back on every reload — occupying a slot in the per-panel tab cap (the #10822 reporter saw 5 restored tabs, 3 already dead), and re-spawning a fresh shell the moment its view reconnected, because the WS route mints a PTY for an id it does not know. Item 1 of #10977.

How

  • useBottomTerminal.ts: the restored id set is captured at module init and flagged pending. The ruling takes two looks, the same protocol fix(chat): roll back the dock tab a failed run-in-terminal dispatch minted #10859 gave the dispatch-deadline probe and for the same reason: the sessions route skips the None placeholder a session holds from ws.prepare() until its shell spawns, so a session another window is opening right now reads exactly like one that never existed — and this store is shared across windows. reconcileRestoredTabs(first) names restored tabs the first answer omits or marks dead as suspects without dropping anything; confirmRestoredTabs(second), fed an uncached answer taken after RUN_IN_TERMINAL_OPENING_GRACE_MS, drops the suspects still missing and keeps the ones now listed live. Either look that cannot rule — request failure, unrecognized shape, or the feature-disabled reply (which returns an empty list without consulting the registry) — keeps every tab and settles: dropping a live shell's scrollback is irreversible, while a kept dead tab is user-closable and its registry entry is the reaper's to clear (it runs every 60 s). useTerminalHydratePending() / isTerminalHydratePending() expose the gate; __resetBottomTerminal clears it.
  • App.tsx: the terminal-enabled query already fetches /api/terminal/sessions at boot; an effect hands its result to the first look and, when there are suspects, waits the grace, fetches once more uncached, and hands that to the confirm look (null on any failure so a probe that never answers still settles). Both looks run under withDeadline (TERMINAL_PROBE_TIMEOUT_MS, 10 s): the panel stays gated until they settle, so a hung socket must be made to answer — past the bound it reads as a failed probe and keeps every tab (GPT round-2 advisory, fixed rather than dispositioned).
  • BottomTerminalPanel.tsx: TerminalTabsView renders nothing while the ruling is pending. This is required, not cosmetic: child effects run before parent effects, so a CliPanel mounted for a restored tab would open its socket — and spawn a shell — before the App-level probe fired, and the probe would then find the very shell it was asked about and keep the tab. Both hosts (dock and popout) share this view.

No DELETE is issued for alive: false entries: the reaper and the WS reconnect path already clear dead registry entries, so a client-side delete would be a second writer for the same fact.

Not in this PR (per the issue): item 2 (visible notice at the tab cap) belongs to #10120, which rewrites this hook and already carries the notice; item 3 (blind send into a confirmed-alive shell) is a readiness-contract question owned by #7638 / RFC #7649.

Tests

Run by path with npx vitest run <file>; all mutation-verified (fix reverted, test fails, fix restored).

  • src/test/useBottomTerminal.hydrateReconcile.test.ts (16): pending only when storage held tabs; the first look names absent and dead tabs as suspects and drops nothing; the confirm look drops the still-missing suspects with activeId refocus and the trimmed list persisted; a suspect the second look lists live is kept (the other-window-opening case); no suspects settles at once; all-gone hides the panel; a tab minted after boot survives both looks omitting it; five non-ruling first-look payloads keep every tab and settle; a non-ruling confirm keeps every suspect; settled sets cannot be reopened; a repeated first look while confirming is a no-op (query refetch); subscribers are notified per phase. Red on base: the module exported no reconciler.
  • src/test/BottomTerminalPanel.hydrateGate.test.tsx (2): no CliPanel and no tab strip while pending and while confirming, then only the kept tab mounts; every tab mounts when the first look could not rule. Boots the store fresh from seeded storage so the restored set is real. Red with the gate line removed.
  • src/test/App.terminalHydrateReconcile.test.tsx (4): both looks omit a tab → dropped, and at least two probes were made; first look omits, second lists live → kept; a confirm look that never answers (msw delay('infinite')) → settles after grace + deadline keeping every suspect; failing request → both kept. Red with the confirm drive replaced by an immediate drop, red with the deadline removed (the hang case runs out its 14 s wait), and red with the App effect removed (the panel would otherwise stay gated forever).
  • Existing terminal suites re-run green by path: App.terminalNavActive, App.terminalEnabledFlag, BottomTerminalPanel.cwd, BottomTerminalPanel.popout, ChatPageMoreCoverage, SidePanelLayout.bottomFloatTerminal, TerminalPopoutFrameCov80, terminalChordFocus, useBottomTerminal.viewportClamp, fenceShell (113 tests, 10 files).
  • npx tsc -b --force and npx eslint on the changed files: clean.

Pattern harvest

Rule candidate: review checklist. Pattern: a client that restores persisted references to server-side resources (tab ids, session ids) without a liveness check at hydrate — the persisted list is treated as truth for a resource the server owns. The two-look absence protocol (absent once is "opening or gone", absent twice across the opening grace is "gone") now exists in two places (dispatch deadline, hydrate); a third caller should extract it.

Other

Why no screenshot: the change adds or restyles no UI element. Every state it can produce already renders today — the dock with N tabs, or closed — so a screenshot would show an existing panel with fewer tabs. The user-visible delta is that tabs whose shells are gone no longer come back after a reload, plus a brief empty frame (two probe round-trips plus a 2 s grace, only when a restored tab is suspect) before the kept tabs mount. A popout window whose restored tabs are all gone returns itself to the main window, as it already does when its last tab closes.

Closes #10977

@CrysisDeu
CrysisDeu requested review from a team and Zedmor September 15, 2026 23:46
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 15, 2026
@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of da72c852f47a89f83f99f808bbd063f0397dbc48 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify a reloaded popout window with suspect tabs settles (dock tests cover the gate; the popout-reload path is only reasoned, not in the test list).

Suggestions

  • The two-look absence protocol now exists twice (dispatch deadline, hydrate) as the PR itself notes — extract it when the third caller appears, not before.

[DESIGN-REVIEWED] da72c85

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of da72c852f47a89f83f99f808bbd063f0397dbc48 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Verify the gated dock stays blank only imperceptibly on a real gateway — a hung probe leaves an empty frame, no feedback, for up to ~40s.

Suggestions

  • TerminalTabsView returns bare null while hydratePending; render a muted skeleton strip (or spinner) instead, since the persisted-open dock shows an empty frame — and offers no new-tab affordance — until both probes settle.

[UX-REVIEWED] da72c85

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 5.6 flagged blocking issues on da72c852f47a89f83f99f808bbd063f0397dbc48; Opus 4.8 adjudication downgraded every one of them to advisory. Adjudication downgraded all 1 blocking finding(s) to advisory: the remedy each one requires is disproportionate to the harm it prevents. Read them as advice, not as merge conditions.

This comment is updated in place on each push.

Review details

BLOCKING -- website/src/App.tsx:1375 -- Hydrate probe failures have no error surface
} catch { /* null: the confirm look could not rule, so every suspect stays */ }
Timeout or failed request -> probe fallback keeps stale tabs -> user receives no failure notice or agent hand-off.
Anchor: errors-use-error-notice
Fix: retain keep-all behavior but render the probe failure through ErrorNotice with askAgent.
[BLOCK-MERGE-DOWNGRADED] da72c85
[GPT-REVIEWED] da72c85

Adjudication (Opus 4.8) — is blocking on each finding proportionate?

I have what I need. Let me record my analysis.

F1 analysis — The catch block at website/src/App.tsx:1375 swallows a failure of the second (confirm) terminal probe and, via confirmRestoredTabs(null), keeps every suspect tab (useBottomTerminal.ts:204-212, live === null → dropped = [] → settle). The finding is anchored to errors-use-error-notice (blocking:true, AUTOSDE.yaml:526-527).

Checking whether the blocking rule actually anchors: the rule governs how an error that is shown to the user renders, and its blocking triggers are (a) a hand-written error surface, or (b) a touched/added ErrorNotice missing a hand-off decision (AUTOSDE.yaml:576-584). Here there is neither — no error surface exists at all; the failure is deliberately swallowed into the fail-safe keep-all path. The rule does not mandate that every caught exception produce a surface. So the blocking trigger is not met and autosde-blocking-rule does not apply; this reduces to a design opinion to add a new surface.

Weighing it:

  • Conditions: page reload with restored tabs whose sessions the first probe omits (App.tsx:1366, useBottomTerminal.ts:190-196), AND the second uncached probe throws/times out within its deadline (App.tsx:1372-1375).
  • System behavior on failure: confirmRestoredTabs(null) keeps all suspects and settles (useBottomTerminal.ts:204-212) — the deliberate safe outcome (no false removal). Recovery: next hydrate re-probes; a user touching a dead tab sees it dead and reconnects. Self-correcting, visible.
  • Harm rung LOW: a missing notification on a kept, visible, self-correcting tab set after a transient hydrate-time probe blip; no data loss. Remedy (new failure-tracking state + an ErrorNotice rendering path in the bottom-terminal store/hook for a condition the design already handles by keeping tabs) carries permanent maintenance load that exceeds this harm.

LOW harm; conditions confirmed at App.tsx:1366,1372-1375 + useBottomTerminal.ts:190-212; recovery is keep-all fail-safe + next-load re-probe. Real fix adds a bespoke error-surface path for a benign, self-correcting transient — cost exceeds harm.

[ADJUDICATION] da72c852f47a89f83f99f808bbd063f0397dbc48 total=1 uphold=0 downgrade=1
DOWNGRADE F1 website/src/App.tsx:1375 reason=disproportionate-remedy
[GPT-ADJUDICATED] da72c852f47a89f83f99f808bbd063f0397dbc48

False positive or not applicable? A repository writer can comment:
/ai-review override gpt da72c852f47a89f83f99f808bbd063f0397dbc48: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of da72c852f47a89f83f99f808bbd063f0397dbc48 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

Fix lands only in the dock store — usePanelTabs restores persisted terminal ids the same way, so dead side-panel tabs still respawn shells on reload.

Not justified as shipped

  • Item 1 — symptom-level (point patch, cause in scope elsewhere): the root cause — persisted client ids for server-owned PTYs restored with no liveness check, against a WS route that mints a PTY for an unknown id (terminal.py:1368-1565) — has 1 counted unfixed sibling: website/src/hooks/usePanelTabs.ts persists sessionId and its own comment says "terminal tabs reconnect to the still-live PTY" (lines 266, 449). The description defers Reconcile persisted terminal dock tabs with the backend at hydrate time #10977 items 2/3 to named owners but names no owner for this sibling; the pattern-harvest section admits the class.
    Clears when: a linked issue owns the side-panel restored-tab liveness check, or this reconcile covers usePanelTabs.
  • Item 7 — zero consumers: isTerminalHydratePending (useBottomTerminal.ts:399) has 0 non-test consumers (grepped; 3 test files only) and repeats getHydratePendingSnapshot's body one line above.
    Subtraction: delete isTerminalHydratePending; tests poll useTerminalHydratePending via renderHook.
    Clears when: the export is deleted or a non-test consumer exists.

What this change ships

Inventory (7 items) — 5 justified

Intent: stop dead persisted dock terminal tabs from coming back — and respawning shells — on reload; a FIX (#10977, #10822).

  1. Dead restored dock tabs dropped after reload; trimmed list persisted, focus refocused — symptom-level: point patch, sibling in usePanelTabs.ts
  2. Restored tabs and strip hidden (brief blank frame) until the backend rules — justified
  3. Second uncached probe after 2 s grace when a restored tab is suspect — justified
  4. Boot terminal-enabled probe now bounded at 10 s instead of hanging — justified
  5. Any probe failure or malformed answer keeps every tab — justified
  6. Store exports wiring the two looks and the pending gate (one counted consumer each) — justified
  7. Test-poll export isTerminalHydratePending — zero consumers: tests only, duplicates the snapshot fn

[FIRST-PRINCIPLES-REVIEWED] da72c85

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed da72c852f47a89f83f99f808bbd063f0397dbc48 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] da72c85

Verdict parsed from the review's SHA-scoped output markers for commit da72c852f47a89f83f99f808bbd063f0397dbc48.

False positive or not applicable? A repository writer can comment:
/ai-review override fable da72c852f47a89f83f99f808bbd063f0397dbc48: <one-sentence reason>

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 16, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/hydrate-reconcile-terminal-tabs-10977 branch from abc7bff to 0cb1d63 Compare September 16, 2026 00:12
@CrysisDeu CrysisDeu added the no-screenshots PR has no visual delta; screenshot gate exempt label Sep 16, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 16, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

CI note on 0cb1d63d2: Pod Boot Canary (Windows) failed with the recurring pod down residue flake ([WinError 32] The process cannot access the file … kcboot….KiroCrew.cmd; test_a_real_pod_boots_under_task_scheduler_and_leaves_nothing_behind). This PR touches only website/src and its tests, so the canary cannot be exercising this change. Re-ran only the failed job of CI run 35039030121; every other CI job on this head is green and is not replaced.

The stale Security Scope Review failure entry belongs to run 35039030156, which the no-screenshots label event superseded; its successor 35039057673 is green.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 16, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

CI note on 0cb1d63d2: GPT 5.6 Review failed closed with no findings — both review passes ended in stream disconnected before completion: idle timeout waiting for SSE, so no [GPT-REVIEWED] marker was written and the lane's own message asks for a re-run. Re-ran only that lane's run (35039030079, attempt 2). It replaces nothing but its own incomplete attempt; no other lane on this head is touched.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 16, 2026
`loadPersisted` restored the dock terminal tab list without asking the
backend which PTY sessions still exist. A tab leaked by a "Run in terminal"
dispatch whose page closed before its rollback deadline (#10822), or one
whose shell the orphan reaper has since killed, therefore came back on every
reload — holding a slot in the per-panel tab cap and, the moment its view
reconnected, minting a fresh shell nobody asked for (the WS route spawns a
PTY for an id it does not know).

The store now marks the restored set as pending at module init and rules on
it against `GET /api/terminal/sessions`, which App already fetches at boot.
The ruling takes two looks, the protocol #10859 gave the dispatch-deadline
probe: the route skips the placeholder a session holds until its shell
spawns, so a session another window is opening reads like one that never
existed, and this store is shared across windows. The first answer only
names suspects (absent or `alive: false`); an uncached second answer after
the opening grace drops the ones still missing and keeps the ones now live.
The trimmed list is persisted and focus moves to a survivor. An answer that
does not rule — request failure, unrecognized shape, or the feature-disabled
reply, which returns an empty list without consulting the registry — keeps
every tab, since removing a live shell's scrollback cannot be undone while a
kept dead tab is user-closable and reaped server-side. Tabs minted after
boot are never candidates.

Both looks run under a deadline: the panel stays gated until they settle,
so a socket that never answers must be made to answer, and past the bound
it reads as a failed probe that keeps every tab.

`TerminalTabsView` draws nothing while the ruling is pending. Effect order
made that necessary rather than cosmetic: a CliPanel mounted for a restored
tab opens its socket before the App-level probe fires, so the probe would
find the very shell it was asked about and keep the tab.

Closes #10977
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 16, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/hydrate-reconcile-terminal-tabs-10977 branch from 0cb1d63 to da72c85 Compare September 16, 2026 01:55
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

CI note on da72c852f: Build Windows Installer (x64) failed in the post-install smoke test (test-windows-installer.ps1:445, "Silent uninstall left a KiroCrew registration behind") after the install and gateway-ready steps had passed. This PR touches only website/src and its tests, and the same job failed the same way on an unrelated PR's Build run earlier tonight (35044009607) while main's Build runs are green, so this is the uninstall smoke test's intermittent registry-residue failure, not this change. Re-ran only the failed job of Build run 35045990490 (attempt 2); no other job on this head is replaced.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • Item 7 — zero consumers: isTerminalHydratePending (span=1a15c2c7c6be) — Rebut. The file already pairs each hook with an imperative twin for non-React callers (useBottomTerminalOpen / isBottomTerminalOpen, documented there for terminalChordFocus.ts); isTerminalHydratePending follows that convention. Its three consumers are the store, gate and App tests, which poll the phase across a real fetch cycle (grace + deadline, up to 12 s) — a renderHook there would wrap every poll in act() for a value the store can answer directly. Deleting it would add test noise to remove a one-line getter.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • Hydrate probe failures have no error surface (span=1461f955f94d) — Rebut, in line with the adjudication. The failure path is the fail-safe: every tab is kept, nothing is lost, and a kept dead tab shows its state the moment it is touched. Nobody asked for anything at boot, so there is no request to report a failure against; the same query's pre-existing !r.ok -> { enabled: true } branch already stays silent on this exact probe for the same reason. A boot-time notice for a transient, self-correcting condition would greet every offline launch with an error about a list the user never asked for.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • TerminalTabsView returns bare null while pending; render a skeleton strip instead (span=838890ee6fd1) — Accept and defer. The blank window is one probe round-trip against an in-memory registry when no restored tab is suspect, and grace plus one more probe (about 2 s) only when one is. A skeleton strip is a new rendered element that needs its own design and evidence; if the wait proves visible in practice it belongs in a follow-up with a screenshot, not as a rider here.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 16, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

CI note on da72c852f: Backend Tests (Windows) (5) was cancelled by the job's 40-minute cap (01:56 → 02:36) while its pytest step was still advancing (progress markers to case 10409, memory-store suites, no failure). The seven sibling shards finished in 17–22 minutes on the same head, so this is a slow runner, not a hang and not this frontend-only change. Re-ran only that job (CI run 35045990424, attempt 2); the other 69 green checks on this head are untouched.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 16, 2026

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

Approved after a full read of the diff on the current head: the change matches the linked issue and body, every load-bearing claim was spot-checked against main, tests pin the behaviour, all review lanes are clean and nothing is left undisposed on this head.

@iamwhatever
iamwhatever enabled auto-merge (squash) September 16, 2026 05:22
@iamwhatever
iamwhatever merged commit cf5b27d into main Sep 16, 2026
120 of 122 checks passed
@iamwhatever
iamwhatever deleted the fix/hydrate-reconcile-terminal-tabs-10977 branch September 16, 2026 05:23
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 16, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…te (kirodotdev#11133)

`loadPersisted` restored the dock terminal tab list without asking the
backend which PTY sessions still exist. A tab leaked by a "Run in terminal"
dispatch whose page closed before its rollback deadline (kirodotdev#10822), or one
whose shell the orphan reaper has since killed, therefore came back on every
reload — holding a slot in the per-panel tab cap and, the moment its view
reconnected, minting a fresh shell nobody asked for (the WS route spawns a
PTY for an id it does not know).

The store now marks the restored set as pending at module init and rules on
it against `GET /api/terminal/sessions`, which App already fetches at boot.
The ruling takes two looks, the protocol kirodotdev#10859 gave the dispatch-deadline
probe: the route skips the placeholder a session holds until its shell
spawns, so a session another window is opening reads like one that never
existed, and this store is shared across windows. The first answer only
names suspects (absent or `alive: false`); an uncached second answer after
the opening grace drops the ones still missing and keeps the ones now live.
The trimmed list is persisted and focus moves to a survivor. An answer that
does not rule — request failure, unrecognized shape, or the feature-disabled
reply, which returns an empty list without consulting the registry — keeps
every tab, since removing a live shell's scrollback cannot be undone while a
kept dead tab is user-closable and reaped server-side. Tabs minted after
boot are never candidates.

Both looks run under a deadline: the panel stays gated until they settle,
so a socket that never answers must be made to answer, and past the bound
it reads as a failed probe that keeps every tab.

`TerminalTabsView` draws nothing while the ruling is pending. Effect order
made that necessary rather than cosmetic: a CliPanel mounted for a restored
tab opens its socket before the App-level probe fires, so the probe would
find the very shell it was asked about and keep the tab.

Closes kirodotdev#10977
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-screenshots PR has no visual delta; screenshot gate exempt

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Reconcile persisted terminal dock tabs with the backend at hydrate time

2 participants