runcastle 1.0.7 → 1.0.9

package/index.js

@@ -26,7 +26,8 @@ __export(exports_paths, {
   envPath: () => envPath,
   dbPath: () => dbPath,
   dataDir: () => dataDir,
-  configPath: () => configPath
+  configPath: () => configPath,
+  burnCacheDir: () => burnCacheDir
 });
 import { homedir } from "os";
 import { join } from "path";
@@ -51,6 +52,9 @@ function sessionDir(id) {
 function worktreeDir(projectId, slug) {
   return join(dataDir(), "worktrees", projectId, slug);
 }
+function burnCacheDir(pm) {
+  return join(dataDir(), "cache", pm);
+}
 function sandboxBuildDir() {
   return join(dataDir(), "sandbox-build");
 }
@@ -99,7 +103,9 @@ var init_config = __esm(() => {
     sandbox: z.enum(["docker", "podman", "noSandbox"]).default("docker"),
     mainBranch: z.string().default("main"),
     sandboxImage: z.string().optional(),
-    burnConcurrency: z.number().int().min(1).max(8).default(3)
+    burnConcurrency: z.number().int().min(1).max(8).default(3),
+    burnMaxIterations: z.number().int().min(1).max(10).default(3),
+    setupCommand: z.string().optional()
   }));
 });
 
@@ -135,6 +141,11 @@ function loadConfig(env = process.env) {
   if (env.RUNCASTLE_BURN_CONCURRENCY) {
     overrides.burnConcurrency = Number(env.RUNCASTLE_BURN_CONCURRENCY);
   }
+  if (env.RUNCASTLE_BURN_MAX_ITERATIONS) {
+    overrides.burnMaxIterations = Number(env.RUNCASTLE_BURN_MAX_ITERATIONS);
+  }
+  if (env.RUNCASTLE_SETUP_COMMAND)
+    overrides.setupCommand = env.RUNCASTLE_SETUP_COMMAND;
   const base = typeof fileConfig === "object" && fileConfig !== null ? fileConfig : {};
   return RuncastleConfig.parse({ ...base, ...overrides });
 }
@@ -2115,11 +2126,14 @@ async function reattachWorktree(path, branch) {
     await git(path).checkout(branch);
   } catch {}
 }
+function tempBranchSlugSegment(slug) {
+  return slug.slice(0, TEMP_BRANCH_SLUG_MAX).replace(/-+$/, "");
+}
 function researchBranchName(slug, waypointSeq, unique) {
-  return `${RESEARCH_BRANCH_PREFIX}${slug}/${waypointSeq}-${unique}`;
+  return `${RESEARCH_BRANCH_PREFIX}${tempBranchSlugSegment(slug)}/${waypointSeq}-${unique}`;
 }
 function ticketBranchName(slug, ticketSeq, unique) {
-  return `${TICKET_BRANCH_PREFIX}${slug}/${ticketSeq}-${unique}`;
+  return `${TICKET_BRANCH_PREFIX}${tempBranchSlugSegment(slug)}/${ticketSeq}-${unique}`;
 }
 async function mergeTempBranch(repoPath, featureBranchName, tempBranch) {
   const g = git(repoPath);
@@ -2187,17 +2201,23 @@ async function cleanupTempBranches(repoPath) {
     const prefix = tempBranchPrefix(name);
     if (!prefix)
       continue;
-    const slug = name.slice(prefix.length).split("/")[0];
-    const target = featureBranch(slug);
+    const seg = name.slice(prefix.length).split("/")[0];
+    const targets = seg ? all.filter((b) => {
+      if (!b.startsWith("feature/"))
+        return false;
+      const featureSlug = b.slice("feature/".length);
+      return featureSlug === seg || tempBranchSlugSegment(featureSlug) === seg;
+    }) : [];
     let merged = false;
-    if (slug && all.includes(target)) {
+    for (const target of targets) {
       try {
         const tip = (await g.revparse([name])).trim();
         const base = (await g.raw(["merge-base", name, target])).trim();
-        merged = tip.length > 0 && tip === base;
-      } catch {
-        merged = false;
-      }
+        if (tip.length > 0 && tip === base) {
+          merged = true;
+          break;
+        }
+      } catch {}
     }
     if (merged && await deleteBranchDetachingWorktrees(g, repoPath, name)) {
       deleted.push(name);
@@ -2344,7 +2364,7 @@ async function mergeInProgress(g) {
     return false;
   }
 }
-var DOCS_PATHSPEC = "docs/features", DENY_DIRTY = "Working tree has uncommitted changes \u2014 commit or stash first", DENY_ACTIVE = "A test drive is already active \u2014 stop it first", DENY_ACTIVE_RUN = "Feature has an active run \u2014 wait for it to finish", DENY_NONE_ACTIVE = "No test drive is active", RESEARCH_BRANCH_PREFIX = "runcastle/research/", TICKET_BRANCH_PREFIX = "runcastle/ticket/", TEMP_BRANCH_PREFIXES, testDriveState;
+var DOCS_PATHSPEC = "docs/features", DENY_DIRTY = "Working tree has uncommitted changes \u2014 commit or stash first", DENY_ACTIVE = "A test drive is already active \u2014 stop it first", DENY_ACTIVE_RUN = "Feature has an active run \u2014 wait for it to finish", DENY_NONE_ACTIVE = "No test drive is active", RESEARCH_BRANCH_PREFIX = "runcastle/research/", TICKET_BRANCH_PREFIX = "runcastle/ticket/", TEMP_BRANCH_PREFIXES, TEMP_BRANCH_SLUG_MAX = 16, testDriveState;
 var init_git = __esm(() => {
   init_paths();
   init_errors();
@@ -2482,6 +2502,46 @@ var init_skills_root = __esm(() => {
   SKILLS_MARKER = join7("packs", "runcastle");
 });
 
+// src/services/agent-stream.ts
+function beginTranscript(ticketId) {
+  transcripts.set(ticketId, { live: true, chunks: [], nextIndex: 0, bytes: 0 });
+}
+function appendTranscript(ticketId, chunk) {
+  const t = transcripts.get(ticketId);
+  if (!t)
+    return;
+  const full = { ...chunk, i: t.nextIndex, ts: chunk.ts ?? Date.now() };
+  t.nextIndex += 1;
+  t.chunks.push(full);
+  t.bytes += full.text.length;
+  while (t.chunks.length > MAX_CHUNKS || t.bytes > MAX_BYTES && t.chunks.length > 1) {
+    const dropped = t.chunks.shift();
+    if (!dropped)
+      break;
+    t.bytes -= dropped.text.length;
+  }
+}
+function endTranscript(ticketId) {
+  const t = transcripts.get(ticketId);
+  if (t)
+    t.live = false;
+}
+function readTranscript(ticketId, after = -1) {
+  const t = transcripts.get(ticketId);
+  if (!t)
+    return { live: false, chunks: [], firstIndex: 0, nextIndex: 0 };
+  return {
+    live: t.live,
+    chunks: after < 0 ? [...t.chunks] : t.chunks.filter((c) => c.i > after),
+    firstIndex: t.chunks[0]?.i ?? t.nextIndex,
+    nextIndex: t.nextIndex
+  };
+}
+var MAX_CHUNKS = 4000, MAX_BYTES = 1500000, transcripts;
+var init_agent_stream = __esm(() => {
+  transcripts = new Map;
+});
+
 // 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 join8 } from "path";
@@ -2594,6 +2654,64 @@ function parseEnvFile(content) {
   }
   return out;
 }
+function detectPackageManager(tc) {
+  const pinned = tc.packageManagerField?.split("@")[0];
+  if (pinned && PACKAGE_MANAGERS.includes(pinned)) {
+    return pinned;
+  }
+  if (tc.lockfiles.bun)
+    return "bun";
+  if (tc.lockfiles.pnpm)
+    return "pnpm";
+  if (tc.lockfiles.yarn)
+    return "yarn";
+  if (tc.lockfiles.npm)
+    return "npm";
+  return tc.hasPackageJson ? "npm" : undefined;
+}
+function resolveSetupCommand(tc, override) {
+  const trimmed = override?.trim();
+  if (trimmed)
+    return trimmed;
+  const pm = detectPackageManager(tc);
+  if (!pm)
+    return;
+  switch (pm) {
+    case "bun":
+      return tc.lockfiles.bun ? "bun install --frozen-lockfile" : "bun install";
+    case "pnpm":
+      return tc.lockfiles.pnpm ? "corepack pnpm install --frozen-lockfile" : "corepack pnpm install";
+    case "yarn":
+      return tc.lockfiles.yarn ? "corepack yarn install --frozen-lockfile" : "corepack yarn install";
+    case "npm":
+      return tc.lockfiles.npm ? "npm ci" : "npm install";
+  }
+}
+function cacheMountFor(pm, hostPath) {
+  return { hostPath, sandboxPath: PM_CACHE_SANDBOX_PATHS[pm] };
+}
+function readRepoToolchain(repoPath) {
+  const pkgPath = join8(repoPath, "package.json");
+  const hasPackageJson = existsSync10(pkgPath);
+  let packageManagerField;
+  if (hasPackageJson) {
+    try {
+      const pkg = JSON.parse(readFileSync4(pkgPath, "utf8"));
+      if (typeof pkg.packageManager === "string")
+        packageManagerField = pkg.packageManager;
+    } catch {}
+  }
+  return {
+    hasPackageJson,
+    ...packageManagerField !== undefined ? { packageManagerField } : {},
+    lockfiles: {
+      bun: existsSync10(join8(repoPath, "bun.lock")) || existsSync10(join8(repoPath, "bun.lockb")),
+      pnpm: existsSync10(join8(repoPath, "pnpm-lock.yaml")),
+      yarn: existsSync10(join8(repoPath, "yarn.lock")),
+      npm: existsSync10(join8(repoPath, "package-lock.json"))
+    }
+  };
+}
 function createStreamThrottle(emit2, opts = {}) {
   const intervalMs = opts.intervalMs ?? 2000;
   const maxChars = opts.maxChars ?? 500;
@@ -2652,10 +2770,11 @@ function createSerialQueue() {
     return next;
   };
 }
-function firstLine(s) {
-  const i = s.indexOf(`
-`);
-  return (i === -1 ? s : s.slice(0, i)).trim();
+function errorHeadline(s) {
+  const lines = s.split(`
+`).map((l) => l.trim()).filter(Boolean);
+  const causes = lines.filter((l) => /^(fatal|error):/i.test(l));
+  return causes.at(-1) ?? lines[0] ?? "";
 }
 async function burnTickets(ctx, tickets2, execute, concurrency = 1) {
   const width = Math.max(1, Math.floor(concurrency));
@@ -2710,7 +2829,7 @@ async function burnTickets(ctx, tickets2, execute, concurrency = 1) {
       failTicket(seq, outcome.error, outcome.event);
       ctx.emitEvent({
         type: "ticket.failed",
-        message: `ticket ${t.seq} failed: ${firstLine(outcome.error)}`,
+        message: `ticket ${t.seq} failed: ${errorHeadline(outcome.error)}`,
         ticketId: t.id,
         data: { error: outcome.error }
       });
@@ -2844,8 +2963,11 @@ function buildBurnAgent(config2, token, model) {
   }
   return agent;
 }
-function selectSandbox(config2) {
-  const imageOpts = { imageName: resolveSandboxImage(config2) };
+function selectSandbox(config2, mounts = []) {
+  const imageOpts = {
+    imageName: resolveSandboxImage(config2),
+    ...mounts.length > 0 ? { mounts } : {}
+  };
   switch (config2.sandbox) {
     case "docker":
       return docker(imageOpts);
@@ -2865,24 +2987,62 @@ async function realExecuteTicketRun(ctx, ticket, config2, token, model, land) {
     DOCS_DIGEST: readDocsDigestFromDisk(project.id, feature.slug),
     COMMIT_CONVENTION: `ticket(${ticket.seq}): <summary>`
   });
+  const toolchain = readRepoToolchain(project.repoPath);
+  const pm = detectPackageManager(toolchain);
+  const setupCommand = resolveSetupCommand(toolchain, config2.setupCommand);
+  const mounts = [];
+  if (config2.sandbox !== "noSandbox" && pm) {
+    const hostCache = burnCacheDir(pm);
+    mkdirSync4(hostCache, { recursive: true });
+    mounts.push(cacheMountFor(pm, hostCache));
+  }
+  if (setupCommand) {
+    ctx.emitEvent({
+      type: "burn.setup",
+      message: `installing deps before agent start: ${setupCommand}`,
+      ticketId: ticket.id
+    });
+  }
   mkdirSync4(logsDir(), { recursive: true });
   const logFilePath = join8(logsDir(), `burn-${feature.id}-${ticket.seq}.log`);
   const throttle = createStreamThrottle((e) => ctx.emitEvent({ ...e, ticketId: ticket.id }));
+  beginTranscript(ticket.id);
+  const onStreamEvent = (event) => {
+    throttle.onEvent(event);
+    if (event.type === "text") {
+      appendTranscript(ticket.id, { kind: "text", text: event.message });
+    } else if (event.type === "toolCall") {
+      appendTranscript(ticket.id, {
+        kind: "tool",
+        text: event.formattedArgs ?? "",
+        name: event.name
+      });
+    }
+  };
   const runOptions = {
     agent: buildBurnAgent(config2, token, model),
-    sandbox: selectSandbox(config2),
+    sandbox: selectSandbox(config2, mounts),
     cwd: project.repoPath,
     prompt,
     branchStrategy: { type: "branch", branch: tempBranch, baseBranch: feature.branch },
     signal: ctx.signal,
     name: `ticket-${ticket.seq}`,
-    logging: { type: "file", path: logFilePath, onAgentStreamEvent: throttle.onEvent }
+    maxIterations: config2.burnMaxIterations,
+    ...setupCommand ? {
+      hooks: {
+        sandbox: {
+          onSandboxReady: [{ command: setupCommand, timeoutMs: SETUP_HOOK_TIMEOUT_MS }]
+        }
+      }
+    } : {},
+    logging: { type: "file", path: logFilePath, onAgentStreamEvent: onStreamEvent }
   };
   let result;
   try {
     result = await run(runOptions);
   } catch (err) {
     throttle.flush();
+    endTranscript(ticket.id);
     if (ctx.signal.aborted)
       throw err;
     const msg = err instanceof Error ? err.message : String(err);
@@ -2899,6 +3059,7 @@ async function realExecuteTicketRun(ctx, ticket, config2, token, model, land) {
     return { status: "failed", error: msg };
   }
   throttle.flush();
+  endTranscript(ticket.id);
   const blocked = readBlockedFile([result.preservedWorktreePath, project.repoPath]);
   const outcome = interpretRunResult(result, blocked);
   if (outcome.status !== "done")
@@ -2918,7 +3079,7 @@ async function realExecuteTicketRun(ctx, ticket, config2, token, model, land) {
     }
     return {
       status: "failed",
-      error: `ticket ${ticket.seq} committed to ${tempBranch} but landing on ${feature.branch} failed: ${firstLine(detail)} \u2014 the branch is preserved for manual recovery`
+      error: `ticket ${ticket.seq} committed to ${tempBranch} but landing on ${feature.branch} failed: ${errorHeadline(detail)} \u2014 the branch is preserved for manual recovery`
     };
   }
   return outcome;
@@ -2947,14 +3108,23 @@ 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", PLACEHOLDERS, ticketBurner;
+var AUTH_MISSING_EVENT = "auth.missing", AUTH_MISSING_MESSAGE = "run `claude setup-token` and put CLAUDE_CODE_OAUTH_TOKEN in ~/.runcastle/.env", PLACEHOLDERS, PACKAGE_MANAGERS, PM_CACHE_SANDBOX_PATHS, SETUP_HOOK_TIMEOUT_MS, ticketBurner;
 var init_ticket_burner = __esm(() => {
   init_src();
   init_config_load();
   init_paths();
   init_skills_root();
+  init_agent_stream();
   init_git();
   PLACEHOLDERS = ["TICKET_JSON", "FEATURE_BRIEF", "DOCS_DIGEST", "COMMIT_CONVENTION"];
+  PACKAGE_MANAGERS = ["bun", "pnpm", "yarn", "npm"];
+  PM_CACHE_SANDBOX_PATHS = {
+    bun: "~/.bun/install/cache",
+    pnpm: "~/.local/share/pnpm/store",
+    yarn: "~/.cache/yarn",
+    npm: "~/.npm"
+  };
+  SETUP_HOOK_TIMEOUT_MS = 15 * 60000;
   ticketBurner = {
     id: "ticket-burner",
     run: (ctx) => burnRun(ctx, resolveBurnDeps(ctx))
@@ -3003,15 +3173,16 @@ async function researchRun(ctx, deps) {
   }
   ctx.emitEvent({
     type: "research.failed",
-    message: `waypoint ${waypoint.seq} research failed: ${firstLine2(outcome.error)}`,
+    message: `waypoint ${waypoint.seq} research failed: ${errorHeadline2(outcome.error)}`,
     data: { waypointId: waypoint.id, error: outcome.error }
   });
   return { status: "failed", summary: outcome.error };
 }
-function firstLine2(s) {
-  const i = s.indexOf(`
-`);
-  return (i === -1 ? s : s.slice(0, i)).trim();
+function errorHeadline2(s) {
+  const lines = s.split(`
+`).map((l) => l.trim()).filter(Boolean);
+  const causes = lines.filter((l) => /^(fatal|error):/i.test(l));
+  return causes.at(-1) ?? lines[0] ?? "";
 }
 function createResearchStreamThrottle(emit2, opts = {}) {
   return createStreamThrottle((e) => emit2({ ...e, type: e.type.replace(/^burn\./, "research.") }), opts);
@@ -3088,7 +3259,7 @@ async function realExecuteResearchRun(ctx, waypoint, config2, token, model) {
     const detail = merge.error ?? "merge failed";
     ctx.emitEvent({
       type: merge.conflict ? "merge.conflict.needs-human" : "research.merge_failed",
-      message: merge.conflict ? `research branch ${tempBranch} conflicts with ${feature.branch} \u2014 merge it manually (git merge ${tempBranch}; resolve; git branch -D ${tempBranch}), then resolve the waypoint` : `could not land ${tempBranch} on ${feature.branch}: ${firstLine2(detail)} \u2014 the branch is preserved for manual recovery`,
+      message: merge.conflict ? `research branch ${tempBranch} conflicts with ${feature.branch} \u2014 merge it manually (git merge ${tempBranch}; resolve; git branch -D ${tempBranch}), then resolve the waypoint` : `could not land ${tempBranch} on ${feature.branch}: ${errorHeadline2(detail)} \u2014 the branch is preserved for manual recovery`,
       data: { tempBranch, featureBranch: feature.branch, conflict: merge.conflict ?? false, error: detail }
     });
     return {
@@ -4832,11 +5003,13 @@ var init_project = __esm(() => {
 import * as z8 from "zod";
 var runRouter;
 var init_run = __esm(() => {
+  init_agent_stream();
   init_repo();
   init_runner();
   init_context();
   runRouter = router({
     get: publicProcedure.input(z8.object({ runId: z8.string() })).query(({ ctx, input }) => getRunRow(ctx, input.runId)),
+    agentTranscript: publicProcedure.input(z8.object({ ticketId: z8.string(), after: z8.number().int().optional() })).query(({ input }) => readTranscript(input.ticketId, input.after ?? -1)),
     cancel: publicProcedure.input(z8.object({ runId: z8.string() })).mutation(({ input }) => {
       cancelRun(input.runId);
       return { ok: true };
@@ -5072,6 +5245,22 @@ var init_settings = __esm(() => {
       valueSchema: z9.number().int().min(1).max(8),
       parseEnv: (raw) => Number(raw)
     },
+    {
+      key: "burnMaxIterations",
+      configKey: "burnMaxIterations",
+      envVar: "RUNCASTLE_BURN_MAX_ITERATIONS",
+      restartRequired: false,
+      valueSchema: z9.number().int().min(1).max(10),
+      parseEnv: (raw) => Number(raw)
+    },
+    {
+      key: "setupCommand",
+      configKey: "setupCommand",
+      envVar: "RUNCASTLE_SETUP_COMMAND",
+      restartRequired: false,
+      valueSchema: z9.string().min(1),
+      parseEnv: idEnv
+    },
     {
       key: "mainBranch",
       configKey: "mainBranch",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcastle",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Burn tickets into shipped features with Claude Code.",
   "license": "MIT",
   "type": "module",

package/skills/burner/implement-ticket.md

@@ -4,6 +4,14 @@
 
 You are a single agent in a sandbox on branch `feature/<slug>`. You have **one ticket**. There is **no human to ask** — no follow-up questions are possible. Everything you need is in this prompt and in the repo. Work carefully, commit only green work, and stop when the ticket is done.
 
+## How you run
+
+You run **non-interactively** (`claude --print`), for up to a few fresh iterations against the same worktree:
+
+- **Ending your turn ends your process.** There are no background-task completion notifications in print mode — a "the notification will re-invoke me" plan never fires. Never end your turn to wait on a background command; run long commands (dependency installs, full test suites) in the foreground with a generous timeout, or poll a backgrounded command to completion *within* the same turn.
+- **You may not be the first iteration.** A previous iteration may have left commits or uncommitted work on this branch. Check `git status` and `git log` before starting; continue the work, don't redo it.
+- **Signal completion.** When the ticket is fully done — every acceptance criterion verified, self-review finished, all work committed — print exactly `<promise>COMPLETE</promise>` as the last line of your final message. Do the same after writing `BLOCKED.md` (see hard rules). Without the signal, the harness assumes you were cut off and spends another iteration.
+
 ## The ticket
 
 ```json
@@ -39,4 +47,4 @@ You are a single agent in a sandbox on branch `feature/<slug>`. You have **one t
 
 - **Never expand scope beyond the ticket.** If you notice adjacent work, worthwhile refactors, or another ticket's territory, leave it. Note it in your final commit body if it matters; do not do it.
 - **No questions, no guessing into the void.** Resolve ambiguity from the ticket context and the code. If two readings both satisfy the acceptance criteria, take the smaller one.
-- **If genuinely blocked** (a dependency ticket's output is not there, the environment fails, or a requirement truly cannot be resolved from context + code): **commit nothing for the blocked part**, write `BLOCKED.md` at the repo root stating precisely what blocked you and what is needed to unblock, and stop. Green, complete parts may still be committed; the blocked part must not be. The orchestrator reads your exit state from the commits — a part with no commits is read as not done.
+- **If genuinely blocked** (a dependency ticket's output is not there, the environment fails, or a requirement truly cannot be resolved from context + code): **commit nothing for the blocked part**, write `BLOCKED.md` at the repo root stating precisely what blocked you and what is needed to unblock, print `<promise>COMPLETE</promise>`, and stop. Green, complete parts may still be committed; the blocked part must not be. The orchestrator reads your exit state from the commits — a part with no commits is read as not done.