castle-web-cli 0.4.71 → 0.4.73

package/dist/agent.js

@@ -171,10 +171,92 @@ function extractDirectives(full) {
         stops,
     };
 }
+// -- 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
+// parse it out of the live stream to drive the task card's avatar/phase (and
+// optionally progress), and strip it from the feed so the raw block never
+// shows. The enumerated activity avatars must match the prompt + the client.
+const SIGNAL_AVATARS = new Set([
+    "thinking",
+    "reading",
+    "building",
+    "painting",
+    "playing",
+]);
+// Parse the `key: value` body of a ```signal block, fail-soft: unknown keys are
+// ignored, progress is clamped 0-100, avatar must be in the enum or it's
+// dropped. `note` and `phase` are aliases for the phase line.
+function parseSignalBody(raw) {
+    const sig = {};
+    for (const line of raw.split("\n")) {
+        const m = /^\s*([a-zA-Z]+)\s*:\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const key = m[1].toLowerCase();
+        const value = m[2].trim();
+        if (!value)
+            continue;
+        if (key === "progress") {
+            const n = parseInt(value, 10);
+            if (Number.isFinite(n))
+                sig.progress = Math.max(0, Math.min(100, n));
+        }
+        else if (key === "avatar") {
+            if (SIGNAL_AVATARS.has(value))
+                sig.avatar = value;
+        }
+        else if (key === "note" || key === "phase") {
+            sig.phase = value;
+        }
+    }
+    return sig;
+}
+// Rewrite complete ```ask picker blocks in a prior assistant turn into a
+// readable line list before replaying the transcript to the router, so the
+// model sees the question it posed (not raw JSON it might echo back). Malformed
+// blocks are left untouched. Mirrors djinn's humanizeAskBlocks.
+const ASK_FENCE = /```ask[ \t]*\r?\n([\s\S]*?)```/g;
+function humanizeAskBlocks(text) {
+    return text.replace(ASK_FENCE, (whole, body) => {
+        try {
+            const data = JSON.parse(body);
+            if (!data || !Array.isArray(data.questions))
+                return whole;
+            const lines = data.questions
+                .map((q) => {
+                if (!q || typeof q.q !== "string" || !Array.isArray(q.options))
+                    return null;
+                const opts = q.options
+                    .filter((o) => typeof o === "string" && o.trim() !== "")
+                    .join(" / ");
+                if (!opts)
+                    return null;
+                const mode = q.multi === true ? "pick any" : "pick one";
+                return `- ${q.q} (${mode}): ${opts}`;
+            })
+                .filter((l) => l !== null);
+            if (lines.length === 0)
+                return whole;
+            return `[You asked the user to choose:\n${lines.join("\n")}]`;
+        }
+        catch {
+            return whole;
+        }
+    });
+}
 function baseName(p) {
     const parts = p.split(/[\\/]/).filter(Boolean);
     return parts[parts.length - 1] || p;
 }
+// First string-typed value among loosely-typed tool inputs, or "" when none is
+// a string (avoids "[object Object]" from String()-ing an object/array value).
+function firstString(...vals) {
+    for (const v of vals)
+        if (typeof v === "string")
+            return v;
+    return "";
+}
 // Matches the per-task progress file an agent writes its 0-100 integer to. We
 // hide those writes from the live feed -- they're constant noise, not work.
 const PROGRESS_FILE_RE = /\.castle\/agent\/tasks\/[^/]+\/progress$/;
@@ -184,13 +266,13 @@ const PROGRESS_FILE_RE = /\.castle\/agent\/tasks\/[^/]+\/progress$/;
 function claudeToolFeedLabel(name, input) {
     const kind = name.toLowerCase();
     if (["edit", "write", "notebookedit", "multiedit"].some((p) => kind.startsWith(p))) {
-        const file = String(input.file_path ?? input.path ?? input.notebook_path ?? "");
+        const file = firstString(input.file_path, input.path, input.notebook_path);
         if (!file || PROGRESS_FILE_RE.test(file))
             return null;
         return `Editing ${baseName(file)}`;
     }
     if (kind.startsWith("read") || kind.startsWith("notebookread")) {
-        const file = String(input.file_path ?? input.path ?? "");
+        const file = firstString(input.file_path, input.path);
         return file ? `Reading ${baseName(file)}` : null;
     }
     return null;
@@ -262,6 +344,141 @@ function envForAgentSpawn(backend) {
     }
     return env;
 }
+function createAgentStreamState() {
+    return {
+        accumulated: "",
+        finalText: "",
+        resultIsError: false,
+        sawResult: false,
+        segmentText: "",
+        needsGap: false,
+        pendingTools: new Map(),
+    };
+}
+// 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/
+// result hooks and dedupe/segment-gap handling).
+//
+// Cursor closes each text segment (e.g. right before a tool call) by
+// re-emitting the segment's full text as one more delta-shaped event; track the
+// current segment so those re-emissions are dropped instead of duplicating
+// lines. Segment boundaries also need a paragraph gap -- cursor starts the next
+// segment without one, which glues "Checking the deck..." lines onto the
+// previous paragraph. Claude tool_use blocks stream their input JSON by block
+// index, accumulated in pendingTools so content_block_stop can label them with
+// the real file / command (and drop progress-file writes).
+function makeAgentEventHandler(opts, state) {
+    const emitDelta = (rawDelta) => {
+        let delta = rawDelta;
+        if (state.needsGap) {
+            state.needsGap = false;
+            if (state.accumulated && !state.accumulated.endsWith("\n\n")) {
+                delta = (state.accumulated.endsWith("\n") ? "\n" : "\n\n") + delta;
+            }
+        }
+        state.segmentText += delta;
+        state.accumulated += delta;
+        opts.onDelta?.(delta);
+        opts.onActivity?.(null);
+    };
+    const handleClaudeEvent = (ev) => {
+        if (ev.type === "stream_event") {
+            const e = ev.event;
+            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: "",
+                    });
+                }
+                else if (e.content_block?.type === "thinking") {
+                    state.needsGap = true;
+                }
+            }
+            else if (e?.type === "content_block_delta") {
+                if (e.delta?.type === "text_delta" &&
+                    typeof e.delta.text === "string" &&
+                    e.delta.text) {
+                    emitDelta(e.delta.text);
+                }
+                else if (e.delta?.type === "thinking_delta" &&
+                    typeof e.delta.thinking === "string" &&
+                    e.delta.thinking) {
+                    opts.onThinking?.(e.delta.thinking);
+                }
+                else if (e.delta?.type === "input_json_delta" &&
+                    typeof e.delta.partial_json === "string") {
+                    const pending = state.pendingTools.get(e.index ?? -1);
+                    if (pending)
+                        pending.buf += e.delta.partial_json;
+                }
+            }
+            else if (e?.type === "content_block_stop") {
+                const pending = state.pendingTools.get(e.index ?? -1);
+                if (pending) {
+                    state.pendingTools.delete(e.index ?? -1);
+                    let input = {};
+                    try {
+                        input = pending.buf
+                            ? JSON.parse(pending.buf)
+                            : {};
+                    }
+                    catch {
+                        /* input JSON arrived partial -- fall back to a generic label */
+                    }
+                    const label = claudeToolFeedLabel(pending.name, input);
+                    if (label)
+                        opts.onActivity?.(label);
+                }
+            }
+        }
+        else if (ev.type === "result") {
+            state.sawResult = true;
+            state.finalText =
+                typeof ev.result === "string" ? ev.result : state.accumulated;
+            state.resultIsError = ev.is_error === true;
+        }
+    };
+    return (ev) => {
+        if (opts.parser === "claude") {
+            handleClaudeEvent(ev);
+            return;
+        }
+        if (ev.type === "assistant" && typeof ev.timestamp_ms === "number") {
+            const message = ev.message;
+            const delta = (message?.content ?? [])
+                .map((c) => (typeof c?.text === "string" ? c.text : ""))
+                .join("");
+            if (!delta)
+                return;
+            const trimmed = delta.trim();
+            if (trimmed.length >= 16 && state.segmentText.trim().endsWith(trimmed))
+                return;
+            emitDelta(delta);
+        }
+        else if (ev.type === "tool_call") {
+            state.segmentText = "";
+            state.needsGap = true;
+            if (ev.subtype === "started")
+                opts.onActivity?.(toolActivityLabel(ev));
+        }
+        else if (ev.type === "thinking") {
+            state.segmentText = "";
+            state.needsGap = true;
+            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;
+        }
+    };
+}
 // One headless agent CLI run (cursor or claude), normalized to the same
 // delta/activity/result hooks. Cursor: assistant events carrying timestamp_ms
 // are text deltas; the trailing assistant event without one repeats the whole
@@ -280,12 +497,9 @@ function runAgentCli(opts) {
             ? fs.createWriteStream(opts.logPath, { flags: "a" })
             : null;
         let settled = false;
-        let accumulated = "";
-        let finalText = "";
-        let resultIsError = false;
-        let sawResult = false;
         let stderrTail = "";
         let lineBuffer = "";
+        const state = createAgentStreamState();
         const settle = (result) => {
             if (settled)
                 return;
@@ -304,129 +518,11 @@ function runAgentCli(opts) {
             }
             settle({
                 ok: false,
-                finalText: finalText || accumulated,
+                finalText: state.finalText || state.accumulated,
                 error: "agent run timed out",
             });
         }, opts.timeoutMs);
-        // Cursor closes each text segment (e.g. right before a tool call) by
-        // re-emitting the segment's full text as one more delta-shaped event;
-        // track the current segment so those re-emissions are dropped instead of
-        // duplicating lines. Segment boundaries also need a paragraph gap --
-        // cursor starts the next segment without one, which glues "Checking the
-        // deck..." lines onto the previous paragraph.
-        let segmentText = "";
-        let needsGap = false;
-        // Accumulate each claude tool_use block's streamed input JSON by block
-        // index, so at content_block_stop we can label it with the real file /
-        // command (and drop progress-file writes).
-        const pendingTools = new Map();
-        const emitDelta = (rawDelta) => {
-            let delta = rawDelta;
-            if (needsGap) {
-                needsGap = false;
-                if (accumulated && !accumulated.endsWith("\n\n")) {
-                    delta = (accumulated.endsWith("\n") ? "\n" : "\n\n") + delta;
-                }
-            }
-            segmentText += delta;
-            accumulated += delta;
-            opts.onDelta?.(delta);
-            opts.onActivity?.(null);
-        };
-        const handleClaudeEvent = (ev) => {
-            if (ev.type === "stream_event") {
-                const e = ev.event;
-                if (e?.type === "content_block_start") {
-                    if (e.content_block?.type === "tool_use") {
-                        needsGap = true;
-                        // Hold the label until content_block_stop, once the input (file /
-                        // command) has streamed in, so we can name it concretely.
-                        pendingTools.set(e.index ?? -1, {
-                            name: String(e.content_block.name ?? ""),
-                            buf: "",
-                        });
-                    }
-                    else if (e.content_block?.type === "thinking") {
-                        needsGap = true;
-                    }
-                }
-                else if (e?.type === "content_block_delta") {
-                    if (e.delta?.type === "text_delta" &&
-                        typeof e.delta.text === "string" &&
-                        e.delta.text) {
-                        emitDelta(e.delta.text);
-                    }
-                    else if (e.delta?.type === "thinking_delta" &&
-                        typeof e.delta.thinking === "string" &&
-                        e.delta.thinking) {
-                        opts.onThinking?.(e.delta.thinking);
-                    }
-                    else if (e.delta?.type === "input_json_delta" &&
-                        typeof e.delta.partial_json === "string") {
-                        const pending = pendingTools.get(e.index ?? -1);
-                        if (pending)
-                            pending.buf += e.delta.partial_json;
-                    }
-                }
-                else if (e?.type === "content_block_stop") {
-                    const pending = pendingTools.get(e.index ?? -1);
-                    if (pending) {
-                        pendingTools.delete(e.index ?? -1);
-                        let input = {};
-                        try {
-                            input = pending.buf
-                                ? JSON.parse(pending.buf)
-                                : {};
-                        }
-                        catch {
-                            /* input JSON arrived partial -- fall back to a generic label */
-                        }
-                        const label = claudeToolFeedLabel(pending.name, input);
-                        if (label)
-                            opts.onActivity?.(label);
-                    }
-                }
-            }
-            else if (ev.type === "result") {
-                sawResult = true;
-                finalText = typeof ev.result === "string" ? ev.result : accumulated;
-                resultIsError = ev.is_error === true;
-            }
-        };
-        const handleEvent = (ev) => {
-            if (opts.parser === "claude") {
-                handleClaudeEvent(ev);
-                return;
-            }
-            if (ev.type === "assistant" && typeof ev.timestamp_ms === "number") {
-                const message = ev.message;
-                const delta = (message?.content ?? [])
-                    .map((c) => (typeof c?.text === "string" ? c.text : ""))
-                    .join("");
-                if (!delta)
-                    return;
-                const trimmed = delta.trim();
-                if (trimmed.length >= 16 && segmentText.trim().endsWith(trimmed))
-                    return;
-                emitDelta(delta);
-            }
-            else if (ev.type === "tool_call") {
-                segmentText = "";
-                needsGap = true;
-                if (ev.subtype === "started")
-                    opts.onActivity?.(toolActivityLabel(ev));
-            }
-            else if (ev.type === "thinking") {
-                segmentText = "";
-                needsGap = true;
-                opts.onActivity?.("thinking");
-            }
-            else if (ev.type === "result") {
-                sawResult = true;
-                finalText = typeof ev.result === "string" ? ev.result : accumulated;
-                resultIsError = ev.is_error === true;
-            }
-        };
+        const handleEvent = makeAgentEventHandler(opts, state);
         child.stdout.on("data", (chunk) => {
             lineBuffer += chunk.toString("utf8");
             let nl = lineBuffer.indexOf("\n");
@@ -451,16 +547,16 @@ function runAgentCli(opts) {
         child.on("error", (err) => {
             settle({
                 ok: false,
-                finalText: accumulated,
+                finalText: state.accumulated,
                 error: `could not run cursor-agent: ${err.message}`,
             });
         });
         child.on("close", (code) => {
-            const ok = code === 0 && !resultIsError && sawResult;
+            const ok = code === 0 && !state.resultIsError && state.sawResult;
             settle({
                 ok,
-                finalText: finalText || accumulated,
-                crashed: !sawResult,
+                finalText: state.finalText || state.accumulated,
+                crashed: !state.sawResult,
                 error: ok
                     ? undefined
                     : `agent exited ${code}${stderrTail ? `: ${stderrTail.slice(-300)}` : ""}`,
@@ -567,15 +663,38 @@ async function runTaskAgentIn(ctx, task) {
     const invocation = buildAgentInvocation(ctx.backend, "task", taskPrompt, ctx.claudeModel);
     let result = { ok: false, finalText: "", error: "not run" };
     let lineBuf = "";
+    // ```signal blocks span multiple lines and must NOT show in the live feed:
+    // track whether we're inside one (line-state machine). Lines arrive complete
+    // (flushFeedLines only emits up to a newline), so a partial fence never
+    // flashes. On close we parse the body and hand it to ctx.onSignal.
+    let inSignal = false;
+    let signalBody = "";
     const flushFeedLines = (delta) => {
         lineBuf += delta;
         let nl = lineBuf.indexOf("\n");
         while (nl >= 0) {
-            const line = lineBuf.slice(0, nl).trim();
+            const rawLine = lineBuf.slice(0, nl);
             lineBuf = lineBuf.slice(nl + 1);
+            nl = lineBuf.indexOf("\n");
+            const line = rawLine.trim();
+            if (inSignal) {
+                if (line === "```") {
+                    inSignal = false;
+                    ctx.onSignal(parseSignalBody(signalBody));
+                    signalBody = "";
+                }
+                else {
+                    signalBody += rawLine + "\n";
+                }
+                continue;
+            }
+            if (line === "```signal") {
+                inSignal = true;
+                signalBody = "";
+                continue;
+            }
             if (line)
                 ctx.onFeed(line);
-            nl = lineBuf.indexOf("\n");
         }
     };
     for (let attempt = 1; attempt <= MAX_TASK_ATTEMPTS; attempt++) {
@@ -607,6 +726,141 @@ async function runTaskAgentIn(ctx, task) {
     result.error = `agent process kept dying (${MAX_TASK_ATTEMPTS} attempts): ${result.error ?? ""}`;
     return result;
 }
+// Launch a task's agent run and wire up its finalization. The settle path is
+// hardened: result-finalization, onFinished, and the reschedule sweep each run
+// under their own try/catch so one bad task turn can neither wedge the board
+// (by skipping the slot free) nor crash the serve.
+function startTask(ctx, task) {
+    const dir = path.join(ctx.tasksDir, task.id);
+    fs.writeFileSync(path.join(dir, "progress"), "0\n");
+    if (!fs.existsSync(path.join(dir, "notes.md")))
+        fs.writeFileSync(path.join(dir, "notes.md"), "");
+    task.status = "running";
+    task.startedAt = nowIso();
+    ctx.touch(task);
+    ctx.onStarted(task);
+    const runCtx = {
+        deckDir: ctx.deckDir,
+        deckLabel: ctx.deckLabel,
+        tasksDir: ctx.tasksDir,
+        children: ctx.children,
+        backend: ctx.backend(),
+        claudeModel: ctx.claudeModel(),
+        stopRequested: ctx.stopRequested,
+        depsSummary: depsSummaryFor(ctx.tasks, task),
+        onFeed: (entry) => ctx.onFeed(task, entry),
+        onRetry: (attempt) => ctx.onRetry(task, attempt),
+        onSignal: (signal) => {
+            let changed = false;
+            if (typeof signal.progress === "number" &&
+                signal.progress !== task.progress) {
+                task.progress = signal.progress;
+                changed = true;
+            }
+            if (signal.avatar && signal.avatar !== task.avatar) {
+                task.avatar = signal.avatar;
+                changed = true;
+            }
+            if (signal.phase && signal.phase !== task.phase) {
+                task.phase = signal.phase;
+                changed = true;
+            }
+            if (changed)
+                ctx.touch(task);
+        },
+    };
+    void runTaskAgentIn(runCtx, task)
+        .then((result) => {
+        // Finalization (fs writes), onFinished, and the reschedule sweep must all
+        // survive a throw -- otherwise a single bad task turn could both skip
+        // freeing the slot (wedging the board) and crash the serve.
+        try {
+            refreshTaskFiles(ctx.tasksDir, task);
+            const wasStopped = ctx.stopRequested.delete(task.id);
+            task.status = wasStopped
+                ? "interrupted"
+                : result.ok
+                    ? "done"
+                    : "failed";
+            // A stopped task is cleared off the board (castle-stop = halt + remove).
+            if (wasStopped)
+                task.acknowledged = true;
+            if (result.ok && !wasStopped)
+                task.progress = 100;
+            task.finishedAt = nowIso();
+            task.resultSummary = wasStopped
+                ? "stopped by the router"
+                : result.ok
+                    ? result.finalText.slice(-RESULT_SUMMARY_CHARS)
+                    : `${result.error ?? "failed"}\n${result.finalText.slice(-RESULT_SUMMARY_CHARS)}`;
+            ctx.touch(task);
+        }
+        catch (err) {
+            console.error(`[task ${task.id}] finalization threw: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+            // Best-effort: still mark the task terminal so it can't hang forever.
+            try {
+                ctx.stopRequested.delete(task.id);
+                task.status = "failed";
+                task.finishedAt = nowIso();
+                task.resultSummary = `internal error finalizing task: ${err instanceof Error ? err.message : String(err)}`;
+                ctx.touch(task);
+            }
+            catch {
+                /* ignore -- the finally still frees the concurrency slot */
+            }
+        }
+        finally {
+            // Always notify and free the slot.
+            try {
+                ctx.onFinished(task);
+            }
+            catch (err) {
+                console.error(`[task ${task.id}] onFinished threw: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+            }
+            ctx.rescheduleAll();
+        }
+    })
+        .catch((err) => {
+        // runTaskAgentIn itself rejected. Free the slot so the board keeps moving.
+        console.error(`[task ${task.id}] run promise rejected: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+        try {
+            ctx.stopRequested.delete(task.id);
+            task.status = "failed";
+            task.finishedAt = nowIso();
+            task.resultSummary = `task run failed: ${err instanceof Error ? err.message : String(err)}`;
+            ctx.touch(task);
+            ctx.onFinished(task);
+        }
+        catch {
+            /* ignore */
+        }
+        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.
+function haltTask(task, children, stopRequested, touch) {
+    if (task.status === "waiting") {
+        task.status = "interrupted";
+        task.acknowledged = true;
+        touch(task);
+    }
+    else if (task.status === "running") {
+        stopRequested.add(task.id);
+        for (const child of children) {
+            if (child.pid === task.pid) {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        }
+    }
+}
 function createTaskStore(opts) {
     const { deckDir, deckLabel, tasksDir, children } = opts;
     const tasks = loadTasks(tasksDir);
@@ -642,52 +896,38 @@ function createTaskStore(opts) {
         // onFinished sweep below when a running task frees a slot.
         if (runningCount() >= MAX_CONCURRENT_TASKS)
             return;
-        start(task);
+        startTask(schedulerCtx, task);
     }
-    function start(task) {
-        const dir = path.join(tasksDir, task.id);
-        fs.writeFileSync(path.join(dir, "progress"), "0\n");
-        if (!fs.existsSync(path.join(dir, "notes.md")))
-            fs.writeFileSync(path.join(dir, "notes.md"), "");
-        task.status = "running";
-        task.startedAt = nowIso();
-        touch(task);
-        opts.onStarted(task);
-        const runCtx = {
-            deckDir,
-            deckLabel,
-            tasksDir,
-            children,
-            backend: opts.backend(),
-            claudeModel: opts.claudeModel(),
-            stopRequested,
-            depsSummary: depsSummaryFor(tasks, task),
-            onFeed: (entry) => opts.onFeed(task, entry),
-            onRetry: (attempt) => opts.onRetry(task, attempt),
-        };
-        void runTaskAgentIn(runCtx, task).then((result) => {
-            refreshTaskFiles(tasksDir, task);
-            const wasStopped = stopRequested.delete(task.id);
-            task.status = wasStopped ? "interrupted" : result.ok ? "done" : "failed";
-            // A stopped task is cleared off the board (castle-stop = halt + remove).
-            if (wasStopped)
-                task.acknowledged = true;
-            if (result.ok && !wasStopped)
-                task.progress = 100;
-            task.finishedAt = nowIso();
-            task.resultSummary = wasStopped
-                ? "stopped by the router"
-                : result.ok
-                    ? result.finalText.slice(-RESULT_SUMMARY_CHARS)
-                    : `${result.error ?? "failed"}\n${result.finalText.slice(-RESULT_SUMMARY_CHARS)}`;
-            touch(task);
-            opts.onFinished(task);
-            // A slot just freed -- restart eligible waiting tasks, earliest-created
-            // first, up to the concurrency cap.
-            for (const waiting of sorted())
+    // Restart eligible waiting tasks, earliest-created first, up to the
+    // concurrency cap. Each start is guarded so one failure can't wedge the rest
+    // of the board. Passed to startTask so a finished run can free its slot.
+    function rescheduleAll() {
+        for (const waiting of sorted()) {
+            try {
                 maybeStart(waiting);
-        });
+            }
+            catch (err) {
+                console.error(`[task ${waiting.id}] maybeStart threw: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+            }
+        }
     }
+    const schedulerCtx = {
+        deckDir,
+        deckLabel,
+        tasksDir,
+        children,
+        tasks,
+        stopRequested,
+        backend: opts.backend,
+        claudeModel: opts.claudeModel,
+        onStarted: opts.onStarted,
+        onFinished: opts.onFinished,
+        onRetry: opts.onRetry,
+        onFeed: opts.onFeed,
+        touch,
+        sorted,
+        rescheduleAll,
+    };
     function spawnFromDirective(directive, originMessageId) {
         const task = {
             id: nanoid(8),
@@ -755,31 +995,7 @@ function createTaskStore(opts) {
     // 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.
-    // 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.
-    function haltTask(task) {
-        if (task.status === "waiting") {
-            task.status = "interrupted";
-            task.acknowledged = true;
-            touch(task);
-        }
-        else if (task.status === "running") {
-            stopRequested.add(task.id);
-            for (const child of children) {
-                if (child.pid === task.pid) {
-                    try {
-                        child.kill("SIGKILL");
-                    }
-                    catch {
-                        /* already gone */
-                    }
-                }
-            }
-        }
-    }
+    // via the stopRequested path (see haltTask).
     function stop(tokens) {
         const ids = meansAll(tokens)
             ? [...tasks.values()]
@@ -789,7 +1005,7 @@ function createTaskStore(opts) {
         for (const id of ids) {
             const task = tasks.get(id);
             if (task)
-                haltTask(task);
+                haltTask(task, children, stopRequested, touch);
         }
     }
     return {
@@ -937,7 +1153,9 @@ function runRouterTurnIn(ctx, instruction) {
             .filter((m) => m.role !== "log" && m.id !== message.id && m.status !== "streaming")
             .map((m) => ({
             role: m.role,
-            text: m.text,
+            // Replace a prior turn's raw ```ask JSON with a readable question list
+            // so the model doesn't re-echo the block verbatim.
+            text: m.role === "assistant" ? humanizeAskBlocks(m.text) : m.text,
             interrupted: m.interrupted,
         })),
         // Only the live board -- match what the user sees. Hide tasks that are
@@ -975,53 +1193,99 @@ function runRouterTurnIn(ctx, instruction) {
             lastActivity = activity;
             ctx.broadcast({ type: "message-activity", id: message.id, activity });
         },
-    }).then((result) => {
-        const interrupted = epoch !== ctx.currentEpoch() && !result.ok;
-        if (interrupted) {
-            // Keep whatever streamed; the continuation turn carries the draft.
-            message.status = "done";
-            message.interrupted = true;
+    })
+        .then((result) => {
+        // 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
+        // body runs under try/catch/finally and every terminal branch falls
+        // through to the finally rather than calling onSettled() inline.
+        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: [],
+                });
+                return;
+            }
+            const { cleaned, directives, checkoffs, stops } = extractDirectives(result.finalText);
+            if (result.ok && checkoffs.length > 0)
+                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).
+            const stale = epoch !== ctx.currentEpoch();
+            const inFlight = new Set(ctx.taskStore
+                .sorted()
+                .filter((t) => t.status === "running" || t.status === "waiting")
+                .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";
+            if (taskIds.length > 0)
+                message.taskIds = taskIds;
             ctx.log.persist();
             ctx.broadcast({
                 type: "message-done",
                 id: message.id,
                 text: message.text,
                 status: message.status,
-                interrupted: true,
-                taskIds: [],
+                taskIds: message.taskIds ?? [],
             });
-            return;
         }
-        const { cleaned, directives, checkoffs, stops } = extractDirectives(result.finalText);
-        if (result.ok && checkoffs.length > 0)
-            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).
-        const stale = epoch !== ctx.currentEpoch();
-        const inFlight = new Set(ctx.taskStore
-            .sorted()
-            .filter((t) => t.status === "running" || t.status === "waiting")
-            .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";
-        if (taskIds.length > 0)
-            message.taskIds = taskIds;
-        ctx.log.persist();
-        ctx.broadcast({
-            type: "message-done",
-            id: message.id,
-            text: message.text,
-            status: message.status,
-            taskIds: message.taskIds ?? [],
-        });
+        catch (err) {
+            // Surface the failure in the UI instead of silently hanging: mark the
+            // in-flight assistant message as errored, persist, and broadcast so the
+            // composer un-freezes and the user sees what happened.
+            const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+            const short = err instanceof Error ? err.message : String(err);
+            console.error(`[router] turn callback threw: ${detail}`);
+            try {
+                message.status = "error";
+                message.text = `${message.text ? message.text + "\n\n" : ""}[router error: ${short}]`;
+                ctx.log.persist();
+                ctx.broadcast({
+                    type: "message-done",
+                    id: message.id,
+                    text: message.text,
+                    status: message.status,
+                    taskIds: message.taskIds ?? [],
+                });
+            }
+            catch (inner) {
+                console.error(`[router] failed to surface turn error: ${inner instanceof Error ? inner.stack ?? inner.message : String(inner)}`);
+            }
+        }
+        finally {
+            ctx.onSettled();
+        }
+    })
+        .catch((err) => {
+        // runAgentCli itself rejected (it normally resolves with result.ok=false,
+        // so this is the rare hard-failure path). Still settle so routerRunning
+        // can't stick true and freeze the composer.
+        console.error(`[router] turn promise rejected: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+        try {
+            ctx.onSettled();
+        }
+        catch (inner) {
+            console.error(`[router] onSettled threw during rejection recovery: ${inner instanceof Error ? inner.stack ?? inner.message : String(inner)}`);
+        }
     });
 }
 // Merge settings changes from the client: validate, persist, broadcast, log.
@@ -1101,6 +1365,194 @@ 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(),
+        });
+    }
+    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 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).
+            const message = {
+                id: item.id,
+                role: "user",
+                text: item.text,
+                at: nowIso(),
+                status: "done",
+            };
+            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 : "";
+        }
+        else {
+            maybeStartRouterTurn();
+        }
+    }
+    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"),
+                });
+            }
+        }
+        persistPending();
+        maybeStartRouterTurn();
+    }
+    recoverPending();
+    return {
+        handleUserMessage,
+        interruptRouter,
+        cancelQueued,
+        isRunning: () => routerRunning,
+        queuedSnippets,
+    };
+}
 export function createAgentServer(opts) {
     const { deckDir, deckLabel } = opts;
     const agentDir = path.join(deckDir, ".castle", "agent");
@@ -1155,78 +1607,33 @@ export function createAgentServer(opts) {
         onFinished: (task) => taskFeeds.map.delete(task.id),
         onFeed: (task, entry) => taskFeeds.push(task, entry),
     });
-    // A new user message interrupts the in-flight router reply: its partial
-    // text stays in the log, and the next turn continues both threads. The
-    // epoch also keeps a killed-but-racing run from spawning tasks.
-    let userEpoch = 0;
-    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 drafts.join("\n\n");
-    }
-    function runRouterTurn(instruction) {
-        runRouterTurnIn({
-            deckDir,
-            deckLabel,
-            agentDir,
-            children: routerChildren,
-            log,
-            broadcast,
-            taskStore,
-            currentEpoch: () => userEpoch,
-            backend: () => settings.router,
-            claudeModel: () => settings.claudeModel,
-        }, instruction);
-    }
-    // User messages awaiting a reply: everything since the last COMPLETED (done,
-    // not interrupted) assistant message. Usually just the latest, but a rapid
-    // burst leaves several queued -- all must be addressed, not only the last.
-    function pendingUserMessages() {
-        let lastAnswered = -1;
-        for (let i = messages.length - 1; i >= 0; i--) {
-            const m = messages[i];
-            if (m.role === "assistant" && m.status === "done" && !m.interrupted) {
-                lastAnswered = i;
-                break;
-            }
+    // The mid-run send queue (queue-by-default, "send now"/Stop interrupt, epoch
+    // guard). Lives in its own factory; createAgentServer just wires it up.
+    const routerQueue = createRouterQueue({
+        deckDir,
+        deckLabel,
+        agentDir,
+        attachmentsDir,
+        routerChildren,
+        log,
+        broadcast,
+        taskStore,
+        messages,
+        settings,
+    });
+    // The user answered an embedded ```ask picker: record the selections on the
+    // assistant message (locks the widget for every client, persists across
+    // reloads) and route the composed reply through the normal user-message path
+    // (so it respects the send queue).
+    function handlePickerChoice(id, answers, text) {
+        const msg = messages.find((m) => m.id === id);
+        if (msg && msg.role === "assistant" && answers && typeof answers === "object") {
+            msg.pickerAnswers = answers;
+            log.persist();
+            broadcast({ type: "message-picker", id, pickerAnswers: msg.pickerAnswers });
         }
-        return messages.slice(lastAnswered + 1).filter((m) => m.role === "user");
-    }
-    function handleUserMessage(text, images) {
-        userEpoch += 1;
-        const interruptedDraft = interruptRouterRuns();
-        const messageId = nanoid(8);
-        const attachments = saveAttachments(attachmentsDir, messageId, images);
-        const message = {
-            id: messageId,
-            role: "user",
-            text,
-            at: nowIso(),
-            status: "done",
-        };
-        if (attachments.length > 0)
-            message.attachments = attachments;
-        log.add(message);
-        // Address every still-unanswered user message (this one plus any earlier
-        // burst messages that interrupted prior turns), not just the latest.
-        const pending = pendingUserMessages();
-        runRouterTurn(userTurnInstruction({
-            messages: pending.map((m) => m.text),
-            interruptedDraft: interruptedDraft || undefined,
-            attachments: pending
-                .flatMap((m) => m.attachments ?? [])
-                .map((name) => path.join(".castle", "agent", "attachments", name)),
-        }));
+        if (text.trim())
+            routerQueue.handleUserMessage(text.trim(), undefined);
     }
     function handleTaskAck(id, rejected) {
         taskStore.acknowledge(id, rejected);
@@ -1240,6 +1647,8 @@ export function createAgentServer(opts) {
             tasks: taskStore.sorted(),
             settings,
             feeds: Object.fromEntries(taskFeeds.map),
+            running: routerQueue.isRunning(),
+            queued: routerQueue.queuedSnippets(),
         };
         socket.send(JSON.stringify(hello));
         socket.on("message", (rawData) => {
@@ -1253,7 +1662,16 @@ export function createAgentServer(opts) {
             const hasText = typeof msg.text === "string" && msg.text.trim() !== "";
             const hasImages = Array.isArray(msg.images) && msg.images.length > 0;
             if (msg.type === "user-message" && (hasText || hasImages)) {
-                handleUserMessage(typeof msg.text === "string" ? msg.text.trim() : "", msg.images);
+                routerQueue.handleUserMessage(typeof msg.text === "string" ? msg.text.trim() : "", msg.images);
+            }
+            else if (msg.type === "interrupt") {
+                routerQueue.interruptRouter();
+            }
+            else if (msg.type === "cancel-queued" && typeof msg.index === "number") {
+                routerQueue.cancelQueued(msg.index);
+            }
+            else if (msg.type === "picker-choice" && typeof msg.id === "string") {
+                handlePickerChoice(msg.id, msg.answers, typeof msg.text === "string" ? msg.text : "");
             }
             else if (msg.type === "task-ack" && typeof msg.id === "string") {
                 handleTaskAck(msg.id, msg.rejected === true);