create-walle 0.9.25 → 0.9.26

package/template/claude-task-manager/docs/approval-hook-sandbox.md

@@ -0,0 +1,84 @@
+# Tier 3: containment via Claude's native Bash sandbox (Phase 4)
+
+## Why this shape (not CTM-side sandboxing)
+
+The research consensus is that approval prompts should be the *escalation path out of a
+sandbox*, not the primary defense — Anthropic's own sandboxing cut permission prompts
+~84%. But **CTM does not execute the agent's tool commands** — Claude does, in its own
+process — so CTM cannot wrap individual command execution from outside.
+
+The clean, low-risk lever is **Claude Code's built-in OS-level Bash sandbox** (macOS
+Seatbelt; Linux bubblewrap+socat), configured through `settings.json` — which CTM
+*already injects* for hook-governed sessions. So Phase 4 just turns that sandbox on for
+CTM sessions. Containment is enforced by the OS on the running process, so it holds
+even when an auto-approved command does more than its name suggests — exactly the
+defense-in-depth the allowlist alone cannot give.
+
+It even fits CTM's worktree workflow: Claude's sandbox special-cases linked git
+worktrees (it allows writes to the main repo's shared `.git` so `git commit` works).
+
+## What shipped
+
+- `buildClaudeHookSettings(port, { sandbox })`: when `sandbox` is truthy, the injected
+  `--settings` also carries `sandbox` — `true` → `{ enabled: true }` (safe default:
+  keeps the unsandboxed-fallback escape hatch, warns-not-fails if the sandbox can't
+  start), or a full sandbox config object passed through verbatim.
+- server.js: gated on a **separate** env flag `CTM_APPROVAL_HOOK_SANDBOX=1` (in addition
+  to `CTM_APPROVAL_HOOK=1`). **Default OFF.**
+
+## Why a separate, default-off flag
+
+Enabling the sandbox changes execution semantics and can add friction:
+- **Network**: no domains are pre-allowed; the first time a command needs a new domain
+  it prompts (which, for us, routes back through the hook). A build that fetches from
+  many hosts will generate approvals until the domains are allow-listed via
+  `sandbox.network.allowedDomains`.
+- **Writes outside cwd**: tools that write to `~/.kube`, `~/.cache`, etc. need
+  `sandbox.filesystem.allowWrite` entries or they fail (then fall back / retry
+  unsandboxed via the escape hatch).
+- **Known-incompatible tools** (`docker`, `watchman`/`jest --watch`, some Go CLIs on
+  macOS TLS) need `excludedCommands`.
+
+So this must be validated against the user's real projects before it goes on the live
+workbench. The default-off flag makes it explicit opt-in, exactly like `CTM_APPROVAL_HOOK`.
+
+## Validated (2026-06-12)
+
+Confirmed on this machine that Claude's Seatbelt sandbox **contains writes**: a
+`touch` to the home directory was blocked ("file writes restricted to the allowed
+working directory"), while writes to the cwd succeed. Notably this held even *without*
+CTM's flag — Claude Code 2.1.x already confines Bash writes to the cwd here (default /
+org policy). So on this machine the `CTM_APPROVAL_HOOK_SANDBOX` flag is **redundant**
+(the underlying sandbox is already active) and was intentionally **not** enabled on the
+primary — flipping a redundant flag via a disruptive restart buys nothing. The flag's
+value is for environments where Claude's sandbox is **not** already on; the capability
+is built, tested, and proven to work.
+
+## How to enable + validate
+
+1. On `/ctm-dev` (or a throwaway session), set both flags:
+   `CTM_APPROVAL_HOOK=1 CTM_APPROVAL_HOOK_SANDBOX=1`.
+2. Drive a real build / test / git workflow; confirm commands run (Seatbelt contains
+   them) and that legitimate network/write needs are either allowed by default (cwd +
+   temp + worktree `.git`) or surfaced as approvals you can allow-list.
+3. Add project-specific `sandbox.filesystem.allowWrite` / `sandbox.network.allowedDomains`
+   / `excludedCommands` as needed (a future increment can let CTM compose these per
+   project). Then flip the env flag on the primary (launchd plist) like CTM_APPROVAL_HOOK.
+
+## Hardening options (not enabled by default — they can break legit use)
+
+- `sandbox.filesystem.denyRead: ["~/.ssh", "~/.aws"]` — the default read policy still
+  allows reading credential files; deny them if the agent never needs to. (aws/gcloud
+  CLIs read `~/.aws`/`~/.config/gcloud`, so denying breaks them — scope carefully.)
+- `sandbox.allowUnsandboxedCommands: false` (strict) — removes the escape hatch so a
+  command can't be retried outside the sandbox. Strong, but turns "incompatible tool"
+  into a hard failure; pair with `excludedCommands`.
+- `sandbox.failIfUnavailable: true` — refuse to start unsandboxed (managed-deployment
+  gate). Default false (warn + run unsandboxed) is the safer interactive default.
+
+## Reference
+
+Claude Code sandbox docs: https://code.claude.com/docs/en/sandboxing and the
+`sandbox.*` keys in https://code.claude.com/docs/en/settings#sandbox-settings.
+The same primitives are the standalone `@anthropic-ai/sandbox-runtime` (used to wrap
+the *whole* agent process — a heavier alternative we deliberately did not take).

package/template/claude-task-manager/docs/codex-app-server-approvals.md

@@ -0,0 +1,72 @@
+# Codex app-server approval bridge (Phase 3)
+
+## Why this is a *bridge foundation*, not a drop-in like Claude hooks
+
+Claude Code lets an **external** process (CTM) answer approvals via a PreToolUse HTTP
+hook **while the user keeps using the TUI**. Codex has **no equivalent TUI-compatible
+hook**. Its programmatic surface is `codex app-server` (JSON-RPC over stdio), and the
+Codex TUI *is itself* an app-server client. So routing Codex approvals through CTM's
+classifier requires CTM to **be** the app-server client — i.e. own the conversation —
+which means a *CTM-driven Codex mode* (CTM renders the turn/items), not an interception
+layer under the existing PTY TUI.
+
+That is a larger product decision than the Claude work. This phase therefore delivers
+the **correctness-critical protocol layer** — tested and validated against the real
+binary — so the driven-mode wiring is a straightforward follow-on, not a research task.
+
+## What shipped
+
+- `lib/codex-approval-bridge.js` — pure mapping (unit-tested, 13 cases):
+  - `parseCodexApprovalRequest(method, params)` normalizes the **five** server→client
+    approval methods to `{ kind, protocol, context }` for the shared `decideApproval`
+    cascade. Handles both protocol generations the 0.132.0 binary emits:
+    - **v2:** `item/commandExecution/requestApproval`, `item/fileChange/requestApproval`,
+      `item/permissions/requestApproval`
+    - **legacy:** `execCommandApproval`, `applyPatchApproval`
+  - `buildCodexApprovalResponse(decision, protocol)` emits the right vocabulary:
+    v2 camelCase `accept|decline|cancel`; legacy snake_case `approved|denied|abort`.
+  - `decisionFromVerdict(verdict)` maps a `decideApproval` result → `allow|deny|abort`
+    (blocklist → `abort` = deny + interrupt the turn).
+- Real-binary validation: the `codex app-server` handshake (`initialize` → `initialized`)
+  was driven against codex-cli **0.132.0** and returns the documented result
+  (`userAgent, codexHome, platformFamily, platformOs`). The protocol layer is correct
+  against the shipping binary.
+
+## What also shipped: the driver engine
+
+- `lib/codex-app-server-client.js` (unit-tested, 10 cases): the stdio JSON-RPC client.
+  - `spawnCodexTransport()` spawns `codex app-server` and frames newline-delimited JSON;
+    a `transport` injection makes the dispatch testable without a real process.
+  - `createCodexAppServerClient({ transport, decide, onItem, onNotification, onApproval })`
+    does the handshake (`initialize` → `initialized`), `startThread` (defaults route
+    approvals to us: `approvalPolicy:"on-request"`, `approvalsReviewer:"user"`,
+    `sandbox:"workspace-write"`), `startTurn`, id-keyed request/response correlation, and
+    dispatches server-initiated approval requests through the bridge to the async
+    `decide(context, kind)` callback — answering keyed by the request id. Fail-closed:
+    `decide` throwing → deny; unknown server requests get an empty result so the agent
+    never wedges.
+- Validated **end-to-end against codex-cli 0.132.0**: the client drives a real
+  `initialize → thread/start → turn/start` and answers a live approval request via the
+  bridge (see the e2e probe). The protocol engine works against the shipping binary.
+
+## Remaining (the product surface)
+
+1. **CTM-driven-Codex session type.** Wire the client into a CTM session: render the
+   `item/*` / `turn/*` stream (CTM owns the UI — reuse the structured renderer used for
+   Wall-E chat), route `decide` through the shared `decideApproval` cascade, and **park**
+   human-needed approvals exactly like the Claude hook (hold the open JSON-RPC request,
+   raise the existing escalation card, resolve from the local/remote answer; dangerous →
+   cancel).
+2. **Product decision:** opt-in CTM-driven Codex sessions vs. the current PTY TUI (which
+   keeps the scrape path). Until that ships, Codex TUI sessions keep the scrape approver.
+
+The engine is also the right substrate for any **programmatic** Codex consumer (e.g. a
+Wall-E coding backend), where there is no TUI and driven mode is the *only* mode — there
+the remaining UI item (1) does not even apply.
+
+## Reference
+
+Exact wire contract (regenerate from the installed binary):
+`codex app-server generate-json-schema --out <dir>` → `ServerRequest.json`,
+`v2/ThreadStartParams.json`, `CommandExecutionRequestApprovalParams.json`, etc.
+See memory `ctm-approver-protocol-hook-prototype-validated` for the full protocol notes.

package/template/claude-task-manager/docs/codex-native-sandbox.md

@@ -0,0 +1,47 @@
+# Codex: native sandbox + on-request approvals (opt-in)
+
+The cheap Codex win that does NOT require driven mode. When CTM spawns a Codex session
+and `CTM_CODEX_SANDBOX=1`, CTM injects Codex's **own** sandbox + approval policy so it
+auto-runs safe commands *inside its native OS sandbox* (Seatbelt on macOS, landlock on
+Linux) and prompts far less — keeping the Codex TUI, no UI rebuild.
+
+- Injected (prepended, before any subcommand): `--sandbox workspace-write
+  --ask-for-approval on-request`.
+- **Never overrides an operator choice:** if the launch args already carry a sandbox /
+  approval / bypass / full-auto flag (or a `-c sandbox_mode=…` / `-c approval_policy=…`),
+  CTM leaves them untouched.
+- Default **OFF** (`CTM_CODEX_SANDBOX` unset). Enable per-environment by setting the env
+  var (launchd plist on the primary, like `CTM_APPROVAL_HOOK`).
+
+`lib/codex-sandbox-args.js` (`injectCodexSandboxArgs`) holds the pure logic (unit-tested);
+server.js applies it at the Codex spawn in `handleCreate`. Flags validated against
+codex-cli 0.132.0; the behavior was confirmed via the app-server e2e (workspace-write +
+on-request auto-ran a shell command without prompting).
+
+## What this is NOT (read before enabling)
+
+This reduces the *number* of Codex prompts and contains execution. It does **not**:
+- route the remaining Codex approvals through CTM's classifier (blocklist / learned
+  rules / verifier) — those still appear as Codex's own TUI widget (the scrape path);
+- give the unified "Needs You" card, remote/phone approval, or park-and-resolve for
+  Codex. **Only driven mode** (`docs/codex-app-server-approvals.md`) does that.
+
+## Cons / catches
+
+- **More autonomous.** Codex auto-runs reads + in-workspace writes without asking
+  (contained by the sandbox). That's the point, but it's a behavior change — hence
+  opt-in, and we never override an operator who deliberately runs Codex cautiously.
+- **Network is OFF** under `workspace-write`. Commands needing the network (`npm install`,
+  `git push`, `curl`) will fail-in-sandbox and escalate (→ prompt) unless you also enable
+  `[sandbox_workspace_write] network_access = true` in `~/.codex/config.toml` — which
+  weakens containment. No free lunch; default is the contained one.
+- **Scrape path stays** for the remaining prompts (fewer of them, but not eliminated).
+- **Codex-version-dependent** flags (`-s/--sandbox`, `-a/--ask-for-approval`) — stable in
+  0.132.0.
+
+## To enable on the primary
+
+Add `CTM_CODEX_SANDBOX=1` to the launchd plist `EnvironmentVariables` and bootout/bootstrap
+(KeepAlive/restart won't re-read plist env). Validate against your real Codex workflows
+first — a network-heavy project may want `network_access = true` or `--sandbox
+danger-full-access` for specific sessions.

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

@@ -243,6 +243,15 @@ CREATE INDEX idx_chat_messages_edited_from ON chat_messages(edited_from_id);
 `chat_branches` can remain temporarily as a compatibility payload, but new code
 should prefer `chat_branch_heads` plus message parent links.
 
+Current transition state: Wall-E sessions persist branch UI state through
+`chat_branch_events` (append-only audit/event log) and `chat_branch_state`
+(latest projection). The projection stores durable `chat_messages.id` references
+for transcript messages and only stores inline message bodies for optimistic
+client-only edits that do not have a durable row yet. Do not restore the old
+behavior where CTM rewrites a full `{branches, active, history}` transcript blob
+on every edit; that path hit request limits once images and long answers were in
+the conversation.
+
 ### CTM Cache Tables
 
 Add nullable tree fields to `session_messages`:
@@ -347,6 +356,11 @@ Existing APIs:
 - `/api/wall-e/chat/history` should continue returning active-path messages.
 - `/api/wall-e/chat/branches` can remain as legacy compatibility, but should
   eventually be backed by first-class branch tables.
+- `/api/wall-e/chat/branch-state` writes the compact ref projection and appends
+  an event. New CTM Wall-E session code should use this instead of posting a full
+  branch/history blob to `/api/wall-e/chat/branches`.
+- `/api/wall-e/chat/branch-events` exposes the append-only event stream for
+  debugging and future incremental clients.
 
 ### CTM Session Messages
 
@@ -517,7 +531,10 @@ Backfill algorithm:
 
 ### Phase 5: Advanced Cleanup
 
-- Retire `chat_branches` JSON blob or make it a derived cache.
+- Retire `chat_branches` JSON blob or make it a derived cache. The current
+  Wall-E browser UIs write compact state/events, so the remaining work is
+  migration/backfill and removing legacy API compatibility once old clients are
+  gone.
 - Add branch-aware memory ranking.
 - Add branch-aware export/import.
 - Add UI for branch rename/delete/hide.

package/template/claude-task-manager/lib/approval-hook.js

@@ -0,0 +1,200 @@
+'use strict';
+
+// Claude Code PreToolUse hook integration for CTM's auto-approver.
+//
+// Instead of screen-scraping the rendered approval widget and injecting keystrokes,
+// CTM injects a PreToolUse HTTP hook into the Claude sessions it spawns (via
+// `claude --settings '<json>'`). Claude then POSTs every governed tool call to CTM's
+// endpoint with STRUCTURED input ({tool_name, tool_input:{command}, session_id, cwd}),
+// and CTM answers with a permissionDecision. This eliminates the parse/quoting/clip/
+// TOCTOU failure class of the scrape path; the literal command is handed to us.
+//
+// Proven against claude 2.1.173 (see memory ctm-approver-protocol-hook-prototype-validated):
+//   - permissionDecision "allow" suppresses the interactive widget entirely;
+//   - "ask" falls through to Claude's native prompt (and shows our reason);
+//   - a hook ERROR or TIMEOUT degrades to the native prompt (FAIL-CLOSED / safe);
+//   - `--settings` MERGES with the user's config rather than replacing it.
+//
+// This module holds the PURE pieces (settings builder + decision→output mapper) so
+// they unit-test without a server. The route wiring lives in server.js.
+
+// Which Claude tools the hook governs (Claude matches tool_name against this regex).
+// Bash is where the auto-approval pain is; Edit/Write/Read/Glob/Grep are low-risk and
+// our classifier auto-allows them; `mcp__.*` brings MCP tool calls under the same
+// cascade (read-only → allow, mutating → human), so their widgets are suppressed too.
+const DEFAULT_MATCHER = 'Bash|Edit|Write|Read|Glob|Grep|NotebookEdit|WebFetch|mcp__.*';
+
+// Build the `--settings` JSON (string) that wires a PreToolUse HTTP hook back to CTM.
+// `port` is CTM's own HTTP port; the hook posts to /api/approval/hook on it.
+// timeoutSec is the per-hook budget — kept generous so a parked (awaiting-human)
+// request resolves on the structured channel before Claude falls back to its widget.
+function buildClaudeHookSettings(port, { matcher = DEFAULT_MATCHER, timeoutSec = 600, path = '/api/approval/hook', token = '', sandbox = false } = {}) {
+  const p = Number(port);
+  if (!Number.isFinite(p) || p <= 0) throw new Error('buildClaudeHookSettings: invalid port');
+  const hook = { type: 'http', url: `http://127.0.0.1:${p}${path}`, timeout: Math.max(1, Math.floor(timeoutSec)) };
+  // Phase 5: a per-session bearer token so only THIS CTM-spawned session can drive a
+  // decision through the (localhost, otherwise-unauthenticated) endpoint. Validated
+  // server-side against the session's stored token; a mismatch fails closed.
+  if (token) hook.headers = { Authorization: `Bearer ${token}` };
+  const settings = { hooks: { PreToolUse: [{ matcher, hooks: [hook] }] } };
+  // Phase 4 (Tier 3): enable Claude Code's built-in OS-level Bash sandbox (macOS
+  // Seatbelt / Linux bubblewrap) so an auto-approved command is CONTAINED — writes
+  // limited to the cwd + temp, network gated. CTM cannot sandbox execution it does not
+  // own; this turns on Claude's native sandbox via the settings we already inject.
+  // `sandbox === true` → safe default (enabled; keeps the unsandboxed-fallback escape
+  // hatch and warns-not-fails if unavailable). Or pass a full sandbox config object.
+  if (sandbox) settings.sandbox = (sandbox === true) ? { enabled: true } : sandbox;
+  return JSON.stringify(settings);
+}
+
+// Check that a request's Authorization header matches the session's expected hook
+// token. A plain string compare (not constant-time) — the token only gates a
+// same-machine, per-session approval decision over localhost, so a timing side channel
+// is not in scope. Returns true when no token is required (backward-compatible:
+// sessions launched before tokens, or non-hook sessions, are not rejected).
+function hookTokenOk(expectedToken, authorizationHeader) {
+  if (!expectedToken) return true; // nothing to enforce
+  return String(authorizationHeader || '') === `Bearer ${expectedToken}`;
+}
+
+// Map our shared decideApproval() result to a Claude PreToolUse hook output object.
+// decideApproval returns { decision: 'allow' | 'ask', decidedBy, riskLevel, reason, ... }.
+//   - 'allow'                       -> permissionDecision 'allow'  (widget suppressed)
+//   - 'ask' from the blocklist      -> permissionDecision 'deny'   (hard refuse + tell the model why)
+//   - 'ask' otherwise (escalation)  -> permissionDecision 'ask'    (Phase 1a: native widget;
+//                                       Phase 1b parks instead and returns allow/deny)
+// Returns the object Claude expects under hookSpecificOutput, plus our internal
+// `_route` tag ('allow'|'deny'|'ask') so the caller can decide whether to park.
+function mapDecisionToHookOutput(d) {
+  const decision = d && d.decision;
+  const reason = (d && d.reason) || '';
+  if (decision === 'allow') {
+    return { _route: 'allow', permissionDecision: 'allow', permissionDecisionReason: reason || 'Auto-approved by CTM' };
+  }
+  // Everything else is "not auto-approved". A blocklist hit is an objective refusal.
+  if (d && d.decidedBy === 'blocklist') {
+    return { _route: 'deny', permissionDecision: 'deny', permissionDecisionReason: reason || 'Blocked by CTM dangerous-command blocklist' };
+  }
+  return { _route: 'ask', permissionDecision: 'ask', permissionDecisionReason: reason || 'CTM routed this to manual review' };
+}
+
+// Wrap a hookSpecificOutput payload into the full hook response body.
+function hookResponseBody(output) {
+  const { _route, ...rest } = output || {};
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', ...rest } };
+}
+
+// Map a Claude PreToolUse payload's tool_name + tool_input to the context object the
+// approver cascade expects. Claude tools: Bash -> command; Edit/Write/Read -> file path.
+const CLAUDE_TOOL_TO_CONTEXT = {
+  Bash: (ti) => ({ toolName: 'Bash command', command: String((ti && ti.command) || '') }),
+  Edit: (ti) => ({ toolName: 'Edit', command: String((ti && ti.file_path) || '') }),
+  Write: (ti) => ({ toolName: 'Write', command: String((ti && ti.file_path) || '') }),
+  NotebookEdit: (ti) => ({ toolName: 'NotebookEdit', command: String((ti && ti.notebook_path) || '') }),
+  Read: (ti) => ({ toolName: 'Read', command: String((ti && ti.file_path) || '') }),
+  Glob: (ti) => ({ toolName: 'Glob', command: String((ti && ti.pattern) || '') }),
+  Grep: (ti) => ({ toolName: 'Grep', command: String((ti && ti.pattern) || '') }),
+  WebFetch: (ti) => ({ toolName: 'WebFetch', command: String((ti && ti.url) || '') }),
+};
+
+// MCP tool calls (tool_name `mcp__<server>__<tool>`) carry their args in tool_input.
+// Serialize a compact descriptor so reviewWithHeuristics (which keys on the tool name
+// for read-only-vs-mutating) and the verifier both have the full call to judge.
+function _mcpContext(toolName, toolInput) {
+  let args = '';
+  try { args = JSON.stringify(toolInput || {}); } catch { args = ''; }
+  if (args === '{}') args = '';
+  const command = args ? `${toolName} ${args}`.slice(0, 2000) : toolName;
+  return { toolName, command };
+}
+
+function contextFromHookPayload(payload) {
+  const toolName = payload && payload.tool_name;
+  const toolInput = (payload && payload.tool_input) || {};
+  const mapper = CLAUDE_TOOL_TO_CONTEXT[toolName];
+  let base;
+  if (mapper) base = mapper(toolInput);
+  else if (/^(?:mcp__|plugin:)/i.test(String(toolName || ''))) base = _mcpContext(toolName, toolInput);
+  else base = { toolName: toolName || 'Unknown', command: '' };
+  return { ...base, warning: '', fullContext: base.command };
+}
+
+// Park manager (Phase 1b): the Map + promise + timeout mechanics for holding a
+// hook request open while a human decides. Pure of CTM internals — the server
+// injects the card raise/clear as side effects (onTimeout) and decides the requestId.
+// park() resolves to 'allow' | 'deny' (resolve() called) or 'ask' (deadline elapsed).
+// One parked request per session; a second park() hands the prior one to 'ask' (the
+// native-widget fallback) so a request is never silently dropped.
+function createHookApprovalPark({ deadlineMs = 590000, onTimeout, now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
+  const map = new Map(); // sessionId -> { resolve, requestId, timer, createdAt }
+  function park(sessionId, requestId) {
+    const existing = map.get(sessionId);
+    if (existing) {
+      map.delete(sessionId);
+      if (existing.timer) clearTimer(existing.timer);
+      try { existing.resolve('ask'); } catch { /* prior awaiter gone */ }
+    }
+    return new Promise((resolve) => {
+      // Register the entry BEFORE arming the timer so the timeout callback always sees
+      // it — a synchronous timer (tests) would otherwise fire before the map.set and
+      // find nothing, never resolving. (Real setTimeout is async, but this is the
+      // correct invariant regardless.)
+      const entry = { resolve, requestId, timer: null, createdAt: now() };
+      map.set(sessionId, entry);
+      entry.timer = setTimer(() => {
+        const cur = map.get(sessionId);
+        if (!cur || cur.requestId !== requestId) return;
+        map.delete(sessionId);
+        try { if (typeof onTimeout === 'function') onTimeout(sessionId, requestId); } catch { /* never break the resolve */ }
+        resolve('ask');
+      }, deadlineMs);
+      if (entry.timer && typeof entry.timer.unref === 'function') entry.timer.unref();
+    });
+  }
+  function resolve(sessionId, decision) {
+    const p = map.get(sessionId);
+    if (!p) return null;
+    map.delete(sessionId);
+    if (p.timer) clearTimer(p.timer);
+    try { p.resolve(decision); } catch { /* awaiter gone */ }
+    return p;
+  }
+  return {
+    park,
+    resolve,
+    has: (sessionId) => map.has(sessionId),
+    size: () => map.size,
+  };
+}
+
+// Shape the approval_decisions row for a parked hook escalation — parity with
+// the scrape path's escalation records so the Permission "Pending" tab stays
+// populated as sessions migrate to the hook. `parts` is the operative-command
+// parse (approval-agent escalationCommandParts) so the row titles with the
+// COMMAND, not a reason label. Pure: the caller owns the DB write.
+function escalationRecordFromPark(sessionId, context, decision, label, parts) {
+  const p = parts || {};
+  return {
+    sessionId,
+    toolName: (context && context.toolName) || '',
+    commandSummary: p.title || String(label || '').slice(0, 160) || 'command',
+    fullContext: String((context && (context.fullContext || context.command)) || '').slice(0, 2000),
+    warning: (context && context.warning) || '',
+    decision: 'escalated',
+    reasoning: (decision && decision.reason) || 'Escalated by the approval hook',
+    decidedBy: (decision && decision.decidedBy) || 'hook',
+    riskLevel: (decision && decision.riskLevel) || 'medium',
+    commandSignature: p.signature || '',
+  };
+}
+
+module.exports = {
+  DEFAULT_MATCHER,
+  buildClaudeHookSettings,
+  hookTokenOk,
+  mapDecisionToHookOutput,
+  hookResponseBody,
+  contextFromHookPayload,
+  createHookApprovalPark,
+  escalationRecordFromPark,
+};

package/template/claude-task-manager/lib/approval-self-adapt.js

@@ -162,6 +162,7 @@ module.exports = {
   learnFromInterrupt,
   learnFromApproveAfterEscalation,
   runSelfAdaptMaintenance,
+  _escapeRegex,
   _sqliteTimeMs,
   DEFAULT_INTERRUPT_WINDOW_MS,
   DEFAULT_APPROVE_WINDOW_MS,

package/template/claude-task-manager/lib/auth-rules.js

@@ -16,12 +16,23 @@ const WS_AUTH_RULES = Object.freeze({
   reconcile: rule('read', false, 'never'),
   resize: rule('read', false, 'never'),
   reflow: rule('read', false, 'never'),
+  // Backpressure flow control: a viewer asks to pause/resume its own output
+  // stream (the server further gates an actual PTY pause to raw-eligible
+  // primaries). Same render-control class as reconcile/reflow — read scope.
+  flow: rule('read', false, 'never'),
+  // Client-reported render diagnostics (rows-flap attribution probe) — telemetry
+  // into the per-session diagnostics ring; rate-limited + scalar-whitelisted in
+  // handleClientDiag, so viewer (read) scope is sufficient.
+  'client-diag': rule('read', false, 'never'),
   'walle-history-request': rule('read', false, 'never'),
 
   input: rule('respond', true, 'remote'),
   'walle-message': rule('respond', true, 'remote'),
   'walle-cancel': rule('respond', true, 'remote'),
   'walle-permission-response': rule('respond', true, 'remote'),
+  // Resolve a parked protocol-hook approval (allow/deny) — same class as
+  // answering any other approval prompt.
+  'approval-resolve': rule('respond', true, 'remote'),
 
   create: rule('create', true, 'remote'),
 

package/template/claude-task-manager/lib/background-llm.js

@@ -23,16 +23,28 @@ const MODEL_TIER_ENV = {
 // so a Wall-E restart doesn't pin us to env for long.
 const WALLE_DEFAULTS_TTL_MS = 30000;
 const WALLE_DEFAULTS_NEGATIVE_TTL_MS = 5000;
-let _walleDefaultsCache = null; // { at, value: {provider, model} | null }
+let _walleDefaultsCache = null; // { at, value: {provider, model} | null, authoritative }
+// Stale-while-revalidate: the last starred default a status fetch ever returned. When
+// Wall-E is slow (>timeout) or briefly down — exactly when the box is busiest — a stale
+// starred default is far better than falling through to env.WALLE_PROVIDER, which launchd
+// pins to whatever the plist said at bootstrap (observed: a stale deepseek pin surviving
+// KeepAlive respawns → 402 churn). The starred default changes rarely and only via a
+// Wall-E that is up, so serving the last-seen value while retrying is always safe.
+let _lastGoodWalleDefaults = null;
 
 function _resetWalleDefaultsCache() {
   _walleDefaultsCache = null;
+  _lastGoodWalleDefaults = null;
 }
 
 async function fetchWalleStatusDefaults(env) {
   const port = Number(env?.WALLE_PORT) || 3457;
+  // 2500ms matches the setup handler's Wall-E status budget: a loaded Wall-E routinely
+  // answers in 0.6–1.2s, and a timeout here means falling back to the (possibly stale)
+  // env pin or last-good value — be generous before giving up.
+  const timeoutMs = Number(env?.CTM_WALLE_DEFAULTS_FETCH_TIMEOUT_MS) || 2500;
   const response = await fetch(`http://127.0.0.1:${port}/api/wall-e/status`, {
-    signal: AbortSignal.timeout(1500),
+    signal: AbortSignal.timeout(timeoutMs),
   });
   if (!response.ok) throw new Error(`Wall-E status returned ${response.status}`);
   const json = await response.json();
@@ -44,21 +56,37 @@ async function getWalleDefaultSelection(options = {}) {
   if (String(env.CTM_BACKGROUND_LLM_WALLE_DEFAULTS || '').trim() === '0') return null;
   const now = Date.now();
   if (_walleDefaultsCache) {
-    const ttl = _walleDefaultsCache.value ? WALLE_DEFAULTS_TTL_MS : WALLE_DEFAULTS_NEGATIVE_TTL_MS;
+    // Stale-served results keep the short negative TTL so a recovered Wall-E is
+    // consulted again promptly; authoritative results get the full TTL. Both are
+    // env-tunable (and 0 disables caching — used by tests to force refetches).
+    const _ttlOf = (key, dflt) => {
+      const n = Number(env[key]);
+      return Number.isFinite(n) && n >= 0 ? n : dflt;
+    };
+    const ttl = _walleDefaultsCache.authoritative
+      ? _ttlOf('CTM_WALLE_DEFAULTS_TTL_MS', WALLE_DEFAULTS_TTL_MS)
+      : _ttlOf('CTM_WALLE_DEFAULTS_NEGATIVE_TTL_MS', WALLE_DEFAULTS_NEGATIVE_TTL_MS);
     if (now - _walleDefaultsCache.at < ttl) return _walleDefaultsCache.value;
   }
   let value = null;
+  let authoritative = false;
   try {
     const fetchStatus = options.fetchWalleStatus || fetchWalleStatusDefaults;
     const status = await fetchStatus(env);
     const provider = sanitizeSetupProviderType(status?.walle_provider || '');
     if (provider) {
       value = { provider, model: typeof status?.walle_model === 'string' ? status.walle_model : '' };
+      authoritative = true;
     }
   } catch {
     value = null;
   }
-  _walleDefaultsCache = { at: now, value };
+  if (authoritative) {
+    _lastGoodWalleDefaults = value;
+  } else {
+    value = _lastGoodWalleDefaults;
+  }
+  _walleDefaultsCache = { at: now, value, authoritative };
   return value;
 }