create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/docs/session-standup-command-center-design.md

@@ -194,6 +194,31 @@ The endpoint should be pure projection logic over active sessions first. Recent
 sessions can be added as a later extension once the active-session dashboard is
 stable.
 
+### Cache And Refresh Contract
+
+The overview must not block first paint on expensive transcript/timeline work.
+`GET /api/sessions/standup` serves a materialized in-process snapshot when one
+exists and refreshes it in the background when it is dirty or older than the
+short refresh interval. If the process has no materialized snapshot yet, the
+endpoint returns a fast bootstrap snapshot that skips timeline projection and
+AI attention classification, then schedules a full refresh.
+
+Response metadata:
+
+- `revision`: content revision for incremental clients.
+- `incremental`: `true` when the response is a delta against `?since=...`.
+- `unchanged`: `true` when the client revision is current.
+- `stale`: `true` when the response is known to be dirty or old enough to call
+  out as stale.
+- `refreshing`: `true` when a background materialized refresh is scheduled or
+  running.
+- `snapshotSource`: `bootstrap-fast` or `materialized`.
+
+Desktop and mobile clients should render their last complete cached snapshot
+immediately, then request `/api/sessions/standup?since=<revision>` in the
+background. The user should see existing cards with a `refreshing` indicator,
+not an empty `Loading sessions...` board, unless no cached snapshot exists.
+
 ## Implementation Phases
 
 Phase 1: Design document
@@ -239,4 +264,3 @@ Future phase: Manager annotations
   version stay one-session-at-a-time?
 - Should manager annotations be cached per session turn, per stream summary, or
   per dashboard refresh?
-

package/template/claude-task-manager/docs/session-title-authority.md

@@ -0,0 +1,32 @@
+# Session Title Authority
+
+CTM has one product-facing session name: `title`.
+
+`label` is a legacy transport/storage alias that remains in `startup_tasks.label` and a few websocket payloads for compatibility. New application logic should read and write `title`; when a legacy `label` must be sent, it should mirror `title`.
+
+## Precedence
+
+1. Explicit user title wins.
+2. A user-looking active `startup_tasks.label` is promoted into `ctm_sessions.title` with `user_renamed=1`.
+3. AI-generated titles may fill `ctm_sessions.title` only when no user title exists.
+4. Runtime generated titles such as `Codex: ~/repo`, `Claude Code: ~/repo`, `Shell: /path`, branch/worktree leaf names, and `Wall-E session` are not user titles.
+
+## Why
+
+Active sessions have two historical data paths:
+
+- `startup_tasks.label`: crash-safe restore state for running tabs.
+- `ctm_sessions.title`: durable catalog title used by recent sessions, review, and search.
+
+If a user names a running Wall-E session `202612-trip`, that title may first live in `startup_tasks.label`. The auto-title job can later write an AI summary such as `Travel planning from cruise plan and conversation` into `ctm_sessions.title`. Without promotion, the browser sees two names for the same tab and different surfaces disagree.
+
+The fix is architectural: promote the user runtime title into the durable title row and mark it user-owned. After that, existing `user_renamed` guards naturally prevent AI title generation from overwriting it.
+
+## Implementation Rules
+
+- Session create/rename should send `title`; `label` may be included only as a compatibility mirror.
+- Rename writes must update both `ctm_sessions.title` and `startup_tasks.label`.
+- Non-user title writers must call through `setSessionTitleNew`; it protects active user startup titles before accepting an AI title.
+- Browser active-session chrome should prefer `meta.title`/user-looking runtime title before recent-session AI fields.
+- Branch-only runtime labels are not user titles unless `userRenamed=1` is explicit. A worktree branch named `evaluation` should render as `Codex session` with an `evaluation` branch badge, not as a user title.
+- New uses of `startup_tasks.label` should be commented as legacy schema compatibility.

package/template/claude-task-manager/docs/session-workspace-binding.md

@@ -0,0 +1,33 @@
+# Session Workspace Binding
+
+CTM sessions have three related concepts that must not be conflated:
+
+- Launch/restore `cwd`: where CTM started or resumed the PTY/provider process. This can be stale after an agent changes directory or moves work.
+- Current runtime context: a provider/CTM-observed working directory signal, such as `update-session-cwd` or a future provider-native cwd hook/status event.
+- Workspace binding: the verified project/worktree CTM should use for branch badges, worktree attention, and finish gates.
+
+The binding resolver intentionally treats launch/restore metadata and current runtime context differently. A durable identity should win over a plain restored repo-root cwd, but an explicitly observed current runtime cwd should win over old identity because it describes where the live session is now.
+
+The workspace binding is resolved from the strongest verified source available:
+
+1. Confirmed current runtime context (`session._runtimeWorkContext`) when its cwd/worktree path maps to a known git worktree, or to a canonical agent worktree path.
+2. Runtime `worktree_path` or `cwd` captured at launch/restore when it maps to a known git worktree.
+3. `ctm_sessions.project_path` / `ctm_sessions.cwd` when they point at an agent worktree.
+4. Linked `agent_sessions.project_path` rows, ordered by recency.
+5. Runtime branch only when it can be verified against the runtime path.
+
+If sources conflict, CTM marks the binding ambiguous and hides the raw runtime branch badge instead of showing a misleading branch. This prevents a stale runtime branch such as `phone-*` from appearing on unrelated active sessions.
+
+Branch refresh is now a verifier. It probes the confirmed current runtime context first; only sessions without that signal fall back to their resolved workspace binding. It may persist `startup_tasks.branch/worktree_path` after git verifies the branch, but it should not let an arbitrary restored cwd silently become session identity. Restore prefers a verified durable binding when one exists, so split-brain sessions recover into their intended worktree rather than falling back to the repo root.
+
+`startup_tasks.cwd`, `startup_tasks.branch`, and `startup_tasks.worktree_path` remain lifecycle/restore state, not a second durable identity table. Current runtime provenance is kept in memory on the session object and is recalculated from provider/CTM signals after restart. If CTM needs this to survive restart later, add explicit provenance fields instead of overloading `agent_sessions.project_path`.
+
+Do not infer current worktree by scraping terminal text. Prefer explicit host/provider signals:
+
+- Claude Code exposes workspace cwd/worktree in status-line and hook data, including cwd-change hooks.
+- Codex/Cursor-style integrations should use their app-server/session metadata or CTM-side cwd update messages when available.
+- Shell text remains presentation, not authority.
+
+## UI Contract
+
+The active sidebar and tab strip use `workspaceBinding.displayBranch` first, then fall back to the raw `branch` only when the binding does not say the runtime branch is unverified. Worktree attention badges continue to come from `worktreeStatus`, but that status is computed against the resolved workspace binding.

package/template/claude-task-manager/docs/skill-intent-resolution-design.md

@@ -0,0 +1,72 @@
+# Skill Intent Resolution
+
+CTM must not treat skill autocomplete as an automation contract. Autocomplete answers
+"what might the user be typing?" while mobile worktree actions ask "which skill can
+perform this operation for this agent?" Those are different problems.
+
+## Goals
+
+- Route phone worktree actions to the selected owning coding session instead of
+  mutating git directly from CTM.
+- Choose the best available skill for each user and machine. Do not assume the
+  user has `tl-commit`.
+- Respect agent dialects: Codex-style skills use `$skill`; Claude Code skills use
+  `/skill`.
+- Avoid message-only skills such as `writing-commit-messages` for operations that
+  need to review, commit, merge, or create pull requests.
+- Cache capability knowledge in the CTM process. A CTM restart rebuilds the cache
+  from the local skill registry, so newly installed or edited skills are picked up
+  without persistent migration state.
+
+## Contract
+
+The backend exposes:
+
+`GET /api/skills/resolve-intent?intent=<intent>&agent=<agent>&cwd=<cwd>`
+
+Supported intents:
+
+- `commit_main`: review and commit local changes in the main checkout.
+- `finish_and_merge`: review, commit intended changes, validate, and integrate a
+  worktree branch into local main.
+- `create_pr`: review/commit as needed, push if needed, and create a pull request.
+
+The response contains the selected skill, invocation prefix, inferred capabilities,
+and a small ranked candidate list for diagnostics.
+
+## Capability Model
+
+Skills can declare explicit metadata:
+
+```yaml
+capabilities:
+  - git.review
+  - git.commit
+  - git.merge.main
+invocation: $
+```
+
+Legacy skills still work. The resolver infers capabilities from name,
+description, source, and existing agent compatibility metadata. Explicit
+capabilities win over inferred text, but inference is intentionally conservative:
+`commit message` means message composition, not git commit authority.
+
+## Caching
+
+`lib/skill-autocomplete.js` caches parsed skill files by workspace. The intent
+resolver adds a second in-memory cache keyed by `cwd + agent + intent` for the
+ranked capability result. The cache is process-local by design:
+
+- CTM restart = fresh parse and fresh intent cache.
+- No persistent cache table means no stale cross-version schema or migration.
+- Tests can clear the cache with `clearSkillIntentCache()`.
+
+## Mobile UX
+
+The phone worktree sheet asks the backend for the action intent instead of
+querying autocomplete for broad words like `commit`, `review`, and `merge`.
+
+If no eligible skill is found, CTM sends a plain-language prompt to the selected
+session. That fallback is deliberate and safer than invoking a weak match. The
+selected agent remains responsible for git state, validation, and reporting
+blockers.

package/template/claude-task-manager/docs/walle-mcp-supervisor-health.md

@@ -0,0 +1,86 @@
+# Wall-E MCP Supervisor Health
+
+CTM serves Wall-E to coding agents through the provider-native `wall-e` MCP stdio bridge. The bridge proxies JSON-RPC to the local Wall-E daemon at `127.0.0.1:3457/mcp`; when the daemon is down it asks the CTM supervisor at `127.0.0.1:3456/api/start/walle` to start it.
+
+## Startup Contract
+
+Wall-E MCP startup has two separate readiness contracts:
+
+- **CTM supervisor readiness**: `/api/start/walle` and `/api/restart/walle` only return success after the daemon answers MCP `initialize`, answers `tools/list`, exposes `walle_memory_status`, and successfully runs `tools/call` for `walle_memory_status`. Spawning a process is not enough.
+- **Provider stdio readiness**: the provider-native stdio bridge must not fail MCP `initialize` or `tools/list` just because the daemon is still starting. If CTM cannot make the daemon ready, stdio enters a degraded MCP mode that exposes only `walle_memory_status`.
+
+This prevents the recurring failure where Codex/Claude remove the `wall-e` MCP server during handshake because `127.0.0.1:3457` briefly refused connections after CTM restart.
+
+In degraded stdio mode:
+
+- `initialize` returns a valid Wall-E MCP serverInfo object with `degraded: true`;
+- `tools/list` returns only `walle_memory_status`;
+- `resources/list`, `resources/templates/list`, and `prompts/list` return empty lists;
+- `tools/call` for `walle_memory_status` returns structured health with `mode: "stdio-degraded"` and the daemon/CTM ports;
+- other tool calls return an MCP tool error result instead of a JSON-RPC handshake error.
+
+The embedded brain DB fallback remains opt-in through `WALLE_MCP_EMBEDDED_DB=1`. Normal provider traffic should go through the daemon so there is one owner for SQLite, live connectors, CTM session context, and telemetry.
+
+## Native Dependency Preflight
+
+Wall-E uses native SQLite modules (`better-sqlite3` and `sqlite-vec`). After a Node upgrade, those modules can fail before Wall-E can bind the HTTP/MCP port. A stale `walle.pid` then turns into a generic `ECONNREFUSED` unless CTM diagnoses the start failure.
+
+Before every supervised Wall-E start or restart, CTM now runs a preflight in the same Node binary that will launch Wall-E:
+
+- load `better-sqlite3`;
+- open an in-memory database and run `PRAGMA quick_check`;
+- load `sqlite-vec` into that database;
+- classify failures as `native_dependency_abi_mismatch`, `native_dependency_missing`, `native_dependency_load_failed`, or `native_dependency_check_timeout`.
+
+For rebuildable failures CTM runs:
+
+```sh
+npm rebuild better-sqlite3 sqlite-vec
+```
+
+Then it repeats the preflight. CTM only spawns Wall-E after the second check passes.
+
+### Shared `node_modules` Guard
+
+The rebuild path is only safe when the Wall-E checkout owns its own
+`wall-e/node_modules` directory. A worktree may symlink
+`wall-e/node_modules` to the primary checkout to save install time; that is
+fine while every process uses the same Node runtime, but it is unsafe for
+native auto-repair. If a Node 26 worktree rebuilds the primary checkout's
+`better_sqlite3.node`, the primary Node 25 daemon can no longer load it; if the
+primary daemon then rebuilds, the worktree breaks. The symptom is an apparent
+compile/load loop where the binary alternates between two `NODE_MODULE_VERSION`
+values.
+
+CTM now inspects `wall-e/node_modules` before automatic install/rebuild. If the
+directory resolves outside the current Wall-E checkout, native dependency
+failures are reported as diagnostics but CTM refuses to mutate the shared
+install. The correct fixes are:
+
+- run the worktree with the same Node binary as the owner checkout; or
+- install isolated Wall-E dependencies in that worktree so its native addon
+  build belongs to that worktree.
+
+## Operator Behavior
+
+This flow does not require restarting the CTM primary process. A provider MCP bridge or the CTM UI can call `/api/start/walle`; the supervisor will repair native modules when possible and start only the Wall-E daemon.
+
+If repair fails, CTM exposes structured status:
+
+- `/api/services/status` includes `walle.code`, `walle.error`, `walle.native_dependency`, `walle.last_start_error`, and `walle.mcp_ready`;
+- proxied Wall-E routes return a 502 JSON body with the same diagnostic fields instead of only `connect ECONNREFUSED`;
+- the stdio MCP bridge reports the CTM start failure through degraded `walle_memory_status` whenever the MCP method can be degraded safely.
+
+If CTM spawns Wall-E but MCP never becomes ready, `/api/start/walle` returns HTTP 503 with `code: "walle_mcp_ready_timeout"` and the failed readiness probe details. That is intentionally different from a successful process start: the client needs tools, not just a PID.
+
+## MCP Smoke Test
+
+After recovery, verify the daemon rather than only the process:
+
+1. `POST /mcp` with `initialize`.
+2. `POST /mcp` with `tools/list`.
+3. `POST /mcp` with `tools/call` for `walle_memory_status`.
+
+All three must succeed before declaring Wall-E MCP reachable.
+
+For provider startup resilience, also test the daemon-down path with self-heal disabled. The stdio bridge should still answer `initialize`, `tools/list`, and `tools/call walle_memory_status` without opening `wall-e-brain.db`.

package/template/claude-task-manager/docs/walle-relay-phone-access-design.md

@@ -6,6 +6,7 @@ Owner: CTM / Wall-E
 Related docs:
 - `claude-task-manager/docs/phone-access-design.md`
 - `claude-task-manager/docs/phone-setup.md`
+- `claude-task-manager/docs/remote-desktop-access-design.md`
 - `claude-task-manager/docs/microsoft-dev-tunnel-phone-access-design.md`
 - `claude-task-manager/docs/session-management-architecture.md`
 
@@ -20,6 +21,13 @@ your own network" setup with a Claude Code-style control plane: CTM keeps
 running locally, makes an outbound TLS connection to a hosted Walle relay, and
 the phone uses a Walle-authenticated web/mobile surface to steer local sessions.
 
+2026-05-27 update: this doc now describes the typed Walle Remote mobile-relay
+path only. It is not the primary direct browser-access plan. Full desktop-style
+browser access for phone and another computer is covered by the unified
+client-device architecture in `remote-desktop-access-design.md`, with private
+Microsoft Dev Tunnel as the default transport and Tailscale as the private
+network alternative. Cloudflare Tunnel is out of scope.
+
 This is not a generic localhost tunnel. The relay carries a narrow typed
 protocol for session review, messaging, and approvals. It must not proxy the
 entire CTM web app or arbitrary local HTTP requests in the MVP.
@@ -51,8 +59,8 @@ execution to cloud infrastructure.
    and requiring step-up confirmation for high-risk commands.
 5. Give the phone a purpose-built triage UI: what needs attention, what changed,
    what can I safely approve, and what should I send next.
-6. Preserve existing Microsoft Dev Tunnel, Tailscale, and Cloudflare paths as
-   fallback transports.
+6. Preserve existing Microsoft Dev Tunnel and Tailscale paths as direct
+   browser transports outside the typed relay.
 
 ## Success Metrics
 
@@ -102,9 +110,8 @@ execution to cloud infrastructure.
 1. User opens CTM on the Mac and goes to `Setup -> Access`.
 2. CTM shows three access methods:
    - Walle Remote, recommended
-   - Microsoft Dev Tunnel quick fallback
+   - Microsoft Dev Tunnel private browser access
    - Tailscale private URL
-   - Cloudflare Access browser URL
 3. User clicks `Set up Walle Remote`.
 4. CTM checks relay prerequisites:
    - Walle account signed in or sign-in available
@@ -180,14 +187,13 @@ execution to cloud infrastructure.
   - Walle Remote `Recommended`
   - Microsoft Dev Tunnel
   - Tailscale
-  - Cloudflare Access
 - Walle Remote panel
   - Status card
   - Pair phone
   - Paired devices
   - Relay connection diagnostics
   - Security/audit link
-- Microsoft Dev Tunnel, Tailscale, and Cloudflare remain collapsible fallback
+- Microsoft Dev Tunnel and Tailscale remain collapsible direct-browser access
   groups.
 
 ### Phone IA
@@ -219,8 +225,9 @@ execution to cloud infrastructure.
 
 ### Desktop: Walle Remote Setup Panel
 
-Layout: use the same access-method pattern as Tailscale/Cloudflare, but Walle
-Remote should be first and marked recommended.
+Layout: use the same access-method pattern as Microsoft Dev Tunnel and
+Tailscale. Walle Remote is the typed mobile-relay option, not the default full
+browser-access option.
 
 Primary states:
 
@@ -469,9 +476,11 @@ High-risk write:
 - `network.setup_change`
 - `ctm.restart`
 
-MVP should implement the read and low-risk write set first. High-risk writes
-can be represented in the UI before they are enabled, but must fail closed until
-step-up and local authorization are implemented.
+MVP implements the read and low-risk write set first. `approval.respond` is the
+first high-risk write allowed through the relay, and only after local CTM
+authorization, idempotency, audit logging, and step-up have accepted the typed
+message. Other high-risk writes can be represented in the UI before they are
+enabled, but must fail closed until the same controls are in place.
 
 `sessions.subscribe` is intentionally not a request/response wrapper around
 `sessions.get`. The local phone app uses the host WebSocket as the foreground
@@ -997,12 +1006,12 @@ The first shippable MVP should include:
 - Phone home with session list.
 - Session detail with stream summary.
 - Send message to session.
-- Read-only approval review.
+- Step-up-gated approval response.
 - Audit log.
 
-Remote approval responses should wait until step-up and idempotency are in
-place. That is the line between a useful remote companion and a risky remote
-admin surface.
+Remote approval responses are allowed only with step-up, idempotency, and local
+audit in place. That is the line between a useful remote companion and a risky
+remote admin surface.
 
 ## Open Questions
 

package/template/claude-task-manager/docs/walle-session-history-hydration.md

@@ -0,0 +1,114 @@
+# Wall-E Session History Hydration
+
+## Problem
+
+Wall-E session history is chat transcript data, not terminal scrollback. CTM used to hydrate visible Wall-E tabs through the same `attach` and `snapshot` restore path used by xterm-backed Codex/Claude sessions. That made a Wall-E tab vulnerable to terminal lifecycle races:
+
+- restart creates deferred startup placeholders;
+- hidden terminal snapshot prewarm can ask the server to auto-start a deferred session;
+- if that happens for a Wall-E placeholder with no visible browser client, the runtime can be marked restored while no `walle-history` payload is delivered;
+- the browser can then sit in `requested && !loaded` state and keep showing "Rehydrating Wall-E session history".
+
+The history read itself is normally cheap. The product boundary was wrong.
+
+## Architecture
+
+Wall-E history now has its own request/response lane:
+
+1. Browser activation calls `WalleSession.requestHistory(...)`.
+2. The client sends `walle-history-request` over the existing CTM WebSocket.
+3. The server resolves the Wall-E transcript source from live session metadata, CTM DB identity, or startup task metadata.
+4. The server replies with `walle-history` from the durable conversation cache or local Wall-E transcript history.
+5. Terminal `snapshot`, `reflow`, and hidden prewarm paths are not allowed to auto-start Wall-E deferred sessions.
+
+This keeps chat history hydration independent from PTY restore. Existing `attach` remains compatible for older clients, but it is no longer the normal browser path for loading a Wall-E conversation.
+
+## Browser Surface Reconciliation
+
+The browser must treat server session type as authoritative after reconnect.
+A tab can exist locally before the latest `list` payload arrives, and that local
+tab may still have a stale terminal container from a previous runtime shape.
+Native Wall-E sessions are not xterm sessions, so reusing that terminal surface
+can leave a `snapshot-loading-overlay` on screen even though the server has
+already reported the session as idle.
+
+On every `sessions-list` refresh:
+
+- if the server reports `type: "walle"` or a native Wall-E marker, the client
+  converts the local session to a Wall-E surface;
+- conversion disposes terminal renderers, timers, xterm instances, stale
+  containers, and loading overlays before rendering the Wall-E transcript view;
+- if an existing Wall-E-shaped local tab is later reported as terminal-backed,
+  the client recreates a terminal stub instead of mutating the Wall-E DOM in
+  place;
+- `server-ready` and restart overlays do not wait for terminal scrollback when
+  the active tab is a native Wall-E session. They request Wall-E history and
+  dismiss the global restore overlay.
+
+This mirrors the boundary used by OpenCode/Claude-style transcript views:
+conversation history is hydrated by a transcript/message lane, while terminal
+snapshot restore is reserved for live terminal sessions.
+
+## Hidden Snapshot Prewarm Policy
+
+Hidden snapshot prewarm is only for hidden sessions that have live terminal
+control. It must not auto-start a deferred provider session just to serialize a
+background snapshot.
+
+Rules:
+
+- skip native Wall-E sessions;
+- skip exited sessions;
+- skip restore-deferred sessions that do not expose terminal input/control;
+- if a legacy/in-flight hidden prewarm receives `session-restore-deferred` with
+  `starting: false`, settle the prewarm immediately instead of waiting for the
+  timeout.
+
+This prevents restart from turning into a serialized background resume storm,
+which was the main reason some tabs appeared to restore slowly or never clear
+their loading state.
+
+## State Contract
+
+The browser treats history loading as an idempotent state machine:
+
+- `idle`: no history request has been made;
+- `loading(requestId)`: a request is in flight;
+- `loaded(requestId)`: history arrived, even if the transcript is empty;
+- `error(requestId)`: the server rejected the request.
+
+If a visible tab is stuck in `requested && !loaded`, activation retries after the retry window instead of assuming the old request will complete. Server responses echo `historyRequestId`, so stale replies cannot overwrite a newer load.
+
+## Server Rules
+
+- `walle-history-request` may read cache/transcript history without starting a deferred runtime.
+- `snapshot` for a Wall-E session is redirected to history hydration and returns a non-terminal snapshot no-op.
+- `_maybeAutoStartDeferredRestore` blocks Wall-E auto-start from snapshot/reflow/prewarm sources.
+- `/api/session/messages` uses the local Wall-E cache/history fast path before falling back to generic JSONL parsing.
+
+## Testing
+
+Regression coverage lives in `tests/walle-history-hydration.test.js`:
+
+- Wall-E deferred sessions do not auto-start from terminal snapshot prewarm.
+- Terminal sessions keep their existing auto-start behavior.
+- requested-but-not-loaded Wall-E history retries after the retry window.
+
+Browser regression coverage:
+
+- `tests/rendering/scenarios/walle-session-default-model.spec.js` verifies that
+  a native Wall-E `sessions-list` update replaces a stale terminal restore
+  surface and requests Wall-E history.
+- `tests/rendering/scenarios/reconnect.spec.js` verifies that hidden deferred
+  tabs are skipped by background snapshot prewarm and that deferred prewarm
+  responses settle immediately.
+
+Run:
+
+```bash
+npm --prefix claude-task-manager test -- --test-name-pattern=walle-history-hydration
+node --check claude-task-manager/server.js
+node --check claude-task-manager/public/js/walle-session.js
+npm --prefix claude-task-manager run test:render -- scenarios/walle-session-default-model.spec.js -g "type transition" --retries=0
+npm --prefix claude-task-manager run test:render -- scenarios/reconnect.spec.js -g "hidden deferred tabs" --retries=0
+```

package/template/claude-task-manager/docs/walle-session-input-queue.md

@@ -0,0 +1,104 @@
+# Wall-E Session Input Queue
+
+## Problem
+
+Wall-E session input currently has two incompatible behaviors:
+
+- The composer stays editable while Wall-E is generating, so users can draft the
+  next prompt.
+- The transport rejects a second `walle-message` while a turn is active, so
+  pressing Enter during generation either does nothing useful or leaves the user
+  with a draft that is not part of the session lifecycle.
+
+The product contract should be explicit: a prompt submitted while Wall-E is busy
+is queued for the same session and dispatched only when the session is ready for
+another normal user turn.
+
+## Architecture
+
+CTM reuses the existing persisted `queueEngine` and `prompt_queues` table. The
+queue remains server-owned; desktop and phone clients only render a projection of
+that state.
+
+```text
+Wall-E composer / Queue Builder
+        |
+        v
+POST /api/queues { append: true, autoStart: true }
+        |
+        v
+queueEngine
+  - persists queue items in prompt_queues
+  - holds pending items while a target is not ready
+  - claims one item at a time as sending
+        |
+        v
+Wall-E readiness gate
+  - blocks while session.abortController exists
+  - blocks when the latest assistant turn has pending external actions and the
+    queued item is not an approval
+        |
+        v
+handleWalleMessage()
+  - appends the user turn to the Wall-E transcript
+  - calls /api/wall-e/chat?stream=1
+  - wakes the queue when the turn finishes
+```
+
+## State Contract
+
+Queue item statuses:
+
+- `pending`: durable item waiting to be dispatched.
+- `sending`: exactly one item claimed by the dispatcher.
+- `sent`: the Wall-E turn completed and the queue may advance.
+- `skipped`: user skipped the item.
+
+Queue status:
+
+- `running`: queue is active. It may be dispatching or waiting on readiness.
+- `paused`: queue will not dispatch until resumed.
+- `done`: no remaining pending work.
+
+Readiness metadata is intentionally separate from persisted queue contents:
+
+- `waitingCode`
+- `waitingReason`
+- `waitingMessage`
+
+These fields explain why a running queue has not dispatched yet. They are
+derived from live session state and rebroadcast over WebSocket; they do not need
+to be durable.
+
+## UX Contract
+
+When the user presses Enter in a Wall-E composer:
+
+- If Wall-E is idle, send the prompt immediately.
+- If Wall-E is generating, append one durable queue item and clear the composer
+  only after the server accepts the queue.
+- If a queue exists, append instead of replacing.
+- Show a compact "Queued next" card above the composer with the next pending
+  prompt and cancel/open-queue actions.
+- Keep the Stop button scoped to the current Wall-E turn. Stopping does not
+  delete queued prompts.
+
+## Safety
+
+The queue must never send a queued normal prompt into an approval boundary. If
+the latest assistant turn contains pending external actions, a queued prompt is
+held until the user sends an approval/denial or cancels the queue. This prevents
+a follow-up question from being interpreted as consent.
+
+## Tests
+
+Required coverage:
+
+- Queue engine waits when a readiness gate returns false, then dispatches on
+  wake.
+- Appending to a running async queue preserves item order.
+- Wall-E composer Enter while generating creates a queue item instead of a
+  second `walle-message`.
+- The queued prompt card renders and clears when queue state is done/deleted.
+- Dev instance browser validation uses real keyboard events against a non-primary
+  CTM port.