castle-web-cli 0.4.75 → 0.4.76

package/dist/agent-prompts.d.ts

@@ -9,9 +9,12 @@ export interface PromptTask {
     status: string;
     progress: number;
     notes: string;
+    files?: string[];
 }
 export declare function buildRouterPrompt(opts: {
     deckLabel: string;
+    quickReference?: string;
+    deckTree?: string;
     messages: PromptMessage[];
     tasks: PromptTask[];
     instruction: string;
@@ -30,5 +33,6 @@ export declare function buildTaskPrompt(opts: {
     notesPath: string;
     depsSummary?: string;
     backend?: "cursor" | "claude";
+    deckTree?: string;
 }): string;
 export declare const CLAUDE_TASK_SYSTEM_REMINDER = "Castle background task agent: work autonomously to completion -- never pause to ask questions or wait for confirmation; finish the task end-to-end, then stop. Prefer the quickest viable change that fully does the job.";

package/dist/agent-prompts.js

@@ -8,11 +8,11 @@
 const TRANSCRIPT_LIMIT = 40;
 const ROUTER_RULES = `You are Castle's create assistant: the fast conversational router for a game-making session. The deck (game project) lives in the current directory and runs live in a pane right next to this chat.
 
-What a deck is: a normal web project served by vite -- index.html plus plain JS/JSX modules, with real npm dependencies (more can be installed), the castle-web-sdk package, and usually a kit framework whose engine, behaviors, scenes, editors, and drawings are ordinary files in this directory. The web platform is fully available (DOM, canvas, npm libraries like react, three, etc.). The deck's CLAUDE.md / AGENTS.md describes the specific setup. NEVER claim something is impossible or unsupported on the platform without checking the deck's files first.
+What a deck is: a normal web project served by vite -- index.html plus plain JS/JSX modules, with real npm dependencies (more can be installed), the castle-web-sdk package, and usually a kit framework whose engine, behaviors, scenes, editors, and drawings are ordinary files in this directory. The web platform is fully available (DOM, canvas, npm libraries like react, three, etc.). The deck's Quick reference and file list below describe its setup; the full CLAUDE.md / AGENTS.md has deeper detail. NEVER claim something is impossible or unsupported on the platform without checking that context (or, for specifics it doesn't cover, the deck's files) first.
 
 Hard rules:
 - You NEVER edit files or run state-changing commands. All building and fixing happens through background task agents -- always hand the longer work to them.
-- You are the fast lane: get to your final reply as quickly as possible. When the user reports something broken, do NOT dig into the code to diagnose it first -- spawn a task whose job is to investigate AND fix it. Only read deck files when your reply itself needs them (answering a question about the deck, grounding a claim -- never make things up); never read as pre-work before spawning a task.
+- You are the fast lane: get to your final reply as quickly as possible. When the user reports something broken, do NOT dig into the code to diagnose it first -- spawn a task whose job is to investigate AND fix it. Only read deck files when your reply itself needs them (answering a question about the deck, grounding a claim -- never make things up); never read as pre-work before spawning a task, and never read files just to learn conventions already covered by the Quick reference.
 - Launch a SET of small steps the user tests one by one -- a pipeline, never one big task they wait on, never untestable fragments. One interacting mechanic = one task (paddle + ball + bricks = one playable core, not three). First step = the smallest genuinely playable thing; later steps build it out. Match breadth to ambition ("basic" = a few steps; "go wild" = many). You're optimizing the user's taste and feedback -- more small testable steps = more points where they steer it into something theirs.
 - The whole goal: every piece of work TESTABLE in actual gameplay ASAP. Start every task as early as possible and run them in PARALLEL. Do NOT break tasks down by which files they touch, and never add \`after:\` just to avoid two tasks editing the same file -- tasks make surgical edits and overlap fine. The only real dependency between tasks is INFORMATION: a task is blocked only when it needs a fact it does not yet have.
 - Dissolve those information-dependencies with a CONTRACT decided up front, instead of serializing tasks. Before spawning, pin the shared names the tasks will agree on -- scene file names, behavior names, drawing file names, tags -- and give each parallel task the exact names it must CREATE or REFERENCE. Then they all run at once and converge to a working game with NO follow-up wiring task: the scene task places actors referencing behaviors and drawings by their agreed names before those files even exist; the behavior tasks create those behavior names; the drawing tasks create those drawing files. (Art: pin a drawing name like drawings/ship up front -> the scene task points an actor at it while another task draws it, in parallel; no place-it-later task.) Fall back to a separate waiting wire-in task (\`after:\` the maker, on the least possible) ONLY when a task truly needs another's actual produced output, not just its agreed name. Working out this breakdown -- what to parallelize, which names to pin up front -- is the core of your job and differs per game.
@@ -47,6 +47,7 @@ comma-separated active-task titles or ids, or \`all\`
 - Never claim the board is cleared without actually emitting the fence.
 - Tasks are one-and-done -- when the user gives feedback on a finished task, spawn a new fix task (and \`castle-done\` the old row) rather than reopening it.
 - Task agents are capable coding agents working in this same deck directory, but they know nothing about this conversation beyond your prompt.
+- Board rows may include \`files:\` for finished work. Use those touched-file lists to aim follow-up/fix tasks and to keep shared names consistent without rereading the deck.
 
 Asking with options (the \`\`\`ask block). When you need the user to settle a few choices at once, emit ONE fenced block tagged \`ask\` containing JSON -- it renders inline in the chat as grouped options they tap and submit together (far better than stacking questions they can only half-answer). Reach for it to pin a direction fast when their ask is vague ("make me a game" -> ask what kind), NOT to interrogate. Options only, no free text.
 
@@ -86,22 +87,29 @@ function renderTasks(tasks) {
     return tasks
         .map((t) => {
         const notes = t.notes.trim() ? ` -- notes: ${t.notes.trim()}` : "";
-        return `- [${t.status} ${t.progress}%] ${t.title} (${t.id})${notes}`;
+        const files = t.files && t.files.length > 0 ? ` -- files: ${t.files.join(", ")}` : "";
+        return `- [${t.status} ${t.progress}%] ${t.title} (${t.id})${notes}${files}`;
     })
         .join("\n");
 }
 export function buildRouterPrompt(opts) {
+    const quickReference = opts.quickReference?.trim()
+        ? `\n\n== how this deck works ==\n${opts.quickReference.trim()}`
+        : "";
+    const deckFiles = opts.deckTree?.trim()
+        ? `\n\n== deck files ==\n${opts.deckTree.trim()}`
+        : "";
     return `${ROUTER_RULES}
 
 == deck ==
-${opts.deckLabel}
-
-== background tasks ==
-${renderTasks(opts.tasks)}
+${opts.deckLabel}${quickReference}${deckFiles}
 
 == conversation so far ==
 ${renderTranscript(opts.messages)}
 
+== background tasks ==
+${renderTasks(opts.tasks)}
+
 == now ==
 ${opts.instruction}
 
@@ -130,6 +138,9 @@ export function buildTaskPrompt(opts) {
     const deps = opts.depsSummary
         ? `\n\nThis task waited on earlier tasks:\n${opts.depsSummary}\n`
         : "";
+    const layout = opts.deckTree?.trim()
+        ? `\n\nDeck files (snapshot at task start; parallel sibling tasks may create files named in your prompt that are absent here):\n\n${opts.deckTree.trim()}\n`
+        : "";
     // Claude-only: collapsing the wrap-up (progress 90 + restart + notes) into
     // one shell call reliably saves 1-2 serial ~7s turns there. Cursor's
     // composer sometimes reacts to the same rule with MORE calls, so it stays
@@ -140,13 +151,14 @@ export function buildTaskPrompt(opts) {
     const wrapUp = opts.backend === "claude"
         ? `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine the 90-progress write, the final \`npm run restart\`, and writing the notes file into a single shell command (\`;\`-separated so the notes land even if the restart hiccups). Then stop -- no extra turns after it.`
         : "";
-    return `You are a background build agent for the Castle deck "${opts.deckLabel}" (current directory). A separate conversation agent dispatched you with one task. Follow the deck's CLAUDE.md / AGENTS.md conventions, and reload the served deck after changes (\`npm run restart\`).
+    return `You are a background build agent for the Castle deck "${opts.deckLabel}" (current directory). A separate conversation agent dispatched you with one task. Follow the deck's CLAUDE.md / AGENTS.md conventions, and reload the served deck after changes (\`npm run restart\`).${layout}
 
 Your task (id ${opts.taskId}): ${opts.title}
 
 ${opts.prompt}${deps}
 
 Operating rules:
+- The file snapshot above is for orientation. Prefer going straight to the files this task touches, but if this is an investigation or debugging task, survey what you need to understand the failure.
 - Speed is of the essence -- go for the quickest viable, testable change, unless this prompt explicitly tells you to take longer and dive deep. It must still amount to at least one meaningful step up (one or a few features, pieces of art, etc.), never a token gesture.
 - The USER is the verifier -- the whole tasks system exists so the user playtests every change themselves. Your first priority is to finish as soon as possible with the change genuinely in place and reachable in the running deck, so the user can test it right away. Do NOT run verification (screenshots especially) unless you are really sure it will catch something a re-read of your own change cannot -- and even then at most one cheap check, never a retry loop. Time spent verifying is time the user is left waiting.
 - The moment implementation is complete and you switch to verifying, write 90 to the progress file -- verification time must not read as stalled progress.

package/dist/agent.js

@@ -277,6 +277,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 +306,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 +364,228 @@ function envForAgentSpawn(backend) {
     }
     return env;
 }
+const DECK_TREE_EXCLUDE = new Set([
+    "node_modules",
+    ".castle",
+    ".git",
+    "dist",
+    ".DS_Store",
+]);
+const DECK_TREE_MAX_ENTRIES = 200;
+// 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);
+        });
+        for (const entry of entries) {
+            if (DECK_TREE_EXCLUDE.has(entry.name))
+                continue;
+            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);
+            }
+        }
+    };
+    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;
+}
+function normalizeTouchedPath(cwd, raw) {
+    if (!raw || raw.includes("\n"))
+        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 +619,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 +668,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 +680,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 +703,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 +764,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 +802,8 @@ function runAgentCli(opts) {
             settle({
                 ok,
                 finalText: state.finalText || state.accumulated,
+                usage: state.usage,
+                filesTouched: touchedFileList(state.filesTouched),
                 crashed: !state.sawResult,
                 error: ok
                     ? undefined
@@ -653,6 +901,7 @@ async function runTaskAgentIn(ctx, task) {
         notesPath: path.join(relDir, "notes.md"),
         depsSummary: ctx.depsSummary,
         backend: ctx.backend,
+        deckTree: buildDeckTree(ctx.deckDir),
     });
     // 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
@@ -787,6 +1036,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"
@@ -1060,6 +1310,24 @@ function asPromptTask(task) {
         status: task.rejected ? "rejected by user" : task.status,
         progress: task.progress,
         notes: task.notes,
+        files: task.files,
+    };
+}
+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) {
@@ -1146,9 +1414,18 @@ function runRouterTurnIn(ctx, instruction) {
     ctx.broadcast({ type: "message-add", message });
     let raw = "";
     let visibleSent = 0;
-    let lastActivity = null;
+    // 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 = 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")
             .map((m) => ({
@@ -1177,6 +1454,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);
@@ -1195,6 +1473,7 @@ function runRouterTurnIn(ctx, instruction) {
         },
     })
         .then((result) => {
+        logRouterUsage(backend, result.usage);
         // 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
@@ -1373,18 +1652,14 @@ function startChildRegistry(registryPath, groups) {
 // 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;
+    const { deckDir, deckLabel, quickReference, 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.
+    // Durable mid-run sends, mirrored to pending-sends.json until drained.
     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.
+    // Persist every mutation so a restart never loses an unsent queued message.
     function persistPending() {
         fs.writeFileSync(pendingPath, JSON.stringify(pendingSends, null, 2) + "\n");
     }
@@ -1417,6 +1692,7 @@ function createRouterQueue(deps) {
         runRouterTurnIn({
             deckDir,
             deckLabel,
+            quickReference,
             agentDir,
             children: routerChildren,
             log,
@@ -1428,10 +1704,7 @@ function createRouterQueue(deps) {
             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.
+    // Drain queued sends into one follow-up turn; no-op while running or empty.
     function maybeStartRouterTurn() {
         if (routerRunning || pendingSends.length === 0)
             return;
@@ -1439,9 +1712,7 @@ function createRouterQueue(deps) {
         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).
+            // Enqueue assigned the durable id/attachments; drain commits them to log.
             const message = {
                 id: item.id,
                 role: "user",
@@ -1555,6 +1826,7 @@ function createRouterQueue(deps) {
 }
 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");
@@ -1601,7 +1873,7 @@ export function createAgentServer(opts) {
         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 +1884,7 @@ export function createAgentServer(opts) {
     const routerQueue = createRouterQueue({
         deckDir,
         deckLabel,
+        quickReference,
         agentDir,
         attachmentsDir,
         routerChildren,
@@ -1644,7 +1917,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(),