runcastle 1.0.22 → 1.0.24

package/bin/runcastle.js

@@ -105,10 +105,14 @@ var init_config = __esm(() => {
     mainBranch: z.string().default("main"),
     sandboxImage: z.string().optional(),
     burnConcurrency: z.number().int().min(1).max(8).default(3),
+    burnCpus: z.number().positive().max(256).optional(),
+    burnGuard: z.boolean().default(true),
     burnMaxIterations: z.number().int().min(1).max(10).default(3),
     burnAttempts: z.number().int().min(1).max(5).default(3),
     burnConflictAttempts: z.number().int().min(0).max(3).default(2),
     setupCommand: z.string().optional(),
+    verifyCommands: z.string().optional(),
+    knownFailures: z.string().optional(),
     burnWorkspace: z.enum(["auto", "mounted", "isolated"]).default("auto")
   }));
 });
@@ -154,8 +158,17 @@ function loadConfig(env = process.env) {
   if (env.RUNCASTLE_BURN_CONFLICT_ATTEMPTS !== undefined) {
     overrides.burnConflictAttempts = Number(env.RUNCASTLE_BURN_CONFLICT_ATTEMPTS);
   }
+  if (env.RUNCASTLE_BURN_CPUS)
+    overrides.burnCpus = Number(env.RUNCASTLE_BURN_CPUS);
+  if (env.RUNCASTLE_BURN_GUARD !== undefined) {
+    overrides.burnGuard = env.RUNCASTLE_BURN_GUARD !== "0" && env.RUNCASTLE_BURN_GUARD !== "false";
+  }
   if (env.RUNCASTLE_SETUP_COMMAND)
     overrides.setupCommand = env.RUNCASTLE_SETUP_COMMAND;
+  if (env.RUNCASTLE_VERIFY_COMMANDS)
+    overrides.verifyCommands = env.RUNCASTLE_VERIFY_COMMANDS;
+  if (env.RUNCASTLE_KNOWN_FAILURES)
+    overrides.knownFailures = env.RUNCASTLE_KNOWN_FAILURES;
   if (env.RUNCASTLE_BURN_WORKSPACE)
     overrides.burnWorkspace = env.RUNCASTLE_BURN_WORKSPACE;
   const base = typeof fileConfig === "object" && fileConfig !== null ? fileConfig : {};
@@ -660,6 +673,72 @@ var init_migrate = __esm(() => {
 // src/util/resolve-executable.ts
 import { existsSync as existsSync3 } from "fs";
 import { win32, posix } from "path";
+function wellKnownBinDirs(opts = {}) {
+  const env = opts.env ?? process.env;
+  const isWin = (opts.platform ?? process.platform) === "win32";
+  const dirs = [];
+  if (isWin) {
+    const home2 = env.USERPROFILE;
+    if (home2) {
+      dirs.push(win32.join(home2, ".local", "bin"), win32.join(home2, ".bun", "bin"));
+    }
+    if (env.APPDATA)
+      dirs.push(win32.join(env.APPDATA, "npm"));
+    if (env.LOCALAPPDATA)
+      dirs.push(win32.join(env.LOCALAPPDATA, "Programs", "claude"));
+    return dirs;
+  }
+  const home = env.HOME;
+  if (home) {
+    dirs.push(posix.join(home, ".local", "bin"), posix.join(home, ".bun", "bin"), posix.join(home, ".npm-global", "bin"));
+  }
+  dirs.push("/usr/local/bin", "/opt/homebrew/bin");
+  return dirs;
+}
+function resolveTool(name, opts = {}) {
+  const env = opts.env ?? process.env;
+  const overrideKey = BIN_OVERRIDE_ENV[name];
+  const override = opts.override ?? (overrideKey ? env[overrideKey] : undefined);
+  const extraDirs = opts.extraDirs ?? wellKnownBinDirs({ ...opts.platform ? { platform: opts.platform } : {}, env });
+  return resolveExecutable(name, { ...opts, extraDirs, ...override ? { override } : {} });
+}
+function spawnTargetFor(resolved, args) {
+  if (/\.(cmd|bat)$/i.test(resolved)) {
+    return { file: process.env.ComSpec ?? "cmd.exe", args: ["/c", resolved, ...args] };
+  }
+  if (/\.ps1$/i.test(resolved)) {
+    return {
+      file: "powershell.exe",
+      args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", resolved, ...args]
+    };
+  }
+  return { file: resolved, args };
+}
+function resolveSpawnTarget(name, args) {
+  return spawnTargetFor(resolveTool(name), args);
+}
+function isBareName(cmd) {
+  return !cmd.includes("/") && !cmd.includes("\\");
+}
+function explainSpawnFailure(cmd, raw) {
+  const detail = raw.trim();
+  if (!isBareName(cmd)) {
+    return `Could not launch ${cmd}${detail ? ` \u2014 ${detail}` : ""}`;
+  }
+  const overrideKey = BIN_OVERRIDE_ENV[cmd];
+  const lines = [
+    `Could not launch \`${cmd}\`: not on the PATH this runcastle server inherited, nor in the usual install locations (~/.local/bin, npm global, ~/.bun/bin).`,
+    `A terminal where \`${cmd}\` works does not prove the server can see it: the server's PATH was captured when it started.`,
+    `Fix: quit runcastle and start it again from a terminal where \`${cmd} --version\` works.`
+  ];
+  if (overrideKey) {
+    lines.push(`If that fails, set ${overrideKey} to the full path (\`where.exe ${cmd}\` / \`which ${cmd}\`) and restart.`);
+  }
+  if (detail)
+    lines.push(`(underlying error: ${detail})`);
+  return lines.join(`
+`);
+}
 function resolveExecutable(name, opts = {}) {
   const exists = opts.exists ?? existsSync3;
   if (opts.override && exists(opts.override))
@@ -667,22 +746,28 @@ function resolveExecutable(name, opts = {}) {
   const isWin = (opts.platform ?? process.platform) === "win32";
   const exts = opts.exts ?? (isWin ? WIN_EXTS : [""]);
   const pathEnv = opts.pathEnv ?? process.env.PATH ?? "";
-  const dirs = pathEnv.split(isWin ? ";" : ":");
   const join5 = isWin ? win32.join : posix.join;
-  for (const dir of dirs) {
-    if (!dir)
-      continue;
-    for (const ext of exts) {
-      const candidate = join5(dir, `${name}${ext}`);
-      if (exists(candidate))
-        return candidate;
+  const scan = (dirs) => {
+    for (const dir of dirs) {
+      if (!dir)
+        continue;
+      for (const ext of exts) {
+        const candidate = join5(dir, `${name}${ext}`);
+        if (exists(candidate))
+          return candidate;
+      }
     }
-  }
-  return name;
+    return null;
+  };
+  return scan(pathEnv.split(isWin ? ";" : ":")) ?? scan(opts.extraDirs ?? []) ?? name;
 }
-var WIN_EXTS;
+var WIN_EXTS, BIN_OVERRIDE_ENV;
 var init_resolve_executable = __esm(() => {
-  WIN_EXTS = [".exe", ".cmd", ".bat", ""];
+  WIN_EXTS = [".exe", ".cmd", ".bat", ".ps1", ""];
+  BIN_OVERRIDE_ENV = {
+    claude: "RUNCASTLE_CLAUDE_BIN",
+    node: "RUNCASTLE_NODE_BIN"
+  };
 });
 
 // src/pty/pty-sidecar.ts
@@ -699,7 +784,7 @@ function resolveNodeExecutable() {
     return override;
   if (!isBun())
     return process.execPath;
-  return resolveExecutable("node", { exts: process.platform === "win32" ? [".exe", ".cmd", ""] : [""] });
+  return resolveTool("node", { exts: process.platform === "win32" ? [".exe", ".cmd", ""] : [""] });
 }
 function resolveNodePtyEntry() {
   try {
@@ -767,11 +852,17 @@ function createSidecarPtySession(cmd, args, opts) {
         case "exit":
           fireExit(typeof msg.code === "number" ? msg.code : 0, msg.signal ?? undefined);
           break;
-        case "error":
-          process.stderr.write(`[pty-sidecar] host error: ${msg.message ?? "unknown"}
+        case "error": {
+          const why = explainSpawnFailure(cmd, msg.message ?? "unknown");
+          process.stderr.write(`[pty-sidecar] host error: ${why}
 `);
+          emitData(Buffer.from(`\r
+${why.replace(/\n/g, `\r
+`)}\r
+`, "utf8"));
           fireExit(1);
           break;
+        }
       }
     }
   });
@@ -780,8 +871,13 @@ function createSidecarPtySession(cmd, args, opts) {
     process.stderr.write(chunk);
   });
   child.on("error", (err) => {
-    process.stderr.write(`[pty-sidecar] failed to spawn node host: ${err.message}
+    const why = explainSpawnFailure(nodeExe, err.message);
+    process.stderr.write(`[pty-sidecar] failed to spawn node host: ${why}
 `);
+    emitData(Buffer.from(`\r
+${why.replace(/\n/g, `\r
+`)}\r
+`, "utf8"));
     fireExit(1);
   });
   child.on("exit", (code, signal) => {
@@ -916,14 +1012,19 @@ function createPtySession(cmd, args, opts) {
 }
 function createNativePtySession(cmd, args, opts) {
   const pty = loadNodePty();
-  const proc = pty.spawn(cmd, args, {
-    name: "xterm-256color",
-    cols: opts.cols ?? 80,
-    rows: opts.rows ?? 24,
-    cwd: opts.cwd,
-    env: cleanEnv(opts.env),
-    useConpty: opts.useConpty ?? true
-  });
+  let proc;
+  try {
+    proc = pty.spawn(cmd, args, {
+      name: "xterm-256color",
+      cols: opts.cols ?? 80,
+      rows: opts.rows ?? 24,
+      cwd: opts.cwd,
+      env: cleanEnv(opts.env),
+      useConpty: opts.useConpty ?? true
+    });
+  } catch (err) {
+    throw new Error(explainSpawnFailure(cmd, err instanceof Error ? err.message : String(err)));
+  }
   let killed = false;
   proc.onExit(() => {
     killed = true;
@@ -958,6 +1059,7 @@ function createNativePtySession(cmd, args, opts) {
 }
 var cached = null, BACKEND_LOGGED;
 var init_pty = __esm(() => {
+  init_resolve_executable();
   init_pty_sidecar();
   BACKEND_LOGGED = Symbol.for("runcastle.pty.backend.logged");
 });
@@ -1698,7 +1800,7 @@ var init_feature_docs = __esm(() => {
 });
 
 // src/services/tickets.ts
-import { asc as asc3, eq as eq5 } from "drizzle-orm";
+import { and as and5, asc as asc3, eq as eq5 } from "drizzle-orm";
 function rowToTicket(row) {
   return {
     id: row.id,
@@ -1808,6 +1910,19 @@ function cancelTicket(ctx, id, reason) {
   });
   return getTicket(ctx, id);
 }
+function sweepOrphanedBurning(ctx, featureId, reason) {
+  const orphaned = ctx.db.select().from(tickets).where(and5(eq5(tickets.featureId, featureId), eq5(tickets.status, "burning"))).all().map(rowToTicket);
+  for (const t of orphaned) {
+    updateTicket(ctx, t.id, { status: "failed", error: reason });
+    emit(ctx, featureId, {
+      type: "ticket.failed",
+      message: `ticket ${t.seq} failed: ${reason}`,
+      ticketId: t.id,
+      data: { error: reason, orphaned: true }
+    });
+  }
+  return orphaned.map((t) => ({ ...t, status: "failed", error: reason }));
+}
 function updateTicket(ctx, id, patch) {
   const current2 = ctx.db.select().from(tickets).where(eq5(tickets.id, id)).get();
   if (!current2)
@@ -2200,6 +2315,34 @@ function researchBranchName(slug, waypointSeq, unique) {
 function ticketBranchName(slug, ticketSeq, unique) {
   return `${TICKET_BRANCH_PREFIX}${tempBranchSlugSegment(slug)}/${ticketSeq}-${unique}`;
 }
+function burnWorktreePath(repoPath, branch) {
+  return join6(repoPath, ".sandcastle", "worktrees", branch.replace(/\//g, "-"));
+}
+async function cleanupBurnWorktree(repoPath, branch, opts = {}) {
+  const path = burnWorktreePath(repoPath, branch);
+  const attempts = Math.max(1, opts.attempts ?? 3);
+  const delayMs = opts.delayMs ?? 750;
+  const g = git(repoPath);
+  for (let attempt = 1;attempt <= attempts && existsSync7(path); attempt++) {
+    try {
+      await g.raw(["worktree", "remove", "--force", path]);
+    } catch {}
+    if (existsSync7(path) && attempt < attempts)
+      await sleep(delayMs);
+  }
+  if (existsSync7(path)) {
+    try {
+      rmSync(path, { recursive: true, force: true });
+    } catch {}
+  }
+  try {
+    await g.raw(["worktree", "prune"]);
+  } catch {}
+  return !existsSync7(path);
+}
+function sleep(ms) {
+  return new Promise((done) => setTimeout(done, ms));
+}
 async function branchCommitsAhead(repoPath, base, branch) {
   try {
     const out = await git(repoPath).raw(["rev-list", "--reverse", `${base}..${branch}`]);
@@ -2786,6 +2929,89 @@ var init_agent_stream = __esm(() => {
   transcripts = new Map;
 });
 
+// src/workflows/burn-guard.ts
+function renderGuardScript(rules = GUARD_RULES) {
+  const lines = [
+    "#!/bin/sh",
+    "# runcastle burn guard (PreToolUse). Generated \u2014 edit burn-guard.ts, not this.",
+    "set -u",
+    "payload=$(cat 2>/dev/null || true)",
+    '[ -n "$payload" ] || exit 0',
+    "command -v jq >/dev/null 2>&1 || exit 0",
+    'tool=$(printf %s "$payload" | jq -r ".tool_name // empty" 2>/dev/null || true)',
+    '[ "$tool" = "Bash" ] || exit 0',
+    'cmd=$(printf %s "$payload" | jq -r ".tool_input.command // empty" 2>/dev/null || true)',
+    '[ -n "$cmd" ] || exit 0',
+    "",
+    "# Match against the command with quoted spans blanked, so an argument is",
+    '# never read as a command: `grep -rn "git stash" docs/` searches for a',
+    "# string, it does not run one.",
+    `cmd=$(printf %s "$cmd" | sed "s/'[^']*'/ /g; s/\\"[^\\"]*\\"/ /g")`,
+    "",
+    "deny() {",
+    `  printf %s "$1" | jq -R -s '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:.}}'`,
+    "  exit 0",
+    "}",
+    ""
+  ];
+  for (const rule of rules) {
+    lines.push(`# ${rule.id}`, `if printf %s "$cmd" | grep -Eq -- ${shSingleQuote(rule.pattern)}; then`, `  deny ${shSingleQuote(rule.reason)}`, "fi", "");
+  }
+  lines.push("exit 0", "");
+  return lines.join(`
+`);
+}
+function shSingleQuote(value) {
+  return `'${value.split("'").join(`'\\''`)}'`;
+}
+function renderGuardSettings() {
+  return {
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: "Bash",
+          hooks: [{ type: "command", command: `sh ${GUARD_SCRIPT_PATH}`, timeout: 5 }]
+        }
+      ]
+    }
+  };
+}
+function buildGuardInstallCommand() {
+  const script = Buffer.from(renderGuardScript(), "utf8").toString("base64");
+  const settings = Buffer.from(JSON.stringify(renderGuardSettings(), null, 2), "utf8").toString("base64");
+  return [
+    `mkdir -p "$HOME/.claude/hooks"`,
+    `printf %s '${script}' | base64 -d > "${GUARD_SCRIPT_PATH}"`,
+    `chmod +x "${GUARD_SCRIPT_PATH}"`,
+    `printf %s '${settings}' | base64 -d > "${GUARD_SETTINGS_PATH}"`
+  ].join(" && ");
+}
+var CMD_START = "(^|[;&|(]|&&)[[:space:]]*", GUARD_RULES, GUARD_SCRIPT_PATH = "$HOME/.claude/hooks/burn-guard.sh", GUARD_SETTINGS_PATH = "$HOME/.claude/settings.json";
+var init_burn_guard = __esm(() => {
+  GUARD_RULES = [
+    {
+      id: "no-stash",
+      pattern: `${CMD_START}git[[:space:]]+stash`,
+      reason: "git stash is blocked in burns: stashed work is invisible to the orchestrator and unrecoverable if this process dies, and only commits survive. To compare against the pre-change state use `git show HEAD:<path>`, or the pre-existing-failure baseline in your prompt."
+    },
+    {
+      id: "no-serialised-tests",
+      pattern: "--maxWorkers|--runInBand|--pool=|--shard=|singleFork|--poolOptions",
+      reason: `Do not override the test runner's concurrency. Measured in this sandbox, a suite that runs in ~55s at its configured concurrency takes 10-20 minutes serialised, so this "safe" flag is the single most expensive habit in a burn. Run the repo's test command as configured. If it is killed for memory, run only the test files your change touches and say so in your final message.`
+    },
+    {
+      id: "no-interpreter-heredoc-edit",
+      pattern: `${CMD_START}(python3?|node|bun|perl|ruby)[[:space:]]+-[[:space:]]*<<`,
+      reason: "Do not rewrite files by piping a heredoc into an interpreter \u2014 individual such calls have been measured at 29s, 57s, 120s and 761s, and a half-written file survives if this process dies mid-command. Use the Edit tool, which is faster, atomic, and fails loudly when its target text is not found."
+    },
+    {
+      id: "no-cat-heredoc-edit",
+      pattern: `${CMD_START}cat[[:space:]]+>>?[[:space:]]*[^[:space:]|]+[[:space:]]*<<`,
+      reason: "Do not write files with `cat > file <<EOF`. Use the Write tool for a new file, or Edit to change part of an existing one."
+    }
+  ];
+});
+
 // src/workflows/ticket-burner.ts
 import { existsSync as existsSync10, mkdirSync as mkdirSync4, readFileSync as readFileSync4, readdirSync as readdirSync3 } from "fs";
 import { dirname as dirname3, join as join9 } from "path";
@@ -2992,6 +3218,24 @@ function buildWorkspaceNotes(mode) {
   ].join(`
 `);
 }
+function buildVerifyNotes(config2) {
+  const commands = config2.verifyCommands?.trim();
+  const failures = config2.knownFailures?.trim();
+  const out = [];
+  if (commands) {
+    out.push("Verify with exactly these commands \u2014 they are correct for this repo, so do not go looking for alternatives or guess at workspace/package filter names:", "", "```", commands, "```");
+  } else {
+    out.push("No verification commands are configured, so derive them ONCE from the repo (root `package.json` scripts, the workspace's own manifest, CI config) before your first test run \u2014 reading a manifest is free, discovering a filter name by running the wrong suite is not. Write the working commands into your notes and reuse them verbatim for the rest of the ticket.");
+  }
+  out.push("");
+  if (failures) {
+    out.push("These tests ALREADY fail on this repo before you touch anything:", "", "```", failures, "```", "", "Treat that as your baseline \u2014 do NOT spend a run establishing it yourself. Only a failure outside this set is yours to fix; if you hit one that looks pre-existing but is not listed, confirm it on a single targeted run of that one test, never a whole-suite re-run.");
+  } else {
+    out.push("No pre-existing-failure baseline is configured. If the suite is already red, capture the baseline ONCE \u2014 the first full run you do, before your changes land, is the baseline \u2014 and compare every later run against those saved results. Never re-run a whole suite just to re-establish what was already failing.");
+  }
+  return out.join(`
+`);
+}
 function readRepoToolchain(repoPath) {
   const pkgPath = join9(repoPath, "package.json");
   const hasPackageJson = existsSync10(pkgPath);
@@ -3048,6 +3292,63 @@ function createStreamThrottle(emit2, opts = {}) {
   };
   return { onEvent, flush: flushText };
 }
+function normalizeCommandForClassification(command) {
+  return command.replace(/<<\s*['"]?(\w+)['"]?[\s\S]*?(^|\n)\s*\1\b/gm, "<<$1 ").replace(/<<\s*['"]?(\w+)['"]?[\s\S]*$/, "<<$1 ").replace(/'[^']*'/g, " ").replace(/"[^"]*"/g, " ");
+}
+function classifyToolCall(name, args) {
+  const byName = TOOL_NAME_CATEGORY[name];
+  if (byName)
+    return byName;
+  if (name !== "Bash")
+    return "other";
+  const normalized = normalizeCommandForClassification(args);
+  for (const [category, pattern] of BASH_PATTERNS) {
+    if (pattern.test(normalized))
+      return category;
+  }
+  return "other";
+}
+function createToolTimer() {
+  const byCategory = {};
+  let calls = 0;
+  let totalMs = 0;
+  let pending = null;
+  let iteration = null;
+  const charge = (category, ms) => {
+    const slot = byCategory[category] ??= { calls: 0, ms: 0 };
+    slot.ms += ms;
+    totalMs += ms;
+  };
+  const onEvent = (event) => {
+    if (event.type === "raw")
+      return;
+    const at = event.timestamp.getTime();
+    if (iteration !== null && event.iteration !== iteration)
+      pending = null;
+    iteration = event.iteration;
+    if (pending) {
+      const gap = at - pending.at;
+      if (gap > 0 && gap <= MAX_ATTRIBUTABLE_GAP_MS)
+        charge(pending.category, gap);
+    }
+    if (event.type === "toolCall") {
+      const category = classifyToolCall(event.name, event.formattedArgs ?? "");
+      const slot = byCategory[category] ??= { calls: 0, ms: 0 };
+      slot.calls += 1;
+      calls += 1;
+      pending = { category, at };
+    } else {
+      pending = { category: "model", at };
+    }
+  };
+  return { onEvent, summary: () => ({ totalMs, calls, byCategory }) };
+}
+function formatTimingSummary(s) {
+  if (s.totalMs === 0)
+    return `${s.calls} tool call(s), no measurable time`;
+  const parts = Object.entries(s.byCategory).sort((a, b) => (b[1]?.ms ?? 0) - (a[1]?.ms ?? 0)).slice(0, 5).map(([c, t]) => `${c} ${Math.round((t?.ms ?? 0) / s.totalMs * 100)}%`);
+  return `${Math.round(s.totalMs / 60000)}min across ${s.calls} tool call(s) \u2014 ${parts.join(", ")}`;
+}
 function interpretRunResult(result, blockedContent) {
   const commits = result.commits.map((c) => c.sha);
   if (commits.length > 0)
@@ -3058,6 +3359,12 @@ ${blockedContent.trim()}` };
   }
   return { status: "failed", error: "agent made no commits" };
 }
+function isWorktreeTeardownError(err) {
+  const msg = err instanceof Error ? err.message : typeof err === "string" ? err : String(err);
+  if (!BURN_WORKTREE_PATH.test(msg))
+    return false;
+  return WORKTREE_REMOVAL_FAILURES.some((p) => p.test(msg));
+}
 function isMergeConflictError(err) {
   const msg = err instanceof Error ? err.message : typeof err === "string" ? err : "";
   return /conflict/i.test(msg) || /git branch -D/i.test(msg) || /automatic merge failed/i.test(msg);
@@ -3357,10 +3664,7 @@ function buildBurnAgent(config2, token, model) {
   return agent;
 }
 function selectSandbox(config2, mounts = []) {
-  const imageOpts = {
-    imageName: resolveSandboxImage(config2),
-    ...mounts.length > 0 ? { mounts } : {}
-  };
+  const imageOpts = buildSandboxOptions(config2, mounts);
   switch (config2.sandbox) {
     case "docker":
       return docker(imageOpts);
@@ -3370,6 +3674,13 @@ function selectSandbox(config2, mounts = []) {
       return noSandbox();
   }
 }
+function buildSandboxOptions(config2, mounts = []) {
+  return {
+    imageName: resolveSandboxImage(config2),
+    ...mounts.length > 0 ? { mounts } : {},
+    ...config2.burnCpus !== undefined ? { cpus: config2.burnCpus } : {}
+  };
+}
 async function realExecuteTicketRun(ctx, ticket, config2, token, model, land, ensureIsolatedPushTarget) {
   const { project, feature } = ctx;
   const workspaceMode = resolveBurnWorkspaceMode(config2);
@@ -3379,11 +3690,13 @@ async function realExecuteTicketRun(ctx, ticket, config2, token, model, land, en
   const featureBrief = buildFeatureBrief(feature);
   const docsDigest = readDocsDigestFromDisk(project.id, feature.slug);
   const workspaceNotes = buildWorkspaceNotes(workspaceMode);
+  const verifyNotes = buildVerifyNotes(config2);
   const basePrompt = renderTicketPrompt(readFileSync4(burnerTemplatePath(), "utf8"), {
     TICKET_JSON: ticketJson,
     FEATURE_BRIEF: featureBrief,
     DOCS_DIGEST: docsDigest,
     COMMIT_CONVENTION: `ticket(${ticket.seq}): <summary>`,
+    VERIFY_NOTES: verifyNotes,
     WORKSPACE_NOTES: workspaceNotes
   });
   const toolchain = readRepoToolchain(project.repoPath);
@@ -3397,12 +3710,16 @@ async function realExecuteTicketRun(ctx, ticket, config2, token, model, land, en
       mounts.push(mount);
     }
   }
+  const guardInstall = config2.burnGuard && config2.sandbox !== "noSandbox" ? buildGuardInstallCommand() : undefined;
+  const withGuard = (setup) => guardInstall === undefined ? setup : setup ? `${guardInstall} && ${setup}` : guardInstall;
   mkdirSync4(logsDir(), { recursive: true });
   const logFilePath = join9(logsDir(), `burn-${feature.id}-${ticket.seq}.log`);
   const throttle = createStreamThrottle((e) => ctx.emitEvent({ ...e, ticketId: ticket.id }));
   beginTranscript(ticket.id);
+  const timer = createToolTimer();
   const onStreamEvent = (event) => {
     throttle.onEvent(event);
+    timer.onEvent(event);
     if (event.type === "text") {
       appendTranscript(ticket.id, { kind: "text", text: event.message });
     } else if (event.type === "toolCall") {
@@ -3447,12 +3764,13 @@ async function realExecuteTicketRun(ctx, ticket, config2, token, model, land, en
       FEATURE_BRIEF: featureBrief,
       DOCS_DIGEST: docsDigest,
       WORKSPACE_NOTES: workspaceNotes,
+      VERIFY_NOTES: verifyNotes,
       FEATURE_BRANCH: feature.branch,
       CONFLICT_FILES: buildConflictFilesBlock(input.files),
       OTHER_SIDE: buildOtherSideBlock(otherSide),
       MERGE_COMMAND: resolveMergeCommand(workspaceMode, feature.branch)
     });
-    const hookCommand = workspaceMode === "isolated" ? buildIsolatedSetupCommand(resolveBranch, setupCommand, pm) : setupCommand;
+    const hookCommand = withGuard(workspaceMode === "isolated" ? buildIsolatedSetupCommand(resolveBranch, setupCommand, pm) : setupCommand);
     appendTranscript(ticket.id, {
       kind: "text",
       text: `
@@ -3486,13 +3804,18 @@ async function realExecuteTicketRun(ctx, ticket, config2, token, model, land, en
     } catch (err) {
       if (ctx.signal.aborted)
         throw err;
-      return {
-        ok: false,
-        branch: await bestTip(),
-        error: ticketAbort.signal.aborted ? "stopped by user during conflict resolution" : errorHeadline(err instanceof Error ? err.message : String(err))
-      };
+      const tip = await bestTip();
+      const teardownOnly = !ticketAbort.signal.aborted && isWorktreeTeardownError(err) && tip === resolveBranch;
+      if (!teardownOnly) {
+        return {
+          ok: false,
+          branch: tip,
+          error: ticketAbort.signal.aborted ? "stopped by user during conflict resolution" : errorHeadline(err instanceof Error ? err.message : String(err))
+        };
+      }
+      await cleanupBurnWorktree(project.repoPath, resolveBranch);
     }
-    const blocked = readBlockedFile([result.preservedWorktreePath, project.repoPath]);
+    const blocked = readBlockedFile([result?.preservedWorktreePath, project.repoPath]);
     if (blocked !== undefined && blocked.trim().length > 0) {
       return {
         ok: false,
@@ -3577,7 +3900,7 @@ ${blocked.trim()}`
     let tempBranch = "";
     for (let attempt = 1;; attempt++) {
       tempBranch = ticketBranchName(feature.slug, ticket.seq, newId("b").slice(2, 10));
-      const hookCommand = workspaceMode === "isolated" ? buildIsolatedSetupCommand(tempBranch, setupCommand, pm) : setupCommand;
+      const hookCommand = withGuard(workspaceMode === "isolated" ? buildIsolatedSetupCommand(tempBranch, setupCommand, pm) : setupCommand);
       if (hookCommand && attempt === 1) {
         ctx.emitEvent({
           type: "burn.setup",
@@ -3627,6 +3950,18 @@ ${retryNotes}` : basePrompt,
             }
           };
         }
+        if (isWorktreeTeardownError(err)) {
+          const removed = await cleanupBurnWorktree(project.repoPath, tempBranch);
+          if (salvaged.length > 0) {
+            ctx.emitEvent({
+              type: "burn.worktree.teardown-failed",
+              message: `ticket ${ticket.seq}: agent finished but sandcastle could not remove its worktree (${errorHeadline(msg)})${removed ? " \u2014 cleaned up" : " \u2014 left on disk"}; landing the ${salvaged.length} commit(s) anyway`,
+              ticketId: ticket.id,
+              data: { branch: tempBranch, error: msg, cleanedUp: removed }
+            });
+            return await landChain(tempBranch, salvaged);
+          }
+        }
         if (isMergeConflictError(err)) {
           if (salvaged.length > 0) {
             preserveChain(tempBranch);
@@ -3700,6 +4035,15 @@ ${blocked.trim()}` };
     activeTicketAborts.delete(ticket.id);
     throttle.flush();
     endTranscript(ticket.id);
+    const timing = timer.summary();
+    if (timing.calls > 0) {
+      ctx.emitEvent({
+        type: "ticket.timing",
+        message: `ticket ${ticket.seq} spent ${formatTimingSummary(timing)}`,
+        ticketId: ticket.id,
+        data: timing
+      });
+    }
   }
 }
 function resolveBurnDeps(ctx) {
@@ -3728,7 +4072,7 @@ function readTokenFromEnvFile(path) {
   const token = fromFile && fromFile.length > 0 ? fromFile : process.env.CLAUDE_CODE_OAUTH_TOKEN;
   return token && token.length > 0 ? token : undefined;
 }
-var AUTH_MISSING_EVENT = "auth.missing", AUTH_MISSING_MESSAGE = "run `claude setup-token` and put CLAUDE_CODE_OAUTH_TOKEN in ~/.runcastle/.env", PACKAGE_MANAGERS, PM_CACHE_SANDBOX_PATHS, SANDBOX_WORKSPACE_PATH = "/home/agent/workspace", ISOLATED_REPO_PATH = "/home/agent/repo", FATAL_ERROR_PATTERNS, RETRYABLE_ERROR_PATTERNS, activeTicketAborts, SETUP_HOOK_TIMEOUT_MS, ticketBurner;
+var AUTH_MISSING_EVENT = "auth.missing", AUTH_MISSING_MESSAGE = "run `claude setup-token` and put CLAUDE_CODE_OAUTH_TOKEN in ~/.runcastle/.env", PACKAGE_MANAGERS, PM_CACHE_SANDBOX_PATHS, SANDBOX_WORKSPACE_PATH = "/home/agent/workspace", ISOLATED_REPO_PATH = "/home/agent/repo", RUN, BASH_PATTERNS, TOOL_NAME_CATEGORY, MAX_ATTRIBUTABLE_GAP_MS, BURN_WORKTREE_PATH, WORKTREE_REMOVAL_FAILURES, FATAL_ERROR_PATTERNS, RETRYABLE_ERROR_PATTERNS, activeTicketAborts, SETUP_HOOK_TIMEOUT_MS, ticketBurner;
 var init_ticket_burner = __esm(() => {
   init_src();
   init_config_load();
@@ -3736,12 +4080,43 @@ var init_ticket_burner = __esm(() => {
   init_skills_root();
   init_agent_stream();
   init_git();
+  init_burn_guard();
   PACKAGE_MANAGERS = ["bun", "pnpm", "yarn", "npm"];
   PM_CACHE_SANDBOX_PATHS = {
     bun: "~/.bun/install/cache",
     yarn: "~/.cache/yarn",
     npm: "~/.npm"
   };
+  RUN = String.raw`(?![\w./-])`;
+  BASH_PATTERNS = [
+    ["tests", new RegExp(String.raw`\b(vitest|jest|pytest|go test|cargo test|bun test|playwright|maestro)${RUN}|\b(pnpm|npm|yarn|bun|npx)\b[^&;|]*?\s(run\s+)?test${RUN}|--testPathPatterns`)],
+    ["typecheck", /\btsc\b|\btypecheck\b|\bmypy\b|\bcargo check\b/],
+    ["build", new RegExp(String.raw`\bbuild${RUN}|\bprisma\s+(generate|migrate)\b|\bcodegen${RUN}`)],
+    ["lint", new RegExp(String.raw`\b(eslint|prettier|ruff|biome|lint|format)${RUN}`)],
+    ["install", /\b(pnpm|npm|yarn|bun|corepack)\s+\w*\s*install\b|\bnpm ci\b/],
+    ["git", /\bgit\b/],
+    ["search", /\b(grep|rg|ag|find)\b/],
+    ["file-read", /\b(cat|sed|head|tail|less|wc|ls)\b/],
+    ["file-edit", /<<\s*['"]?(PY|EOF|SH|JS|TS)\b|\bpython3?\s+-\s*<</]
+  ];
+  TOOL_NAME_CATEGORY = {
+    Read: "file-read",
+    NotebookRead: "file-read",
+    Grep: "search",
+    Glob: "search",
+    Edit: "file-edit",
+    Write: "file-edit",
+    NotebookEdit: "file-edit"
+  };
+  MAX_ATTRIBUTABLE_GAP_MS = 20 * 60000;
+  BURN_WORKTREE_PATH = /[\\/]\.sandcastle[\\/]worktrees[\\/]/i;
+  WORKTREE_REMOVAL_FAILURES = [
+    /failed to delete/i,
+    /directory not empty|enotempty/i,
+    /unable to (unlink|delete)/i,
+    /is not a working tree/i,
+    /resource busy|ebusy|eperm|eacces/i
+  ];
   FATAL_ERROR_PATTERNS = [
     /invalid (api key|x-api-key)/i,
     /authentication|unauthorized|permission denied/i,
@@ -3879,16 +4254,26 @@ async function realExecuteResearchRun(ctx, waypoint, config2, token, model) {
     logging: { type: "file", path: logFilePath, onAgentStreamEvent: throttle.onEvent }
   };
   let result;
+  let salvaged = [];
   try {
     result = await run2(runOptions);
   } catch (err) {
     throttle.flush();
     if (ctx.signal.aborted)
       throw err;
-    return { status: "failed", error: err instanceof Error ? err.message : String(err) };
+    const msg = err instanceof Error ? err.message : String(err);
+    salvaged = isWorktreeTeardownError(err) ? await branchCommitsAhead(project.repoPath, feature.branch, tempBranch) : [];
+    if (salvaged.length === 0)
+      return { status: "failed", error: msg };
+    const removed = await cleanupBurnWorktree(project.repoPath, tempBranch);
+    ctx.emitEvent({
+      type: "burn.worktree.teardown-failed",
+      message: `waypoint ${waypoint.seq}: agent finished but sandcastle could not remove its worktree (${errorHeadline2(msg)})${removed ? " \u2014 cleaned up" : " \u2014 left on disk"}; landing the ${salvaged.length} commit(s) anyway`,
+      data: { tempBranch, error: msg, cleanedUp: removed }
+    });
   }
   throttle.flush();
-  const outcome = interpretResearchResult(result, docRelPath);
+  const outcome = result ? interpretResearchResult(result, docRelPath) : { status: "done", commits: salvaged, docRelPath };
   if (outcome.status !== "done")
     return outcome;
   const merge = await mergeTempBranch(project.repoPath, feature.branch, tempBranch);
@@ -4024,7 +4409,7 @@ async function startRun(ctx, featureId, workflowId, opts = {}) {
     },
     signal: controller.signal
   };
-  const done = executeRun(ctx, runId, featureId, def.run(wctx), controller, async () => {
+  const done = executeRun(ctx, runId, featureId, workflowId, def.run(wctx), controller, async () => {
     if (talkDetached)
       await reattachWorktree(talkWorktree, feature.branch);
   });
@@ -4033,7 +4418,7 @@ async function startRun(ctx, featureId, workflowId, opts = {}) {
 function cancelRun(runId) {
   controllers.get(runId)?.abort();
 }
-async function executeRun(ctx, runId, featureId, runPromise, controller, cleanup) {
+async function executeRun(ctx, runId, featureId, workflow2, runPromise, controller, cleanup) {
   let status = "failed";
   let summary = "run failed";
   try {
@@ -4054,6 +4439,9 @@ async function executeRun(ctx, runId, featureId, runPromise, controller, cleanup
   }
   ctx.db.update(runs).set({ status, endedAt: Date.now(), summary }).where(eq6(runs.id, runId)).run();
   releaseForSession(ctx, runId);
+  if (workflowClaimsFeatureBranch(workflow2)) {
+    sweepOrphanedBurning(ctx, featureId, `orphaned \u2014 the run ended (${status}) while it was burning`);
+  }
   emit(ctx, featureId, {
     type: "run.finished",
     message: `run ${status}: ${summary}`,
@@ -4195,7 +4583,7 @@ function advance(ctx, featureId) {
 async function burn(ctx, featureId, opts = {}) {
   const feature = getFeatureRow(ctx, featureId);
   const running = hasActiveRun(ctx, featureId);
-  const tickets2 = listByFeature2(ctx, featureId);
+  let tickets2 = listByFeature2(ctx, featureId);
   const pending = tickets2.filter((t) => t.status !== "done" && t.status !== "failed" && t.status !== "cancelled");
   const restarting = feature.phase === "implementation" && !running;
   const iterating = feature.phase === "review" && !running && pending.length >= 1;
@@ -4213,6 +4601,8 @@ async function burn(ctx, featureId, opts = {}) {
     throw new GateError(tickets2.length > 0 ? "no burnable tickets \u2014 every ticket is cancelled" : "no tickets to burn");
   }
   if (restarting) {
+    sweepOrphanedBurning(ctx, featureId, "orphaned \u2014 the previous run died while it was burning");
+    tickets2 = listByFeature2(ctx, featureId);
     const failed = opts.resetFailed === false ? [] : tickets2.filter((t) => t.status === "failed");
     for (const t of failed) {
       updateTicket(ctx, t.id, { status: "pending", error: null });
@@ -5316,7 +5706,7 @@ var init_artifacts = __esm(() => {
 import { existsSync as existsSync13 } from "fs";
 import { dirname as dirname5, join as join13, resolve as resolve7 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
-import { and as and5, eq as eq8 } from "drizzle-orm";
+import { and as and6, eq as eq8 } from "drizzle-orm";
 function ptyExitMessage(exitCode) {
   const label = typeof exitCode === "number" ? String(exitCode) : "unknown";
   return `terminal exited (code ${label})`;
@@ -5342,14 +5732,10 @@ function buildClaudeArgs(input) {
   ];
 }
 function resolveClaudeExecutable() {
-  return resolveExecutable("claude", { override: process.env.RUNCASTLE_CLAUDE_BIN });
+  return resolveTool("claude");
 }
 function claudeSpawnTarget(claudeArgs) {
-  const exe = resolveClaudeExecutable();
-  if (/\.(cmd|bat)$/i.test(exe)) {
-    return { file: process.env.ComSpec ?? "cmd.exe", args: ["/c", exe, ...claudeArgs] };
-  }
-  return { file: exe, args: claudeArgs };
+  return spawnTargetFor(resolveClaudeExecutable(), claudeArgs);
 }
 function resolvePluginDir(fromDir = dirname5(fileURLToPath5(import.meta.url))) {
   const rel = join13("packages", "skills", "packs", "runcastle");
@@ -5377,7 +5763,7 @@ function resolvePluginDir(fromDir = dirname5(fileURLToPath5(import.meta.url))) {
   `)}`);
 }
 function activeRunFor(ctx, featureId) {
-  const row = ctx.db.select().from(runs).where(and5(eq8(runs.featureId, featureId), eq8(runs.status, "running"))).limit(1).get();
+  const row = ctx.db.select().from(runs).where(and6(eq8(runs.featureId, featureId), eq8(runs.status, "running"))).limit(1).get();
   return row ? rowToRun(row) : null;
 }
 function assertSpawnable(ctx, feature, excludeSessionId) {
@@ -6264,6 +6650,14 @@ var init_settings = __esm(() => {
       valueSchema: z9.number().int().min(0).max(3),
       parseEnv: (raw) => Number(raw)
     },
+    {
+      key: "burnCpus",
+      configKey: "burnCpus",
+      envVar: "RUNCASTLE_BURN_CPUS",
+      restartRequired: false,
+      valueSchema: z9.number().positive().max(256),
+      parseEnv: (raw) => Number(raw)
+    },
     {
       key: "setupCommand",
       configKey: "setupCommand",
@@ -6272,6 +6666,22 @@ var init_settings = __esm(() => {
       valueSchema: z9.string().min(1),
       parseEnv: idEnv
     },
+    {
+      key: "verifyCommands",
+      configKey: "verifyCommands",
+      envVar: "RUNCASTLE_VERIFY_COMMANDS",
+      restartRequired: false,
+      valueSchema: z9.string().min(1),
+      parseEnv: idEnv
+    },
+    {
+      key: "knownFailures",
+      configKey: "knownFailures",
+      envVar: "RUNCASTLE_KNOWN_FAILURES",
+      restartRequired: false,
+      valueSchema: z9.string().min(1),
+      parseEnv: idEnv
+    },
     {
       key: "mainBranch",
       configKey: "mainBranch",
@@ -6470,10 +6880,7 @@ var init_doctor = __esm(() => {
 import { spawn as spawn2 } from "child_process";
 function createSystemExec(opts = {}) {
   return (command, args) => new Promise((resolve9) => {
-    const resolved = resolveExecutable(command);
-    const isShim = /\.(cmd|bat)$/i.test(resolved);
-    const file = isShim ? process.env.ComSpec ?? "cmd.exe" : resolved;
-    const spawnArgs = isShim ? ["/c", resolved, ...args] : args;
+    const { file, args: spawnArgs } = resolveSpawnTarget(command, args);
     let stdout = "";
     let stderr = "";
     const child = spawn2(file, spawnArgs, { cwd: opts.cwd, windowsHide: true });
@@ -6624,12 +7031,29 @@ function prepareSandboxBuildContext() {
 }
 function createTokenVerifier(exec) {
   return async (token) => {
+    if (token.length < 8) {
+      return {
+        valid: false,
+        detail: "token looks malformed (too short) \u2014 saved to ~/.runcastle/.env anyway",
+        fix: "Re-run `claude setup-token` and paste the whole line it prints (it starts with `sk-ant-oat`)."
+      };
+    }
     const out = await exec("claude", ["--version"]);
-    if (!(out.ok && out.code === 0)) {
-      return { valid: false, detail: "claude CLI not found \u2014 cannot verify the token" };
+    if (!out.ok) {
+      return {
+        valid: false,
+        detail: "Token saved to ~/.runcastle/.env, but runcastle could not launch `claude` to verify it. " + "That is a PATH problem in this server process, not a missing install \u2014 a terminal that finds " + "`claude` proves nothing about the PATH runcastle was started with.",
+        fix: "Quit runcastle and start it again from a terminal where `claude --version` works. " + "If it still fails, pin the path: set RUNCASTLE_CLAUDE_BIN to the full path from " + "`where.exe claude` (Windows) or `which claude` (macOS/Linux), then restart runcastle."
+      };
     }
-    if (token.length < 8) {
-      return { valid: false, detail: "token looks malformed (too short)" };
+    if (out.code !== 0) {
+      const why = (out.stderr.trim() || out.stdout.trim()).split(`
+`)[0] ?? "";
+      return {
+        valid: false,
+        detail: `Token saved to ~/.runcastle/.env, but \`claude --version\` exited ${out.code}` + `${why ? `: ${why}` : " with no output"}.`,
+        fix: "Run `claude --version` yourself and fix what it reports \u2014 the Claude Code install is broken, not the token."
+      };
     }
     return { valid: true, detail: "token captured to ~/.runcastle/.env" };
   };
@@ -6681,10 +7105,7 @@ var init_setup2 = __esm(() => {
       const spec = terminalSpec(input.kind, { runtime, imageName, sandcastleBin });
       const sessionId = newId("setup");
       const cwd = input.kind === "build-image" ? prepareSandboxBuildContext() : process.cwd();
-      const resolved = resolveExecutable(spec.cmd);
-      const isShim = /\.(cmd|bat)$/i.test(resolved);
-      const file = isShim ? process.env.ComSpec ?? "cmd.exe" : resolved;
-      const args = isShim ? ["/c", resolved, ...spec.args] : spec.args;
+      const { file, args } = resolveSpawnTarget(spec.cmd, spec.args);
       ptyRegistry().create({
         sessionId,
         cmd: file,
@@ -6814,12 +7235,22 @@ import * as z12 from "zod";
 var ticketRouter;
 var init_ticket = __esm(() => {
   init_features();
+  init_repo();
   init_tickets();
   init_ticket_burner();
   init_context();
   ticketRouter = router({
     retry: publicProcedure.input(z12.object({ ticketId: z12.string(), fresh: z12.boolean().optional() })).mutation(({ ctx, input }) => retryTicket(ctx, input.ticketId, { fresh: input.fresh })),
-    stop: publicProcedure.input(z12.object({ ticketId: z12.string() })).mutation(({ input }) => ({ stopped: stopTicketRun(input.ticketId) })),
+    stop: publicProcedure.input(z12.object({ ticketId: z12.string() })).mutation(({ ctx, input }) => {
+      if (stopTicketRun(input.ticketId))
+        return { stopped: true, swept: false };
+      const ticket = getTicket(ctx, input.ticketId);
+      if (ticket.status === "burning" && !hasActiveRun(ctx, ticket.featureId)) {
+        sweepOrphanedBurning(ctx, ticket.featureId, "orphaned \u2014 the run that was burning it is gone");
+        return { stopped: false, swept: true };
+      }
+      return { stopped: false, swept: false };
+    }),
     cancel: publicProcedure.input(z12.object({ ticketId: z12.string(), reason: z12.string().optional() })).mutation(({ ctx, input }) => cancelTicket(ctx, input.ticketId, input.reason))
   });
 });
@@ -6860,6 +7291,7 @@ async function reconcileStaleRuns(ctx) {
       continue;
     ctx.db.update(runs).set({ status: "failed", endedAt: Date.now(), summary: "orphaned by server restart" }).where(eq11(runs.id, run3.id)).run();
     const released = releaseForSession(ctx, run3.id);
+    const swept = workflowClaimsFeatureBranch(run3.workflow) ? sweepOrphanedBurning(ctx, run3.featureId, "orphaned by server restart \u2014 retry to resume its commits") : [];
     if (workflowClaimsFeatureBranch(run3.workflow)) {
       const feature = tryGetFeature(ctx, run3.featureId);
       const project = feature ? getProjectById(ctx, feature.projectId) : null;
@@ -6876,7 +7308,8 @@ async function reconcileStaleRuns(ctx) {
       data: {
         runId: run3.id,
         workflow: run3.workflow,
-        releasedWaypointIds: released.map((w) => w.id)
+        releasedWaypointIds: released.map((w) => w.id),
+        sweptTicketSeqs: swept.map((t2) => t2.seq)
       }
     });
     reconciled.push(run3);
@@ -6894,6 +7327,7 @@ var init_reconcile_runs = __esm(() => {
   init_events();
   init_git();
   init_repo();
+  init_tickets();
   init_waypoints();
   init_runner();
 });