castle-web-cli 0.4.125 → 0.4.127

package/dist/agent.d.ts

@@ -34,6 +34,7 @@ interface TaskRecord {
     title: string;
     prompt: string;
     after: string[];
+    item?: string;
     status: TaskStatus;
     progress: number;
     notes: string;
@@ -51,6 +52,11 @@ interface TaskRecord {
     phase?: string;
     acknowledged?: boolean;
     rejected?: boolean;
+    durable?: string;
+    what?: string;
+    files?: string[];
+    knobs?: string[];
+    durablePending?: boolean;
     blockedBy?: string[];
 }
 export declare function roleUsesOpenrouter(backend: AgentBackend, claudeModel: ClaudeModel): boolean;

package/dist/agent.js

@@ -22,7 +22,9 @@ import * as path from 'path';
 import { nanoid } from 'nanoid';
 import { WebSocketServer } from 'ws';
 import { rawDataToString } from './ide.js';
-import { buildRouterPrompt, buildTaskPrompt, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, } from './agent-prompts.js';
+import { PLAN_FILE } from './localPaths.js';
+import { applyPlanOps, buildRouterPrompt, buildTaskPrompt, parsePlanOps, planOpenQuestionLines, truncateToBytes, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, } from './agent-prompts.js';
+import { readCastleJson } from './castleJson.js';
 import { checkOpenrouterKey, checkOpenrouterModel, openrouterCatalogEntry, primeOpenrouterCatalog, } from './openrouter-catalog.js';
 import { classifyProviderError, failureCopy, setReaderTimeZone, } from './agent-failures.js';
 import { fetchBudget, meteringHeaders, newAgentSessionId, reportCursorRun, withCustomHeaders, } from './metering.js';
@@ -517,6 +519,11 @@ const TASK_SPAWN_STAGGER_MS = Number(process.env.CASTLE_TASK_SPAWN_STAGGER_MS) |
 const TASK_POLL_MS = 1_000;
 const FENCE_HOLDBACK = '```castle-';
 const RESULT_SUMMARY_CHARS = 600;
+// Byte ceiling on the plan.md injected into router turns and task prompts.
+// Nothing bounds the file itself -- ops touch one line each and the user pastes
+// what they like -- meanwhile the whole prompt rides inside one argv entry (see
+// TRANSCRIPT_BYTE_BUDGET in agent-prompts.ts), so this term needs its own bound.
+const PLAN_BYTE_BUDGET = 8 * 1024;
 const MAX_ATTACHMENTS = 6;
 const MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024;
 const TERMINAL_STATUSES = ['done', 'failed', 'interrupted'];
@@ -548,27 +555,37 @@ 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.
+// Parse one ```castle-task fence's body (title line, optional "after:" and
+// "item:" lines in either order, 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 = [];
+    let item;
     while (lines.length > 0) {
-        const headerMatch = /^(after):\s*(.*)$/i.exec((lines[0] ?? '').trim());
+        const headerMatch = /^(after|item):\s*(.*)$/i.exec((lines[0] ?? '').trim());
         if (!headerMatch)
             break;
         lines.shift();
+        if (headerMatch[1].toLowerCase() === 'item') {
+            const label = headerMatch[2].trim();
+            // `item: -` is the fence saying "chore, no plan item" -- an answer, not
+            // an omission, so it lands the same as no line at all.
+            if (label && label !== '-')
+                item = label;
+            continue;
+        }
         after.push(...headerMatch[2]
             .split(',')
             .map((s) => s.trim())
             .filter(Boolean));
     }
-    return { title, after, prompt: lines.join('\n').trim() };
+    return { title, after, item, 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
@@ -577,6 +594,18 @@ function parseTaskFenceBody(body) {
 function taskFenceRegex() {
     return /```castle-task[ \t]*\r?\n([\s\S]*?)```/g;
 }
+// Take the body of a ```castle-plan fence out of a router reply: the ops it
+// wants applied to plan.md. A reply emitting more than one is stating more ops,
+// so the bodies concatenate in order. Returns the reply with every such fence
+// removed.
+function takePlanFence(source) {
+    const bodies = [];
+    const rest = source.replace(/```castle-plan[ \t]*\r?\n([\s\S]*?)```/g, (_match, body) => {
+        bodies.push(String(body));
+        return '';
+    });
+    return { plan: bodies.length > 0 ? bodies.join('\n') : undefined, rest };
+}
 // 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) {
@@ -594,7 +623,8 @@ function extractDirectives(full) {
             return '';
         });
     };
-    const withoutDone = listFence(listFence(full, 'castle-done', checkoffs), 'castle-stop', stops);
+    const { plan, rest } = takePlanFence(full);
+    const withoutDone = listFence(listFence(rest, 'castle-done', checkoffs), 'castle-stop', stops);
     const cleaned = withoutDone.replace(taskFenceRegex(), (_match, body) => {
         const directive = parseTaskFenceBody(String(body));
         if (directive)
@@ -606,8 +636,166 @@ function extractDirectives(full) {
         directives,
         checkoffs,
         stops,
+        plan,
+    };
+}
+const planSessions = new Map();
+// What a deck that says nothing gets. Off unless the serve was told otherwise,
+// so a serve nobody configured -- one started from a terminal, or by a caller
+// that forgot the flag -- lands on the default rather than quietly handing the
+// feature to someone outside the rollout. The cloud editor sets it per user
+// from a feature gate; see serveOnPort in castle-www's cloudSandbox.ts.
+function planDefault() {
+    return process.env.CASTLE_AGENT_PLAN === 'on';
+}
+function planSession(deckDir) {
+    const existing = planSessions.get(deckDir);
+    if (existing)
+        return existing;
+    const declared = readCastleJson(deckDir)?.agent?.plan;
+    const session = {
+        enabled: declared === 'on' ? true : declared === 'off' ? false : planDefault(),
+        notices: [],
+        asyncNotices: [],
+        quietBuildTurns: 0,
+    };
+    planSessions.set(deckDir, session);
+    return session;
+}
+function readPlanSnapshot(deckDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(deckDir, PLAN_FILE), 'utf8');
+    }
+    catch {
+        return { raw: null };
+    }
+    if (!raw.trim())
+        return { raw };
+    if (Buffer.byteLength(raw, 'utf8') <= PLAN_BYTE_BUDGET)
+        return { raw, text: raw.trim() };
+    return {
+        raw,
+        text: `${truncateToBytes(raw, PLAN_BYTE_BUDGET).trim()}\n\n(trimmed -- plan.md is longer than this. Tell the user it has grown too long; it should stay a short working plan.)`,
+    };
+}
+// How many op notices ride into the next router turn. More than a handful is a
+// fence that went wrong wholesale, and the first few say so.
+const PLAN_NOTICE_LIMIT = 6;
+// Apply a ```castle-plan fence's ops to <deck>/plan.md. The file is re-read
+// HERE rather than passed down from prompt-build time: an op names the one line
+// it touches, so a user editing another part of the plan while the turn ran
+// keeps their edit and the op still lands. (Full-file fences could do neither,
+// which is what the old stale-snapshot guard was for.)
+function applyPlanFence(deckDir, body, sources) {
+    const session = planSession(deckDir);
+    // An opted-out deck is never told plan.md exists, so a fence here is a stray
+    // -- applying it would put a file on a deck that asked for none. The fence is
+    // still stripped from the reply upstream, same as any other.
+    if (!session.enabled)
+        return 'dropped';
+    const { ops, unparsed } = parsePlanOps(body);
+    const notices = unparsed.map((line) => `\`${line}\` is not an op, so nothing was applied for it`);
+    const current = readPlanSnapshot(deckDir).raw ?? '';
+    const result = ops.length > 0 ? applyPlanOps(current, ops, sources) : undefined;
+    notices.push(...(result?.notices ?? []));
+    for (const notice of notices)
+        console.error(`[router] plan fence: ${notice}`);
+    session.notices = notices.slice(0, PLAN_NOTICE_LIMIT);
+    if (!result || result.applied === 0)
+        return result ? 'unchanged' : 'dropped';
+    const text = `${result.text}\n`;
+    if (text === current)
+        return 'unchanged';
+    try {
+        fs.writeFileSync(path.join(deckDir, PLAN_FILE), text);
+        return 'written';
+    }
+    catch (err) {
+        console.error(`[router] could not write ${PLAN_FILE}: ${err instanceof Error ? err.message : String(err)}`);
+        return 'dropped';
+    }
+}
+// What a taste op's quote is checked against. The WHOLE message store, not the
+// 40-message window the router was shown: the check is one substring test per
+// message, and being permissive costs nothing here -- in practice the router
+// quotes what is in front of it. Task reports reach back the same way, since a
+// finished task's record outlives both its nomination and its board row. A user
+// statement so old it has left the store is a memory the router can no longer
+// evidence, and asking to confirm it is the right end of that.
+//
+// A task's quotable text is every field of it the ROUTER IS SHOWN -- the same
+// notes and failure reason asPromptTask puts on the board row, not only the
+// `durable:` nomination. Measured 26-08-15: with the nomination alone, 2 of 10
+// taste ops in a t1 run were routed away for quoting a failed task's error line
+// byte-for-byte out of the prompt in front of them. A check that rejects a
+// verbatim quote of its own prompt teaches the router to stop quoting.
+function planOpSources(taskStore, messages) {
+    const taskReports = new Map();
+    for (const task of taskStore.sorted()) {
+        const row = asPromptTask(task);
+        const text = [task.durable, row.error, row.notes].filter((s) => s?.trim()).join('\n');
+        if (text)
+            taskReports.set(task.id, text);
+    }
+    return {
+        taskReports,
+        userMessages: messages.filter((m) => m.role === 'user').map((m) => m.text),
+    };
+}
+// What the router's next turn is told about the plan, or undefined when the
+// deck has it switched off -- see RouterPlanOpts. Reading the notices clears
+// them: they are one-shots about a fence the router has since been shown the
+// result of.
+function routerPlanOpts(deckDir, snapshot, nominations, tasks) {
+    const session = planSession(deckDir);
+    if (!session.enabled)
+        return undefined;
+    const notices = [...session.notices, ...session.asyncNotices].slice(0, PLAN_NOTICE_LIMIT);
+    session.notices = [];
+    session.asyncNotices = [];
+    return {
+        fileText: snapshot.text,
+        pendingDurables: nominations.map((t) => ({
+            taskId: t.id,
+            taskTitle: t.title,
+            text: t.durable ?? '',
+        })),
+        finishedWork: planFinishedWork(tasks),
+        notices,
     };
 }
+// The agenda nudge. A reply that spawned work, asked nothing (no probe chips,
+// no question mark), while `## Open questions` holds a standing line, is a
+// quiet build turn; the second in a row queues a notice naming the top line.
+// Counting quiet turns and naming the line is exactly what five wordings of a
+// prompt rule could not get the router to do for itself (0 across 14 samples,
+// 26-08-18) and what the notice-shaped close rule showed it does do when told.
+function trackStandingQuestions(ctx, cleaned, spawnedWork) {
+    const session = planSession(ctx.deckDir);
+    if (!session.enabled)
+        return;
+    const askedSomething = /\[\[[^\]\n]+\]\]/.test(cleaned) || cleaned.includes('?');
+    if (askedSomething || !spawnedWork) {
+        session.quietBuildTurns = 0;
+        return;
+    }
+    const standing = planOpenQuestionLines(readPlanSnapshot(ctx.deckDir).raw ?? '');
+    if (standing.length === 0) {
+        session.quietBuildTurns = 0;
+        return;
+    }
+    session.quietBuildTurns += 1;
+    if (session.quietBuildTurns < 2)
+        return;
+    session.quietBuildTurns = 0;
+    session.asyncNotices.push(`the plan's top open question has now sat through two build turns with nothing asked -- this is the turn to ask it, in its own words, while work spawns anyway: ${standing[0]}`);
+}
+function taskPlanOpts(deckDir, item, finishedWork) {
+    if (!planSession(deckDir).enabled)
+        return undefined;
+    return { fileText: readPlanSnapshot(deckDir).text, item, finishedWork };
+}
 // 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,
@@ -1898,6 +2086,58 @@ async function runAgentTurn(opts) {
 function persistTaskFile(tasksDir, task) {
     fs.writeFileSync(path.join(tasksDir, task.id, 'task.json'), JSON.stringify(task, null, 2) + '\n');
 }
+// The task index: one row per task this deck has ever spawned, addressed by the
+// plan item it advanced. It is the complete address book (step 2 searches it by
+// item label to find the handoffs worth reading) and, filtered to running rows,
+// the live claims board.
+//
+// Runtime-exclusive -- unlike plan.md, which has two writers, this has exactly
+// one, which is why the claim data lives here rather than in the plan. It is
+// written whether or not the deck has the plan doc switched on: it is a disk
+// receipt, never injected into a prompt, so it costs an off deck nothing.
+const TASK_INDEX_FILE = 'index.md';
+const TASK_INDEX_HEADER = '# tasks\n# <task-id> | <item> | <title> | <created> | <status> | <touching>\n';
+// A pipe-delimited row can't carry a pipe. Titles come from the router's fence
+// and can hold anything.
+function indexCell(value) {
+    return value.replace(/\|/g, '/').replace(/\s+/g, ' ').trim();
+}
+function taskIndexLine(task) {
+    return [
+        task.id,
+        indexCell(task.item ?? '-') || '-',
+        indexCell(task.title),
+        task.createdAt.slice(0, 10),
+        task.status,
+        // `touching` is in the grammar from the start though nothing writes it
+        // until claims land (step 1.5), so today's index still parses then.
+        '',
+    ].join(' | ');
+}
+function writeTaskIndex(tasksDir, tasks) {
+    const rows = [...tasks.values()]
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
+        .map(taskIndexLine);
+    const body = `${TASK_INDEX_HEADER}${rows.join('\n')}${rows.length > 0 ? '\n' : ''}`;
+    const file = path.join(tasksDir, TASK_INDEX_FILE);
+    try {
+        if (fs.readFileSync(file, 'utf8') === body)
+            return;
+    }
+    catch {
+        /* no index yet -- writing it below is the change */
+    }
+    const tmp = `${file}.tmp`;
+    try {
+        // Written aside and renamed: a running task agent may be reading this file
+        // at any moment, and a torn read is a claims board with rows missing.
+        fs.writeFileSync(tmp, body);
+        fs.renameSync(tmp, file);
+    }
+    catch (err) {
+        console.error(`[tasks] could not write ${TASK_INDEX_FILE}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 // 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
@@ -1917,8 +2157,84 @@ function loadTasks(tasksDir) {
     }
     return tasks;
 }
+// A handoff line is one fact, and a long one is a summary rather than the
+// single fact the prompt asks for.
+const HANDOFF_MAX_CHARS = 200;
+const HANDOFF_MAX_LIST = 8;
+// One field of the handoff file -- the FIRST line carrying it, since the prompt
+// asks for one of each and a task that wrote several has already missed the
+// point.
+function handoffField(handoff, field) {
+    const match = new RegExp(`^${field}:\\s*(.+)$`, 'i');
+    for (const line of handoff.split('\n')) {
+        const found = match.exec(line.trim());
+        if (found)
+            return found[1].trim().slice(0, HANDOFF_MAX_CHARS);
+    }
+    return undefined;
+}
+function handoffList(handoff, field) {
+    const items = (handoffField(handoff, field) ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .slice(0, HANDOFF_MAX_LIST);
+    return items.length > 0 ? items : undefined;
+}
+// Pull the handoff file into the record. `durable:` additionally goes PENDING
+// on arrival -- it is a proposal the router has to answer -- while the others
+// are just facts the digest derives `## Built` from.
+function refreshHandoff(dir, task) {
+    let handoff;
+    try {
+        handoff = fs.readFileSync(path.join(dir, 'handoff'), 'utf8');
+    }
+    catch {
+        return false;
+    }
+    let changed = false;
+    const durable = handoffField(handoff, 'durable');
+    if (durable && durable !== task.durable) {
+        task.durable = durable;
+        task.durablePending = true;
+        changed = true;
+    }
+    const what = handoffField(handoff, 'what');
+    if (what && what !== task.what) {
+        task.what = what;
+        changed = true;
+    }
+    for (const field of ['files', 'knobs']) {
+        const list = handoffList(handoff, field);
+        if (list && list.join(', ') !== (task[field] ?? []).join(', ')) {
+            task[field] = list;
+            changed = true;
+        }
+    }
+    return changed;
+}
+// What the plan's derived `## Built` is made of: the work of tasks that
+// actually finished, addressed by the plan item they advanced. A task that
+// belongs to no item, failed, or never wrote a `what:` line has nothing to
+// contribute -- the section is what EXISTS, not what was attempted.
+function planFinishedWork(tasks) {
+    const work = [];
+    for (const task of tasks) {
+        if (task.status !== 'done' || !task.item || task.item === '-' || !task.what)
+            continue;
+        work.push({
+            item: task.item,
+            what: task.what,
+            files: task.files,
+            knobs: task.knobs,
+            at: task.finishedAt ?? task.updatedAt,
+        });
+    }
+    return work;
+}
 // Task agents report through plain files: an integer in `progress`, free
-// text in `notes.md`. Pull both into the record; true when anything changed.
+// text in `notes.md`, and a `handoff` file of one-line facts. Pull them into
+// the record; true when anything changed.
 function refreshTaskFiles(tasksDir, task) {
     const dir = path.join(tasksDir, task.id);
     let changed = false;
@@ -1943,6 +2259,8 @@ function refreshTaskFiles(tasksDir, task) {
     catch {
         /* no notes file yet */
     }
+    if (refreshHandoff(dir, task))
+        changed = true;
     return changed;
 }
 // "after:" entries may reference task ids or titles -- including titles of
@@ -2050,6 +2368,7 @@ async function runTaskAgentIn(ctx, task) {
         prompt: task.prompt,
         progressPath: path.join(relDir, 'progress'),
         notesPath: path.join(relDir, 'notes.md'),
+        handoffPath: path.join(relDir, 'handoff'),
         depsSummary: ctx.depsSummary,
         backend: ctx.backend,
         // Slimmed once contents are inlined -- see DECK_TREE_SLIM_* above.
@@ -2058,6 +2377,7 @@ async function runTaskAgentIn(ctx, task) {
             : undefined),
         deckContents,
         quickReference: ctx.quickReference,
+        plan: taskPlanOpts(ctx.deckDir, task.item, ctx.finishedWork),
         siblings: ctx.siblings,
     });
     // No /goal wrapper: it makes a fresh evaluator re-check the WHOLE task
@@ -2196,6 +2516,9 @@ function startTask(ctx, task) {
             .sorted()
             .filter((t) => t.id !== task.id && !(t.acknowledged && isTerminal(t.status)))
             .map((t) => ({ title: t.title, status: t.status })),
+        // Not filtered to the live board like the siblings above: a task the user
+        // has already checked off is exactly the work most likely to be rebuilt.
+        finishedWork: planFinishedWork(ctx.sorted()),
         onFeed: (entry) => ctx.onFeed(task, entry),
         onRetry: (attempt) => ctx.onRetry(task, attempt),
         onSignal: (signal) => {
@@ -2323,6 +2646,9 @@ function haltTask(task, children, stopRequested, touch) {
 function createTaskStore(opts) {
     const { deckDir, deckLabel, tasksDir, children } = opts;
     const tasks = loadTasks(tasksDir);
+    // Covers both a deck whose tasks predate the index and the interrupted-status
+    // rewrites loadTasks just did.
+    writeTaskIndex(tasksDir, tasks);
     // Tasks the router asked to stop: their killed process must not read as a
     // crash (no retry) and they finalize as interrupted, not failed.
     const stopRequested = new Set();
@@ -2332,6 +2658,7 @@ function createTaskStore(opts) {
     function touch(task) {
         task.updatedAt = nowIso();
         persistTaskFile(tasksDir, task);
+        writeTaskIndex(tasksDir, tasks);
         opts.onUpdate(task);
     }
     function runningCount() {
@@ -2404,6 +2731,7 @@ function createTaskStore(opts) {
             title: directive.title,
             prompt: directive.prompt,
             after: resolveDeps(tasks, directive.after),
+            item: directive.item,
             status: 'waiting',
             progress: 0,
             notes: '',
@@ -2414,6 +2742,7 @@ function createTaskStore(opts) {
         fs.mkdirSync(path.join(tasksDir, task.id), { recursive: true });
         tasks.set(task.id, task);
         persistTaskFile(tasksDir, task);
+        writeTaskIndex(tasksDir, tasks);
         opts.onUpdate(task);
         maybeStart(task);
         return task.id;
@@ -2428,6 +2757,21 @@ function createTaskStore(opts) {
         touch(task);
         return task;
     }
+    function pendingDurables() {
+        return sorted().filter((t) => t.durablePending && t.durable);
+    }
+    // Every pending nomination clears on the next fence, promoted or not: the
+    // router saw them all and made one pass of taste over them, and re-offering
+    // the ones it passed over would just relitigate the same call every turn.
+    // Lossy by design -- the handoff files on disk stay the record.
+    function clearPendingDurables() {
+        for (const task of tasks.values()) {
+            if (!task.durablePending)
+                continue;
+            task.durablePending = false;
+            persistTaskFile(tasksDir, task);
+        }
+    }
     const pollTimer = setInterval(() => {
         for (const task of tasks.values()) {
             if (task.status !== 'running')
@@ -2445,6 +2789,7 @@ function createTaskStore(opts) {
                 persistTaskFile(tasksDir, task);
             }
         }
+        writeTaskIndex(tasksDir, tasks);
     }
     // True when a fence body is the special token "all" / "*" (clear/stop
     // everything, no per-task enumeration).
@@ -2484,6 +2829,8 @@ function createTaskStore(opts) {
         acknowledge,
         checkOff,
         stop,
+        pendingDurables,
+        clearPendingDurables,
         shutdown,
     };
 }
@@ -2579,6 +2926,7 @@ function asPromptTask(task) {
         status: task.rejected ? 'rejected by user' : task.status,
         progress: task.progress,
         notes: task.notes,
+        item: task.item,
         error: task.status === 'failed' ? firstErrorLine(task.resultSummary) : undefined,
         blockedBy: task.status === 'blocked' ? task.blockedBy : undefined,
     };
@@ -2747,7 +3095,7 @@ function resolveFailure(result) {
 // 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) {
+function routerTurnPrompt(ctx, instruction, selfMessageId, plan) {
     // Smith-only, smaller budget than a task's -- see TASK_DECK_CONTENTS_BUDGET/
     // ROUTER_DECK_CONTENTS_BUDGET's comment (the router prompt is already the
     // largest one this serve builds).
@@ -2775,6 +3123,7 @@ function routerTurnPrompt(ctx, instruction, selfMessageId) {
             .sorted()
             .filter((t) => !(t.acknowledged && isTerminal(t.status)))
             .map(asPromptTask),
+        plan: routerPlanOpts(ctx.deckDir, plan, ctx.taskStore.pendingDurables(), ctx.taskStore.sorted()),
         instruction,
     });
 }
@@ -2881,7 +3230,7 @@ function runRouterTurnIn(ctx, instruction, attachments = []) {
     // 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 prompt = routerTurnPrompt(ctx, instruction, message.id, readPlanSnapshot(ctx.deckDir));
     const backend = ctx.backend();
     void runAgentTurn({
         backend,
@@ -2939,11 +3288,24 @@ function runRouterTurnIn(ctx, instruction, attachments = []) {
                 settleInterruptedTurn(ctx, message);
                 return;
             }
-            const { cleaned, directives, checkoffs, stops } = extractDirectives(result.finalText);
+            const { cleaned, directives, checkoffs, stops, plan } = extractDirectives(result.finalText);
             if (result.ok && checkoffs.length > 0)
                 ctx.taskStore.checkOff(checkoffs);
             if (result.ok && stops.length > 0)
                 ctx.taskStore.stop(stops);
+            // Settle-time only, unlike task fences: nothing is waiting on the file,
+            // and a half-streamed op line is a line that says something else.
+            if (result.ok && plan) {
+                const written = applyPlanFence(ctx.deckDir, plan, planOpSources(ctx.taskStore, ctx.log.messages));
+                if (written === 'written')
+                    message.planUpdated = true;
+                // Any fence that became ops is the router's answer to the pending
+                // nominations, including one whose ops all no-oped -- it looked and
+                // passed. A fence that never parsed decided nothing, so they stay
+                // pending for the turn that redoes it.
+                if (written !== 'dropped')
+                    ctx.taskStore.clearPendingDurables();
+            }
             // 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 --
@@ -2963,6 +3325,7 @@ function runRouterTurnIn(ctx, instruction, attachments = []) {
             if (result.ok) {
                 message.text = cleaned;
                 message.status = 'done';
+                trackStandingQuestions(ctx, cleaned, taskIds.length > 0);
             }
             else {
                 const failure = resolveFailure(result);
@@ -3003,6 +3366,7 @@ function runRouterTurnIn(ctx, instruction, attachments = []) {
                 status: message.status,
                 taskIds: message.taskIds ?? [],
                 errorDetail: message.errorDetail,
+                planUpdated: message.planUpdated,
                 // Broadcast-only, never persisted: the client console.errors this so
                 // the whole provider response is inspectable without leaving the
                 // browser. Keeping it out of MessageRecord is the same call
@@ -3598,6 +3962,9 @@ export function createAgentServer(opts) {
     const attachmentsDir = path.join(agentDir, 'attachments');
     const messagesPath = path.join(agentDir, 'messages.json');
     fs.mkdirSync(tasksDir, { recursive: true });
+    // Read the plan opt-out now so the whole serve shares one answer -- see
+    // planSession.
+    planSession(deckDir);
     // Warm the OpenRouter catalog now so the first pre-flight and the first
     // popover open read a cache instead of paying for the fetch. Fire-and-forget
     // by design -- nothing here depends on it, and it falls open if it fails.

package/dist/castleJson.d.ts

@@ -11,6 +11,9 @@ export interface CastleJson {
     imports?: Record<string, DeckImport>;
     autoUpdateWhenImported?: boolean;
     main?: string;
+    agent?: {
+        plan?: 'on' | 'off';
+    };
     starterScene?: string;
     [key: string]: unknown;
 }

package/dist/ide.js

@@ -21,7 +21,7 @@ import { readEditorConfig, resolveFileTypes, } from './editorConfig.js';
 import { UNSUPPORTED_MEDIA } from './unsupportedMedia.js';
 import { IMPORT_API_PREFIX, handleImportApi } from './importBrowse.js';
 import { readRequestBody, sendJson } from './httpJson.js';
-import { COVER_FILE } from './localPaths.js';
+import { COVER_FILE, PLAN_FILE } from './localPaths.js';
 import { applyVersionRestore, createVersion, NotOnThisLine, pendingChanges, UnsavedChanges, versionSummaries, } from './versions.js';
 import { envForUserShell, installCliShims } from './byo-auth.js';
 const HeadlessTerminal = headlessPkg.Terminal;
@@ -301,6 +301,15 @@ function filterDeckFiles(files, config) {
     }
     return result;
 }
+// The deck's own files, curated. The plan is exempt: it is the platform's file,
+// not one a kit's visiblePaths were written to name, so a curated deck would
+// hide it by omission -- it shows whenever it exists.
+function filterOwnFiles(files, config) {
+    const result = filterDeckFiles(files, config);
+    if (files.includes(PLAN_FILE) && !result.includes(PLAN_FILE))
+        result.push(PLAN_FILE);
+    return result;
+}
 // Filter each import by the editor config of the deck it came from: strip the
 // `imports/<alias>/` prefix so the dependency's own visible/hidden globs match
 // the paths they were written against, then put it back.
@@ -760,7 +769,7 @@ function handleFilesApi(deckDir, req, res, reqPath) {
             // is the deck that knows which of its files are worth showing.
             const own = listed.filter((f) => !isImportPath(f));
             files = [
-                ...filterDeckFiles(own, readEditorConfig(deckDir)),
+                ...filterOwnFiles(own, readEditorConfig(deckDir)),
                 ...filterImportedFiles(deckDir, listed.filter(isImportPath)),
             ].sort((a, b) => a.localeCompare(b));
         }

package/dist/localPaths.d.ts

@@ -4,4 +4,5 @@ export declare function getCliEntryPath(): string;
 export declare function getSdkPackagePath(): string;
 export declare function getKitsDir(): string;
 export declare const COVER_FILE = "preview.png";
+export declare const PLAN_FILE = "plan.md";
 export declare function toPosixPath(filepath: string): string;