@lchase/kiln 0.5.0 → 0.6.0

package/README.md

@@ -42,6 +42,60 @@ Workflows (`workflows/*.yaml`) and prompts (`prompts/`) are read from the packag
 
 Each checkout is a git repo with a commit at `HEAD`. `tick` adds a worktree and leaves uncommitted files in the checkout as they are. The job edits the worktree, on branch `yak/<run-id>`. With the default `deliver: "local"`, Kiln does not push. `deliver: "pr"` pushes that branch and opens a draft pull request. See [Delivery and dependencies](#delivery-and-dependencies).
 
+## Sandbox
+
+Sandbox mode is off. Set it in the kiln config when agent steps should run inside yak's Docker sandbox instead of on the machine. A workflow block overrides the global one field by field. `mode` omitted means off at that layer. `allowDomains`, when set, replaces the list.
+
+```json
+{
+  "sandbox": { "mode": "docker" },
+  "workflows": {
+    "investigation": { "sandbox": { "mode": "off" } }
+  }
+}
+```
+
+`image` overrides `yak-agent-sandbox:latest`. Leave it unset to use that tag.
+
+With mode `docker`, tick injects `sandbox: docker` and `allowedDomains` under every agent step in the rendered workflow. The default allowlist is exact hostnames, matched by the proxy as `dstdomain` (a subdomain is not implied):
+
+- `api.anthropic.com`
+- `registry.npmjs.org`
+- `github.com`
+- `api.github.com`
+- `codeload.github.com`
+- `objects.githubusercontent.com`
+- `raw.githubusercontent.com`
+
+That is the Anthropic API, the npm registry, and the GitHub hosts a fetch or install dials. It is not the open internet.
+
+| Step | Where it runs |
+| --- | --- |
+| feature: spec, build, security, ux, ui, code, approver | Docker sandbox |
+| investigation: explore | Docker sandbox |
+| fix: build | Docker sandbox. A pull-request fix uses the same allowlist. |
+| feature: verify | Host. It runs `KILN_TEST` through Kiln's truncate wrapper. Yak's command sandbox does not forward that environment and uses `--network none`. |
+| approve gates | Host. A person answers them. |
+| feature: land, fix: land | Host. `git commit` uses the host git identity. Publishing the fix branch is the kiln process. |
+| Pull request open, `git push`, `gh pr view`, feedback reads | Host kiln process. They are not workflow steps. |
+
+`kiln sandbox` prints the resolved mode, the allowlist, and anything still missing. `kiln sandbox build` builds the images yak ships but does not publish, from the tag that matches the installed `@lchase/yak`:
+
+```bash
+docker build -t yak-agent-sandbox:latest https://github.com/lchase/yak.git#yak-v0.7.1:docker/agent-sandbox
+docker build -t yak-agent-sandbox-proxy:latest https://github.com/lchase/yak.git#yak-v0.7.1:docker/agent-proxy
+```
+
+The agent image is `node:22-slim` plus the Claude CLI at `/app/claude-cli`. It has no git. `kiln sandbox build` adds `git` and `ca-certificates` and tags that result `yak-agent-sandbox:latest` as well. The proxy image is `yak-agent-sandbox-proxy:latest` (squid on port 3128). Yak mounts the worktree at `/workspace` and puts the container on an `--internal` network whose only egress is that proxy.
+
+A linked worktree's `.git` file points at the checkout's common git dir, which is outside that mount. `git` inside the container cannot see the repository until yak mounts that dir too. Land stays on the host, where the worktree link works.
+
+On macOS, Claude subscription auth lives in the keychain. Yak forwards only `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` into the container, and never a `~/.claude` directory. Before the first sandboxed launch, run `claude setup-token` and export `CLAUDE_CODE_OAUTH_TOKEN` in the environment that `kiln tick` or `kiln serve` inherits. Kiln checks that the variable is set. It does not print or write the value. An API key in `ANTHROPIC_API_KEY` works the same way.
+
+`kiln tick` and `kiln serve` name what is missing when sandbox mode is on: the docker binary, the docker daemon, each image, the credential, and a yak build that actually reads `allowedDomains` from the workflow. Installed `@lchase/yak` 0.7.1 drops `sandbox`, `image`, and `allowedDomains` while loading YAML, and opens the proxy with only `api.anthropic.com`. Kiln refuses to launch in that case, because the job would run on the host with the open internet. The job stays failed until `kiln retry`, after that piece is fixed. The yak change that copies those fields and passes `allowedDomains` into `createAgentSandboxNetwork` has to be in the installed package first.
+
+A step that fails with yak reason `sandbox-error` goes to Needs human. The card shows the failure detail. Kiln does not schedule an automatic retry for it. The card of a sandboxed job shows `sandbox · docker` in the same monospace metadata as the rest of the board.
+
 ## Register repos
 
 ```bash

package/dist/attention.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { INVESTIGATION_WORKFLOW } from "./findings.js";
+import { SANDBOX_PREFLIGHT_PREFIX } from "./sandbox.js";
 /**
  * Attention order for `kiln serve`. Built from the same derived jobs as
  * `kiln status`. The console renders this and does not classify jobs again.
@@ -103,9 +104,11 @@ export function attentionReason(job, tail = errorTail(job)) {
             return question ? `Gate: ${oneLine(question)}` : "Waiting on a person";
         }
         case "dead":
-            return "Run died before it finished";
+            return job.sandboxError ? `Sandbox: ${oneLine(job.sandboxError)}` : "Run died before it finished";
         case "failed": {
-            const why = firstLine(job.launchError) || firstLine(job.deliveryError) || firstLine(job.failureDetail) || firstLine(tail) || "Run failed";
+            if (job.sandboxError)
+                return `Sandbox: ${oneLine(job.sandboxError)}`;
+            const why = failureLine(job.launchError) || firstLine(job.deliveryError) || firstLine(job.failureDetail) || firstLine(tail) || "Run failed";
             return `Failed: ${oneLine(why)}`;
         }
         case "in-review":
@@ -228,6 +231,7 @@ function attentionRevision(needsYou, inFlight, doneRecently, graph) {
             item.job.lastFailureReason ?? "",
             item.job.nextRetryAt ?? "",
             feedbackStamp(item.job),
+            item.job.sandboxed ? "sandbox" : "",
         ]),
         inFlight: inFlight.map((item) => [
             item.job.jobId,
@@ -238,6 +242,7 @@ function attentionRevision(needsYou, inFlight, doneRecently, graph) {
             item.job.lastFailureReason ?? "",
             item.job.nextRetryAt ?? "",
             feedbackStamp(item.job),
+            item.job.sandboxed ? "sandbox" : "",
         ]),
         doneRecently: doneRecently.map((item) => [item.job.jobId, item.job.state]),
         edges: graph.edges.map((edge) => [edge.from, edge.to, edge.stack]),
@@ -262,3 +267,14 @@ function firstLine(text) {
     const line = text.split("\n").find((candidate) => candidate.trim().length > 0);
     return line?.trim();
 }
+/** The preflight header names the policy. The card should name the missing piece. */
+function failureLine(text) {
+    const line = firstLine(text);
+    if (!line?.startsWith(SANDBOX_PREFLIGHT_PREFIX))
+        return line;
+    const bullet = text
+        ?.split("\n")
+        .map((candidate) => candidate.trim())
+        .find((candidate) => candidate.startsWith("- "));
+    return bullet ? bullet.slice(2) : line;
+}

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { addRepo, renderRepoList, resolveKilnConfig } from "./config.js";
+import { renderSandboxStatus, runSandboxBuild } from "./sandbox.js";
 import { answerJob, retryJob, runStatus, runTick } from "./driver.js";
 import { startServe } from "./serve.js";
 import { addFromFile } from "./intake/file.js";
@@ -18,6 +19,7 @@ function usage() {
         "       kiln approve <jobId> [--config <file>]",
         "       kiln reject <jobId> [--config <file>]",
         "       kiln retry <jobId> [--config <file>]",
+        "       kiln sandbox [build] [--config <file>]",
         "       kiln serve [--port 4100] [--tick <seconds>|--no-tick] [--config <file>]",
         "",
         "repo add registers a checkout. A relative path is stored absolute, resolved",
@@ -69,6 +71,11 @@ function usage() {
         "Empty stages collapse. Approve, reject, and retry call the same",
         "functions as the CLI. POST from another origin is rejected. A tick",
         "runs every 30 seconds unless --no-tick is set, using the tick lock.",
+        "",
+        "sandbox prints the resolved mode, allowlist, and anything missing before a",
+        "sandboxed run can start. sandbox build builds the yak agent and proxy images",
+        "and installs git into the agent image. Sandbox mode stays off until the kiln",
+        "config sets it. A run that fails with yak reason sandbox-error is not retried.",
     ].join("\n"));
     process.exit(2);
 }
@@ -315,6 +322,21 @@ function importCommand(argv) {
     if (result.warnings.length > 0)
         process.stderr.write(`${result.warnings.join("\n")}\n`);
 }
+function sandboxCommand(argv) {
+    const build = argv[0] === "build";
+    const flags = parseFlags(build ? argv.slice(1) : argv);
+    rejectServeFlags(flags);
+    if (flags.positionals.length !== 0 || flags.test || hasIntakeFlags(flags) || flags.deliver || flags.base || flags.stack) {
+        usage();
+    }
+    if (build) {
+        runSandboxBuild();
+        process.stdout.write("built yak-agent-sandbox:latest and yak-agent-sandbox-proxy:latest\n");
+        return;
+    }
+    const config = resolveKilnConfig({ configPath: flags.configPath });
+    process.stdout.write(renderSandboxStatus(config));
+}
 function tickCommand(argv) {
     const flags = parseFlags(argv);
     rejectServeFlags(flags);
@@ -422,6 +444,10 @@ async function main() {
         retryCommand(argv.slice(1));
         return;
     }
+    if (command === "sandbox") {
+        sandboxCommand(argv.slice(1));
+        return;
+    }
     if (command === "serve") {
         await serveCommand(argv.slice(1));
         return;

package/dist/config.js

@@ -49,6 +49,8 @@ export function loadKilnConfig(configPath, options = {}) {
         maxAttempts: parsed.data.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
         maxFixRounds: parsed.data.maxFixRounds ?? DEFAULT_MAX_FIX_ROUNDS,
         adapter: parsed.data.adapter ?? "claude-code",
+        sandbox: parsed.data.sandbox ?? {},
+        workflowSandbox: workflowSandboxFrom(parsed.data.workflows),
         ...(jira ? { jira } : {}),
     };
 }
@@ -235,6 +237,16 @@ function pathToStore(userPath, cwd, home) {
         return userPath;
     return resolve(cwd, userPath);
 }
+function workflowSandboxFrom(workflows) {
+    if (!workflows)
+        return {};
+    const out = {};
+    for (const [name, entry] of Object.entries(workflows)) {
+        if (entry.sandbox)
+            out[name] = entry.sandbox;
+    }
+    return out;
+}
 function jiraFromFile(jira) {
     if (!jira)
         return undefined;

package/dist/driver.js

@@ -11,7 +11,8 @@ import { readJobSpec, resolveJobSpec } from "./jobs.js";
 import { jobBasename, packageRoot } from "./paths.js";
 import { decide, isLanded, jobState, } from "./reconcile.js";
 import { fileMtimeMs, isPidAlive, readAttemptLedger, recoverRuns, resetAttemptLedger, } from "./reliability.js";
-import { gateAnswerCommand, renderStatus, renderTick, statusView, yakCliPath, } from "./report.js";
+import { gateAnswerCommand, renderStatus, renderTick, statusView, yakCliPath, sandboxFailureDetail, } from "./report.js";
+import { AGENT_SANDBOX_IMAGE, injectAgentSandbox, jobIsSandboxed, probeSandboxEnvironment, PROXY_SANDBOX_IMAGE, requiredSandboxImages, resolveSandbox, sandboxIsEnabled, sandboxPreflight, sandboxPreflightFor, } from "./sandbox.js";
 import { JobSchema } from "./schemas.js";
 import { leafStepIds, materializeWorkflow, workflowInputs, workflowNeedsTestCommand, workflowStepPlan } from "./workflow.js";
 const TAG_PREFIX = "kiln:";
@@ -39,13 +40,18 @@ export function runTick(config, host = defaultHost(), options = {}) {
     const now = options.now ?? new Date();
     return withTickLock(config.kilnDir, () => {
         const notes = recoverRuns(config, observe(config, host).observation.jobs, { startup, now });
+        const facts = sandboxIsEnabled(config)
+            ? (options.sandboxFacts ?? probeSandboxEnvironment(process.env, requiredSandboxImages(config)))
+            : undefined;
         const midway = observe(config, host);
         bindOpenFixRuns(config, midway);
         const published = publishReadyFixes(config, host, midway);
         const world = observe(config, host);
         const feedbackNotes = watchPullRequests(config, world, host);
         const actions = decide(world.observation, now);
-        return apply(config, world, actions, host, notes, now, [...published, ...feedbackNotes]);
+        const body = apply(config, world, actions, host, notes, now, [...published, ...feedbackNotes], facts);
+        const problem = facts ? sandboxPreflight(config, facts) : undefined;
+        return problem ? `${problem}\n${body}` : body;
     });
 }
 /** Startup pass shared by `kiln tick` (via `runTick`) and `kiln serve`. Idempotent. */
@@ -247,6 +253,7 @@ function observe(config, host) {
             ...(exhausted ? { retriesExhausted: true } : {}),
             ...(picked.retired ? { runRetired: true } : {}),
             ...(ledgerResult === "corrupt" ? { ledgerError: "attempt ledger is unreadable" } : {}),
+            ...(entry.job ? { sandboxed: jobIsSandboxed(config, entry.job.id, entry.job.workflow) } : {}),
             ...(feedback?.rounds.length ? { feedbackRounds: feedback.rounds } : {}),
             ...(feedback?.exhausted ? { feedbackExhausted: true } : {}),
             ...(feedback?.ambiguous ? { feedbackAmbiguous: true } : {}),
@@ -268,7 +275,7 @@ function observe(config, host) {
         jobs: records,
     };
 }
-function apply(config, world, actions, host, notes = [], now = new Date(), feedbackNotes = []) {
+function apply(config, world, actions, host, notes = [], now = new Date(), feedbackNotes = [], sandboxFacts) {
     const launches = [];
     const delivers = [];
     const findings = [];
@@ -297,7 +304,12 @@ function apply(config, world, actions, host, notes = [], now = new Date(), feedb
             if (!job) {
                 throw new Error(`Tick planned a fix for ${action.jobId}, which is not in the observed jobs.`);
             }
-            const report = startFix(config, world, job, host, now);
+            const blocked = sandboxBlock(config, "fix", sandboxFacts);
+            if (blocked) {
+                feedbackNotes.push(`fix ${action.jobId} not started\n${blocked}`);
+                continue;
+            }
+            const report = startFix(config, world, job, host, now, sandboxFacts);
             launches.push({ ...report, kind: "fix" });
             continue;
         }
@@ -305,7 +317,7 @@ function apply(config, world, actions, host, notes = [], now = new Date(), feedb
         if (!job) {
             throw new Error(`Tick planned a launch for ${action.jobId}, which is not in the observed jobs.`);
         }
-        const report = launchJob(config, world, job, host);
+        const report = launchJob(config, world, job, host, sandboxFacts);
         launches.push(action.type === "retry" ? { ...report, retry: true } : report);
     }
     return renderTick(world.observation, actions, launches, delivers, findings, notes, feedbackNotes);
@@ -620,7 +632,7 @@ function markFeedback(kilnDir, jobId, reason) {
  * The round is written only after that commit resolves, so a missing sha
  * retries on the next tick without consuming a round.
  */
-function startFix(config, world, job, host, now) {
+function startFix(config, world, job, host, now, sandboxFacts) {
     const observed = world.observation.jobs.find((candidate) => candidate.jobId === job.id);
     const plan = observed?.feedbackPlan;
     const repo = config.repos[job.repo];
@@ -661,11 +673,11 @@ function startFix(config, world, job, host, now) {
         writeBreadcrumb(breadcrumbPath(config.kilnDir, job.id), { jobId: job.id, pid: 0, logPath });
         return { jobId: job.id, repo: job.repo, kind: "fix", output: message };
     }
-    const report = launchFixRun(config, job, host, repo.path, headSha, specText);
+    const report = launchFixRun(config, job, host, repo.path, headSha, specText, sandboxFacts);
     return { ...report, output: `round ${round}\n${report.output}` };
 }
 /** Relaunch the open fix round. Does not append a round. Failures become a dead launch so retry can see them. */
-function launchOpenFix(config, world, job, host, checkout, open) {
+function launchOpenFix(config, world, job, host, checkout, open, sandboxFacts) {
     let specText;
     let headSha;
     try {
@@ -682,7 +694,7 @@ function launchOpenFix(config, world, job, host, checkout, open) {
         writeBreadcrumb(breadcrumbPath(config.kilnDir, job.id), { jobId: job.id, pid: 0, logPath });
         return { jobId: job.id, repo: job.repo, kind: "fix", output: message };
     }
-    return launchFixRun(config, job, host, checkout, headSha, specText);
+    return launchFixRun(config, job, host, checkout, headSha, specText, sandboxFacts);
 }
 function resolveCommit(host, checkout, sha) {
     try {
@@ -694,12 +706,15 @@ function resolveCommit(host, checkout, sha) {
     }
 }
 /** `workflows/fix.yaml` on `headSha`. Commits on `yak/<run-id>`. Does not push. */
-function launchFixRun(config, job, host, checkout, headSha, specText) {
+function launchFixRun(config, job, host, checkout, headSha, specText, sandboxFacts) {
     const sourceWorkflow = readFileSync(join(packageRoot(), "workflows", "fix.yaml"), "utf8");
     const workflow = materializeWorkflow(config.kilnDir, job.id, "fix");
     const repo = config.repos[job.repo];
     const logPath = join(config.kilnDir, "logs", `${jobBasename(job.id)}.log`);
     mkdirSync(dirname(logPath), { recursive: true });
+    const blocked = commitAgentSandbox(config, job.id, "fix", workflow, logPath, sandboxFacts);
+    if (blocked)
+        return { jobId: job.id, repo: job.repo, kind: "fix", output: blocked };
     ensureCheckoutExcludes(checkout);
     const input = workflowInputs(sourceWorkflow, {
         title: job.title,
@@ -724,6 +739,34 @@ function launchFixRun(config, job, host, checkout, headSha, specText) {
         logPath,
     });
 }
+/**
+ * Names why a sandboxed workflow cannot launch. Does not write a round or a
+ * breadcrumb. `undefined` when this workflow stays on the host or the checks pass.
+ */
+function sandboxBlock(config, workflowName, sandboxFacts) {
+    const sandbox = resolveSandbox(config.sandbox, config.workflowSandbox[workflowName]);
+    if (sandbox.mode !== "docker")
+        return undefined;
+    const checked = sandboxFacts ??
+        probeSandboxEnvironment(process.env, [PROXY_SANDBOX_IMAGE, sandbox.image ?? AGENT_SANDBOX_IMAGE]);
+    return sandboxPreflightFor(sandbox, config.adapter, checked);
+}
+/**
+ * Inject `sandbox: docker` into a materialized workflow and refuse the launch
+ * when preflight fails. The refusal is a launch error with no yak process.
+ */
+function commitAgentSandbox(config, jobId, workflowName, workflowPath, logPath, sandboxFacts) {
+    const sandbox = resolveSandbox(config.sandbox, config.workflowSandbox[workflowName]);
+    if (sandbox.mode !== "docker")
+        return undefined;
+    writeFileSync(workflowPath, injectAgentSandbox(readFileSync(workflowPath, "utf8"), sandbox));
+    const problem = sandboxBlock(config, workflowName, sandboxFacts);
+    if (!problem)
+        return undefined;
+    writeLaunchError(config.kilnDir, jobId, problem);
+    writeFileSync(logPath, `${problem}\n`);
+    return problem;
+}
 function agentArgs(config, job, workflow, headSha, input) {
     const args = [
         yakCliPath(),
@@ -783,7 +826,7 @@ function spawnAgent(host, spec) {
     child.unref();
     return { pid: child.pid ?? 0 };
 }
-function launchJob(config, world, job, host) {
+function launchJob(config, world, job, host, sandboxFacts) {
     const repo = config.repos[job.repo];
     if (!repo) {
         throw new Error(`Repo ${job.repo} is not registered. Run kiln repo add ${job.repo} <path>.`);
@@ -791,7 +834,7 @@ function launchJob(config, world, job, host) {
     const feedback = readFeedbackLedger(config.kilnDir, job.id);
     const open = feedback && feedback !== "corrupt" ? openFeedbackRound(feedback) : undefined;
     if (open)
-        return launchOpenFix(config, world, job, host, repo.path, open);
+        return launchOpenFix(config, world, job, host, repo.path, open, sandboxFacts);
     const sourceWorkflow = readFileSync(join(packageRoot(), "workflows", `${job.workflow}.yaml`), "utf8");
     const testCommand = repo.test;
     if (workflowNeedsTestCommand(sourceWorkflow) && !testCommand?.trim()) {
@@ -805,6 +848,9 @@ function launchJob(config, world, job, host) {
     let specText;
     try {
         clearLaunchError(config.kilnDir, job.id);
+        const blocked = commitAgentSandbox(config, job.id, job.workflow, workflow, logPath, sandboxFacts);
+        if (blocked)
+            return { jobId: job.id, repo: job.repo, output: blocked };
         assertStackTarget(world, job);
         baseSha = resolveLaunchBase({
             checkout: repo.path,
@@ -887,6 +933,7 @@ function scanRuns(config) {
             const finished = [...events].reverse().find((event) => event.t === "run.finished");
             const stepPlan = readRunStepPlan(runDir);
             const stepEvents = stepEventsFrom(events);
+            const sandboxError = sandboxFailureDetail(stepEvents);
             const pid = livePid(events);
             const activityMs = eventActivityMs(events) ?? fileMtimeMs(join(runDir, "journal.jsonl"));
             const finishedReason = finished && typeof finished.reason === "string" ? finished.reason : undefined;
@@ -904,6 +951,7 @@ function scanRuns(config) {
                 ...(pid !== undefined ? { pid } : {}),
                 ...(activityMs !== undefined ? { activityMs } : {}),
                 ...(finishedReason ? { finishedReason } : {}),
+                ...(sandboxError ? { sandboxError } : {}),
             };
             const list = byTag.get(started.tag) ?? [];
             list.push(run);
@@ -919,11 +967,12 @@ function stepEventsFrom(events) {
             continue;
         if (!event.stepId)
             continue;
-        const detail = event.t === "step.failed" ? formatFailure(event.failure) : undefined;
+        const failure = event.t === "step.failed" ? formatFailure(event.failure) : undefined;
         found.push({
             t: event.t,
             stepId: event.stepId,
-            ...(detail ? { detail } : {}),
+            ...(failure?.detail ? { detail: failure.detail } : {}),
+            ...(failure?.reason ? { failureReason: failure.reason } : {}),
         });
     }
     return found;
@@ -934,7 +983,12 @@ function formatFailure(failure) {
     const detail = typeof failure.detail === "string" ? failure.detail.trim() : "";
     const reason = typeof failure.reason === "string" ? failure.reason.trim() : "";
     const text = detail && reason ? `${detail} (${reason})` : detail || reason;
-    return text || undefined;
+    if (!text && !reason)
+        return undefined;
+    return {
+        ...(text ? { detail: text } : {}),
+        ...(reason ? { reason } : {}),
+    };
 }
 function readRunStepPlan(runDir) {
     const file = join(runDir, "workflow.json");

package/dist/reliability.js

@@ -90,6 +90,10 @@ export function recoverRuns(config, jobs, options) {
         const existing = readAttemptLedger(config.kilnDir, job.jobId);
         if (existing === "corrupt")
             continue;
+        if (job.run?.sandboxError && job.run.status !== "alive") {
+            suppressAutomaticRetry(config.kilnDir, job.jobId);
+            continue;
+        }
         const pending = pendingFailure(job, config, options);
         if (!pending)
             continue;
@@ -113,6 +117,18 @@ export function recoverRuns(config, jobs, options) {
     }
     return notes;
 }
+/** Drop a scheduled retry so a sandbox failure stays in Needs human. */
+function suppressAutomaticRetry(kilnDir, jobId) {
+    const existing = readAttemptLedger(kilnDir, jobId);
+    if (!existing || existing === "corrupt" || !existing.nextRetryAt)
+        return;
+    const written = {
+        jobId: existing.jobId,
+        attempts: existing.attempts,
+        ...(existing.ignoredRunIds && existing.ignoredRunIds.length > 0 ? { ignoredRunIds: existing.ignoredRunIds } : {}),
+    };
+    writeLedger(kilnDir, written);
+}
 function pendingFailure(job, config, options) {
     if (job.run?.gateDecision === "reject")
         return undefined;

package/dist/report.js

@@ -77,6 +77,27 @@ export function latestStepFailure(events) {
     }
     return undefined;
 }
+/**
+ * Detail of the latest unresolved step whose yak reason is `sandbox-error`.
+ * The `(sandbox-error)` suffix formatFailure adds is stripped.
+ */
+export function sandboxFailureDetail(events) {
+    const settled = new Set();
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (!event)
+            continue;
+        if (event.t === "step.started" || event.t === "step.completed") {
+            settled.add(event.stepId);
+            continue;
+        }
+        if (event.t !== "step.failed" || settled.has(event.stepId) || event.failureReason !== "sandbox-error")
+            continue;
+        const text = (event.detail ?? "").replace(/\s*\(sandbox-error\)\s*$/, "").trim();
+        return text || "The sandbox could not run this step.";
+    }
+    return undefined;
+}
 /**
  * Derived state for every job, or for one id.
  * Throws `No job <id>` when that id is not on disk, same as `kiln status`.
@@ -124,6 +145,11 @@ export function statusDetails(job) {
         lines.push(`log ${job.logPath}`);
     if (job.state === "failed" && job.launchError)
         lines.push(job.launchError);
+    if (job.sandboxError && (job.state === "failed" || job.state === "dead" || job.state === "needs-human")) {
+        lines.push(`sandbox ${job.sandboxError}`);
+    }
+    if (job.sandboxed)
+        lines.push("sandbox docker");
     if (job.ledgerError)
         lines.push(job.ledgerError);
     if (job.feedbackLedgerError)
@@ -257,6 +283,8 @@ function toStatusJob(job, observation) {
         ...(job.logTail ? { logTail: job.logTail } : {}),
         ...(job.diffSummary ? { diffSummary: job.diffSummary } : {}),
         ...(failureDetail ? { failureDetail } : {}),
+        ...(job.run?.sandboxError ? { sandboxError: job.run.sandboxError } : {}),
+        ...(job.sandboxed ? { sandboxed: true } : {}),
         ...boardFields(job),
     };
 }

package/dist/sandbox.js

@@ -0,0 +1,363 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { jobBasename } from "./paths.js";
+/**
+ * Opt-in Docker sandbox for Kiln agent steps.
+ *
+ * Off unless kiln config sets `sandbox.mode` to `docker` (a per-workflow
+ * block can override that). Kiln injects `sandbox: docker` under each
+ * agent step. verify, the approve gate, and land stay on the host: yak's
+ * command sandbox does not forward `KILN_TEST` or the truncate wrapper,
+ * and land commits with the host git identity. Pull requests and
+ * `gh pr view` run in the kiln process.
+ *
+ * @lchase/yak 0.7.1 drops `sandbox`, `image`, and `allowedDomains` while
+ * loading workflow YAML, and calls `createAgentSandboxNetwork` with only
+ * `api.anthropic.com`. Kiln refuses to launch while that is still true,
+ * because the job would run on the host.
+ */
+export const AGENT_SANDBOX_IMAGE = "yak-agent-sandbox:latest";
+export const PROXY_SANDBOX_IMAGE = "yak-agent-sandbox-proxy:latest";
+export const CONTAINER_CLI_PATH = "/app/claude-cli";
+export const CONTAINER_WORKDIR = "/workspace";
+/**
+ * Hosts a coding agent needs on a typical Node repo, and nothing wider.
+ * `api.anthropic.com` is the model API. The rest are npm and the GitHub
+ * hosts a fetch or an install actually dials. Exact hostnames only: the
+ * proxy matches `dstdomain` without a leading dot, so a subdomain is not
+ * implied.
+ */
+export const DEFAULT_SANDBOX_DOMAINS = [
+    "api.anthropic.com",
+    "registry.npmjs.org",
+    "github.com",
+    "api.github.com",
+    "codeload.github.com",
+    "objects.githubusercontent.com",
+    "raw.githubusercontent.com",
+];
+/** Printed at the start of a tick when sandbox mode is on and a check failed. */
+export const SANDBOX_PREFLIGHT_PREFIX = "Sandbox is on, and a sandboxed run cannot start:";
+/** Present in a yak build that copies `allowedDomains` off the agent step. */
+export const YAK_ALLOWLIST_MARKER = "raw.agent.allowedDomains";
+/**
+ * Workflow override wins per field. An omitted field inherits the global
+ * setting, then the built-in default. `allowDomains`, when set, replaces
+ * the list rather than extending it, so a tighter workflow cannot keep a
+ * wider global host by accident.
+ */
+export function resolveSandbox(global, workflow) {
+    const mode = workflow?.mode ?? global?.mode ?? "off";
+    const image = workflow?.image ?? global?.image;
+    const allowDomains = workflow?.allowDomains ?? global?.allowDomains ?? DEFAULT_SANDBOX_DOMAINS;
+    return {
+        mode,
+        allowDomains: [...allowDomains],
+        ...(image ? { image } : {}),
+    };
+}
+/** Resolved sandboxes that would actually containerize a packaged or configured workflow. */
+export function sandboxTargets(config) {
+    const names = new Set(["feature", "investigation", "fix", ...Object.keys(config.workflowSandbox)]);
+    const targets = [];
+    for (const name of names) {
+        const resolved = resolveSandbox(config.sandbox, config.workflowSandbox[name]);
+        if (resolved.mode === "docker")
+            targets.push(resolved);
+    }
+    return targets;
+}
+export function sandboxIsEnabled(config) {
+    return sandboxTargets(config).length > 0;
+}
+export function requiredSandboxImages(config) {
+    const targets = sandboxTargets(config);
+    if (targets.length === 0)
+        return [];
+    const images = new Set([PROXY_SANDBOX_IMAGE]);
+    for (const target of targets)
+        images.add(target.image ?? AGENT_SANDBOX_IMAGE);
+    return [...images];
+}
+/**
+ * Insert `sandbox: docker` as the first keys of every `agent:` block.
+ * Command steps, gates, and comments are left alone. A block that already
+ * has `sandbox:` is not edited again.
+ */
+export function injectAgentSandbox(yaml, sandbox) {
+    if (sandbox.mode !== "docker")
+        return yaml;
+    const lines = yaml.split("\n");
+    const out = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        out.push(line);
+        const match = /^(\s*)agent:\s*(?:#.*)?$/.exec(line);
+        if (!match)
+            continue;
+        const base = match[1]?.length ?? 0;
+        if (blockHasKey(lines, index + 1, base, "sandbox"))
+            continue;
+        const child = childIndent(lines, index + 1, base);
+        const pad = " ".repeat(child);
+        out.push(`${pad}sandbox: docker`);
+        if (sandbox.image)
+            out.push(`${pad}image: ${yamlDoubleQuote(sandbox.image)}`);
+        out.push(`${pad}allowedDomains:`);
+        for (const domain of sandbox.allowDomains)
+            out.push(`${pad}  - ${domain}`);
+    }
+    return out.join("\n");
+}
+/**
+ * True when this job's rendered workflow sandboxes agents.
+ * A job that has not been rendered yet follows the current config.
+ */
+export function jobIsSandboxed(config, jobId, workflow) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(workflow)) {
+        return resolveSandbox(config.sandbox, config.workflowSandbox[workflow]).mode === "docker";
+    }
+    const dir = join(config.kilnDir, "rendered", jobBasename(jobId));
+    const names = workflow === "fix" ? ["fix.yaml"] : [`${workflow}.yaml`, "fix.yaml"];
+    let sawRender = false;
+    for (const name of names) {
+        try {
+            const text = readFileSync(join(dir, name), "utf8");
+            sawRender = true;
+            if (/^\s*sandbox:\s*docker\s*$/m.test(text))
+                return true;
+        }
+        catch {
+            // That render is absent.
+        }
+    }
+    if (sawRender)
+        return false;
+    return resolveSandbox(config.sandbox, config.workflowSandbox[workflow]).mode === "docker";
+}
+export function yakDistHonorsAllowlist(distSource) {
+    return distSource.includes(YAK_ALLOWLIST_MARKER);
+}
+export function credentialPresent(env) {
+    return Boolean(env.ANTHROPIC_API_KEY?.trim() || env.CLAUDE_CODE_OAUTH_TOKEN?.trim());
+}
+/**
+ * Names every missing piece. Returns undefined when this sandbox can launch.
+ * The text never includes an environment value.
+ */
+export function sandboxPreflightFor(sandbox, adapter, facts) {
+    if (sandbox.mode !== "docker")
+        return undefined;
+    return formatPreflight(missingPieces([sandbox.image ?? AGENT_SANDBOX_IMAGE], adapter, facts));
+}
+/** Union of every workflow whose resolved mode is docker. */
+export function sandboxPreflight(config, facts) {
+    const images = requiredSandboxImages(config);
+    if (images.length === 0)
+        return undefined;
+    const agentImages = images.filter((image) => image !== PROXY_SANDBOX_IMAGE);
+    return formatPreflight(missingPieces(agentImages, config.adapter, facts));
+}
+export function sandboxPreflightMessage(config, facts) {
+    if (!sandboxIsEnabled(config))
+        return undefined;
+    return sandboxPreflight(config, facts ?? probeSandboxEnvironment(process.env, requiredSandboxImages(config)));
+}
+/**
+ * `docker` argv yak 0.7.1 builds for one sandboxed agent step
+ * (`dockerAgentRunArgs` in `@lchase/yak`). Kiln does not spawn docker
+ * itself. Credential values are copied through so a test can show the
+ * shape; do not log the result when `env` holds a real token.
+ */
+export function agentSandboxDockerArgs(input) {
+    const env = input.env ?? {};
+    const credentialEnv = ["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"]
+        .filter((key) => env[key] !== undefined)
+        .flatMap((key) => ["-e", `${key}=${env[key]}`]);
+    return [
+        "run",
+        "--rm",
+        "-i",
+        "--network",
+        input.networkName,
+        "-v",
+        `${input.cwd}:${CONTAINER_WORKDIR}`,
+        "-w",
+        CONTAINER_WORKDIR,
+        "-e",
+        `HTTPS_PROXY=${input.proxyUrl}`,
+        "-e",
+        `HTTP_PROXY=${input.proxyUrl}`,
+        ...credentialEnv,
+        input.image ?? AGENT_SANDBOX_IMAGE,
+        CONTAINER_CLI_PATH,
+        ...input.cliArgs,
+    ];
+}
+/** Proxy sidecar argv from yak's `startProxyArgs`. */
+export function proxySandboxDockerArgs(networkName, allowedDomains) {
+    return [
+        "run",
+        "-d",
+        "--rm",
+        "--name",
+        `${networkName}-proxy`,
+        "--network",
+        networkName,
+        "-e",
+        `ALLOWED_DOMAINS=${allowedDomains.join(",")}`,
+        PROXY_SANDBOX_IMAGE,
+    ];
+}
+export function sandboxImageBuildArgs(yakVersion) {
+    const ref = `yak-v${yakVersion}`;
+    const remote = "https://github.com/lchase/yak.git";
+    return [
+        ["build", "-t", AGENT_SANDBOX_IMAGE, `${remote}#${ref}:docker/agent-sandbox`],
+        ["build", "-t", PROXY_SANDBOX_IMAGE, `${remote}#${ref}:docker/agent-proxy`],
+    ];
+}
+/** git is not in yak's node:22-slim agent image. Agents shell out to git. */
+export function sandboxGitOverlayDockerfile() {
+    return [
+        "FROM yak-agent-sandbox:latest",
+        "USER root",
+        "RUN apt-get update \\",
+        " && apt-get install -y --no-install-recommends git ca-certificates \\",
+        " && rm -rf /var/lib/apt/lists/*",
+        "",
+    ].join("\n");
+}
+export function renderSandboxStatus(config, facts) {
+    const names = [...new Set(["feature", "investigation", "fix", ...Object.keys(config.workflowSandbox)])].sort();
+    const lines = names.map((name) => {
+        const resolved = resolveSandbox(config.sandbox, config.workflowSandbox[name]);
+        const image = resolved.image ? `  image ${resolved.image}` : "";
+        const domains = resolved.mode === "docker" ? `  allow ${resolved.allowDomains.join(" ")}` : "";
+        return `${name}  ${resolved.mode}${image}${domains}`;
+    });
+    const problem = sandboxPreflightMessage(config, facts);
+    lines.push(problem ?? (sandboxIsEnabled(config) ? "sandbox ready" : "sandbox off"));
+    return `${lines.join("\n")}\n`;
+}
+export function runSandboxBuild() {
+    const version = installedYakVersion();
+    for (const args of sandboxImageBuildArgs(version))
+        runDocker(args);
+    const dir = mkdtempSync(join(tmpdir(), "kiln-sandbox-"));
+    const file = join(dir, "Dockerfile");
+    writeFileSync(file, sandboxGitOverlayDockerfile());
+    runDocker(["build", "-t", AGENT_SANDBOX_IMAGE, "-f", file, dir]);
+}
+export function probeSandboxEnvironment(env = process.env, images = [AGENT_SANDBOX_IMAGE, PROXY_SANDBOX_IMAGE]) {
+    const binary = dockerResult(["--version"]);
+    const dockerBinary = binary.status === 0;
+    const daemon = dockerBinary ? dockerResult(["info"]) : undefined;
+    const present = dockerBinary && daemon?.status === 0
+        ? images.filter((name) => dockerResult(["image", "inspect", name]).status === 0)
+        : [];
+    const yak = readInstalledYak();
+    return {
+        dockerBinary,
+        dockerDaemon: daemon?.status === 0,
+        images: present,
+        yakVersion: yak.version,
+        yakDist: yak.dist,
+        env,
+    };
+}
+function missingPieces(agentImages, adapter, facts) {
+    const missing = [];
+    if (!facts.dockerBinary) {
+        missing.push("docker binary is not on PATH");
+    }
+    else if (!facts.dockerDaemon) {
+        missing.push("docker daemon is not reachable");
+    }
+    else {
+        if (!facts.images.includes(PROXY_SANDBOX_IMAGE)) {
+            missing.push(`image ${PROXY_SANDBOX_IMAGE} is missing (kiln sandbox build)`);
+        }
+        for (const image of agentImages) {
+            if (!facts.images.includes(image))
+                missing.push(`image ${image} is missing (kiln sandbox build)`);
+        }
+    }
+    if (adapter === "claude-code" && !credentialPresent(facts.env)) {
+        missing.push("no Claude credential for the sandbox. The container only receives ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN. macOS keychain login is not forwarded. Run `claude setup-token` and export CLAUDE_CODE_OAUTH_TOKEN for this kiln process.");
+    }
+    if (!yakDistHonorsAllowlist(facts.yakDist)) {
+        missing.push(`installed @lchase/yak ${facts.yakVersion} does not pass allowedDomains from a workflow step into the sandbox proxy. @lchase/yak 0.7.1 drops sandbox, image, and allowedDomains when it loads workflow YAML, and the proxy allowlist stays api.anthropic.com. Kiln will not launch an unsandboxed run while sandbox mode is docker.`);
+    }
+    return missing;
+}
+function formatPreflight(missing) {
+    if (missing.length === 0)
+        return undefined;
+    return `${SANDBOX_PREFLIGHT_PREFIX}\n${missing.map((line) => `- ${line}`).join("\n")}`;
+}
+function childIndent(lines, start, base) {
+    for (let index = start; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        if (line.trim().length === 0)
+            continue;
+        const indent = /^(\s*)/.exec(line)?.[1]?.length ?? 0;
+        if (indent <= base)
+            break;
+        return indent;
+    }
+    return base + 2;
+}
+function blockHasKey(lines, start, base, key) {
+    for (let index = start; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        if (line.trim().length === 0)
+            continue;
+        const indent = /^(\s*)/.exec(line)?.[1]?.length ?? 0;
+        if (indent <= base)
+            return false;
+        if (new RegExp(`^\\s*${key}:\\s*`).test(line))
+            return true;
+    }
+    return false;
+}
+function yamlDoubleQuote(value) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+function installedYakVersion() {
+    return readInstalledYak().version;
+}
+function readInstalledYak() {
+    const require = createRequire(import.meta.url);
+    const pkgPath = require.resolve("@lchase/yak/package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const version = typeof pkg.version === "string" && pkg.version.length > 0 ? pkg.version : "unknown";
+    let dist = "";
+    try {
+        dist = readFileSync(join(dirname(pkgPath), "dist", "index.js"), "utf8");
+    }
+    catch {
+        dist = "";
+    }
+    return { version, dist };
+}
+function dockerResult(args) {
+    const result = spawnSync("docker", args, { encoding: "utf8", stdio: "ignore" });
+    return { status: result.error ? null : result.status };
+}
+function runDocker(args) {
+    const result = spawnSync("docker", args, { stdio: "inherit" });
+    if (result.error) {
+        const code = result.error.code;
+        if (code === "ENOENT") {
+            throw new Error("docker binary is not on PATH. Install Docker and run kiln sandbox build again.");
+        }
+        throw new Error(`docker ${args[0] ?? "build"} failed: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`docker ${args.join(" ")} exited ${result.status ?? "with a signal"}.`);
+    }
+}

package/dist/schemas.js

@@ -26,6 +26,22 @@ export const JiraConfigSchema = z.object({
     email: z.string().optional(),
     apiToken: z.string().optional(),
 });
+/**
+ * Opt-in Docker sandbox. Omitted mode means off at that layer.
+ * `image` overrides yak's `yak-agent-sandbox:latest`.
+ * `allowDomains` replaces the built-in host list when set.
+ */
+const HOSTNAME = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+export const SandboxSettingsSchema = z.object({
+    mode: z.enum(["off", "docker"]).optional(),
+    image: z
+        .string()
+        .min(1)
+        .regex(/^\S+$/, "image must not contain whitespace")
+        .optional(),
+    allowDomains: z.array(z.string().regex(HOSTNAME, "must be a hostname")).min(1).optional(),
+});
+const WORKFLOW_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 /** No yak event and no log output for this long stalls a running job. `<= 0` disables it. */
 export const DEFAULT_STALL_TIMEOUT_MS = 15 * 60 * 1000;
 /** Transient failures retry until this many attempts, then the job is dead. */
@@ -48,6 +64,9 @@ export const KilnConfigFileSchema = z.object({
      */
     maxFixRounds: z.number().int().min(1).optional(),
     adapter: z.enum(["mock", "claude-code"]).optional(),
+    sandbox: SandboxSettingsSchema.optional(),
+    /** Per-workflow sandbox override. A set field replaces the global one; an omitted field inherits. */
+    workflows: z.record(z.string().regex(WORKFLOW_KEY), z.object({ sandbox: SandboxSettingsSchema.optional() })).optional(),
     repos: z.record(z.string(), RepoEntrySchema),
     jira: JiraConfigSchema.optional(),
 });

package/dist/serve-page.js

@@ -127,6 +127,7 @@ function card(item, stage) {
 <div class="branch repo">${escapeHtml(job.repo)}</div>
 <p class="title">${escapeHtml(job.title || job.jobId)}</p>
 ${branch ? `<div class="branch">${escapeHtml(branch)}</div>` : ""}
+${sandboxHtml(job)}
 ${prLink(job)}
 ${roundsHtml(job, stage)}
 ${attemptHtml(job, stage)}
@@ -146,6 +147,7 @@ function sheet(item) {
 <div class="num">${escapeHtml(num)}</div>
 <h3>${escapeHtml(job.title || job.jobId)}</h3>
 ${branch ? `<div class="branch">${escapeHtml(branch)}</div>` : ""}
+${sandboxHtml(job)}
 ${prLink(job)}
 ${actionsHtml(item)}
 <button type="button" class="close" data-close aria-label="Close">×</button>
@@ -198,6 +200,11 @@ function actionsHtml(item) {
         return "";
     return `<div class="d-actions">${forms.join("")}</div>`;
 }
+function sandboxHtml(job) {
+    if (!job.sandboxed)
+        return "";
+    return `<div class="meta">sandbox · docker</div>`;
+}
 function roundsHtml(job, stage) {
     const rounds = job.rounds ?? [];
     const last = rounds[rounds.length - 1]?.n;

package/dist/serve.js

@@ -5,6 +5,7 @@ import { answerJob, readStatus, retryJob, runTick, startupRecovery } from "./dri
 import { defaultHost } from "./host.js";
 import { INVESTIGATION_WORKFLOW } from "./findings.js";
 import { packageRoot } from "./paths.js";
+import { SANDBOX_PREFLIGHT_PREFIX } from "./sandbox.js";
 import { renderConsole, renderMessagePage, renderTextPage } from "./serve-page.js";
 const BODY_LIMIT = 65_536;
 const TEXT_LIMIT = 100_000;
@@ -71,7 +72,12 @@ export function loadServeCss() {
 }
 function safeTick(config, secrets, startup) {
     try {
-        runTick(config, defaultHost(), { startup });
+        const report = runTick(config, defaultHost(), { startup });
+        if (report.startsWith(SANDBOX_PREFLIGHT_PREFIX)) {
+            const tickAt = report.indexOf("\ntick ");
+            const head = tickAt === -1 ? report : report.slice(0, tickAt);
+            process.stderr.write(`${redact(head.trimEnd(), secrets)}\n`);
+        }
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lchase/kiln",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Run a workflow on any registered repo. A markdown spec is the input.",
   "type": "module",
   "bin": {

package/workflows/feature.yaml

@@ -1,5 +1,10 @@
 # One Kiln job, run by yak (@lchase/yak).
 #
+# Sandbox (kiln config `sandbox.mode: docker`, off by default): tick injects
+# `sandbox: docker` under each agent step (spec, build, security, ux, ui,
+# code, approver). verify, the approve gate, and land stay on the host.
+# Pull request open and `gh pr view` run in the kiln process.
+#
 # Faithful to Lawrence Chase's factory plugin v0.7.0 (MIT):
 # https://github.com/lchase/coding-agent-plugins/tree/4c84a2ce7fbde5ac298c0de9f0b90141eac4ed98/plugins/factory
 #   skills/factory/SKILL.md          (the loop: spec, build, 4 reviews, approver)

package/workflows/fix.yaml

@@ -1,5 +1,9 @@
 # One pull-request fix, run by yak (@lchase/yak).
 #
+# Sandbox (kiln config `sandbox.mode: docker`, off by default): tick injects
+# `sandbox: docker` under the build agent. land stays on the host, and Kiln
+# fast-forwards the pull request branch from the host.
+#
 # The same builder as workflows/feature.yaml (factory builder, opus). Kiln
 # launches it with `yak run --isolation worktree --from <pull request head>`
 # on a job whose pull request is already open. Yak cuts a worktree branch

package/workflows/investigation.yaml

@@ -1,5 +1,8 @@
 # One Kiln investigation, run by yak (@lchase/yak).
 #
+# Sandbox (kiln config `sandbox.mode: docker`, off by default): tick injects
+# `sandbox: docker` under the explore agent. The approve gate stays on the host.
+#
 # A spike, probe, or research ticket. The agent explores the worktree and
 # returns a findings document. A person approves or rejects it. There is no
 # build, review, verify, or land step, and Kiln does not open a pull request