castle-web-cli 0.4.26 → 0.4.28

package/dist/agent-prompts.js

@@ -13,7 +13,7 @@ What a deck is: a normal web project served by vite -- index.html plus plain JS/
 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.
-- ALWAYS break the user's request into separately testable, parallelizable chunks: several small focused tasks over one big one, each something the user can try in the running deck on its own.
+- Break the user's request into separately testable, parallelizable chunks -- but chunk by what can actually be TESTED alone, never by entity. Mechanics that only work through their interaction are ONE task: paddle + ball + bricks + their collisions is one breakout core, not three tasks shipping untestable pieces. Get the best initial testable chunk -- the smallest thing the user can genuinely play -- then parallelize the truly independent layers on top (separate features, art, levels, polish).
 - Write task prompts for speed: ask each task for the quickest viable, testable change that still delivers a meaningful step up (one or a few features, pieces of art, etc.). Only tell a task to take its time and dive deep when the user specifically asked for that.
 - To spawn a background task, include a fenced block in your reply:
 
@@ -34,6 +34,13 @@ comma-separated titles or ids of the finished tasks
 \`\`\`
 
 - NEVER check a task off on your own judgment -- only a clear user statement that it works (or an explicit ask to clear it) counts. When in doubt, leave the row on the board.
+- To STOP tasks (running or waiting) when the user asks or their work is clearly no longer wanted, include:
+
+\`\`\`castle-stop
+comma-separated titles or ids of the tasks to stop
+\`\`\`
+
+Stopped tasks show as interrupted on the board. If a new task replaces the stopped work, prefer \`supersedes:\` on the new task instead.
 - Tasks are one-and-done -- when the user gives feedback on a finished task, spawn a new fix task rather than reopening the old one.
 - Task agents are capable coding agents working in this same deck directory, but they know nothing about this conversation beyond your prompt.
 

package/dist/agent.js

@@ -14,7 +14,7 @@
 // Backend CLI: cursor-agent in headless print mode (stream-json). The router
 // runs with --mode ask (read-only at the CLI level); task agents run with
 // --force. Claude support can slot in later behind runAgentCli.
-import { spawn } from 'child_process';
+import { execFileSync, spawn } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { nanoid } from 'nanoid';
@@ -118,15 +118,19 @@ function visibleLength(raw) {
 function extractDirectives(full) {
     const directives = [];
     const checkoffs = [];
-    const doneRe = /```castle-done[ \t]*\r?\n([\s\S]*?)```/g;
-    const withoutDone = full.replace(doneRe, (_match, body) => {
-        for (const token of String(body).split(/[,\n]/)) {
-            const trimmed = token.trim();
-            if (trimmed)
-                checkoffs.push(trimmed);
-        }
-        return '';
-    });
+    const stops = [];
+    const listFence = (source, name, into) => {
+        const re = new RegExp('```' + name + '[ \\t]*\\r?\\n([\\s\\S]*?)```', 'g');
+        return source.replace(re, (_match, body) => {
+            for (const token of String(body).split(/[,\n]/)) {
+                const trimmed = token.trim();
+                if (trimmed)
+                    into.push(trimmed);
+            }
+            return '';
+        });
+    };
+    const withoutDone = listFence(listFence(full, 'castle-done', checkoffs), 'castle-stop', stops);
     const fenceRe = /```castle-task[ \t]*\r?\n([\s\S]*?)```/g;
     const cleaned = withoutDone.replace(fenceRe, (_match, body) => {
         const lines = String(body).replace(/\r/g, '').split('\n');
@@ -148,7 +152,7 @@ function extractDirectives(full) {
         }
         return '';
     });
-    return { cleaned: cleaned.replace(/\n{3,}/g, '\n\n').trim(), directives, checkoffs };
+    return { cleaned: cleaned.replace(/\n{3,}/g, '\n\n').trim(), directives, checkoffs, stops };
 }
 // Claude names tools directly (Read, Edit, Bash, ...).
 function claudeToolActivityLabel(name) {
@@ -413,9 +417,68 @@ function depsSummaryFor(tasks, task) {
         .map((dep) => `- "${dep.title}" finished ${dep.status}${dep.notes.trim() ? `; notes: ${dep.notes.trim()}` : ''}`);
     return lines.join('\n') || undefined;
 }
+async function runTaskAgentIn(ctx, task) {
+    const dir = path.join(ctx.tasksDir, task.id);
+    const relDir = path.relative(ctx.deckDir, dir);
+    const taskPrompt = buildTaskPrompt({
+        deckLabel: ctx.deckLabel,
+        taskId: task.id,
+        title: task.title,
+        prompt: task.prompt,
+        progressPath: path.join(relDir, 'progress'),
+        notesPath: path.join(relDir, 'notes.md'),
+        depsSummary: ctx.depsSummary,
+    });
+    // Claude task runs get /goal (claude code's built-in commit-to-completion
+    // command) plus the system-prompt autonomy reminder.
+    const invocation = buildAgentInvocation(ctx.backend, 'task', ctx.backend === 'claude' ? `/goal ${taskPrompt}` : taskPrompt, ctx.claudeModel);
+    let result = { ok: false, finalText: '', error: 'not run' };
+    let lineBuf = '';
+    const flushFeedLines = (delta) => {
+        lineBuf += delta;
+        let nl = lineBuf.indexOf('\n');
+        while (nl >= 0) {
+            const line = lineBuf.slice(0, nl).trim();
+            lineBuf = lineBuf.slice(nl + 1);
+            if (line)
+                ctx.onFeed(line);
+            nl = lineBuf.indexOf('\n');
+        }
+    };
+    for (let attempt = 1; attempt <= MAX_TASK_ATTEMPTS; attempt++) {
+        result = await runAgentCli({
+            cwd: ctx.deckDir,
+            command: invocation.command,
+            args: invocation.args,
+            parser: ctx.backend,
+            timeoutMs: TASK_TIMEOUT_MS,
+            logPath: path.join(dir, 'log.jsonl'),
+            children: ctx.children,
+            onSpawn: (pid) => {
+                task.pid = pid;
+            },
+            onDelta: (delta) => flushFeedLines(delta),
+            onActivity: (activity) => {
+                if (activity)
+                    ctx.onFeed(`[${activity}]`);
+            },
+        });
+        if (ctx.stopRequested.has(task.id))
+            return result;
+        if (!result.crashed)
+            return result;
+        if (attempt < MAX_TASK_ATTEMPTS)
+            ctx.onRetry(attempt + 1);
+    }
+    result.error = `agent process kept dying (${MAX_TASK_ATTEMPTS} attempts): ${result.error ?? ''}`;
+    return result;
+}
 function createTaskStore(opts) {
     const { deckDir, deckLabel, tasksDir, children } = opts;
     const tasks = loadTasks(tasksDir);
+    // 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();
     function sorted() {
         return [...tasks.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
     }
@@ -435,62 +498,6 @@ function createTaskStore(opts) {
             return;
         start(task);
     }
-    // Run the task agent, re-running if the process dies mid-task (crash, not
-    // a normal finish). After MAX_TASK_ATTEMPTS dead processes the task fails.
-    async function runTaskAgent(task, dir) {
-        const relDir = path.relative(deckDir, dir);
-        const backend = opts.backend();
-        const taskPrompt = buildTaskPrompt({
-            deckLabel,
-            taskId: task.id,
-            title: task.title,
-            prompt: task.prompt,
-            progressPath: path.join(relDir, 'progress'),
-            notesPath: path.join(relDir, 'notes.md'),
-            depsSummary: depsSummaryFor(tasks, task),
-        });
-        // Claude task runs get /goal (claude code's built-in commit-to-completion
-        // command) plus the system-prompt autonomy reminder.
-        const invocation = buildAgentInvocation(backend, 'task', backend === 'claude' ? `/goal ${taskPrompt}` : taskPrompt, opts.claudeModel());
-        let result = { ok: false, finalText: '', error: 'not run' };
-        let lineBuf = '';
-        const flushFeedLines = (delta) => {
-            lineBuf += delta;
-            let nl = lineBuf.indexOf('\n');
-            while (nl >= 0) {
-                const line = lineBuf.slice(0, nl).trim();
-                lineBuf = lineBuf.slice(nl + 1);
-                if (line)
-                    opts.onFeed(task, line);
-                nl = lineBuf.indexOf('\n');
-            }
-        };
-        for (let attempt = 1; attempt <= MAX_TASK_ATTEMPTS; attempt++) {
-            result = await runAgentCli({
-                cwd: deckDir,
-                command: invocation.command,
-                args: invocation.args,
-                parser: backend,
-                timeoutMs: TASK_TIMEOUT_MS,
-                logPath: path.join(dir, 'log.jsonl'),
-                children,
-                onSpawn: (pid) => {
-                    task.pid = pid;
-                },
-                onDelta: (delta) => flushFeedLines(delta),
-                onActivity: (activity) => {
-                    if (activity)
-                        opts.onFeed(task, `[${activity}]`);
-                },
-            });
-            if (!result.crashed)
-                return result;
-            if (attempt < MAX_TASK_ATTEMPTS)
-                opts.onRetry(task, attempt + 1);
-        }
-        result.error = `agent process kept dying (${MAX_TASK_ATTEMPTS} attempts): ${result.error ?? ''}`;
-        return result;
-    }
     function start(task) {
         const dir = path.join(tasksDir, task.id);
         fs.writeFileSync(path.join(dir, 'progress'), '0\n');
@@ -500,15 +507,30 @@ function createTaskStore(opts) {
         task.startedAt = nowIso();
         touch(task);
         opts.onStarted(task);
-        void runTaskAgent(task, dir).then((result) => {
+        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);
-            task.status = result.ok ? 'done' : 'failed';
-            if (result.ok)
+            const wasStopped = stopRequested.delete(task.id);
+            task.status = wasStopped ? 'interrupted' : result.ok ? 'done' : 'failed';
+            if (result.ok && !wasStopped)
                 task.progress = 100;
             task.finishedAt = nowIso();
-            task.resultSummary = result.ok
-                ? result.finalText.slice(-RESULT_SUMMARY_CHARS)
-                : `${result.error ?? 'failed'}\n${result.finalText.slice(-RESULT_SUMMARY_CHARS)}`;
+            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);
             for (const waiting of tasks.values())
@@ -580,7 +602,34 @@ function createTaskStore(opts) {
         for (const id of resolveDeps(tasks, tokens))
             acknowledge(id, false);
     }
-    return { sorted, get: (id) => tasks.get(id), spawnFromDirective, acknowledge, checkOff, shutdown };
+    // The router stops tasks by title or id (castle-stop fence). Waiting tasks
+    // are cancelled outright; running ones get their agent process killed and
+    // finalize as interrupted via the stopRequested path.
+    function stop(tokens) {
+        for (const id of resolveDeps(tasks, tokens)) {
+            const task = tasks.get(id);
+            if (!task)
+                continue;
+            if (task.status === 'waiting') {
+                task.status = 'interrupted';
+                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 */
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return { sorted, get: (id) => tasks.get(id), spawnFromDirective, acknowledge, checkOff, stop, shutdown };
 }
 // -- attachments ----------------------------------------------------------------
 const ATTACHMENT_MIME = {
@@ -756,9 +805,11 @@ function runRouterTurnIn(ctx, instruction) {
             });
             return;
         }
-        const { cleaned, directives, checkoffs } = extractDirectives(result.finalText);
+        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();
@@ -805,6 +856,62 @@ function applyAgentSettings(incoming, ctx) {
     fs.writeFileSync(ctx.settingsPath, JSON.stringify(settings, null, 2) + '\n');
     ctx.broadcast({ type: 'settings', settings });
 }
+function killOrphanAgents(registryPath) {
+    const recorded = readJsonFile(registryPath) ?? [];
+    for (const entry of recorded) {
+        if (typeof entry?.pid !== 'number')
+            continue;
+        try {
+            const cmd = execFileSync('ps', ['-p', String(entry.pid), '-o', 'command='], {
+                encoding: 'utf8',
+            }).trim();
+            if (cmd.includes('cursor-agent') || cmd.includes('claude')) {
+                process.kill(entry.pid, 'SIGKILL');
+            }
+        }
+        catch {
+            /* pid not running anymore */
+        }
+    }
+    try {
+        fs.writeFileSync(registryPath, '[]\n');
+    }
+    catch {
+        /* registry dir missing -- created later */
+    }
+}
+function startChildRegistry(registryPath, groups) {
+    let last = '';
+    const timer = setInterval(() => {
+        const live = [];
+        for (const group of groups) {
+            for (const child of group) {
+                if (typeof child.pid === 'number' && child.exitCode === null) {
+                    live.push({ pid: child.pid, command: child.spawnfile });
+                }
+            }
+        }
+        const snapshot = JSON.stringify(live);
+        if (snapshot === last)
+            return;
+        last = snapshot;
+        try {
+            fs.writeFileSync(registryPath, snapshot + '\n');
+        }
+        catch {
+            /* best effort */
+        }
+    }, 2_000);
+    return () => {
+        clearInterval(timer);
+        try {
+            fs.writeFileSync(registryPath, '[]\n');
+        }
+        catch {
+            /* best effort */
+        }
+    };
+}
 export function createAgentServer(opts) {
     const { deckDir, deckLabel } = opts;
     const agentDir = path.join(deckDir, '.castle', 'agent');
@@ -815,6 +922,11 @@ export function createAgentServer(opts) {
     const taskChildren = new Set();
     const routerChildren = new Set();
     const clients = new Set();
+    // Kill agent processes orphaned by a previous serve that died uncleanly,
+    // then start tracking this serve's own children.
+    const childRegistryPath = path.join(agentDir, 'children.json');
+    killOrphanAgents(childRegistryPath);
+    const stopChildRegistry = startChildRegistry(childRegistryPath, [taskChildren, routerChildren]);
     function broadcast(body) {
         const payload = JSON.stringify(body);
         for (const socket of clients) {
@@ -955,6 +1067,7 @@ export function createAgentServer(opts) {
                 /* already gone */
             }
         }
+        stopChildRegistry();
         wss.close();
     }
     return { handleUpgrade, handleHttpRequest, shutdown };

package/dist/serve.js

@@ -170,6 +170,9 @@ export async function serve(dir, options = {}) {
     });
     process.on('SIGINT', () => process.exit());
     process.on('SIGTERM', () => process.exit());
+    // Terminal close: exit through the handlers so child agent processes die
+    // with the serve instead of orphaning.
+    process.on('SIGHUP', () => process.exit());
     // The WS server forwards `restart` to the browser, but it also needs the
     // Vite instance so it can drop transform caches first (see invalidateModuleCaches).
     const viteHolder = { vite: null };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"