runcastle 1.0.8 → 1.0.10

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,10 @@ 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(),
+    burnWorkspace: z.enum(["auto", "mounted", "isolated"]).default("auto")
   }));
 });
 
@@ -135,6 +142,13 @@ 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;
+  if (env.RUNCASTLE_BURN_WORKSPACE)
+    overrides.burnWorkspace = env.RUNCASTLE_BURN_WORKSPACE;
   const base = typeof fileConfig === "object" && fileConfig !== null ? fileConfig : {};
   return RuncastleConfig.parse({ ...base, ...overrides });
 }
@@ -2491,6 +2505,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";
@@ -2603,6 +2657,97 @@ 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) {
+  const sandboxPath = PM_CACHE_SANDBOX_PATHS[pm];
+  return sandboxPath ? { hostPath, sandboxPath } : undefined;
+}
+function resolveBurnWorkspaceMode(config2, platform = process.platform) {
+  if (config2.sandbox === "noSandbox")
+    return "mounted";
+  if (config2.burnWorkspace === "auto")
+    return platform === "linux" ? "mounted" : "isolated";
+  return config2.burnWorkspace;
+}
+function buildIsolatedSetupCommand(tempBranch, setupCommand) {
+  const hookFile = `${ISOLATED_REPO_PATH}/.git/hooks/post-commit`;
+  const parts = [
+    `git -C ${SANDBOX_WORKSPACE_PATH} config receive.denyCurrentBranch updateInstead`,
+    `git clone ${SANDBOX_WORKSPACE_PATH} ${ISOLATED_REPO_PATH}`,
+    `printf '#!/bin/sh\\nexec git push --quiet origin HEAD:%s\\n' '${tempBranch}' > ${hookFile}`,
+    `chmod +x ${hookFile}`
+  ];
+  if (setupCommand)
+    parts.push(`cd ${ISOLATED_REPO_PATH} && ${setupCommand}`);
+  return parts.join(" && ");
+}
+function buildWorkspaceNotes(mode) {
+  if (mode === "mounted") {
+    return "Work in the current directory \u2014 it is the repo checkout on your branch.";
+  }
+  return [
+    `Your working repository is \`${ISOLATED_REPO_PATH}\` \u2014 a clone on the container's fast native filesystem, with dependencies already installed. Do ALL work there: \`cd ${ISOLATED_REPO_PATH}\` first; every file you read, edit, test, and commit lives under it.`,
+    "",
+    `The directory you start in (\`${SANDBOX_WORKSPACE_PATH}\`) is a slow mounted mirror used only to collect your commits \u2014 never edit files, install, or run tests there. Your commits sync back automatically (a post-commit hook pushes them); just commit as normal.`,
+    "",
+    `If you are blocked and write \`BLOCKED.md\`, write it at \`${ISOLATED_REPO_PATH}/BLOCKED.md\` AND copy it to \`${SANDBOX_WORKSPACE_PATH}/BLOCKED.md\` so the orchestrator can see it.`
+  ].join(`
+`);
+}
+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;
@@ -2854,8 +2999,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);
@@ -2868,31 +3016,74 @@ function selectSandbox(config2) {
 async function realExecuteTicketRun(ctx, ticket, config2, token, model, land) {
   const { project, feature } = ctx;
   const tempBranch = ticketBranchName(feature.slug, ticket.seq, newId("b").slice(2, 10));
+  const workspaceMode = resolveBurnWorkspaceMode(config2);
   const template = readFileSync4(burnerTemplatePath(), "utf8");
   const prompt = renderTicketPrompt(template, {
     TICKET_JSON: buildTicketJson(ticket),
     FEATURE_BRIEF: buildFeatureBrief(feature),
     DOCS_DIGEST: readDocsDigestFromDisk(project.id, feature.slug),
-    COMMIT_CONVENTION: `ticket(${ticket.seq}): <summary>`
+    COMMIT_CONVENTION: `ticket(${ticket.seq}): <summary>`,
+    WORKSPACE_NOTES: buildWorkspaceNotes(workspaceMode)
   });
+  const toolchain = readRepoToolchain(project.repoPath);
+  const pm = detectPackageManager(toolchain);
+  const setupCommand = resolveSetupCommand(toolchain, config2.setupCommand);
+  const mounts = [];
+  if (config2.sandbox !== "noSandbox" && pm) {
+    const mount = cacheMountFor(pm, burnCacheDir(pm));
+    if (mount) {
+      mkdirSync4(mount.hostPath, { recursive: true });
+      mounts.push(mount);
+    }
+  }
+  const hookCommand = workspaceMode === "isolated" ? buildIsolatedSetupCommand(tempBranch, setupCommand) : setupCommand;
+  if (hookCommand) {
+    ctx.emitEvent({
+      type: "burn.setup",
+      message: workspaceMode === "isolated" ? `preparing isolated workspace (native-FS clone)${setupCommand ? ` + deps install: ${setupCommand}` : ""}` : `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,
+    ...hookCommand ? {
+      hooks: {
+        sandbox: {
+          onSandboxReady: [{ command: hookCommand, 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);
@@ -2909,6 +3100,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")
@@ -2957,14 +3149,28 @@ 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, SANDBOX_WORKSPACE_PATH = "/home/agent/workspace", ISOLATED_REPO_PATH = "/home/agent/repo", 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"];
+  PLACEHOLDERS = [
+    "TICKET_JSON",
+    "FEATURE_BRIEF",
+    "DOCS_DIGEST",
+    "COMMIT_CONVENTION",
+    "WORKSPACE_NOTES"
+  ];
+  PACKAGE_MANAGERS = ["bun", "pnpm", "yarn", "npm"];
+  PM_CACHE_SANDBOX_PATHS = {
+    bun: "~/.bun/install/cache",
+    yarn: "~/.cache/yarn",
+    npm: "~/.npm"
+  };
+  SETUP_HOOK_TIMEOUT_MS = 15 * 60000;
   ticketBurner = {
     id: "ticket-burner",
     run: (ctx) => burnRun(ctx, resolveBurnDeps(ctx))
@@ -4741,6 +4947,17 @@ import { eq as eq9, isNull } from "drizzle-orm";
 function listProjects(ctx) {
   return ctx.db.select().from(projects).where(isNull(projects.closedAt)).all().map(rowToProject);
 }
+function isTranslatedWindowsMount(repoPath, platform = process.platform) {
+  return platform === "linux" && /^\/mnt\/[a-z](\/|$)/i.test(repoPath);
+}
+function warnIfTranslatedMount(ctx, projectId, repoPath) {
+  if (!isTranslatedWindowsMount(repoPath))
+    return;
+  emitProject(ctx, projectId, {
+    type: "project.slow-path",
+    message: `${repoPath} is a Windows drive mounted into Linux (/mnt) \u2014 git and burns pay a per-file translation tax here; clone the repo into the Linux filesystem (e.g. ~/projects) for native speed`
+  });
+}
 async function openProject(ctx, repoPath) {
   await assertRepoTolerant(ctx, repoPath);
   const mainBranch = await detectMainBranchTolerant(ctx, repoPath);
@@ -4753,6 +4970,7 @@ async function openProject(ctx, repoPath) {
       type: "project.opened",
       message: `project ${existing.name} re-opened at ${repoPath} (${mainBranch})`
     });
+    warnIfTranslatedMount(ctx, existing.id, repoPath);
     return reopened;
   }
   const row = {
@@ -4769,6 +4987,7 @@ async function openProject(ctx, repoPath) {
     type: "project.opened",
     message: `project ${name} at ${repoPath} (${mainBranch})`
   });
+  warnIfTranslatedMount(ctx, project.id, repoPath);
   return project;
 }
 function closeProject(ctx, projectId) {
@@ -4843,11 +5062,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 };
@@ -5083,6 +5304,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.8",
+  "version": "1.0.10",
   "description": "Burn tickets into shipped features with Claude Code.",
   "license": "MIT",
   "type": "module",

package/skills/burner/implement-ticket.md

@@ -4,6 +4,18 @@
 
 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.
+
+## Where to work
+
+{{WORKSPACE_NOTES}}
+
 ## The ticket
 
 ```json
@@ -30,6 +42,8 @@ You are a single agent in a sandbox on branch `feature/<slug>`. You have **one t
 
    `{{COMMIT_CONVENTION}}`
 
+   Run any full suite **once**, capturing output to a file (`<test command> > /tmp/test-run.log 2>&1`; check the exit code), then grep the file for failures and details — never re-run the whole suite just to re-read or filter its output.
+
 5. **Self-review before you finish (forked code-review — two axes).** When all acceptance criteria pass, review your own diff along both axes, then fix what you find and re-run typecheck + tests:
    - **Standards** — does the diff follow the conventions of the surrounding code? Watch for the smells: duplicated logic (extract it), mysterious names (rename), primitive obsession (give the concept a type), speculative generality (delete anything the ticket did not ask for), feature envy, data clumps.
    - **Spec = this ticket** — is every acceptance criterion actually met, and is there **nothing in the diff the ticket did not ask for**? Missing and extra both count.
@@ -39,4 +53,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.