castle-web-cli 0.4.75 → 0.4.77

package/dist/agent.js

@@ -91,6 +91,24 @@ const MAX_TASK_ATTEMPTS = 3;
 // limits. Over-cap tasks stay queued ('waiting') and start, earliest-created
 // first, as running ones finish. Conservative default; override via env.
 const MAX_CONCURRENT_TASKS = Number(process.env.CASTLE_MAX_CONCURRENT_TASKS) || 4;
+// Base backoff (ms) before a crashed task agent is relaunched, scaled by
+// attempt number and jittered (see waitBeforeTaskRetry). Incident (2026-07):
+// the router spawned 4 parallel tasks whose cursor-agent processes all
+// crashed at startup within ~1.3s with a macOS keychain error ("Security
+// command failed: Security process exited with code: 44" -- credential
+// lookup contention when many cursor-agent processes start at once). The old
+// instant retry burned all 3 attempts of every task inside that same ~6s
+// contention window (11 agent processes launched in ~7s); the one retry that
+// happened to land ~2s later succeeded, so growing + jittered spacing
+// between attempts gives the keychain time to clear. Override for tests /
+// impatient devs, same pattern as CASTLE_MAX_CONCURRENT_TASKS above.
+const TASK_RETRY_BACKOFF_BASE_MS = Number(process.env.CASTLE_TASK_RETRY_BACKOFF_MS) || 1500;
+// Minimal spacing enforced between successive task-agent PROCESS LAUNCHES
+// (see staggerTaskSpawn) -- the initial simultaneous spawn is itself part of
+// the same thundering herd as the retry storm above, independent of it.
+// Router turns are unaffected: only one ever runs at a time. Override for
+// tests / impatient devs.
+const TASK_SPAWN_STAGGER_MS = Number(process.env.CASTLE_TASK_SPAWN_STAGGER_MS) || 400;
 const TASK_POLL_MS = 1_000;
 const FENCE_HOLDBACK = "```castle-";
 const RESULT_SUMMARY_CHARS = 600;
@@ -125,6 +143,35 @@ function visibleLength(raw) {
     }
     return raw.length;
 }
+// Parse one ```castle-task fence's body (title line, optional "after:" line,
+// then the prompt) into a directive. Shared by the settle-time full-text
+// extraction below and the mid-stream incremental scanner (runRouterTurnIn),
+// so a fence spawned early behaves identically to one spawned at settle.
+function parseTaskFenceBody(body) {
+    const lines = body.replace(/\r/g, "").split("\n");
+    const title = (lines.shift() ?? "").trim();
+    if (!title)
+        return null;
+    const after = [];
+    while (lines.length > 0) {
+        const headerMatch = /^(after):\s*(.*)$/i.exec((lines[0] ?? "").trim());
+        if (!headerMatch)
+            break;
+        lines.shift();
+        after.push(...headerMatch[2]
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean));
+    }
+    return { title, after, prompt: lines.join("\n").trim() };
+}
+// A fresh RegExp per call -- this is matched with manual .exec() loops in
+// TWO independent call sites (settle-time extractDirectives via .replace, and
+// the mid-stream scanNewTaskFences via a lastIndex-seeded loop) that must
+// never share mutable lastIndex state.
+function taskFenceRegex() {
+    return /```castle-task[ \t]*\r?\n([\s\S]*?)```/g;
+}
 // Pull ```castle-task fenced directives out of a finished router reply.
 // Block format: title line, then an optional "after:" line, then the prompt.
 function extractDirectives(full) {
@@ -143,25 +190,10 @@ function extractDirectives(full) {
         });
     };
     const withoutDone = listFence(listFence(full, "castle-done", checkoffs), "castle-stop", stops);
-    const fenceRe = /```castle-task[ \t]*\r?\n([\s\S]*?)```/g;
-    const cleaned = withoutDone.replace(fenceRe, (_match, body) => {
-        const lines = String(body).replace(/\r/g, "").split("\n");
-        const title = (lines.shift() ?? "").trim();
-        const headers = { after: [] };
-        while (lines.length > 0) {
-            const headerMatch = /^(after):\s*(.*)$/i.exec((lines[0] ?? "").trim());
-            if (!headerMatch)
-                break;
-            lines.shift();
-            headers[headerMatch[1].toLowerCase()] = headerMatch[2]
-                .split(",")
-                .map((s) => s.trim())
-                .filter(Boolean);
-        }
-        const prompt = lines.join("\n").trim();
-        if (title) {
-            directives.push({ title, after: headers.after, prompt });
-        }
+    const cleaned = withoutDone.replace(taskFenceRegex(), (_match, body) => {
+        const directive = parseTaskFenceBody(String(body));
+        if (directive)
+            directives.push(directive);
         return "";
     });
     return {
@@ -171,6 +203,28 @@ function extractDirectives(full) {
         stops,
     };
 }
+// Scan `raw` for ```castle-task fences that have FULLY closed since
+// `fromIndex` -- i.e. their closing ``` has already streamed in -- and parse
+// each into a directive. Returns the index just past the last one consumed,
+// so the next call only looks at genuinely new text. castle-done / castle-
+// stop fences are deliberately NOT scanned here: they stay settle-only (see
+// runRouterTurnIn) since they are cheap and order-sensitive, and acting on a
+// stop/done fence before the reply is even finished streaming would be
+// surprising.
+function scanNewTaskFences(raw, fromIndex) {
+    const re = taskFenceRegex();
+    re.lastIndex = fromIndex;
+    const directives = [];
+    let nextIndex = fromIndex;
+    let match;
+    while ((match = re.exec(raw))) {
+        const directive = parseTaskFenceBody(match[1]);
+        if (directive)
+            directives.push(directive);
+        nextIndex = re.lastIndex;
+    }
+    return { directives, nextIndex };
+}
 // -- agent signals (```signal blocks from task agents) -----------------------
 // A running task agent narrates in prose and periodically emits ONE fenced
 // ```signal block of progress metadata (mirrors djinn's lib/markdown.ts). We
@@ -277,6 +331,26 @@ function claudeToolFeedLabel(name, input) {
     }
     return null;
 }
+// Coarse activity label for a claude tool from its NAME alone (available at
+// content_block_start, before the input JSON streams in). Router-only fallback
+// so the streaming reply's activity line reflects EVERY tool -- including the
+// commands/searches claudeToolFeedLabel intentionally drops from task feeds.
+// Mirrors the cursor toolActivityLabel verbs so the two backends read alike.
+function genericClaudeToolLabel(name) {
+    const kind = name.toLowerCase();
+    if (kind.startsWith("read") || kind.startsWith("notebookread"))
+        return "Reading the deck";
+    if (["edit", "write", "notebook", "multiedit"].some((p) => kind.startsWith(p)))
+        return "Editing files";
+    if (kind.startsWith("bash") || kind.includes("terminal"))
+        return "Running a command";
+    if (["grep", "glob", "ls"].some((p) => kind.startsWith(p)) ||
+        kind.includes("search"))
+        return "Searching the deck";
+    if (kind.startsWith("web"))
+        return "Searching the web";
+    return "Working";
+}
 // Human-readable label for a tool_call event, e.g. readToolCall -> "reading
 // the deck". Shown as the streaming message's activity line.
 function toolActivityLabel(ev) {
@@ -286,13 +360,13 @@ function toolActivityLabel(ev) {
         : undefined;
     const kind = (key ?? "").slice(0, -"ToolCall".length).toLowerCase();
     if (["read", "glob", "grep", "ls", "list"].some((p) => kind.startsWith(p))) {
-        return "reading the deck";
+        return "Reading the deck";
     }
     if (["write", "edit", "delete", "mv"].some((p) => kind.startsWith(p)))
-        return "editing files";
+        return "Editing files";
     if (["shell", "bash", "terminal"].some((p) => kind.startsWith(p)))
-        return "running a command";
-    return "working";
+        return "Running a command";
+    return "Working";
 }
 // Castle's agent CLI keys, delivered to the sandbox as a file
 // (~/.castle/keys.json) rather than sandbox-wide env -- so an ambient key can't
@@ -344,17 +418,253 @@ function envForAgentSpawn(backend) {
     }
     return env;
 }
+const DECK_TREE_EXCLUDE = new Set([
+    "node_modules",
+    ".castle",
+    ".git",
+    "dist",
+    ".DS_Store",
+]);
+const DECK_TREE_MAX_ENTRIES = 200;
+// Per-directory listing cap. A successful deck accumulates hundreds of
+// drawings; without this, one big directory exhausts the global budget
+// depth-first and every directory sorting after it (scenes/ included) vanishes
+// from the snapshot entirely. Summarizing the overflow as "(+N more .pxart)"
+// keeps every directory visible and turns the count itself into signal.
+const DECK_TREE_PER_DIR = 15;
+// Shallow orientation snapshot for router/task prompts. Best-effort by design:
+// filesystem hiccups should cost context, not fail an agent turn.
+function buildDeckTree(deckDir) {
+    const lines = [];
+    const walk = (dir, prefix, depth) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => {
+            if (a.isDirectory() !== b.isDirectory())
+                return a.isDirectory() ? -1 : 1;
+            return a.name.localeCompare(b.name);
+        });
+        const visible = entries.filter((e) => !DECK_TREE_EXCLUDE.has(e.name));
+        for (const entry of visible.slice(0, DECK_TREE_PER_DIR)) {
+            if (lines.length >= DECK_TREE_MAX_ENTRIES) {
+                lines.push(`${prefix}...`);
+                return;
+            }
+            const isDir = entry.isDirectory();
+            lines.push(`${prefix}${entry.name}${isDir ? "/" : ""}`);
+            if (isDir && depth < 1) {
+                walk(path.join(dir, entry.name), prefix + "  ", depth + 1);
+            }
+        }
+        const rest = visible.slice(DECK_TREE_PER_DIR);
+        if (rest.length > 0 && lines.length < DECK_TREE_MAX_ENTRIES) {
+            // Name the overflow's extension when it's uniform ("+214 more .pxart"),
+            // since that tells the reader what kind of files dominate the directory.
+            const exts = new Set(rest.map((e) => (e.isDirectory() ? "/" : path.extname(e.name))));
+            const [only] = exts;
+            const suffix = exts.size === 1 && only && only !== "/" ? ` ${only}` : "";
+            lines.push(`${prefix}(+${rest.length} more${suffix})`);
+        }
+    };
+    walk(deckDir, "", 0);
+    return lines.join("\n");
+}
+function readQuickReference(deckDir) {
+    for (const name of ["CLAUDE.md", "AGENTS.md"]) {
+        let raw = "";
+        try {
+            raw = fs.readFileSync(path.join(deckDir, name), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const heading = /^## Quick reference\s*$/im.exec(raw);
+        if (!heading || heading.index === undefined)
+            continue;
+        const bodyStart = raw.indexOf("\n", heading.index);
+        if (bodyStart < 0)
+            return "";
+        const rest = raw.slice(bodyStart + 1);
+        const nextHeading = /^##\s+/m.exec(rest);
+        return (nextHeading ? rest.slice(0, nextHeading.index) : rest).trim();
+    }
+    return "";
+}
+const TOUCHED_FILE_LIMIT = 10;
+function collectStrings(value, out) {
+    if (typeof value === "string") {
+        out.push(value);
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value)
+            collectStrings(item, out);
+    }
+    else if (value && typeof value === "object") {
+        for (const item of Object.values(value)) {
+            collectStrings(item, out);
+        }
+    }
+}
+function toolWritesFiles(name) {
+    const kind = name.toLowerCase();
+    return ["edit", "write", "notebookedit", "multiedit", "delete"].some((p) => kind.startsWith(p));
+}
+function toolRunsShell(name) {
+    const kind = name.toLowerCase();
+    return (kind.startsWith("bash") ||
+        kind.startsWith("shell") ||
+        kind.includes("terminal"));
+}
+function drawingPathForDrawArg(raw) {
+    const name = raw.replace(/^['"]|['"]$/g, "").trim();
+    if (!name || name.startsWith("-") || name.includes("\n"))
+        return null;
+    if (name.startsWith("drawings/")) {
+        return name.endsWith(".pxart") ? name : `${name}.pxart`;
+    }
+    return `drawings/${name.endsWith(".pxart") ? name : `${name}.pxart`}`;
+}
+function shellTouchedCandidates(command) {
+    const out = [];
+    const redirectRe = /(?:^|[\s;|])(?:\d*)>>?\s*(?!&)(?:"([^"]+)"|'([^']+)'|([^\s;&|]+))/g;
+    for (const match of command.matchAll(redirectRe)) {
+        const target = match[1] ?? match[2] ?? match[3];
+        if (target)
+            out.push(target);
+    }
+    const drawRe = /npm\s+run\s+draw\s+--\s+([^\s;&|]+)/g;
+    for (const match of command.matchAll(drawRe)) {
+        const drawing = drawingPathForDrawArg(match[1] ?? "");
+        if (drawing)
+            out.push(drawing);
+    }
+    return out;
+}
+// Guards every touched-file candidate (shell redirects AND tool file-path
+// args) against junk that isn't plausibly a path. Added because
+// shellTouchedCandidates' redirect regex treats any `>`-plus-token as a
+// write target, so a command merely CONTAINING `>=` (e.g. a numeric
+// comparison inside a quoted inline JS/awk script) false-matches as a
+// redirect to "=" (or "=5" with no space around the `>=`) -- neither looks
+// like a real file. A leading "-" is rejected too, mirroring
+// drawingPathForDrawArg's flag guard above.
+function looksLikeTouchedPath(raw) {
+    return /[a-zA-Z0-9]/.test(raw) && raw[0] !== "-" && raw[0] !== "=";
+}
+function normalizeTouchedPath(cwd, raw) {
+    if (!raw || raw.includes("\n") || !looksLikeTouchedPath(raw))
+        return null;
+    const abs = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+    const rel = path.relative(cwd, abs);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel))
+        return null;
+    const normalized = rel.split(path.sep).join("/");
+    if (normalized.startsWith(".castle/") || PROGRESS_FILE_RE.test(normalized)) {
+        return null;
+    }
+    return normalized;
+}
+function addTouchedFiles(files, cwd, toolName, input) {
+    const candidates = [];
+    if (toolWritesFiles(toolName)) {
+        collectStrings([
+            input.file_path,
+            input.path,
+            input.notebook_path,
+            input.old_path,
+            input.new_path,
+        ], candidates);
+    }
+    else if (toolRunsShell(toolName) && typeof input.command === "string") {
+        candidates.push(...shellTouchedCandidates(input.command));
+    }
+    else {
+        return;
+    }
+    for (const candidate of candidates) {
+        const normalized = normalizeTouchedPath(cwd, candidate);
+        if (normalized)
+            files.add(normalized);
+    }
+}
+function cursorToolNameAndInput(ev) {
+    const call = ev.tool_call;
+    const key = call ? Object.keys(call).find((k) => k.endsWith("ToolCall")) : undefined;
+    if (!call || !key)
+        return null;
+    const input = call[key];
+    const args = input && typeof input === "object"
+        ? input.args
+        : undefined;
+    return {
+        name: key.slice(0, -"ToolCall".length),
+        input: args && typeof args === "object"
+            ? args
+            : input && typeof input === "object"
+                ? input
+                : {},
+    };
+}
+function touchedFileList(files) {
+    const sorted = [...files].sort();
+    if (sorted.length <= TOUCHED_FILE_LIMIT)
+        return sorted;
+    return [
+        ...sorted.slice(0, TOUCHED_FILE_LIMIT),
+        `+${sorted.length - TOUCHED_FILE_LIMIT} more`,
+    ];
+}
 function createAgentStreamState() {
     return {
         accumulated: "",
         finalText: "",
         resultIsError: false,
+        usage: undefined,
+        filesTouched: new Set(),
         sawResult: false,
         segmentText: "",
         needsGap: false,
         pendingTools: new Map(),
     };
 }
+function parseCliUsage(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const src = raw;
+    const usage = {};
+    for (const key of [
+        "input_tokens",
+        "output_tokens",
+        "cache_creation_input_tokens",
+        "cache_read_input_tokens",
+    ]) {
+        const value = src[key];
+        if (typeof value === "number")
+            usage[key] = value;
+    }
+    return Object.keys(usage).length > 0 ? usage : undefined;
+}
+function formatTokenCount(value) {
+    if (typeof value !== "number")
+        return "?";
+    if (value >= 1000)
+        return `${(value / 1000).toFixed(1)}k`;
+    return String(value);
+}
+function logRouterUsage(backend, usage) {
+    if (!usage)
+        return;
+    const input = formatTokenCount(usage.input_tokens);
+    const read = formatTokenCount(usage.cache_read_input_tokens);
+    const created = formatTokenCount(usage.cache_creation_input_tokens);
+    const output = formatTokenCount(usage.output_tokens);
+    console.error(`[agent usage] router ${backend}: input=${input} cache_read=${read} cache_created=${created} output=${output}`);
+}
 // Build the per-run stdout event handler over a shared mutable parser state.
 // Splitting the cursor + claude stream decoding out of runAgentCli keeps each
 // within the max-lines budget; behavior is identical (same delta/activity/
@@ -388,15 +698,22 @@ function makeAgentEventHandler(opts, state) {
             if (e?.type === "content_block_start") {
                 if (e.content_block?.type === "tool_use") {
                     state.needsGap = true;
-                    // Hold the label until content_block_stop, once the input (file /
-                    // command) has streamed in, so we can name it concretely.
-                    state.pendingTools.set(e.index ?? -1, {
-                        name: String(e.content_block.name ?? ""),
-                        buf: "",
-                    });
+                    const name = String(e.content_block.name ?? "");
+                    // Router: show a coarse label NOW (name is known) so the activity
+                    // line isn't stuck on the prior state while the tool runs; the
+                    // concrete label (with the file) refines it at content_block_stop.
+                    if (opts.labelUnknownTools)
+                        opts.onActivity?.(genericClaudeToolLabel(name));
+                    // Hold the concrete label until content_block_stop, once the input
+                    // (file / command) has streamed in, so we can name it concretely.
+                    state.pendingTools.set(e.index ?? -1, { name, buf: "" });
                 }
                 else if (e.content_block?.type === "thinking") {
                     state.needsGap = true;
+                    // Surface extended thinking as the activity line (mirrors the cursor
+                    // path's `thinking` signal). The next text delta clears it via
+                    // emitDelta's onActivity(null); a tool block relabels it.
+                    opts.onActivity?.("Thinking");
                 }
             }
             else if (e?.type === "content_block_delta") {
@@ -430,6 +747,7 @@ function makeAgentEventHandler(opts, state) {
                     catch {
                         /* input JSON arrived partial -- fall back to a generic label */
                     }
+                    addTouchedFiles(state.filesTouched, opts.cwd, pending.name, input);
                     const label = claudeToolFeedLabel(pending.name, input);
                     if (label)
                         opts.onActivity?.(label);
@@ -441,6 +759,7 @@ function makeAgentEventHandler(opts, state) {
             state.finalText =
                 typeof ev.result === "string" ? ev.result : state.accumulated;
             state.resultIsError = ev.is_error === true;
+            state.usage = parseCliUsage(ev.usage);
         }
     };
     return (ev) => {
@@ -463,19 +782,23 @@ function makeAgentEventHandler(opts, state) {
         else if (ev.type === "tool_call") {
             state.segmentText = "";
             state.needsGap = true;
+            const tool = cursorToolNameAndInput(ev);
+            if (tool)
+                addTouchedFiles(state.filesTouched, opts.cwd, tool.name, tool.input);
             if (ev.subtype === "started")
                 opts.onActivity?.(toolActivityLabel(ev));
         }
         else if (ev.type === "thinking") {
             state.segmentText = "";
             state.needsGap = true;
-            opts.onActivity?.("thinking");
+            opts.onActivity?.("Thinking");
         }
         else if (ev.type === "result") {
             state.sawResult = true;
             state.finalText =
                 typeof ev.result === "string" ? ev.result : state.accumulated;
             state.resultIsError = ev.is_error === true;
+            state.usage = parseCliUsage(ev.usage);
         }
     };
 }
@@ -520,6 +843,8 @@ function runAgentCli(opts) {
                 ok: false,
                 finalText: state.finalText || state.accumulated,
                 error: "agent run timed out",
+                usage: state.usage,
+                filesTouched: touchedFileList(state.filesTouched),
             });
         }, opts.timeoutMs);
         const handleEvent = makeAgentEventHandler(opts, state);
@@ -556,6 +881,8 @@ function runAgentCli(opts) {
             settle({
                 ok,
                 finalText: state.finalText || state.accumulated,
+                usage: state.usage,
+                filesTouched: touchedFileList(state.filesTouched),
                 crashed: !state.sawResult,
                 error: ok
                     ? undefined
@@ -568,7 +895,10 @@ function runAgentCli(opts) {
 function persistTaskFile(tasksDir, task) {
     fs.writeFileSync(path.join(tasksDir, task.id, "task.json"), JSON.stringify(task, null, 2) + "\n");
 }
-// Tasks left "running" by a dead serve are as finished as they will get.
+// Tasks left "running" by a dead serve are as finished as they will get. A
+// persisted "blocked" task is left as-is: it is not "waiting", so maybeStart
+// never reconsiders it and it can't wedge or auto-start; it just sits on the
+// board (blockedBy intact) until the router stops it, same as before restart.
 function loadTasks(tasksDir) {
     const tasks = new Map();
     for (const entry of fs.existsSync(tasksDir) ? fs.readdirSync(tasksDir) : []) {
@@ -632,15 +962,78 @@ function resolveDeps(tasks, tokens) {
     }
     return [...new Set(resolved)];
 }
+export function classifyDeps(tasks, task) {
+    const blockedBy = [];
+    let waiting = false;
+    for (const id of task.after) {
+        const dep = tasks.get(id);
+        // A dep id that no longer resolves to a task (its row was cleared) or one
+        // that finished "done" is satisfied -- nothing left to wait on.
+        if (!dep || dep.status === "done")
+            continue;
+        if (dep.status === "failed" || dep.status === "interrupted") {
+            blockedBy.push(dep.title);
+        }
+        else {
+            waiting = true;
+        }
+    }
+    if (blockedBy.length > 0)
+        return { kind: "blocked", blockedBy };
+    return { kind: waiting ? "waiting" : "ready" };
+}
+// Cap on how much of an upstream task's wrap-up prose rides into a dependent's
+// prompt. resultSummary is already capped at RESULT_SUMMARY_CHARS; this trims
+// further so a multi-dep task doesn't front-load pages of handoff.
+const DEP_SUMMARY_CHARS = 400;
 function depsSummaryFor(tasks, task) {
     if (task.after.length === 0)
         return undefined;
     const lines = task.after
         .map((id) => tasks.get(id))
         .filter((dep) => !!dep)
-        .map((dep) => `- "${dep.title}" finished ${dep.status}${dep.notes.trim() ? `; notes: ${dep.notes.trim()}` : ""}`);
+        .map((dep) => {
+        const parts = [`- "${dep.title}" finished ${dep.status}`];
+        if (dep.files && dep.files.length > 0)
+            parts.push(`  files it touched: ${dep.files.join(", ")}`);
+        // The agent's own closing prose is the real handoff -- names it created,
+        // what it wired, what it left undone. The notes file is player-facing
+        // and deliberately stripped of that detail.
+        const summary = dep.resultSummary?.trim();
+        if (summary)
+            parts.push(`  its wrap-up: ${summary.slice(-DEP_SUMMARY_CHARS).replace(/\n+/g, " ")}`);
+        if (dep.notes.trim())
+            parts.push(`  player notes: ${dep.notes.trim()}`);
+        return parts.join("\n");
+    });
     return lines.join("\n") || undefined;
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Chained-promise gate spacing out task-agent PROCESS LAUNCHES -- deliberately
+// NOT a queue class, just a promise each launch chains onto. Why: the
+// 2026-07 keychain-contention incident (see TASK_SPAWN_STAGGER_MS above) was
+// triggered by several cursor-agent processes starting at the exact same
+// instant; spacing consecutive launches out by TASK_SPAWN_STAGGER_MS avoids
+// that without limiting how many can run concurrently once they're up.
+let taskSpawnGate = Promise.resolve();
+function staggerTaskSpawn() {
+    const readyToLaunch = taskSpawnGate;
+    taskSpawnGate = readyToLaunch.then(() => sleep(TASK_SPAWN_STAGGER_MS));
+    return readyToLaunch;
+}
+// Jittered, attempt-scaled backoff before relaunching a crashed task agent
+// (see TASK_RETRY_BACKOFF_BASE_MS's comment for why). Checks stopRequested
+// both before AND after the sleep -- a stop landing mid-backoff must not
+// relaunch the task. Returns true if the caller should give up retrying.
+async function waitBeforeTaskRetry(attempt, stopRequested, taskId) {
+    if (stopRequested.has(taskId))
+        return true;
+    const backoffMs = TASK_RETRY_BACKOFF_BASE_MS * attempt + Math.random() * 1000;
+    await sleep(backoffMs);
+    return stopRequested.has(taskId);
+}
 async function runTaskAgentIn(ctx, task) {
     const dir = path.join(ctx.tasksDir, task.id);
     const relDir = path.relative(ctx.deckDir, dir);
@@ -653,6 +1046,9 @@ async function runTaskAgentIn(ctx, task) {
         notesPath: path.join(relDir, "notes.md"),
         depsSummary: ctx.depsSummary,
         backend: ctx.backend,
+        deckTree: buildDeckTree(ctx.deckDir),
+        quickReference: ctx.quickReference,
+        siblings: ctx.siblings,
     });
     // No /goal wrapper: it makes a fresh evaluator re-check the WHOLE task
     // prompt (including user-only "done when you reach wave 5"-style play
@@ -698,6 +1094,7 @@ async function runTaskAgentIn(ctx, task) {
         }
     };
     for (let attempt = 1; attempt <= MAX_TASK_ATTEMPTS; attempt++) {
+        await staggerTaskSpawn();
         result = await runAgentCli({
             cwd: ctx.deckDir,
             command: invocation.command,
@@ -720,8 +1117,11 @@ async function runTaskAgentIn(ctx, task) {
             return result;
         if (!result.crashed)
             return result;
-        if (attempt < MAX_TASK_ATTEMPTS)
+        if (attempt < MAX_TASK_ATTEMPTS) {
             ctx.onRetry(attempt + 1);
+            if (await waitBeforeTaskRetry(attempt, ctx.stopRequested, task.id))
+                return result;
+        }
     }
     result.error = `agent process kept dying (${MAX_TASK_ATTEMPTS} attempts): ${result.error ?? ""}`;
     return result;
@@ -747,7 +1147,15 @@ function startTask(ctx, task) {
         backend: ctx.backend(),
         claudeModel: ctx.claudeModel(),
         stopRequested: ctx.stopRequested,
+        quickReference: ctx.quickReference,
         depsSummary: depsSummaryFor(ctx.tasks, task),
+        // Same visibility rule as the router's board (hide acked+finished rows),
+        // minus this task itself. Snapshot at start -- consistent with the deck
+        // tree, and the prompt says so.
+        siblings: ctx
+            .sorted()
+            .filter((t) => t.id !== task.id && !(t.acknowledged && isTerminal(t.status)))
+            .map((t) => ({ title: t.title, status: t.status, files: t.files })),
         onFeed: (entry) => ctx.onFeed(task, entry),
         onRetry: (attempt) => ctx.onRetry(task, attempt),
         onSignal: (signal) => {
@@ -787,6 +1195,7 @@ function startTask(ctx, task) {
                 task.acknowledged = true;
             if (result.ok && !wasStopped)
                 task.progress = 100;
+            task.files = result.filesTouched ?? [];
             task.finishedAt = nowIso();
             task.resultSummary = wasStopped
                 ? "stopped by the router"
@@ -837,12 +1246,14 @@ function startTask(ctx, task) {
         ctx.rescheduleAll();
     });
 }
-// Halt + remove an active task (castle-stop): a waiting one is cancelled and
-// cleared off the board immediately; a running one gets its agent process
-// killed and is cleared when it finalizes (the stopRequested path acks it).
-// No-op on terminal tasks.
+// Halt + remove an active task (castle-stop): a waiting or blocked one is
+// cancelled and cleared off the board immediately; a running one gets its
+// agent process killed and is cleared when it finalizes (the stopRequested
+// path acks it). No-op on terminal tasks. A "blocked" task never got a
+// process, so it collapses the same way "waiting" does -- this is the only
+// way a blocked row ever clears (see ROUTER_RULES).
 function haltTask(task, children, stopRequested, touch) {
-    if (task.status === "waiting") {
+    if (task.status === "waiting" || task.status === "blocked") {
         task.status = "interrupted";
         task.acknowledged = true;
         touch(task);
@@ -875,12 +1286,6 @@ function createTaskStore(opts) {
         persistTaskFile(tasksDir, task);
         opts.onUpdate(task);
     }
-    function depsAreSettled(task) {
-        return task.after.every((id) => {
-            const dep = tasks.get(id);
-            return !dep || isTerminal(dep.status);
-        });
-    }
     function runningCount() {
         let n = 0;
         for (const t of tasks.values())
@@ -889,8 +1294,20 @@ function createTaskStore(opts) {
         return n;
     }
     function maybeStart(task) {
-        if (task.status !== "waiting" || task.acknowledged || !depsAreSettled(task))
+        if (task.status !== "waiting" || task.acknowledged)
             return;
+        const deps = classifyDeps(tasks, task);
+        if (deps.kind === "waiting")
+            return;
+        // A dep finalized failed/interrupted -- this task can never do its job
+        // (the output it needed never materialized), so it flips to "blocked"
+        // instead of ever starting. Only the router clears it (castle-stop).
+        if (deps.kind === "blocked") {
+            task.status = "blocked";
+            task.blockedBy = deps.blockedBy;
+            touch(task);
+            return;
+        }
         // Concurrency cap: at most MAX_CONCURRENT_TASKS agents run at once. Over-cap
         // tasks stay 'waiting' and are restarted -- earliest-created first -- by the
         // onFinished sweep below when a running task frees a slot.
@@ -918,6 +1335,7 @@ function createTaskStore(opts) {
         children,
         tasks,
         stopRequested,
+        quickReference: opts.quickReference,
         backend: opts.backend,
         claudeModel: opts.claudeModel,
         onStarted: opts.onStarted,
@@ -993,13 +1411,16 @@ function createTaskStore(opts) {
             acknowledge(id, false);
     }
     // The router stops tasks by title or id (castle-stop fence), or "all" to
-    // stop everything still active. Waiting tasks are cancelled outright;
-    // running ones get their agent process killed and finalize as interrupted
-    // via the stopRequested path (see haltTask).
+    // stop everything still active. Waiting (and blocked -- a waiting task that
+    // will never start) tasks are cancelled outright; running ones get their
+    // agent process killed and finalize as interrupted via the stopRequested
+    // path (see haltTask).
     function stop(tokens) {
         const ids = meansAll(tokens)
             ? [...tasks.values()]
-                .filter((t) => t.status === "running" || t.status === "waiting")
+                .filter((t) => t.status === "running" ||
+                t.status === "waiting" ||
+                t.status === "blocked")
                 .map((t) => t.id)
             : resolveDeps(tasks, tokens);
         for (const id of ids) {
@@ -1053,6 +1474,57 @@ function saveAttachments(attachmentsDir, messageId, images) {
     }
     return saved;
 }
+// Cap on the failure detail shown in a board row -- just enough for the
+// router to reason about what went wrong, not the full crash dump.
+const ERROR_PREVIEW_CHARS = 200;
+// A failed task's resultSummary starts with the error text (see startTask's
+// finalization block) followed by trailing output; the first non-empty line
+// is USUALLY the router-relevant part, with two exceptions handled below.
+//
+// Exception 1 (pre-existing): a clean-exit self-reported failure (stream-json
+// `result` event with is_error: true, exit code 0) leaves runAgentCli's
+// generic "agent exited 0" here with no stderr tail to make it informative --
+// the agent's own stated reason is the next line (the finalText tail).
+//
+// Exception 2: runAgentCli's exit-code wrapper ("agent exited N[: stderr
+// tail]", possibly re-wrapped as "agent process kept dying (N attempts):
+// ...") embeds the crashed process's raw, possibly multi-line stderr
+// verbatim. If that stderr itself contains newlines, the actually
+// informative line can land one or more lines below this wrapper -- e.g. the
+// 2026-07 keychain incident, where line 1 was a useless
+// "agent process kept dying (3 attempts): agent exited 1: cursor-retrieval:
+// tracing to '/var/folders/.../cursor_retrieval....log'" while the real
+// "Error: Security command failed: Security process exited with code: 44"
+// sat right below it. Only these two wrapper shapes get this treatment --
+// "agent run timed out" and "could not run cursor-agent: <message>" (the
+// other two runAgentCli error strings) are already the whole story on line 1
+// and are left alone, same as before.
+const EXIT_WRAPPER_RE = /^agent (exited \d+|process kept dying)/;
+function looksLikeErrorLine(line) {
+    return /\berror\b/i.test(line);
+}
+function firstErrorLine(resultSummary) {
+    const lines = resultSummary
+        ?.split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0) ?? [];
+    if (lines.length === 0)
+        return undefined;
+    const first = lines[0];
+    if (first === "agent exited 0") {
+        return (lines[1] ?? first).slice(0, ERROR_PREVIEW_CHARS);
+    }
+    if (!EXIT_WRAPPER_RE.test(first) || looksLikeErrorLine(first)) {
+        return first.slice(0, ERROR_PREVIEW_CHARS);
+    }
+    const betterLine = lines.slice(1).find(looksLikeErrorLine);
+    if (!betterLine)
+        return first.slice(0, ERROR_PREVIEW_CHARS);
+    // Keep the wrapper as context (e.g. "3 attempts") when it fits; otherwise
+    // the real error line must stay fully visible within the cap on its own.
+    const combined = `${first}: ${betterLine}`;
+    return (combined.length <= ERROR_PREVIEW_CHARS ? combined : betterLine).slice(0, ERROR_PREVIEW_CHARS);
+}
 function asPromptTask(task) {
     return {
         id: task.id,
@@ -1060,6 +1532,26 @@ function asPromptTask(task) {
         status: task.rejected ? "rejected by user" : task.status,
         progress: task.progress,
         notes: task.notes,
+        files: task.files,
+        error: task.status === "failed" ? firstErrorLine(task.resultSummary) : undefined,
+        blockedBy: task.status === "blocked" ? task.blockedBy : undefined,
+    };
+}
+function asClientTask(task) {
+    return {
+        id: task.id,
+        title: task.title,
+        status: task.status,
+        progress: task.progress,
+        notes: task.notes,
+        createdAt: task.createdAt,
+        startedAt: task.startedAt,
+        finishedAt: task.finishedAt,
+        resultSummary: task.resultSummary,
+        avatar: task.avatar,
+        phase: task.phase,
+        acknowledged: task.acknowledged,
+        rejected: task.rejected,
     };
 }
 function createTaskFeeds(broadcast) {
@@ -1131,26 +1623,47 @@ function makeAttachmentHandler(attachmentsDir) {
         return true;
     };
 }
-// One router turn: stream a reply message, then spawn the directives it
-// emitted (unless a newer user message superseded this turn).
-function runRouterTurnIn(ctx, instruction) {
-    const epoch = ctx.currentEpoch();
-    const message = {
-        id: nanoid(8),
-        role: "assistant",
-        text: "",
-        at: nowIso(),
-        status: "streaming",
-    };
-    ctx.log.messages.push(message);
-    ctx.broadcast({ type: "message-add", message });
-    let raw = "";
-    let visibleSent = 0;
-    let lastActivity = null;
-    const prompt = buildRouterPrompt({
+// Classify from the error strings runAgentCli actually produces (see its
+// child.on("error"), timeout, and close handlers).
+function classifyRouterFailure(error) {
+    if (error?.startsWith("could not run"))
+        return "spawn";
+    if (error === "agent run timed out")
+        return "timeout";
+    return "exit";
+}
+// Plain-language copy for a failed turn. `salvaged` = the turn already
+// produced something the user can see (streamed text and/or spawned tasks),
+// so "pick it back up" framing fits; a turn that died with nothing is a clean
+// hiccup. `willRetry` = the queue is about to re-run this instruction itself.
+function routerFailureCopy(opts) {
+    if (opts.willRetry) {
+        return "Something went wrong on my end -- give me a moment to try that again.";
+    }
+    const tasksNote = opts.spawnedTasks
+        ? " The steps I already kicked off are still running."
+        : "";
+    switch (opts.kind) {
+        case "spawn":
+            return `I couldn't start working on that -- something in this setup isn't right. If this keeps happening, the person running this session needs to take a look.${tasksNote}`;
+        case "timeout":
+            return `That took me too long and I had to stop partway. Send another message and I'll pick it back up.${tasksNote}`;
+        case "exit":
+            return `Something went wrong on my end partway through. Send another message and I'll pick it back up.${tasksNote}`;
+    }
+}
+// Assemble the full stateless prompt for one router turn: rules + deck
+// context + transcript replay (minus log lines and the in-flight reply) +
+// the live board + this turn's instruction.
+function routerTurnPrompt(ctx, instruction, selfMessageId) {
+    return buildRouterPrompt({
         deckLabel: ctx.deckLabel,
+        quickReference: ctx.quickReference,
+        deckTree: buildDeckTree(ctx.deckDir),
         messages: ctx.log.messages
-            .filter((m) => m.role !== "log" && m.id !== message.id && m.status !== "streaming")
+            .filter((m) => m.role !== "log" &&
+            m.id !== selfMessageId &&
+            m.status !== "streaming")
             .map((m) => ({
             role: m.role,
             // Replace a prior turn's raw ```ask JSON with a readable question list
@@ -1167,6 +1680,108 @@ function runRouterTurnIn(ctx, instruction) {
             .map(asPromptTask),
         instruction,
     });
+}
+// A turn killed before producing anything visible (a fold, or a manual Stop
+// pressed during the pre-text lull) leaves an empty husk that would otherwise
+// replay into every future transcript as a blank assistant line -- drop it
+// from the log instead. Decided here, with final knowledge, rather than at
+// kill time: a text delta can race the SIGKILL and still land in
+// message.text, in which case this falls through to the normal
+// interrupted-draft path so the continuation turn can carry it. A message
+// with spawned taskIds is NEVER dropped even with empty text -- those tasks
+// are already running and the UI's task chips need this message as their
+// anchor, so it always takes the interrupted-draft (kept) path instead.
+function settleInterruptedTurn(ctx, message) {
+    const hasSpawnedTasks = (message.taskIds?.length ?? 0) > 0;
+    if (message.text.trim() === "" && !hasSpawnedTasks) {
+        const idx = ctx.log.messages.indexOf(message);
+        if (idx >= 0)
+            ctx.log.messages.splice(idx, 1);
+        ctx.log.persist();
+        ctx.broadcast({
+            type: "message-done",
+            id: message.id,
+            text: "",
+            status: "done",
+        });
+        return;
+    }
+    // Keep whatever streamed and/or spawned; the continuation turn carries the
+    // text draft (tasks already launched by this turn just stay on the board).
+    message.status = "done";
+    message.interrupted = true;
+    ctx.log.persist();
+    ctx.broadcast({
+        type: "message-done",
+        id: message.id,
+        text: message.text,
+        status: message.status,
+        interrupted: true,
+        taskIds: message.taskIds ?? [],
+    });
+}
+// Spawn ```castle-task fences AS EACH ONE completes during streaming, instead
+// of waiting for the whole reply to settle -- shaves the time-to-first-task
+// off long replies. Mirrors the settle path's spawn logic exactly: same
+// directive parsing (parseTaskFenceBody), same in-flight title dedup, and the
+// same `after:` resolution against the live task board -- which by now
+// already includes any tasks spawned earlier in this same reply, so an
+// `after:` referencing an earlier fence's title resolves correctly.
+function spawnCompletedTaskFences(ctx, message, midStream, raw) {
+    const { directives, nextIndex } = scanNewTaskFences(raw, midStream.scannedUpTo);
+    midStream.scannedUpTo = nextIndex;
+    if (directives.length === 0)
+        return;
+    const inFlight = new Set(ctx.taskStore
+        .sorted()
+        .filter((t) => t.status === "running" || t.status === "waiting")
+        .map((t) => t.title.toLowerCase()));
+    const newIds = [];
+    for (const directive of directives) {
+        const key = directive.title.toLowerCase();
+        if (inFlight.has(key) || midStream.spawnedTitles.has(key))
+            continue;
+        newIds.push(ctx.taskStore.spawnFromDirective(directive, message.id));
+        midStream.spawnedTitles.add(key);
+    }
+    if (newIds.length === 0)
+        return;
+    message.taskIds = [...(message.taskIds ?? []), ...newIds];
+    // No text change (the fence stays hidden by the holdback until the reply
+    // ends) -- this delta only carries the updated taskIds so connected clients
+    // can react (e.g. show task chips) before the turn finishes.
+    ctx.broadcast({
+        type: "message-delta",
+        id: message.id,
+        delta: "",
+        taskIds: message.taskIds,
+    });
+}
+// One router turn: stream a reply message, then spawn the directives it
+// emitted (unless a newer user message superseded this turn).
+function runRouterTurnIn(ctx, instruction) {
+    const epoch = ctx.currentEpoch();
+    const message = {
+        id: nanoid(8),
+        role: "assistant",
+        text: "",
+        at: nowIso(),
+        status: "streaming",
+    };
+    ctx.log.messages.push(message);
+    ctx.broadcast({ type: "message-add", message });
+    let raw = "";
+    let visibleSent = 0;
+    const midStream = { scannedUpTo: 0, spawnedTitles: new Set() };
+    // Seed the activity line to "thinking" immediately -- covers the otherwise
+    // silent spawn + first-token lull (fresh CLI process, prompt processing,
+    // extended thinking) before any stream event arrives. The stream then
+    // overrides it: a tool relabels it, the first text delta clears it. Seeding
+    // lastActivity too dedups the redundant broadcast when the claude thinking
+    // block later re-emits "thinking".
+    let lastActivity = "Thinking";
+    ctx.broadcast({ type: "message-activity", id: message.id, activity: "Thinking" });
+    const prompt = routerTurnPrompt(ctx, instruction, message.id);
     const backend = ctx.backend();
     const invocation = buildAgentInvocation(backend, "router", prompt, ctx.claudeModel());
     void runAgentCli({
@@ -1177,6 +1792,7 @@ function runRouterTurnIn(ctx, instruction) {
         timeoutMs: ROUTER_TIMEOUT_MS,
         logPath: path.join(ctx.agentDir, "router-log.jsonl"),
         children: ctx.children,
+        labelUnknownTools: true,
         onDelta: (delta) => {
             raw += delta;
             const visible = visibleLength(raw);
@@ -1186,6 +1802,9 @@ function runRouterTurnIn(ctx, instruction) {
                 message.text += slice;
                 ctx.broadcast({ type: "message-delta", id: message.id, delta: slice });
             }
+            // Spawning changes WHEN a fence is acted on, not what is displayed --
+            // the holdback above still hides fenced text until the reply ends.
+            spawnCompletedTaskFences(ctx, message, midStream, raw);
         },
         onActivity: (activity) => {
             if (activity === lastActivity)
@@ -1195,6 +1814,10 @@ function runRouterTurnIn(ctx, instruction) {
         },
     })
         .then((result) => {
+        logRouterUsage(backend, result.usage);
+        // Signals the finally -> onSettled(retryable): the turn failed cleanly
+        // enough (transient, nothing salvaged) that the queue may re-run it.
+        let retryable = false;
         // The settle path must ALWAYS reach ctx.onSettled() (clears
         // routerRunning + flushes pendingSends). A throw here on Node v25 would
         // otherwise both freeze the composer and crash the serve, so the whole
@@ -1203,18 +1826,7 @@ function runRouterTurnIn(ctx, instruction) {
         try {
             const interrupted = epoch !== ctx.currentEpoch() && !result.ok;
             if (interrupted) {
-                // Keep whatever streamed; the continuation turn carries the draft.
-                message.status = "done";
-                message.interrupted = true;
-                ctx.log.persist();
-                ctx.broadcast({
-                    type: "message-done",
-                    id: message.id,
-                    text: message.text,
-                    status: message.status,
-                    interrupted: true,
-                    taskIds: [],
-                });
+                settleInterruptedTurn(ctx, message);
                 return;
             }
             const { cleaned, directives, checkoffs, stops } = extractDirectives(result.finalText);
@@ -1222,8 +1834,11 @@ function runRouterTurnIn(ctx, instruction) {
                 ctx.taskStore.checkOff(checkoffs);
             if (result.ok && stops.length > 0)
                 ctx.taskStore.stop(stops);
-            // Drop directives from stale turns, and any whose title matches a task
-            // already in flight (two runs reacting to the same ask).
+            // Drop directives from stale turns, any whose title matches a task
+            // already in flight (two runs reacting to the same ask), and any
+            // already spawned mid-stream by spawnCompletedTaskFences above --
+            // otherwise the settle-time full-text parse would launch a second
+            // copy of the same fence.
             const stale = epoch !== ctx.currentEpoch();
             const inFlight = new Set(ctx.taskStore
                 .sorted()
@@ -1231,12 +1846,34 @@ function runRouterTurnIn(ctx, instruction) {
                 .map((t) => t.title.toLowerCase()));
             const toSpawn = stale
                 ? []
-                : directives.filter((d) => !inFlight.has(d.title.toLowerCase()));
-            const taskIds = toSpawn.map((d) => ctx.taskStore.spawnFromDirective(d, message.id));
-            message.text = result.ok
-                ? cleaned
-                : `${cleaned ? cleaned + "\n\n" : ""}[router error: ${result.error ?? "unknown"}]`;
-            message.status = result.ok ? "done" : "error";
+                : directives.filter((d) => !inFlight.has(d.title.toLowerCase()) &&
+                    !midStream.spawnedTitles.has(d.title.toLowerCase()));
+            const newlySpawnedIds = toSpawn.map((d) => ctx.taskStore.spawnFromDirective(d, message.id));
+            const taskIds = [...(message.taskIds ?? []), ...newlySpawnedIds];
+            if (result.ok) {
+                message.text = cleaned;
+                message.status = "done";
+            }
+            else {
+                const kind = classifyRouterFailure(result.error);
+                // Only a turn that produced NOTHING visible is safe to silently
+                // re-run: with streamed text or spawned tasks in play, a retry
+                // would answer the same instruction twice (and could re-spawn
+                // near-duplicate tasks past the title dedup). Spawn failures are
+                // persistent (the CLI itself won't launch) and timeouts are too
+                // expensive to repeat blind, so only "exit" crashes retry.
+                const salvaged = cleaned !== "" || taskIds.length > 0;
+                retryable = kind === "exit" && !salvaged;
+                const copy = routerFailureCopy({
+                    kind,
+                    spawnedTasks: taskIds.length > 0,
+                    willRetry: retryable && ctx.canAutoRetry(),
+                });
+                message.text = cleaned ? `${cleaned}\n\n${copy}` : copy;
+                message.status = "error";
+                message.errorDetail = result.error ?? "unknown failure";
+                console.error(`[router] turn failed (${kind}): ${message.errorDetail}`);
+            }
             if (taskIds.length > 0)
                 message.taskIds = taskIds;
             ctx.log.persist();
@@ -1246,6 +1883,7 @@ function runRouterTurnIn(ctx, instruction) {
                 text: message.text,
                 status: message.status,
                 taskIds: message.taskIds ?? [],
+                errorDetail: message.errorDetail,
             });
         }
         catch (err) {
@@ -1257,7 +1895,9 @@ function runRouterTurnIn(ctx, instruction) {
             console.error(`[router] turn callback threw: ${detail}`);
             try {
                 message.status = "error";
-                message.text = `${message.text ? message.text + "\n\n" : ""}[router error: ${short}]`;
+                const copy = "Something went wrong on my end partway through. Send another message and I'll pick it back up.";
+                message.text = `${message.text ? message.text + "\n\n" : ""}${copy}`;
+                message.errorDetail = short;
                 ctx.log.persist();
                 ctx.broadcast({
                     type: "message-done",
@@ -1265,6 +1905,7 @@ function runRouterTurnIn(ctx, instruction) {
                     text: message.text,
                     status: message.status,
                     taskIds: message.taskIds ?? [],
+                    errorDetail: message.errorDetail,
                 });
             }
             catch (inner) {
@@ -1272,7 +1913,7 @@ function runRouterTurnIn(ctx, instruction) {
             }
         }
         finally {
-            ctx.onSettled();
+            ctx.onSettled(retryable);
         }
     })
         .catch((err) => {
@@ -1365,83 +2006,113 @@ function startChildRegistry(registryPath, groups) {
         }
     };
 }
-// Mid-run send queue (mirrors djinn's AltManager.pendingSends): a user message
-// sent while the router is mid-turn QUEUES instead of interrupting. It flushes
-// into a single follow-up turn when the current turn settles. An explicit
-// interrupt ("send now" / Stop) kills the run and flushes early. The epoch
-// keeps a killed-but-racing run from spawning tasks. Lives in its own factory
-// so createAgentServer stays within the max-lines budget; the queue-by-default
-// semantics are unchanged.
-function createRouterQueue(deps) {
-    const { deckDir, deckLabel, agentDir, attachmentsDir, routerChildren, log, broadcast, taskStore, messages, settings, } = deps;
-    let userEpoch = 0;
-    let routerRunning = false;
-    // Queued mid-run sends. Each entry carries the message id it will be logged
-    // under and the attachment filenames already saved to disk at enqueue time,
-    // so the whole queue is durable: it is mirrored to pending-sends.json and can
-    // be recovered if the serve restarts before the queue drains.
-    const pendingSends = [];
-    const pendingPath = path.join(agentDir, "pending-sends.json");
-    let pendingInterruptedDraft = "";
-    // Mirror the in-memory queue to disk. Called on every mutation (enqueue,
-    // drain, cancel, recover) so a restart never loses an unsent queued message.
-    function persistPending() {
-        fs.writeFileSync(pendingPath, JSON.stringify(pendingSends, null, 2) + "\n");
-    }
-    function queuedSnippets() {
-        return pendingSends.map((p) => p.text.trim()).filter(Boolean);
-    }
-    function broadcastRouterState() {
-        broadcast({
-            type: "router-state",
-            running: routerRunning,
-            queued: queuedSnippets(),
-        });
+// Restart recovery: load the durable queue mirror, keeping only well-formed
+// sends that never reached the message log. A send whose id is already in
+// messages.json was committed by a prior drain (its turn ran, finished or
+// not -- a logged message is considered handled), so re-queueing it would
+// double-deliver. Order is preserved.
+function loadRecoverableSends(pendingPath, committedIds) {
+    const stored = readJsonFile(pendingPath);
+    if (!Array.isArray(stored))
+        return [];
+    const recovered = [];
+    for (const item of stored) {
+        if (item &&
+            typeof item.id === "string" &&
+            typeof item.text === "string" &&
+            Array.isArray(item.attachments) &&
+            !committedIds.has(item.id)) {
+            recovered.push({
+                id: item.id,
+                text: item.text,
+                attachments: item.attachments.filter((a) => typeof a === "string"),
+            });
+        }
     }
-    function interruptRouterRuns() {
-        const drafts = messages
-            .filter((m) => m.role === "assistant" && m.status === "streaming")
-            .map((m) => m.text.trim())
-            .filter(Boolean);
-        for (const child of routerChildren) {
-            try {
-                child.kill("SIGKILL");
-            }
-            catch {
-                /* already gone */
-            }
+    return recovered;
+}
+// A turn's user messages are only "spent" once the turn has produced visible
+// output -- text or side effects committed. Until then, killing the turn
+// (fold or manual interrupt) must not lose them: they have to survive and
+// re-enter the next instruction. A turn that has spawned tasks counts as
+// having visible output too, even with no text yet -- a launched task agent
+// cannot be un-launched, so folding it away would abandon in-flight work, not
+// just discard stale intent.
+function turnHasVisibleOutput(messages) {
+    return messages.some((m) => m.role === "assistant" &&
+        m.status === "streaming" &&
+        (m.text.trim() !== "" || (m.taskIds?.length ?? 0) > 0));
+}
+// Re-queue a turn's already-logged user messages (its `inFlightSends`) onto
+// the front of the pending queue, marked `logged` so the next drain composes
+// them into the instruction again without adding a second user bubble. Shared
+// by the auto-fold path and the manual interrupt path -- both lose the
+// original messages from instruction composition the same way if a turn is
+// killed before producing anything visible.
+function reclaimInFlightSends(pendingSends, inFlightSends) {
+    if (inFlightSends.length === 0)
+        return;
+    pendingSends.unshift(...inFlightSends.map((s) => ({ ...s, logged: true })));
+}
+// Mirror the in-memory queue to disk. Called on every mutation (enqueue,
+// drain, cancel, recover) so a restart never loses an unsent queued message.
+function persistPendingSends(ctx) {
+    fs.writeFileSync(ctx.pendingPath, JSON.stringify(ctx.state.pendingSends, null, 2) + "\n");
+}
+function computeQueuedSnippets(pendingSends) {
+    return pendingSends.map((p) => p.text.trim()).filter(Boolean);
+}
+function broadcastQueueState(ctx) {
+    ctx.broadcast({
+        type: "router-state",
+        running: ctx.state.routerRunning,
+        queued: computeQueuedSnippets(ctx.state.pendingSends),
+    });
+}
+// Kill all in-flight router child processes, returning any partial draft text
+// they had streamed (joined) so a manual interrupt can carry it forward.
+function killRouterChildren(ctx) {
+    const drafts = ctx.messages
+        .filter((m) => m.role === "assistant" && m.status === "streaming")
+        .map((m) => m.text.trim())
+        .filter(Boolean);
+    for (const child of ctx.routerChildren) {
+        try {
+            child.kill("SIGKILL");
         }
-        return drafts.join("\n\n");
-    }
-    function runRouterTurn(instruction) {
-        runRouterTurnIn({
-            deckDir,
-            deckLabel,
-            agentDir,
-            children: routerChildren,
-            log,
-            broadcast,
-            taskStore,
-            currentEpoch: () => userEpoch,
-            backend: () => settings.router,
-            claudeModel: () => settings.claudeModel,
-            onSettled: onRouterSettled,
-        }, instruction);
-    }
-    // Drain the queue into the log as real user messages and start one follow-up
-    // turn addressing them all (a burst batches into a single turn). A pending
-    // interrupted draft from a "send now" / Stop is carried into the instruction.
-    // No-op while a turn is running or the queue is empty.
-    function maybeStartRouterTurn() {
-        if (routerRunning || pendingSends.length === 0)
-            return;
-        const drained = pendingSends.splice(0, pendingSends.length);
-        const texts = [];
-        const attachmentPaths = [];
-        for (const item of drained) {
-            // The message id and attachments were assigned/saved at enqueue time and
-            // persisted in pending-sends.json, so the drain just commits them to the
-            // message log under that same id (recovery dedupes on it; see below).
+        catch {
+            /* already gone */
+        }
+    }
+    return drafts.join("\n\n");
+}
+function startRouterTurn(ctx, instruction) {
+    ctx.state.lastInstruction = instruction;
+    runRouterTurnIn({
+        deckDir: ctx.deckDir,
+        deckLabel: ctx.deckLabel,
+        quickReference: ctx.quickReference,
+        agentDir: ctx.agentDir,
+        children: ctx.routerChildren,
+        log: ctx.log,
+        broadcast: ctx.broadcast,
+        taskStore: ctx.taskStore,
+        currentEpoch: () => ctx.state.userEpoch,
+        backend: () => ctx.settings.router,
+        claudeModel: () => ctx.settings.claudeModel,
+        canAutoRetry: () => !ctx.state.autoRetryUsed && ctx.state.pendingSends.length === 0,
+        onSettled: (retryable) => onRouterQueueSettled(ctx, retryable),
+    }, instruction);
+}
+// Commit each drained send to the message log (skipping ones already logged
+// -- see PendingSend.logged -- so a re-carried send doesn't double its user
+// bubble) and collect the instruction pieces: message texts and attachment
+// paths, in drain order.
+function commitDrainedSends(drained, log) {
+    const texts = [];
+    const attachmentPaths = [];
+    for (const item of drained) {
+        if (!item.logged) {
             const message = {
                 id: item.id,
                 role: "user",
@@ -1452,109 +2123,183 @@ function createRouterQueue(deps) {
             if (item.attachments.length > 0)
                 message.attachments = item.attachments;
             log.add(message);
-            if (item.text.trim())
-                texts.push(item.text);
-            for (const name of item.attachments) {
-                attachmentPaths.push(path.join(".castle", "agent", "attachments", name));
-            }
         }
-        // The queue is now committed to messages.json; clear its durable mirror.
-        persistPending();
-        const draft = pendingInterruptedDraft;
-        pendingInterruptedDraft = "";
-        routerRunning = true;
-        broadcastRouterState();
-        runRouterTurn(userTurnInstruction({
-            messages: texts,
-            interruptedDraft: draft || undefined,
-            attachments: attachmentPaths,
-        }));
-    }
-    // The turn settled: clear the busy flag, broadcast it, then flush anything
-    // that queued mid-turn (a clean end and an interrupt take the same path).
-    function onRouterSettled() {
-        routerRunning = false;
-        broadcastRouterState();
-        maybeStartRouterTurn();
-    }
-    function handleUserMessage(text, images) {
-        // Mid-run: queue (don't interrupt). It shows as a queued row in the
-        // composer and flushes when the current turn settles. Idle: start now.
-        // Persist at enqueue (assign the final message id, save attachments to
-        // disk, mirror the queue to pending-sends.json) so a restart before the
-        // queue drains can recover the send instead of silently dropping it.
-        const id = nanoid(8);
-        const attachments = saveAttachments(attachmentsDir, id, images);
-        pendingSends.push({ id, text, attachments });
-        persistPending();
-        if (routerRunning)
-            broadcastRouterState();
-        else
-            maybeStartRouterTurn();
-    }
-    // "Send now" (a queued row) / Stop (empty composer): kill the running turn,
-    // capturing its partial draft so the follow-up turn continues it; the killed
-    // run's settle flushes the queue. When idle, just flush (covers a stray
-    // interrupt with messages already queued).
-    function interruptRouter() {
-        if (routerRunning) {
-            userEpoch += 1;
-            const draft = interruptRouterRuns();
-            // Only carry the partial draft forward when a queued message will consume
-            // it imminently ("Send now"). A bare Stop (empty composer) must not park
-            // the draft, or it leaks into the next unrelated message.
-            pendingInterruptedDraft = pendingSends.length > 0 ? draft : "";
+        if (item.text.trim())
+            texts.push(item.text);
+        for (const name of item.attachments) {
+            attachmentPaths.push(path.join(".castle", "agent", "attachments", name));
+        }
+    }
+    return { texts, attachmentPaths };
+}
+// Drain the queue into the log as real user messages and start one follow-up
+// turn addressing them all (a burst batches into a single turn). A pending
+// interrupted draft from a "send now" / Stop is carried into the instruction.
+// No-op while a turn is running or the queue is empty.
+function maybeStartRouterQueueTurn(ctx) {
+    const { state } = ctx;
+    if (state.routerRunning || state.pendingSends.length === 0)
+        return;
+    state.autoRetryUsed = false;
+    state.autoFoldUsed = false;
+    const drained = state.pendingSends.splice(0, state.pendingSends.length);
+    // Kept so a fold or manual interrupt of THIS turn can hand these sends back
+    // to reclaimInFlightSends if it dies before producing anything visible.
+    state.inFlightSends = drained;
+    const { texts, attachmentPaths } = commitDrainedSends(drained, ctx.log);
+    // The queue is now committed to messages.json; clear its durable mirror.
+    persistPendingSends(ctx);
+    const draft = state.pendingInterruptedDraft;
+    state.pendingInterruptedDraft = "";
+    state.routerRunning = true;
+    broadcastQueueState(ctx);
+    startRouterTurn(ctx, userTurnInstruction({
+        messages: texts,
+        interruptedDraft: draft || undefined,
+        attachments: attachmentPaths,
+    }));
+}
+// The turn settled: clear the busy flag, broadcast it, then flush anything
+// that queued mid-turn (a clean end and an interrupt take the same path). A
+// retryable failure (transient crash, nothing salvaged) re-runs the same
+// instruction once instead -- unless a queued user message is waiting, in
+// which case flushing it supersedes the retry (its turn re-covers things).
+function onRouterQueueSettled(ctx, retryable) {
+    const { state } = ctx;
+    state.routerRunning = false;
+    if (retryable &&
+        !state.autoRetryUsed &&
+        state.pendingSends.length === 0 &&
+        state.lastInstruction) {
+        state.autoRetryUsed = true;
+        state.routerRunning = true;
+        broadcastQueueState(ctx);
+        startRouterTurn(ctx, state.lastInstruction);
+        return;
+    }
+    broadcastQueueState(ctx);
+    maybeStartRouterQueueTurn(ctx);
+}
+// Auto-interrupt ("fold") a pre-text router turn into the very message that
+// triggered it: the turn hasn't produced anything visible yet, so restarting
+// it fresh -- covering the original message(s) AND the new one -- beats
+// letting it finish answering stale intent. No draft to park: a pre-text turn
+// never streamed anything to continue. The killed run's interrupted-settle
+// branch (settleInterruptedTurn) drops its now-empty message, and its
+// onSettled -> maybeStartRouterQueueTurn drains the re-queued batch into one
+// combined instruction.
+function foldRouterQueueTurn(ctx) {
+    const { state } = ctx;
+    state.userEpoch += 1;
+    killRouterChildren(ctx);
+    reclaimInFlightSends(state.pendingSends, state.inFlightSends);
+    persistPendingSends(ctx);
+    state.autoFoldUsed = true;
+    broadcastQueueState(ctx);
+}
+function handleQueueUserMessage(ctx, text, images) {
+    const { state } = ctx;
+    // Mid-run: queue (don't interrupt). It shows as a queued row in the
+    // composer and flushes when the current turn settles. Idle: start now.
+    // Persist at enqueue (assign the final message id, save attachments to
+    // disk, mirror the queue to pending-sends.json) so a restart before the
+    // queue drains can recover the send instead of silently dropping it.
+    const id = nanoid(8);
+    const attachments = saveAttachments(ctx.attachmentsDir, id, images);
+    state.pendingSends.push({ id, text, attachments });
+    persistPendingSends(ctx);
+    if (state.routerRunning) {
+        // The new send was just pushed above, so folding now (which unshifts the
+        // old in-flight batch ahead of it) yields the correct order: [old
+        // messages..., this new one].
+        if (!state.autoFoldUsed && !turnHasVisibleOutput(ctx.messages)) {
+            foldRouterQueueTurn(ctx);
         }
         else {
-            maybeStartRouterTurn();
+            broadcastQueueState(ctx);
         }
     }
-    function cancelQueued(index) {
-        if (!Number.isInteger(index) || index < 0 || index >= pendingSends.length)
-            return;
-        pendingSends.splice(index, 1);
-        persistPending();
-        broadcastRouterState();
-    }
-    // Restart recovery: reload the durable queue and re-enqueue only sends that
-    // never reached the message log. A send whose id is already in messages.json
-    // was committed by a prior drain (its turn ran, finished or not -- matching
-    // origin/main, a logged message is considered handled), so re-queueing it
-    // would double-deliver; we drop those. Survivors keep their original order
-    // and start a follow-up turn, so an interrupted serve resumes them exactly
-    // once instead of losing them.
-    function recoverPending() {
-        const stored = readJsonFile(pendingPath);
-        if (!Array.isArray(stored))
-            return;
-        const committed = new Set(messages.map((m) => m.id));
-        for (const item of stored) {
-            if (item &&
-                typeof item.id === "string" &&
-                typeof item.text === "string" &&
-                Array.isArray(item.attachments) &&
-                !committed.has(item.id)) {
-                pendingSends.push({
-                    id: item.id,
-                    text: item.text,
-                    attachments: item.attachments.filter((a) => typeof a === "string"),
-                });
-            }
+    else {
+        maybeStartRouterQueueTurn(ctx);
+    }
+}
+// "Send now" (a queued row) / Stop (empty composer): kill the running turn,
+// capturing its partial draft so the follow-up turn continues it; the killed
+// run's settle flushes the queue. When idle, just flush (covers a stray
+// interrupt with messages already queued).
+function interruptRouterQueue(ctx) {
+    const { state } = ctx;
+    if (state.routerRunning) {
+        // A follow-up already queued ("Send now") means the user wants the turn
+        // continued with more intent; an empty queue means a bare Stop -- abandon
+        // the turn outright. Captured before reclaim, which would otherwise fill
+        // the queue and make every Stop look like a Send now.
+        const hasFollowUp = state.pendingSends.length > 0;
+        state.userEpoch += 1;
+        const draft = killRouterChildren(ctx);
+        // Only a continued turn ("Send now") reclaims its in-flight sends so they
+        // re-enter the next instruction. A bare Stop must NOT reclaim: doing so
+        // re-queues the just-killed message and the settle immediately restarts an
+        // identical turn -- the Stop appears to have no effect.
+        if (hasFollowUp && !turnHasVisibleOutput(ctx.messages)) {
+            reclaimInFlightSends(state.pendingSends, state.inFlightSends);
+            persistPendingSends(ctx);
         }
-        persistPending();
-        maybeStartRouterTurn();
+        // Only carry the partial draft forward when a queued message will consume
+        // it imminently ("Send now"). A bare Stop (empty composer) must not park
+        // the draft, or it leaks into the next unrelated message.
+        state.pendingInterruptedDraft = hasFollowUp ? draft : "";
     }
-    recoverPending();
+    else {
+        maybeStartRouterQueueTurn(ctx);
+    }
+}
+function cancelQueuedSend(ctx, index) {
+    const { state } = ctx;
+    if (!Number.isInteger(index) || index < 0 || index >= state.pendingSends.length)
+        return;
+    state.pendingSends.splice(index, 1);
+    persistPendingSends(ctx);
+    broadcastQueueState(ctx);
+}
+// Mid-run send queue (mirrors djinn's AltManager.pendingSends): a user message
+// sent while the router is mid-turn QUEUES instead of interrupting. It flushes
+// into a single follow-up turn when the current turn settles. An explicit
+// interrupt ("send now" / Stop) kills the run and flushes early. The epoch
+// keeps a killed-but-racing run from spawning tasks. Lives in its own factory
+// so createAgentServer stays within the max-lines budget; the queue-by-default
+// semantics are unchanged.
+function createRouterQueue(deps) {
+    const ctx = {
+        ...deps,
+        pendingPath: path.join(deps.agentDir, "pending-sends.json"),
+        state: {
+            userEpoch: 0,
+            routerRunning: false,
+            pendingSends: [],
+            inFlightSends: [],
+            pendingInterruptedDraft: "",
+            autoRetryUsed: false,
+            autoFoldUsed: false,
+            lastInstruction: "",
+        },
+    };
+    // Restart recovery: re-enqueue sends that never reached the message log,
+    // so an interrupted serve resumes them exactly once instead of losing them.
+    ctx.state.pendingSends.push(...loadRecoverableSends(ctx.pendingPath, new Set(deps.messages.map((m) => m.id))));
+    persistPendingSends(ctx);
+    maybeStartRouterQueueTurn(ctx);
     return {
-        handleUserMessage,
-        interruptRouter,
-        cancelQueued,
-        isRunning: () => routerRunning,
-        queuedSnippets,
+        handleUserMessage: (text, images) => handleQueueUserMessage(ctx, text, images),
+        interruptRouter: () => interruptRouterQueue(ctx),
+        cancelQueued: (index) => cancelQueuedSend(ctx, index),
+        isRunning: () => ctx.state.routerRunning,
+        queuedSnippets: () => computeQueuedSnippets(ctx.state.pendingSends),
     };
 }
 export function createAgentServer(opts) {
     const { deckDir, deckLabel } = opts;
+    const quickReference = readQuickReference(deckDir);
     const agentDir = path.join(deckDir, ".castle", "agent");
     const tasksDir = path.join(agentDir, "tasks");
     const attachmentsDir = path.join(agentDir, "attachments");
@@ -1598,10 +2343,11 @@ export function createAgentServer(opts) {
         deckLabel,
         tasksDir,
         children: taskChildren,
+        quickReference,
         backend: () => settings.tasks,
         claudeModel: () => settings.claudeModel,
         // Task lifecycle stays on the board only -- log lines for it were spam.
-        onUpdate: (task) => broadcast({ type: "task-update", task }),
+        onUpdate: (task) => broadcast({ type: "task-update", task: asClientTask(task) }),
         onStarted: () => undefined,
         onRetry: (task, attempt) => addLog(`agent died, retrying (${attempt}/${MAX_TASK_ATTEMPTS}): ${task.title}`),
         onFinished: (task) => taskFeeds.map.delete(task.id),
@@ -1612,6 +2358,7 @@ export function createAgentServer(opts) {
     const routerQueue = createRouterQueue({
         deckDir,
         deckLabel,
+        quickReference,
         agentDir,
         attachmentsDir,
         routerChildren,
@@ -1644,7 +2391,7 @@ export function createAgentServer(opts) {
         const hello = {
             type: "hello",
             messages,
-            tasks: taskStore.sorted(),
+            tasks: taskStore.sorted().map(asClientTask),
             settings,
             feeds: Object.fromEntries(taskFeeds.map),
             running: routerQueue.isRunning(),