feat(btw): retain native side sessions

packages/coding-agent/CHANGELOG.md

@@ -11,8 +11,55 @@
 - Assistant text painted during smooth streaming no longer vanishes and bursts back: `syncTrailingAssistantText` now yields the streaming head to the reveal controller while it paces (smooth streaming on, no toolCall in the head), so the paced prefix and the full head can no longer overwrite each other mid-stream ([#1102](https://github.com/code-yeongyu/senpi/pull/1102)).
 - The goal continuation wait countdown no longer renders over the Working indicator during externally started turns; the `goal-wait` footer segment now hides while a turn runs and restores itself when the session parks again, leaving the cache-warm schedule and iteration accounting untouched ([#1100](https://github.com/code-yeongyu/senpi/pull/1100)).
 - Webfetch now safely discards redirect response bodies under Bun 1.4.0's bare `undici`, which may omit `body.dump()`, by falling back to argument-free stream destruction instead of re-emitting cleanup failures as uncaught stream errors ([#1089](https://github.com/code-yeongyu/senpi/issues/1089)).
-
-### Added
+- Retained BTW picker switches now revalidate the selected session after asynchronous pre-switch
+  guards, preventing a replaced JSONL path from opening an unrelated session.
+- Direct BTW returns and catalog discovery now reject path-reused Main or active-side session
+  files before switching, snapshotting, or deleting.
+- Retained BTW creation and switching now revalidate parent and destination identities after
+  asynchronous veto and shutdown hooks, preventing stale session managers from being applied.
+- Identity cancellations after shutdown now leave a rebound live runtime, and retained parent
+  checks use bounded session headers instead of loading complete transcripts.
+- Cancellation recovery preserves the outgoing session identity, tree, and effective cwd, while
+  new/resume destinations are revalidated again after asynchronous runtime construction.
+- Stale candidate runtimes now run shutdown hooks before disposal, and recovered persisted sessions
+  are revalidated after construction before the host rebinds them.
+- Retained replacements now revalidate after removed-extension handlers and cancel when source
+  activity or tree generation changes during asynchronous switch vetoes.
+- Streaming Ctrl+C close remains destructive, while guarded teardown prevents any later prompt
+  from starting on the outgoing session during shutdown handlers.
+- Streaming-origin BTW closes now track prompt-admission generation, preventing later queued or
+  direct submissions during asynchronous switch vetoes from being aborted.
+- Guarded replacements now revalidate after host rebind before callbacks, and typed extension
+  command hosts inherit every public identity/source option.
+- Replacement sessions now block external prompt admission through callback completion, and
+  cancelled guarded creation removes its still-owned persisted side transcript.
+- Replacement locks now block extension-triggered turns outside callbacks, while cancelled-side
+  cleanup atomically quarantines files and restores the outgoing runtime even when cleanup fails.
+- Replacement callback privilege is now method-scoped, and cancelled-side cleanup verifies
+  ownership both before and after quarantine to preserve already-active replacements.
+- Recovery now falls back on metadata errors, custom trigger turns count toward source generation,
+  and a pending replacement admits only the registered BTW close command.
+- Retained BTW initial turns now release their switch reservation after prompt admission, allowing
+  Ctrl+C to close a slow or hung first answer.
+- Retained prompt reservations now wait for actual provider admission, and destructive side
+  deletion preserves path-reused replacement sessions through an atomic ID-bound inode claim.
+- Rejected BTW shortcut dispatch no longer strands its reservation, and concurrent replacement
+  writers are restored without leaving valid sessions at hidden quarantine paths.
+- Retained BTW creation now restores the outgoing session when setup or initialized-session
+  persistence fails, removing inode-owned headerless partial files instead of leaving prompts bound
+  to a replacement-pending candidate; cleanup quarantines before identity validation so concurrent
+  path replacements survive, and initialized writes stay bound to the claimed descriptor so a
+  pre-write pathname swap cannot be overwritten. Failed candidates detach persistence before
+  extension shutdown handlers can append into a reused path.
+- User abort during an asynchronous `agent_settled` handler now rejects discarded deferred BTW
+  shortcuts and releases their pending reservation after clearing the old delivery generation,
+  allowing synchronous retry without recapture or settlement hangs.
+
+### Added
+
+- Retained multi-session `/btw` TUI with native transcripts, a Main/numbered-side/New picker,
+  configurable `Ctrl+/`, `Ctrl+_`, and `Ctrl+7` switching, idle Escape-Escape return, and
+  current-side Ctrl+C deletion; non-TUI side queries remain one-shot and parallel.
 
 ### Changed
 

packages/coding-agent/src/changes.md

@@ -1,5 +1,146 @@
 # changes
 
+## 2026-08-23 - retained BTW sessions and configurable switch routing
+
+### What changed
+
+- The builtin BTW TUI path creates separate retained host sessions and uses native session
+  selection/transcripts instead of the one-shot widget.
+- The fresh replacement context applies a retained side's captured model and thinking level before
+  its first turn. A typed `newSession` policy capability persists the tool ban without crossing the
+  extension/core boundary, forces later extension startup to keep the active set empty, and blocks
+  Cursor exec registered-tool lookup. Final payload enforcement strips provider-native tools after
+  every extension transform.
+- Main-side context snapshots follow Main's selected tree leaf rather than the file's physical
+  tail; retained siblings inherit that persisted leaf, and an oversized newest message is
+  truncated instead of emptying the snapshot. Creation waits for Main to settle before reloading
+  the catalog and snapshotting.
+- Session tool policy is enforced at `ExtensionRunner`'s final payload boundary, covering normal,
+  compaction, and cache-keepalive provider requests after all extension transforms.
+- Extension command contexts expose typed session listing/inspection. `newSession` can opt into
+  flushing initialized metadata before returning, which keeps empty retained sides durable without
+  crossing the extension/core boundary.
+- BTW rejects a Main session path until its JSONL exists, not merely until the path has been
+  allocated.
+- BTW switch input yields to an active extension dialog, and side creation validates captured model
+  authentication before replacing Main.
+- Native provider prompt contributors honor the typed session tool-policy flag, keeping retained
+  side prompts coherent with their empty provider/tool surfaces.
+- Interactive extension dialog state includes selectors, inputs, and editors, preventing raw
+  extension shortcuts from invisibly orphaning any of those pending flows.
+- BTW inline questions require an active model before replacement, and retained catalogs match
+  parent session identity as well as filesystem path.
+- Returning from a retained side restores Main's captured leaf across command, close, and picker
+  surfaces. Interactive dialog gating follows the actual focused component, including auth flows.
+- Focused dialogs also retain destructive Ctrl+C. Duplicate retained labels include session
+  identity, and direct parent return validates the destination session ID before side deletion.
+- BTW TUI dispatch uses idle/pending/running reservation to collapse concurrent shortcuts; picker
+  choices carry expected IDs and reject path-reuse replacements after selection.
+- Side close reinspects the visible session ID immediately before unlink. BTW catalog discovery uses
+  bounded custom-entry inspection rather than full transcript parsing.
+- ModelRegistry exposes live provider authentication checks; BTW requires one before replacing Main.
+- Header-only session listing removes full-summary scans from BTW catalog construction, and close
+  restores the captured Main leaf even when side identity or unlink checks fail.
+- Metadata discovery skips malformed rows and separately inspects the active Main/parent path, so
+  explicit sessions outside the configured directory remain switchable.
+- Returning to an external Main preserves the configured session storage directory, and Escape used
+  to cancel a focused dialog cannot count toward the side's session-level return pair.
+- Inline creation stops after Main identity loss; missing-cwd recovery keeps authoritative session
+  rows; terminal/bash-timeout/todo/imagegen prompts are suppressed under retained no-tools policy.
+- Creation revalidates settled Main ID, recovered siblings bypass header-cwd prefiltering before
+  exact parent matching, and imagegen skill discovery is suppressed when tools are disabled.
+- MCP session attachment and server-instruction injection are suppressed under retained no-tools policy.
+- Repeated Ctrl+C collapses to one destructive close; direct return and picker identity checks use
+  header-only inspection rather than full transcript parsing.
+- Switch and destructive close share one mutual-exclusion gate across raw and direct commands.
+- Main return joins the same action mutex, and retained no-tools sessions skip MCP startup attachment.
+- Retained no-tools sessions omit ordinary skill guidance that would require the unavailable read tool.
+- BTW shortcuts dispatch collision-resolved builtin invocation names instead of hardcoded command text.
+- Model-specific prompt presets cannot reintroduce file-tool guidance in retained no-tools sessions.
+- New BTW rejects same-path Main replacement even when both catalog loads observe the replacement.
+- Shared session-directory catalog scans exclude unrelated cwd rows before custom-data inspection.
+- BTW creation rejects parent-path reuse that occurs during asynchronous authentication preflight.
+- BTW action reservations persist across runner generations; disabled model selection resets presets.
+- BTW creation cannot replace a source that became active or advanced to a newer leaf during auth.
+- Retained parent snapshots are deferred until creation's final idle wait and source-leaf capture.
+- Picker session switches wait for idle before and after target identity validation.
+- Session switches can carry an expected destination ID through asynchronous pre-switch guards;
+  BTW uses it to reject and refresh a path-reused target before current-session teardown.
+- Direct BTW Main returns and closes pass the parent ID into that guard, while catalog discovery
+  rejects current-path metadata whose persisted side ID differs from the live session.
+- New-session replacement accepts an expected parent ID and validates it after async veto and
+  shutdown phases; guarded resume also reopens its destination after teardown before applying it.
+- Post-teardown cancellation recovers and rebinds the outgoing runtime before returning, and
+  expected parent identities use header-only metadata inspection instead of full JSONL loading.
+- `SessionManager.cloneInMemory()` preserves detached identity/tree state for recovery, retained
+  cwd overrides survive rebinding, and replacement identities are checked after runtime creation.
+- Stale constructed candidates emit `session_shutdown` before disposal; recovery rechecks its
+  persisted outgoing path after construction and falls back to the detached snapshot before rebind.
+- Failed retained setup or initialized-session persistence tears down the applied candidate,
+  removes any inode-claimed partial file even without a parseable header, and restores the outgoing
+  runtime before reporting the failure. Cleanup quarantines before inode validation so a path
+  replacement between inspection and deletion is restored instead of unlinked. Persistence writes
+  through the still-open claim descriptor and rejects a pathname identity swap before activation;
+  the failed candidate disables persistence before its shutdown lifecycle.
+- Candidate identity is rechecked after removed-extension handlers, while source expectations let
+  guarded new/resume operations reject active or leaf-changed sessions after async vetoes.
+- Source guards distinguish pre-existing streaming actions from activity begun during vetoes, and
+  AgentSession blocks new prompt admission after guarded teardown starts.
+- AgentSession exposes a monotonic prompt-admission generation through extension contexts; BTW
+  source guards use it to reject later queued/direct submissions during streaming switch vetoes.
+  The getter remains optional for external extension hosts, while Senpi supplies it on every live
+  command context.
+- Runtime identity checks now cover the awaited host-rebind phase before callbacks, and command
+  action option types alias public context methods to prevent typed hosts dropping BTW guards.
+- Applied replacement sessions reject external prompts until callbacks finish; guarded creation
+  rollback deletes the initialized side file only when its persisted ID still matches.
+- Replacement turn locks cover prompt/custom/user paths with callback-scoped privilege; cancelled
+  file cleanup uses atomic quarantine and cannot prevent outgoing runtime recovery.
+- Replacement privilege is synchronous per context method rather than callback-wide, and side
+  cleanup performs pre-rename plus post-rename ownership validation.
+- Recovery catches bounded metadata failures, custom triggerTurn admissions increment source
+  generation, and replacement-pending narrowly recognizes the registered BTW close invocation.
+- Retained initial turns release their switch reservation after prompt admission so Ctrl+C can
+  acquire and execute the destructive close while the first answer is still streaming.
+- Replacement-context prompts report actual provider admission after asynchronous preflight, and
+  BTW side deletion atomically claims and ID-validates the file inode before unlink.
+- Fire-and-forget extension dispatch reports host rejection so shortcut reservations can roll back;
+  conditional side deletion preserves both a path-reused session and concurrent recreated data.
+- Settlement-deferred dispatch also reports cancellation when user-abort generation changes,
+  resolving the deferred turn claim and releasing shortcut reservations for discarded actions.
+  Delivery state is cleared before callbacks so synchronous retries cannot be recaptured.
+- `packages/coding-agent/src/core/agent-session-runtime.ts`: replacement lifecycle carries typed
+  setup, persistence, and session tool policy.
+- `packages/coding-agent/src/core/agent-session.ts`: replacement actions expose the new typed
+  command-context capabilities.
+- `packages/coding-agent/src/core/keybindings.ts`: configurable BTW switch defaults include all
+  terminal-safe aliases.
+- `packages/coding-agent/src/core/model-registry.ts`: retained creation can run the live provider
+  auth check before replacement.
+- `packages/coding-agent/src/core/sdk.ts`: the public session creation contract carries retained
+  setup/policy options.
+- `packages/coding-agent/src/core/session-manager.ts`: initialized persistence and bounded
+  header/custom-metadata discovery support retained catalogs.
+- `app.btw.switch` adds Ctrl+/, Ctrl+_, and Ctrl+7 defaults.
+- Interactive extension UI exposes active key matching and effective-key lookup for configurable
+  terminal routing and visible fallback hints.
+
+### Why
+
+- Side conversations need durable identity, host scrolling, reliable return/close behavior, and a
+  fallback when an editor such as Zed reserves Ctrl+/ before the terminal receives it.
+
+### Why an extension could not handle it
+
+- Retained session replacement, model/auth preflight, session persistence, key parsing, SDK
+  contracts, and metadata-only discovery require host APIs that extensions consume but cannot
+  safely implement by reaching into private runtime state.
+
+### Expected merge-conflict zones
+
+- MEDIUM: builtin BTW wiring and keybinding definitions.
+- LOW: extension UI context and interactive implementation.
+
 ## 2026-08-22 - emit agent_idle after settlement-deferred turns resolve
 
 ### What changed