create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/docs/mobile-live-streaming.md

@@ -31,11 +31,21 @@ session card and subsequent skill lookups include the session's agent and cwd.
 
 The mobile shell keeps a capped localStorage snapshot for instant paint. The cap
 is intentionally high enough for normal CTM dashboards, so users with hundreds
-of sessions still get incremental refreshes. If the snapshot is complete, the
-next standup call sends `?since=<revision>` and the server may return an
-incremental delta. If the cached snapshot was capped, the phone still paints it
-optimistically but intentionally drops the revision so the server returns a full
-standup response and fills in the omitted sessions.
+of sessions still get incremental refreshes. A fresh complete snapshot sends
+`?since=<revision>` and the server may return an incremental delta. A stale but
+not expired snapshot still paints immediately as a preview, but intentionally
+drops the revision so the server returns a full standup response. If the cached
+snapshot was capped, the phone also drops the revision so the server fills in
+the omitted sessions.
+
+The snapshot is not an auth source and is not current status by itself. If the
+phone boots with a cached snapshot but CTM reports missing/expired device auth,
+the UI must label the rows as a cached preview, show a pairing action, and avoid
+presenting cached running/waiting lanes as authoritative. When a phone pairing
+claim completes, the claim page clears the cached snapshot and writes a
+short-lived "force full standup" marker. The next `/m/#status` load consumes
+that marker and requests `/api/sessions/standup` without `since`, so a re-paired
+phone cannot keep stale status data through an incremental no-op response.
 
 The standup response contract is:
 
@@ -46,6 +56,10 @@ The standup response contract is:
   changed or newly added session cards;
 - revisions must ignore volatile relative-age fields so a phone poll does not
   download every session just because "last activity 1m ago" became "2m ago".
+- session cards use `worktreeStatus` as the canonical local-work summary. The
+  phone cache may read legacy `worktree` cards, but it normalizes them back to
+  `worktreeStatus` before rendering or persisting so changed-file/commit chips
+  survive a reload before the next HTTP refresh finishes.
 
 The key lifecycle messages are:
 
@@ -73,6 +87,14 @@ This avoids blocking resume or watch flows on large JSONL files. The HTTP
 history path is still valuable for older transcript context, but it must not own
 freshness.
 
+The detail view also keeps a small, browser-local transcript tail per session.
+That tail is a non-authoritative preview only: opening a session can show the
+last known durable messages before WebSocket or HTTP history finishes, then the
+canonical `/api/session/messages` response replaces cached rows while preserving
+new live events that arrived during hydration. The cache is capped by session
+count, message count, message text length, and age, and it is cleared when the
+phone consumes a forced full-refresh marker after re-pairing.
+
 Live events are deduplicated by the strongest available key:
 
 1. `eventId`

package/template/claude-task-manager/docs/mobile-remote-submission-lifecycle.md

@@ -0,0 +1,69 @@
+# Mobile Remote Submission Lifecycle
+
+Phone sends are split into two separate contracts:
+
+1. **Transport delivery**: the phone delivered an authenticated remote message to CTM on the Mac.
+2. **Agent acceptance**: CTM has evidence that the target Claude/Codex/Wall-E session accepted that message.
+
+The phone must not treat transport delivery as final. PTY-based agents use real terminal line editors, so a successful write plus Enter only proves that CTM interacted with the terminal. It does not prove the agent added the prompt to its transcript.
+
+## Data Model
+
+`ctm_remote_submissions` is the durable backend ledger keyed by the remote message id.
+
+Stored fields intentionally avoid a second full prompt copy:
+
+- `message_id`, `session_id`, `device_id`, `message_type`
+- `text_hash` for matching and diagnostics
+- `text_preview` for UI status only
+- `status`, `result_json`, timestamps, attempt count, and last error
+
+The full prompt should live in the provider/session transcript once accepted. Before acceptance, the phone keeps its transport outbox locally until CTM acknowledges the remote envelope.
+
+## Statuses
+
+- `received`: CTM received the remote envelope.
+- `typed_to_pty`: CTM wrote the text to the terminal.
+- `observing`: CTM pressed Enter and is waiting for acceptance evidence.
+- `durable_user_message_seen`: the prompt is present in CTM's session prompt/message index.
+- `response_started`: the target session became busy after submission.
+- `accepted_by_terminal`: the terminal advanced after Enter and the prompt is no longer visibly waiting.
+- `blocked`: CTM refused to type because the session was busy, blocked by approval, or not ready.
+- `failed`: CTM started delivery but could not complete it.
+- `needs_attention`: CTM delivered bytes but could not prove acceptance, or the prompt still appears at the terminal prompt.
+
+## Observation Rules
+
+For Claude/Codex terminal sessions, CTM records a pre-submit terminal marker, writes text, presses Enter, then observes asynchronously:
+
+- First preference: match the submitted text in the durable prompt/message index.
+- Second preference: session status turns busy after the submit.
+- Third preference: terminal output advances after Enter. If CTM recorded a
+  before-Enter terminal marker, advancement from the pre-typing marker is not
+  enough because it can be only the terminal echo of CTM typing the reply.
+- Attention path: the submitted text still appears at the visible prompt after a grace period, or no acceptance signal arrives before timeout.
+
+If the exact submitted prompt is still active and the terminal marker did not
+move after the first Enter, CTM may press Enter one more time. This retry is
+only for a visible stuck composer state; it is not a generic resend of the
+remote message and it does not duplicate the phone envelope.
+
+Observation broadcasts `remote-submission-status` over the shared websocket and exposes reconnect state at:
+
+`GET /api/remote/submissions?session_id=<id>`
+
+Both CTM web and phone can consume the same status stream. The phone renders durable pending/attention rows in the timeline. The composer status is only transient feedback for the current text box action, so attention rows must not be mirrored into a second red warning below the input. Desktop can add the same affordance later without changing the backend contract.
+
+## UX Rules
+
+- Phone outbox removal means “Mac accepted the envelope,” not “agent accepted the prompt.”
+- While observing, the composer may show “Delivered to Mac. Waiting for the agent to accept it...” as in-flight feedback.
+- If attention is needed, show the backend reason in the remote-submission timeline row and keep the composer free for the next action.
+- Once accepted, remove pending attention rows and refresh the transcript so the durable prompt/reply replaces optimistic UI.
+- Do not hide a pending/attention row just because the phone rendered an optimistic local copy of the submitted prompt; only durable transcript evidence should resolve the remote-submission row.
+
+## Regression Risks
+
+- Do not retry an envelope after CTM acknowledged it. Retries use the same message id only for network ambiguity before a server response.
+- Do not store full prompt text in the backend ledger.
+- Do not change Claude/Codex copy/paste behavior; this lifecycle observes the existing text-then-Enter terminal contract.

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

@@ -15,21 +15,37 @@ from it without re-doing the research.
 default-deny authorization, one-time device claims, secure-context rollout,
 notification event sources, Cloudflare Access validation, and phone-side UX.
 
-2026-05-09 Walle Relay update: the recommended long-term product path is now
-the hosted Walle Relay remote-control model in
-`claude-task-manager/docs/walle-relay-phone-access-design.md`. This document
-remains the detailed fallback transport plan for Tailscale and Cloudflare.
+2026-05-09 Walle Relay update: the recommended long-term product path was
+initially framed as the hosted Walle Relay remote-control model in
+`claude-task-manager/docs/walle-relay-phone-access-design.md`. That remains
+useful for typed mobile relay workflows, but it is no longer the primary direct
+browser-access architecture.
 
 2026-05-10 Microsoft Dev Tunnel update: Microsoft Dev Tunnel is a quick
 browser fallback that avoids VPN, DNS, and Cloudflare setup, but it is still a
 tunnel transport rather than the Walle Relay product path. See
 `claude-task-manager/docs/microsoft-dev-tunnel-phone-access-design.md`.
 
-2026-05-19 private Microsoft Tunnel update: Microsoft Dev Tunnel must stay
-private by default. CTM no longer creates anonymous Dev Tunnel browser access.
-The phone signs into the same Microsoft/GitHub identity used by `devtunnel` on
-the Mac before Microsoft forwards traffic to CTM. CTM still issues its own
-device token for scopes, revocation, audit, and optional passkey step-up.
+2026-05-30 correction (supersedes a brief 2026-05-19 "private by default"
+experiment): Microsoft Dev Tunnel defaults to **app-gated** (CTM-authenticated)
+access — the tunnel is reachable by URL and CTM's own device token + passkey +
+step-up are the gate, behind an unguessable tunnel URL. Forcing the tunnel
+"private" (interactive Microsoft/GitHub edge sign-in) bricks the phone, because
+the PWA's `fetch()` + `WebSocket` cannot follow the cross-origin login redirect —
+the symptom is "can't connect / times out". Private is now an explicit opt-in
+only (UI selection, `CTM_MS_TUNNEL_ACCESS_MODE=private`, or
+`options.allowPrivateAccess`); a private value coming only from persisted state is
+migrated back to app-gated on the next start so the phone keeps working. For a
+real edge sign-in that is PWA/WebSocket-compatible, use Cloudflare Access or
+Tailscale instead. See
+`claude-task-manager/docs/microsoft-dev-tunnel-phone-access-design.md`.
+
+2026-05-27 unified remote-access update: direct browser access for both phone
+and desktop uses the same CTM client-device architecture. Microsoft Dev Tunnel
+private access is the default direct transport, Tailscale is the private-network
+alternative, and Cloudflare Tunnel is out of scope. See
+`claude-task-manager/docs/remote-desktop-access-design.md` and
+`claude-task-manager/docs/microsoft-dev-tunnel-phone-access-design.md`.
 
 ---
 
@@ -272,7 +288,12 @@ violates G2 of the threat model.
   doesn't see content), but device identity could be issued maliciously.
   Mitigation: tailnet lock (signed device joins) is available if paranoid.
 
-### 4.2 Option B — Cloudflare Tunnel + Cloudflare Access (BACKUP / public URL)
+### 4.2 Legacy Option B — Cloudflare Tunnel + Cloudflare Access (DO NOT IMPLEMENT)
+
+2026-05-27 decision: Cloudflare Tunnel is no longer part of the CTM remote
+access plan. Keep this section only as historical threat-model context for old
+deployments. New work should use private Microsoft Dev Tunnel by default or
+Tailscale as the private-network alternative.
 
 ```
 [Internet client]──HTTPS──[Cloudflare edge]──QUIC tunnel──[cloudflared on Mac]──[CTM:3456]
@@ -370,6 +391,18 @@ Loopback requests get all scopes but still go through the same route registry
 so tests exercise one path. Remote requests must resolve to a non-revoked
 device token before any `/api/*` route or WS message handler runs.
 
+**Loopback-trust security invariant (`lib/transport-security.js` `isLoopbackRequest`).**
+A managed tunnel (devtunnel) forwards remote clients to CTM over `127.0.0.1`, so a
+loopback socket peer alone does NOT prove a request is on-box. Loopback full-admin
+trust requires ALL of: (1) a loopback socket peer, (2) **no** proxy/tunnel
+forwarding markers (`X-Forwarded-For/Host/Proto`, `Forwarded`, `X-Real-IP`,
+`X-MS-Original-Host`, `X-Original-Host`, `CF-Connecting-IP`), (3) no non-loopback
+browser `Origin`/`Referer`, and (4) a loopback or absent `Host`. A genuinely local
+browser or CLI never sends forwarding markers; Azure Dev Tunnels (and every
+standard proxy) always stamp them, so any tunnel-forwarded request fails closed
+and must present a device token like any other remote client. This invariant is
+the linchpin of the whole model — never relax it to "loopback socket ⇒ trusted".
+
 **New table**: `ctm_device_tokens`
 ```sql
 CREATE TABLE ctm_device_tokens (
@@ -1055,11 +1088,12 @@ memory-search endpoint if we want free-text memory search in mobile.
 |--------|-----------------------------------|---------------|---------|
 | POST   | `/api/auth/device-claims`          | loopback only | Create one-time phone pairing claim |
 | DELETE | `/api/auth/device-claims/:id`      | loopback only | Cancel unclaimed QR |
-| POST   | `/api/auth/claim/begin-passkey`    | claim secret  | Begin WebAuthn registration for a claim |
-| POST   | `/api/auth/claim/finish`           | claim secret  | Finish passkey registration, mint device token cookie |
+| POST   | `/api/auth/claim/begin-passkey`    | claim secret  | Begin WebAuthn registration or same-phone recovery for a claim |
+| POST   | `/api/auth/claim/finish`           | claim secret  | Finish registration/recovery and mint device token cookie |
 | GET    | `/api/auth/me`                     | token         | Current device label, scopes, step-up freshness |
 | GET    | `/api/auth/devices`                | loopback only | List devices |
 | DELETE | `/api/auth/devices/:id`            | loopback or admin+step-up | Revoke |
+| POST   | `/api/auth/device-duplicates/revoke` | loopback only | Keep one duplicate phone pairing and revoke the others |
 | POST   | `/api/auth/begin-step-up`          | token         | Begin WebAuthn assertion |
 | POST   | `/api/auth/finish-step-up`         | token         | Complete WebAuthn assertion, create step-up session |
 | POST   | `/api/auth/register-passkey`       | token+step-up or loopback | Add replacement passkey |
@@ -1196,7 +1230,10 @@ with Face ID, agent resumes within 2 s.
 **Acceptance**: phone is locked, agent reaches `waiting_input`, lock-screen
 banner appears within 5 s; tap → unlocks → opens to detail.
 
-### Batch 7 (Optional) — Cloudflare Tunnel + Access fallback
+### Batch 7 (Removed) — Cloudflare Tunnel + Access fallback
+
+2026-05-27 decision: do not implement this batch for CTM remote access. It is
+kept here only to explain old references in the risk register.
 
 - Documentation + optional settings.
 - Configure expected team domain, Access application AUD, allowed email, and
@@ -1230,7 +1267,7 @@ banner appears within 5 s; tap → unlocks → opens to detail.
 | R14 | Idle hook creates noisy or false high-priority notifications        | High-priority push only from `waiting_input`, approval detection, crash, or explicit task transition |
 | R15 | Offline phone replays stale mutation after reconnect                | Do not queue mutations offline; user must re-open action and step up again |
 | R16 | Passkey registered on tailnet origin fails on Cloudflare origin     | Store `rp_id`/origin per credential; require separate credential enrollment per origin |
-| R17 | Anonymous Dev Tunnel access exposes CTM pairing and app auth to the public internet | Do not create anonymous access; reset stale port access to Dev Tunnels defaults; UI labels Microsoft Tunnel as private |
+| R17 | App-gated Dev Tunnel is reachable by URL (no edge sign-in) | The unguessable tunnel URL is not the gate — CTM's device token + per-origin passkey + step-up + default-deny route registry + rate-limit/lockout + audit are. For a stronger perimeter, opt into private (desktop browser only — breaks the phone PWA) or use Cloudflare Access / Tailscale |
 | R18 | User mistakes passkey for Microsoft account verification            | UI and docs say Microsoft/GitHub identity is checked by Dev Tunnels; CTM passkey only proves a registered credential for this origin |
 
 ### 10.2 Decisions from review
@@ -1370,7 +1407,8 @@ is the design's success.
 - Tailscale docs — Funnel, MagicDNS, certs.
   https://tailscale.com/docs/features/tailscale-funnel
   https://tailscale.com/docs/how-to/set-up-https-certificates
-- Cloudflare Tunnel + Access self-hosted public app and JWT validation.
+- Legacy Cloudflare Tunnel + Access references for old threat-model context,
+  not for new remote-access implementation.
   https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/
   https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/
 - SimpleWebAuthn (Node passkey lib). https://github.com/MasterKale/SimpleWebAuthn

package/template/claude-task-manager/docs/phone-passkey-identity.md

@@ -0,0 +1,122 @@
+# CTM Phone Passkey Identity
+
+CTM phone pairing has one durable identity rule:
+
+> The same phone on the same WebAuthn relying-party ID reuses the same CTM
+> passkey and the same CTM device row. It does not create another passkey.
+
+This document defines the pairing, recovery, origin, cleanup, and testing
+contracts for that rule.
+
+## Terms
+
+- **Phone profile**: CTM's best local match for a physical phone, currently the
+  normalized device label plus the browser/device hint parsed from the user
+  agent, for example `Owner iPhone` plus `iPhone Safari`.
+- **Origin**: Browser origin such as
+  `https://ctm-a8f39c-3456.usw2.devtunnels.ms`.
+- **RP ID**: WebAuthn relying-party ID. In CTM it is the origin host.
+- **Device token**: CTM's opaque cookie-backed token stored only as a hash in
+  `ctm_device_tokens`.
+- **Passkey credential**: WebAuthn public-key credential stored in
+  `ctm_webauthn_credentials`.
+
+## Pairing Decision
+
+When a claim reaches `POST /api/auth/claim/begin-passkey`, CTM resolves the
+claim origin and RP ID, then applies this order:
+
+1. Find an active authorized device with the same phone profile and a passkey
+   credential for the same RP ID.
+2. If one exists, return WebAuthn authentication options with `mode: "recover"`.
+   The phone confirms Face ID against the existing passkey.
+3. On `POST /api/auth/claim/finish` with `mode: "recover"`, CTM rotates the
+   token hash on the existing device row, updates its scopes/label from the new
+   claim, records `claim_recover`, and sets a fresh `ctm_token` cookie.
+4. No new `ctm_device_tokens` row and no new `ctm_webauthn_credentials` row are
+   created in this recovery path.
+5. If no same-RP credential exists but the same phone profile has an active
+   credential for another RP ID, CTM returns
+   `phone_origin_rotation_required`. It does not create another passkey.
+6. Only if there is no reusable same-phone identity does CTM return
+   `mode: "register"` and create a new device/passkey after WebAuthn
+   registration succeeds.
+
+This preserves the user's expectation that re-pairing the same phone is a
+reconnect, not an identity fork.
+
+## Origin Constraint
+
+WebAuthn credentials and browser cookies are origin/RP scoped. CTM cannot make a
+passkey created for one tunnel host work on another tunnel host.
+
+Examples:
+
+- Reopening `https://ctm-a8f39c-3456.usw2.devtunnels.ms/m/` uses the same RP
+  ID as the original pairing link from that host.
+- `ctm-a8f39c-3456.usw2.devtunnels.ms` and
+  `ctm-b91e02-3456.usw2.devtunnels.ms` are different RP IDs.
+
+The product consequence is intentional:
+
+- Same phone, same RP ID: reuse the existing passkey.
+- Same phone, different RP ID: stop and ask the user to open the stable phone
+  URL or explicitly revoke/replace the old phone pairing.
+
+Stable Tailscale, Cloudflare, or persistent Dev Tunnel origins are therefore
+part of the auth design, not just network convenience.
+
+## Duplicate Cleanup
+
+The recovery path prevents new duplicates, but older CTM versions may already
+have created repeated phone rows. CTM handles those in two ways:
+
+- After any successful new claim or claim recovery, CTM revokes active older
+  rows in the same duplicate group and records `device_revoke_duplicate`.
+- `Setup -> Access -> Paired phones` exposes a `Keep newest` or `Keep this
+  phone` action for existing duplicate groups. It calls
+  `POST /api/auth/device-duplicates/revoke` and keeps the selected device.
+
+Revoked devices remain in the database for audit, but setup hides removed rows
+behind a compact "removed connections" note.
+
+## Short-Lived Artifact Retention
+
+Pairing creates temporary rows that are not phone identities:
+
+- `ctm_device_claims`
+- `ctm_pairing_requests`
+- `ctm_webauthn_challenges`
+
+CTM prunes expired unclaimed claims, resolved/expired pairing requests, and old
+WebAuthn challenges through `cleanupMobileAuthArtifacts()`. Claimed device
+tokens, passkey credentials, and audit rows are not deleted by this cleanup.
+
+## User-Facing UX
+
+The phone claim page distinguishes the two flows:
+
+- Registration: `Face ID & Pair`
+- Recovery: `Face ID & Reconnect`
+
+Settings distinguishes normal auth health from duplicate cleanup:
+
+- Active paired phones show status, last seen time, origin, and duplicate notes.
+- Duplicate actions revoke only the other active devices in the same phone
+  profile group.
+- Different-origin same-phone conflicts require an explicit user decision
+  because CTM cannot prove the old RP credential on the new origin.
+
+## Verification Contract
+
+Tests should cover:
+
+1. Same phone plus same RP returns `mode: "recover"` from
+   `/api/auth/claim/begin-passkey`.
+2. Recovery finishes by rotating the existing device token hash.
+3. Recovery leaves `ctm_device_tokens` and `ctm_webauthn_credentials` counts
+   unchanged.
+4. Same phone plus different active RP returns
+   `phone_origin_rotation_required`.
+5. Manual duplicate cleanup revokes only the non-kept active devices.
+6. Expired WebAuthn challenges are pruned without deleting device identities.

package/template/claude-task-manager/docs/phone-setup.md

@@ -73,6 +73,9 @@ name before running `tailscale cert`.
 - HTTPS is enabled only when both `CTM_TLS_CERT` and `CTM_TLS_KEY` are present.
 - Mutating HTTP routes and WebSocket connections reject mismatched browser
   origins.
+- Phone passkeys are reused by phone profile and WebAuthn RP ID. See
+  [Phone Passkey Identity](phone-passkey-identity.md) for the same-phone
+  recovery and duplicate-cleanup contract.
 
 ## Cloudflare Tunnel + Access Fallback
 

package/template/claude-task-manager/docs/prompt-editing-tree-design.md

@@ -1,6 +1,9 @@
 # Prompt Editing Tree Design
 
-> Status: design only, not implemented
+> Status: staged implementation. Wall-E chat already has branch snapshots;
+> CTM Wall-E coding sessions now use the same active-path snapshot contract for
+> delete-from-prompt and edit/resend forks. The full immutable DAG schema below
+> remains the longer-term target.
 > Date: 2026-05-03
 > Scope: Wall-E chat, CTM Wall-E sessions, CTM transcript/review/session-memory caches
 
@@ -38,6 +41,27 @@ review panel, resume path, and Wall-E memory tools will use the wrong branch.
   provider CLIs can rewrite native history.
 - Avoid destructive JSONL truncation as the default editing primitive.
 
+## Implemented CTM Wall-E Coding Session Contract
+
+The first implementation intentionally reuses Wall-E's existing
+`chat_branches` sidecar instead of introducing a second CTM table.
+
+- The browser keeps `messages` as the active visible path.
+- Editing a user prompt saves the old suffix as a branch version, replaces the
+  visible suffix with the edited prompt, and resends from that point.
+- Deleting a user prompt truncates the visible path before that prompt and
+  saves the truncated active path.
+- Branch selection swaps the visible suffix without mutating message content.
+- Every Wall-E coding send includes `contextMessages`, a compact active-path
+  history, so `wall-e/chat.js` does not build model context from abandoned
+  chronological rows.
+- Review/session history reads prefer the durable branch snapshot when it
+  exists, then fall back to legacy CTM JSONL and Wall-E chat history.
+
+This gives the user-visible and model-visible behavior now while keeping the
+raw JSONL append-only. The later DAG migration can move the same semantics into
+first-class message-parent tables without changing the product behavior.
+
 ## Non-Goals
 
 - Do not implement this design in this document.