create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/docs/remote-desktop-access-design.md

@@ -0,0 +1,268 @@
+# CTM Remote Desktop Access Design
+
+Status: Design update from user feedback
+Date: 2026-05-27
+Owner: CTM / Wall-E
+Related docs:
+- `claude-task-manager/docs/phone-access-design.md`
+- `claude-task-manager/docs/microsoft-dev-tunnel-phone-access-design.md`
+- `claude-task-manager/docs/mobile-live-streaming.md`
+
+External references:
+- Microsoft Dev Tunnels security:
+  `https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/security`
+- Microsoft Dev Tunnels CLI reference:
+  `https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/cli-commands`
+- Tailscale quickstart:
+  `https://tailscale.com/docs/how-to/quickstart`
+- Tailscale access controls:
+  `https://tailscale.com/docs/features/access-control/acls`
+
+## Decisions
+
+1. **Microsoft Dev Tunnel is the default browser remote-desktop transport.**
+   It gives a second computer a normal browser URL without DNS setup, VPN setup,
+   or Cloudflare Tunnel. It supports two explicit access modes:
+   CTM-authenticated connect for phone-friendly pairing, and private
+   Microsoft/GitHub gate when the user wants provider auth before CTM loads.
+   Neither mode allows anonymous CTM app access.
+2. **Cloudflare Tunnel is out of scope.** Do not add it to the remote desktop
+   IA, default setup path, or MVP plan.
+3. **Tailscale is the secure private-network alternative.** It requires both
+   sides to be authenticated into the same tailnet, or an explicitly shared
+   machine accepted by an authenticated Tailscale user. CTM still applies its
+   own device auth after the network connection succeeds.
+4. **No temporary desktop mode.** A remote computer is either not paired or is a
+   trusted CTM client device. Avoid split policies such as "temporary desktop"
+   or "lite desktop" unless a later product requirement justifies them.
+5. **Remote desktop gets full CTM access after auth.** The UX should be almost
+   the same as using CTM locally: full dashboard, terminal tabs, conversation
+   tabs, prompt editor, model selectors, queue, setup, reviews, worktrees, and
+   raw terminal input. The difference is that remote access passes through
+   network identity, CTM device auth, origin checks, route/WS authorization,
+   passkey step-up for high-risk actions, and audit.
+6. **Mobile and desktop share one architecture.** The only difference is the
+   surface: `/m/` is a mobile UX and `/` is the desktop UX. Pairing, device
+   identity, scopes, WebAuthn credentials, origin binding, WebSocket tickets,
+   revocation, audit, and route/WS policy should be shared.
+
+## Product Shape
+
+`Setup -> Access` should present:
+
+1. `Microsoft Dev Tunnel` - default remote computer access.
+2. `Tailscale` - private tailnet access.
+3. `Walle Remote` - typed mobile/relay control, not full desktop mirroring.
+
+Do not show Cloudflare Tunnel in the remote desktop flow.
+
+Each direct transport publishes two URLs:
+
+```text
+desktop_url = <origin>/
+mobile_url  = <origin>/m/
+```
+
+The same CTM instance, device store, auth rules, and WebSocket server back both
+URLs. The surface only controls layout and UX.
+
+## Architecture
+
+```text
+Remote browser
+  -> Transport identity
+     -> Microsoft Dev Tunnel CTM-authenticated connect
+     -> or Microsoft Dev Tunnel private browser access
+     -> or Tailscale tailnet identity + ACL/grant
+  -> CTM same-origin HTTPS/WS endpoint
+  -> CTM client-device token
+  -> CTM origin allowlist + WebSocket ticket
+  -> Auth rule registry for HTTP routes and WS message types
+  -> Passkey step-up for high-risk remote actions
+  -> Audit + revoke closes active WebSockets
+```
+
+The current code already has most of this shape:
+
+- `auth-context.js` resolves loopback versus remote device auth.
+- `auth-rules.js` classifies HTTP routes and WS message types.
+- `mobile-auth-store.js` stores device tokens, WebAuthn credentials, step-up
+  sessions, audit, and revocation.
+- `transport-security.js` blocks wildcard binds and validates origins.
+- `server.js` checks Cloudflare Access only when configured, validates CTM
+  device tokens, checks origins, enforces step-up, and closes WebSockets when a
+  device is revoked.
+
+The needed architectural cleanup is to stop treating this as "mobile auth".
+The shared layer should become `client-device` or `remote-client` internally:
+
+```text
+client_device
+  id
+  title
+  surface_last_used: desktop | mobile
+  transport_last_used: microsoft-dev-tunnel | tailscale | loopback
+  scopes: read, respond, create, admin
+  origins / rp_ids
+  token hash
+  WebAuthn credentials
+  audit / revoke metadata
+```
+
+DB migration can preserve existing table names initially, but the code and docs
+should use the product term `client device`. `mobile-*` names should become
+compatibility aliases, not the mental model.
+
+## Microsoft Dev Tunnel Default
+
+Microsoft documents that, by default, hosting and connecting require
+authentication with the same Microsoft, Entra, or GitHub account that created
+the tunnel, and that anonymous access is an explicit opt-in. CTM should expose
+that as an explicit private mode, not as a hidden failure state.
+
+For phone access, CTM-authenticated mode is the better default: Dev Tunnels
+allows anonymous `connect` to this one port so the browser can reach CTM, and
+CTM then enforces client-device auth, origin checks, route/WS authorization,
+passkey step-up, audit, and revocation.
+
+Required flow:
+
+1. The Mac signs into `devtunnel` with Microsoft or GitHub.
+2. CTM creates or reuses a persistent tunnel ID.
+3. CTM creates port `3456` with protocol `http`.
+4. CTM applies the selected access mode:
+   - CTM-authenticated mode creates/verifies anonymous `connect` on this
+     tunnel/port.
+   - Private Microsoft gate mode resets/removes anonymous `connect` access.
+5. CTM starts `devtunnel host <tunnel-id>`.
+6. The remote computer opens the `desktop_url`.
+7. Microsoft/GitHub authentication happens before CTM loads only in private
+   Microsoft gate mode.
+8. After the request reaches CTM, CTM requires client-device pairing or an
+   existing CTM device token.
+9. The paired desktop gets full CTM access subject to CTM remote auth rules.
+
+The remote browser should not receive a Dev Tunnel access token in a URL. If a
+future headless/non-browser client needs tunnel access, use Microsoft’s
+`X-Tunnel-Authorization` header flow, not CTM browser URLs.
+
+Migration rule:
+
+- If CTM detects anonymous Dev Tunnel access while the selected mode is private
+  Microsoft gate, show a security warning and offer `Reset to private`.
+- If CTM-authenticated mode is selected, anonymous `connect` is the intended
+  transport state and should not be treated as stale.
+
+## Tailscale Alternative
+
+Tailscale is not the default for this desktop flow because it requires both
+machines to be in an authenticated Tailscale relationship. That can be:
+
+- both devices logged into the same tailnet;
+- the Mac shared to another authenticated Tailscale user;
+- a managed device/auth-key flow for machines you control.
+
+For CTM this is a clean security boundary:
+
+```text
+Tailscale proves the remote machine/user can reach the Mac on port 3456.
+CTM proves this browser is an approved CTM client device.
+```
+
+CTM should still bind only to loopback or a specific Tailscale IP. Do not bind
+to `0.0.0.0`. Tailscale ACLs/grants should restrict `3456` to the intended
+user/device where possible.
+
+## Full Desktop Access Policy
+
+There is one remote desktop policy: `trusted full desktop`.
+
+Allowed after device pairing:
+
+- load `/` desktop UI;
+- open all session tabs;
+- subscribe to terminal and conversation streams;
+- type into terminal sessions;
+- send Wall-E/coding messages;
+- create sessions;
+- use prompts, queues, reviews, model selectors, and setup pages.
+
+Still protected:
+
+- remote mutations must match `auth-rules.js`;
+- routes/WS messages with `stepUp: remote` require a fresh passkey step-up;
+- loopback-only routes remain loopback-only;
+- `/hook/*`, `/v1/logs`, OAuth proxy routes, local telemetry ingress, and local
+  permission helper endpoints stay local-only;
+- every remote mutation is audited by device, route/message type, origin, IP,
+  scope, and step-up state.
+
+This gives local-like power without pretending a remote browser is loopback.
+
+## Pairing UX
+
+Use one pairing model for phone and desktop:
+
+```text
+Pair device
+  Choose surface: Desktop or Phone
+  Choose transport: Microsoft Dev Tunnel or Tailscale
+  Choose device title
+  Approve locally on the Mac
+  Register passkey for this origin
+  Issue CTM client-device token
+```
+
+Pairing URLs:
+
+```text
+desktop claim: <origin>/claim?claim=...&secret=...&surface=desktop
+mobile claim:  <origin>/m/claim?claim=...&secret=...&surface=mobile
+```
+
+If a remote desktop opens `/` without a CTM token, it should show an auth gate
+that can request pairing. Do not expose the dashboard until CTM auth succeeds.
+
+## UI Requirements
+
+Desktop remote banner:
+
+```text
+Remote Desktop
+Microsoft Dev Tunnel · user@example.com · CTM device: Owner MacBook
+Step-up: fresh / expired
+[Step up] [Revoke this device] [Logout]
+```
+
+The banner should be compact and dismissible for the current session, but a
+security status indicator must remain visible when remote.
+
+Setup Access should show:
+
+- `Desktop URL`;
+- `Phone URL`;
+- tunnel account;
+- CTM device status;
+- last used device;
+- revoke controls;
+- stale anonymous-access warning when detected.
+
+## Test Plan
+
+Required tests before implementation is accepted:
+
+- Microsoft private tunnel flow does not call or recommend anonymous access
+  creation.
+- Stale anonymous access detection surfaces a warning and reset action.
+- Remote desktop opening `/` without CTM token shows auth/pairing gate, not the
+  dashboard.
+- Remote desktop opening `/` with paired CTM token loads the same desktop UI.
+- Remote WebSocket can read with `read` scope.
+- Remote terminal `input` requires `respond` scope and fresh step-up when the
+  route registry requires it.
+- Admin/session/setup mutations require `admin` or `create` as defined by
+  `auth-rules.js` and fresh step-up when remote.
+- Revoke device closes active desktop WebSockets.
+- Tailscale setup emits both `desktop_url` and `mobile_url`.
+- Existing `/m/` phone flows still work from the same device/auth store.
+- Loopback desktop behavior remains unchanged.

package/template/claude-task-manager/docs/restart-lifecycle-architecture.md

@@ -0,0 +1,95 @@
+# CTM Restart Lifecycle Architecture
+
+CTM restart must make the HTTP process replaceable quickly while preserving
+browser-side tab state and terminal snapshots. The critical path is intentionally
+small: acknowledge the restart request, stop accepting new connections, drain
+or force-close network handles, checkpoint SQLite, stop child processes, and
+exit for launchd.
+
+## Phases
+
+1. **Announce**
+   - `/api/restart/ctm` sends `server-restarting` to connected browsers before
+     any sockets are closed.
+   - Browsers should keep local tab, route, draft, and terminal cache state while
+     reconnecting.
+
+2. **Stop Intake**
+   - CTM calls `server.close()` for each listener so no new HTTP requests are
+     accepted.
+   - Idle HTTP keep-alive sockets are closed immediately.
+   - Remaining HTTP sockets are force-closed after a bounded grace window.
+
+3. **Close Upgraded Sockets**
+   - The WebSocket server runs in `noServer` mode, so HTTP listener close does
+     not own upgraded WebSocket connections.
+   - CTM closes each tracked WebSocket with service-restart code `1012`, waits a
+     short grace window for the close handshake, then terminates stragglers.
+
+4. **Stop Background Work**
+   - Scheduler, session capture, session stream, and JSONL watcher stop before
+     PTYs are killed.
+   - CTM DB-owner queued writes are drained with a timeout. Timed-out work is
+     logged with active/pending labels instead of blocking restart indefinitely.
+
+5. **Persist And Exit**
+   - CTM performs a passive WAL checkpoint, closes its SQLite connection, kills
+     PTYs, stops Wall-E, then exits non-zero so launchd starts the replacement.
+
+## Startup Contract
+
+The new process should listen before non-critical reconciliation work starts.
+Session metadata and cached terminal state are the only startup-critical data.
+Heavy work such as permission-file reconciliation, JSONL full scans, prompt
+harvest, conversation import, FTS backfill, and title/model refresh belongs
+behind timers or scheduler jobs with idle checks and bounded batches.
+
+## Restored Session Runtime State
+
+Restart restore has two separate signals:
+
+- **Runtime liveness**: CTM has spawned or is spawning a PTY so the tab can be
+  used again.
+- **Semantic activity**: the agent produced new output, or the user submitted
+  new input that can produce new output.
+
+The UI must not merge these signals. During startup, restored PTYs are marked
+`resuming` and their initial replay output is quarantined for a bounded restore
+window. That replay may hydrate the browser terminal, but it must not update
+`lastActivity`, `lastPtyActivity`, SessionStream activity, or the live status
+bus. If no real provider output arrives, the session naturally falls back to
+`idle` when the restore window expires. If the user types into the session, the
+restore quarantine ends immediately because any following output belongs to the
+new turn.
+
+This keeps CTM restart behavior predictable:
+
+1. Restart begins: existing sessions are not promoted to fresh running work.
+2. Restore starts: session status is `resuming`.
+3. Restore replay draws: terminal cache may update, activity freshness does not.
+4. No new work arrives: status becomes `idle`; last-output time remains old.
+5. User input or real provider work arrives: status can become `running` and
+   freshness advances from that real event.
+
+`startup_tasks.status` is lifecycle metadata, not the UI source of truth.
+Heartbeats may update ownership fields such as process id and heartbeat time,
+but they must not rewrite a task status to `running`. Desktop, phone, and
+standup cards should read the server live-status projection instead.
+
+## SQLite Contract
+
+CTM owns `task-manager.db`; Wall-E owns `wall-e-brain.db`. CTM background writes
+that are not request-critical should go through the CTM DB-owner queue so restart
+can drain a single known queue. SQLite WAL allows concurrent readers with one
+writer, but CTM still keeps application-level write ownership explicit so
+background maintenance cannot race restart, backup, or recovery.
+
+## Anti-Patterns
+
+- Do not add long synchronous startup scans before `listen`.
+- Do not rely on `server.close()` to close WebSocket clients.
+- Do not leave background timers running during restart.
+- Do not block process exit waiting for unbounded child-process or DB work.
+- Do not read/write CTM and Wall-E SQLite files from both processes as peers.
+- Do not let restore replay, heartbeats, or PTY attach bytes advance session
+  freshness or promote a restored session to `running`.

package/template/claude-task-manager/docs/runtime-work-control-plane.md

@@ -0,0 +1,53 @@
+# Runtime Work Control Plane
+
+CTM now treats agent work as runtime-owned state, not text inferred from the terminal.
+
+## Goals
+
+- Show active Wall-E turns, tools, shells, queued work, and recent completions in the session UI.
+- Keep performance isolation: large terminal/tool output stays in the worker/runtime that produced it.
+- Give desktop and phone the same lightweight work-state projection.
+- Leave a clean adapter surface for Codex/Claude PTY workers later.
+
+## Architecture
+
+The authoritative runtime emits task lifecycle events. CTM stores only lightweight metadata in `runtime_tasks`:
+
+- `ctm_session_id`, `agent_session_id`, `turn_id`
+- `kind`: `turn`, `shell`, `tool`, `skill`, or `agent`
+- `status`: `queued`, `running`, `stopping`, `completed`, `failed`, `cancelled`, or `stopped`
+- labels, previews, provider/model, control capabilities, worker scope
+
+Heavy artifacts are not stored in this table. Shell stdout remains in scrollback chunks or provider transcripts. Wall-E tool output remains in the Wall-E transcript/runtime stream. Task rows may point to those sources with `output_ref` later.
+
+## Worker Process Decision
+
+The control plane should not run heavy work in the CTM main process.
+
+- Wall-E-owned sessions keep tool execution in the Wall-E daemon/runtime.
+- Claude/Codex terminal sessions keep PTY rendering and output capture in the session host/headless terminal workers.
+- CTM main process owns the small task registry and broadcasts compact `work-state` frames.
+- Future worker adapters should emit the same metadata events from their session worker instead of letting the browser scrape terminal text.
+
+This gives isolation without fragmenting the UI contract.
+
+## UI Contract
+
+Desktop Wall-E sessions render a compact workbar above the composer:
+
+- chips for running work, shells, tools, skills, queued items, and isolation status
+- a focused summary of the most recent active/recent task
+- `Manage` opens task rows grouped into Active and Recent
+- active turns expose `Stop`, which maps to the existing `walle-cancel` flow
+
+Phone status rows consume `runtimeWork`/`runtime_work` from session payloads and show compact active-work chips.
+
+## Adapter Rule
+
+Each runtime adapter should emit normalized lifecycle events:
+
+1. `startTurn`
+2. `tool_call` / `tool_result`
+3. `completeTurn` or `requestStop`
+
+Adapters must never stream full stdout through `runtime_tasks`. If UI needs output, the task row should carry an `output_ref` to the existing transcript, scrollback, or artifact source.

package/template/claude-task-manager/docs/session-interactive-wait-surfaces.md

@@ -0,0 +1,38 @@
+# Session Interactive Wait Surfaces
+
+CTM models three different "waiting for the user" states. They must not share
+one approval UI because they have different risk and action semantics.
+
+## States
+
+- `approval`: the agent is asking permission to run a tool, edit files, or take
+  another side-effecting action. This is a security/control-plane decision.
+- `choice`: the agent is asking the user to pick from a terminal menu, such as a
+  Claude `AskUserQuestion` planning question. This is normal conversation flow,
+  not permission.
+- `input`: the agent is idle at a free-form composer.
+
+## UI Contract
+
+- Only `approval` may show the desktop `Approval needed` banner with
+  Approve/Deny actions.
+- `choice` must never show approval wording or Approve/Deny buttons. The live
+  terminal menu is the primary UI on desktop; mobile may render a tappable
+  `Terminal choice` card that sends `session.select_choice`.
+- `input` should not surface an approval or choice card.
+
+## Control Plane
+
+- `approval.respond` is high-risk and step-up gated on remote clients.
+- `session.select_choice` is a medium-risk terminal interaction that verifies the
+  live menu before pressing Enter.
+- Desktop must preserve the same separation: raw `1\r` approval shortcuts belong
+  only to approval prompts, not normal choices.
+
+## Regression Invariant
+
+For any `waiting-for-input` event with `reason: "choice"`:
+
+- no `.session-approval-banner` should be visible;
+- text `Approval needed` should not be rendered;
+- Approve/Deny buttons should not exist for that state.

package/template/claude-task-manager/docs/session-needs-you-dismissal.md

@@ -0,0 +1,84 @@
+# Session Needs You Dismissal
+
+## Problem
+
+CTM shows operator-attention sessions in several places: the desktop Active Sessions list, the Sessions overview/standup page, and the phone/iPad Status page. These surfaces used to mix labels such as "Waiting" and "Needs User", and mobile had a local-only dismiss behavior. That made the same session appear actionable on one surface and quiet on another.
+
+The shared contract is now:
+
+- User-facing attention label: `Needs You`.
+- Backend lane/status source of truth: `needs_user` / `waiting_input`.
+- Dismissal persistence: `startup_tasks`, so the choice survives refreshes and CTM restarts.
+- Reset trigger: only a newer submitted user prompt/input marker for the same session.
+
+## Data Model
+
+`startup_tasks` stores three attention fields:
+
+- `attention_dismissed_at`: when the operator dismissed the current attention state.
+- `attention_dismissed_input_at`: the latest user-prompt marker known when dismissed.
+- `last_user_prompt_input_at`: latest known submitted prompt/input that can reset the dismissal.
+
+The dismissal is active when:
+
+```text
+attention_dismissed_at > 0
+and (last_user_prompt_input_at is empty or last_user_prompt_input_at <= attention_dismissed_input_at)
+```
+
+This intentionally ignores passive events: terminal redraws, session heartbeats, agent output, status polling, restore/resume transitions, and websocket reconnects.
+
+## API
+
+Desktop and mobile both use:
+
+```http
+POST /api/sessions/:sessionId/attention-dismiss
+Content-Type: application/json
+
+{ "dismissed": true }
+```
+
+The response includes both camelCase and snake_case marker fields:
+
+- `attentionDismissedAt` / `attention_dismissed_at`
+- `attentionDismissedInputAt` / `attention_dismissed_input_at`
+- `lastUserPromptInputAt` / `last_user_prompt_input_at`
+- `attentionDismissedActive` / `attention_dismissed_active`
+
+Sending `{ "dismissed": false }` clears the dismissal.
+
+## Reset Semantics
+
+The reset marker is written when CTM sees a real submitted user prompt for a non-blocking waiting state. The guard is deliberate:
+
+- Approval/choice prompts should not be reset by pressing `1`, `2`, `y`, `n`, or Escape.
+- Running/idle flicker should not reset a dismissal.
+- Agent output after dismissal should not reset a dismissal.
+- A new user prompt that starts the session again should reset it.
+
+## UI Contract
+
+Desktop:
+
+- Active Sessions groups show `Needs You`.
+- `Needs You` rows expose a compact `Dismiss` action.
+- The Sessions overview card action area shows `Dismiss` on `needs_user` cards.
+- The top attention banner can be dismissed with the same durable API.
+
+Mobile/iPad:
+
+- Status grouping uses the same backend lane and label.
+- Local storage dismissal is only a fallback for older snapshots; server marker fields override it.
+- A server-reported newer `lastUserPromptInputAt` clears any local fallback.
+
+## Testing
+
+Important regression coverage:
+
+- `tests/session-standup.test.js`: classifier demotes dismissed attention and resets only after newer user prompt markers.
+- `tests/active-session-collapse.test.js`: desktop Active Sessions label/render harness.
+- `tests/rendering/scenarios/standup-command-nav.spec.js`: overview card/banner dismiss actions.
+- `tests/rendering/scenarios/mobile-pwa.spec.js`: mobile dismissal survives reload/output-only refresh and resets on newer prompt marker.
+
+Do not reintroduce frontend-only dismissal state as the source of truth. It will regress cross-device consistency after reloads and CTM restarts.

package/template/claude-task-manager/docs/session-render-state-management-design.md

@@ -49,6 +49,41 @@ If none of those changed, tab activation should be a cheap paint/focus operation
 show the existing terminal, fit if necessary, refresh the canvas, align helper
 textarea, preserve scroll intent, and avoid attach/snapshot/reflow.
 
+## TerminalRenderController Contract
+
+The browser must have one mutation owner per terminal session:
+`TerminalRenderController`. The server can classify output, coalesce obvious
+transport bursts, and produce authoritative headless snapshots, but it cannot
+own browser rendering because it does not know the active DOM, xterm parser
+state, WebGL renderer state, split visibility, focused input, or scroll intent.
+
+All xterm mutations should route through the controller:
+
+- `term.write()` for live PTY bytes, snapshots, cursor repair, status cleanup,
+  and lifecycle banners;
+- `term.refresh()` and `clearTextureAtlas()` for paint recovery;
+- `fitAddon.fit()` and `term.resize()` for layout changes;
+- `scrollToLine()` for follow-bottom and preserved-scroll restoration.
+
+The controller is not just a wrapper. It is the ordering contract:
+
+- all writes enter xterm through the controller, which records pending callbacks
+  and relies on xterm's FIFO parser for normal live output; barrier jobs such as
+  snapshot restore and renderer repair wait for the relevant write callbacks
+  before they declare the view settled;
+- synchronized output frames are treated as atomic paint regions, so refresh,
+  fit, scroll, and repair jobs wait until the frame closes;
+- snapshot restore is a barrier job with a restore epoch/source, and stale
+  snapshots are rejected or sanitized before replaying;
+- active native input/composer display owns the screen until its lease settles;
+- paint/fit/scroll requests are intents queued behind writes instead of direct
+  side effects from arbitrary timers;
+- render tests wait on controller/readiness state or persistent semantic output,
+  not on transient text that a legitimate full-screen redraw can erase.
+
+This makes the existing `SessionViewState` useful as the high-level state model
+and moves low-level terminal side effects into a single place.
+
 ## Existing Useful Pieces
 
 The current code already has several strong building blocks.
@@ -132,6 +167,25 @@ If the current tuple equals `lastReadyTuple`, a tab switch must not replay a
 snapshot. It may still call xterm `refresh()` and align/focus because those are
 idempotent paint operations.
 
+The render controller keeps a lower-level tuple for terminal mutation ordering:
+
+```js
+{
+  writeSeq,
+  activeJob,
+  queuedJobs,
+  openSynchronizedFrameDepth,
+  lastWriteSource,
+  lastMutationSource,
+  lastSettledAt
+}
+```
+
+`SessionViewState` answers "is this visible view ready?" while
+`TerminalRenderController` answers "which terminal mutation is allowed to run
+next?" Both are required. A render ledger without mutation ownership can still
+observe a race after it already happened.
+
 ## View Phases
 
 | Phase | Meaning | Exit condition |
@@ -323,27 +377,37 @@ these user-visible contracts:
 
 ## Implementation Plan
 
-Phase 1: Document and instrument
+Phase 1: Document, instrument, and establish mutation ownership
 
 - Land this design document.
 - Add `window._ctmGetSessionViewState(id)` backed by existing flags and render
   ledger.
 - Add logging for overlay dismissal reason and blockers.
+- Add `TerminalRenderController` as the single browser-side write queue for live
+  output, snapshots, cursor repair, stale-status cleanup, and lifecycle banners.
+- Expose controller state from `window._ctmGetTerminalRenderState(id)` so render
+  tests can prove the queue has settled.
 
-Phase 2: Client restore coordinator
+Phase 2: Client restore coordinator and snapshot barriers
 
 - Extend `terminal-restore-state.js` from one-shot decisions into a small pure
   reducer/helper for phases, epochs, and readiness.
 - Replace restart overlay dismissal on snapshot arrival with render-ledger
   readiness.
 - Replace hard 5 second loading dismissal with `ready` or `degraded`.
+- Treat snapshot restore as a controller barrier: clear stale local queues,
+  reject stale restore epochs, and sanitize stale Codex transient `Working`
+  rows when an authoritative non-running status is newer than the busy frame.
 
-Phase 3: Tab activation idempotency
+Phase 3: Paint, fit, scroll, and repair through controller intents
 
 - Formalize the hot-tab unchanged path using epoch tuples.
 - Make attach/snapshot/reflow decisions table-driven.
 - Keep existing blank-tab and real Codex tab-switch tests, then add stricter
   "zero server restore request when unchanged" assertions.
+- Move force-paint, texture-atlas clear, fit/resize, scroll restore, cursor
+  repair, and blank-gap compaction behind controller intent helpers so they do
+  not run inside pending writes or synchronized frames.
 
 Phase 4: Hidden output, split panes, and resize
 
@@ -357,6 +421,30 @@ Phase 5: Server priority and stale response hygiene
 - Add request ids/markers to snapshot diagnostics and stale rejection.
 - Limit background cache warm concurrency.
 
+## Current Implementation Slice
+
+The first production slice should cover the failures that motivated this design:
+
+- controller-routed writes for live output, snapshot replay, cursor repair,
+  submitted prompt cleanup, transient Codex `Working` cleanup, blank-gap
+  compaction, and crash banners. Normal live bytes still rely on xterm's parser
+  FIFO; CTM does not add a second browser-side serialization layer that could
+  slow or reorder typing feedback;
+- deferred refresh/texture-atlas clearing while writes or synchronized frames
+  are active;
+- stale Codex busy-row cleanup before or immediately after idle snapshot restore;
+- active-input ownership gates late snapshot paint/scroll follow-up so Claude and
+  Codex prompt drafts are not moved or repainted by stale restore callbacks;
+- bounded Codex semantic prompt repair only rewrites an already visible blank
+  prompt row, and explicitly excludes provider image-reference path drafts so
+  compact `[Image #N]` paste UX never flashes local file paths in the terminal;
+- no-retry render coverage for Codex working-status cleanup, synchronized redraw
+  streams, skill typing stability, stale snapshot typing, tab-switch
+  idempotency, and slash picker flows.
+
+Remaining legacy direct paint/fit/scroll paths can then be migrated behind the
+same controller without changing the external behavior again.
+
 ## Open Questions
 
 - Should CTM keep hot terminals for all recent sessions, or should the hot cache