@lchase/kiln 0.4.0 → 0.6.0

package/dist/reconcile.js

@@ -5,7 +5,7 @@ export function inFlightCount(observation) {
     return observation.jobs.filter((job) => inFlight(job, observation)).length;
 }
 function inFlight(job, observation) {
-    if (job.error)
+    if (job.error || job.feedbackExhausted || job.feedbackAmbiguous)
         return false;
     const state = jobState(job, observation);
     return state === "running" || state === "needs-human" || state === "approved";
@@ -20,8 +20,17 @@ function inFlight(job, observation) {
  * An investigation is `done` on approve and never `in-review`.
  */
 export function jobState(job, observation) {
-    if (job.launching && (!job.run || job.runRetired))
+    if (job.fixAwaitingPublish)
+        return "in-review";
+    if (job.launching && (!job.run || job.runRetired || job.fixInProgress))
         return "running";
+    if ((job.feedbackExhausted || job.feedbackAmbiguous) && isLanded(job) && !job.fixInProgress) {
+        if (job.delivery?.merged || job.delivery?.prState === "MERGED")
+            return "done";
+        if (job.delivery?.prState === "CLOSED")
+            return "failed";
+        return "needs-human";
+    }
     if (job.run && !job.runRetired)
         return activeRunState(job);
     if (job.run && isLanded(job))
@@ -126,10 +135,16 @@ function needsDelivery(job) {
     return true;
 }
 function canLaunch(job, observation) {
-    if (job.error || job.run || job.launching || job.launchFailed)
+    if (job.error || job.run || job.launching || job.launchFailed || job.fixInProgress)
         return false;
     return dependenciesMet(job, observation);
 }
+/** An in-review job with new pull request feedback and room under `maxFixRounds`. */
+function canStartFix(job) {
+    if (job.error || job.launching || job.fixInProgress || job.fixAwaitingPublish)
+        return false;
+    return job.feedbackPlan?.action === "fix";
+}
 /** A recorded transient failure whose backoff has elapsed. One retry per tick, ahead of a new job. */
 function canRetry(job, observation, now) {
     if (job.error || job.launching || job.retriesExhausted || job.ledgerError)
@@ -164,6 +179,14 @@ export function decide(observation, now = new Date()) {
             continue;
         actions.push({ type: "deliver", jobId: job.jobId, repo: job.repo });
     }
+    for (const job of observation.jobs) {
+        if (job.feedbackPlan?.action === "exhaust") {
+            actions.push({ type: "mark-feedback", jobId: job.jobId, reason: "feedback-exhausted" });
+        }
+        else if (job.feedbackPlan?.action === "ambiguous") {
+            actions.push({ type: "mark-feedback", jobId: job.jobId, reason: "feedback-ambiguous" });
+        }
+    }
     if (inFlightCount(observation) >= observation.maxConcurrent)
         return actions;
     const retry = observation.jobs.find((job) => canRetry(job, observation, now));
@@ -171,6 +194,11 @@ export function decide(observation, now = new Date()) {
         actions.push({ type: "retry", jobId: retry.jobId, repo: retry.repo });
         return actions;
     }
+    const fix = observation.jobs.find((job) => canStartFix(job));
+    if (fix) {
+        actions.push({ type: "start-fix", jobId: fix.jobId, repo: fix.repo });
+        return actions;
+    }
     const ready = observation.jobs.filter((job) => canLaunch(job, observation));
     const healthy = ready.filter((job) => !job.launchError);
     const picked = healthy[0] ?? ready[0];

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

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { readBoardFiles, readReviewRounds } from "./board.js";
+import { feedbackRoundText } from "./feedback.js";
 import { INVESTIGATION_WORKFLOW } from "./findings.js";
 import { inFlightCount, isDone, isLanded, jobState, } from "./reconcile.js";
 export function shellQuote(value) {
@@ -76,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`.
@@ -123,8 +145,19 @@ 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)
+        lines.push(job.feedbackLedgerError);
+    if ((job.feedbackRounds?.length ?? 0) > 0)
+        lines.push(`feedback ${job.feedbackRounds?.length}`);
+    if (job.state === "needs-human" && job.feedbackReason)
+        lines.push(`reason ${job.feedbackReason}`);
     if (job.attemptCount > 0)
         lines.push(`attempts ${job.attemptCount}`);
     if (job.lastFailureReason)
@@ -197,10 +230,15 @@ function toStatusJob(job, observation) {
         };
     }
     const state = jobState(job, observation);
-    const gates = state === "needs-human" && job.run ? job.run.gates.map(toGateView) : [];
+    const feedbackReason = job.feedbackExhausted
+        ? "feedback-exhausted"
+        : job.feedbackAmbiguous
+            ? "feedback-ambiguous"
+            : undefined;
+    const gates = state === "needs-human" && job.run && !feedbackReason ? job.run.gates.map(toGateView) : [];
     const prNumber = job.delivery?.prNumber;
     const runId = job.run?.runId;
-    const showBranch = (state === "done" || state === "in-review") && runId !== undefined;
+    const showBranch = runId !== undefined && (state === "done" || state === "in-review" || feedbackReason !== undefined);
     const failureDetail = job.run?.stepEvents ? latestStepFailure(job.run.stepEvents) : undefined;
     return {
         jobId: job.jobId,
@@ -224,6 +262,8 @@ function toStatusJob(job, observation) {
         ...(job.lastFailureReason ? { lastFailureReason: job.lastFailureReason } : {}),
         ...(job.nextRetryAt && !job.retriesExhausted ? { nextRetryAt: job.nextRetryAt } : {}),
         ...(job.ledgerError ? { ledgerError: job.ledgerError } : {}),
+        ...(job.feedbackLedgerError ? { feedbackLedgerError: job.feedbackLedgerError } : {}),
+        ...(feedbackReason ? { feedbackReason } : {}),
         ...(job.launchError ? { launchError: job.launchError } : {}),
         ...(job.delivery?.error ? { deliveryError: job.delivery.error } : {}),
         ...(job.delivery?.viewError ? { viewError: job.delivery.viewError } : {}),
@@ -243,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),
     };
 }
@@ -258,12 +300,29 @@ function boardFields(job) {
         ...(job.workflow ? { workflow: job.workflow } : {}),
         gates: job.run?.gates ?? [],
     });
+    for (const round of job.feedbackRounds ?? []) {
+        const label = round.trigger === "ci" ? "CI" : "review";
+        files.push({
+            id: `feedback-r${round.round}`,
+            group: "Feedback",
+            label: `R${round.round} ${label}.md`,
+            text: feedbackRoundText(round),
+            tone: round.outcome ? "good" : "warn",
+        });
+    }
     return {
         ...(rounds.length > 0 ? { rounds } : {}),
+        ...(job.feedbackRounds?.length ? { feedbackRounds: job.feedbackRounds } : {}),
         ...(files.length > 0 ? { files } : {}),
     };
 }
 function progressFor(job) {
+    if (job.fixInProgress && !job.run) {
+        return [
+            { id: "build", phase: "current" },
+            { id: "land", phase: "pending" },
+        ];
+    }
     const plan = job.run?.stepPlan?.length ? job.run.stepPlan : (job.stepPlan ?? []);
     return stepProgress(plan, job.run?.stepEvents ?? []);
 }
@@ -317,7 +376,7 @@ function blockReasons(job, observation) {
     }
     return reasons;
 }
-export function renderTick(observation, actions, launches, delivers = [], findings = [], notes = []) {
+export function renderTick(observation, actions, launches, delivers = [], findings = [], notes = [], feedbackNotes = []) {
     const lines = [`tick  inFlight=${inFlightCount(observation)}  maxConcurrent=${observation.maxConcurrent}`];
     for (const job of observation.jobs) {
         if (job.error)
@@ -341,18 +400,26 @@ export function renderTick(observation, actions, launches, delivers = [], findin
         const next = note.nextRetryAt ? `  next ${note.nextRetryAt}` : "  dead";
         lines.push(`${note.kind} ${note.jobId}  ${note.reason}  attempt ${note.attempt}${next}`);
     }
+    for (const note of feedbackNotes) {
+        if (note.trim())
+            lines.push(note);
+    }
     for (const launch of launches) {
-        lines.push(`${launch.retry ? "retry" : "launch"} ${launch.jobId}  ${launch.repo}`);
+        const verb = launch.kind === "fix" ? "fix" : launch.retry ? "retry" : "launch";
+        lines.push(`${verb} ${launch.jobId}  ${launch.repo}`);
         for (const line of launch.output.split("\n")) {
             if (line.trim())
                 lines.push(`  ${line}`);
         }
     }
-    if (!actions.some((action) => action.type === "launch" || action.type === "retry") &&
-        launches.length === 0 &&
-        delivers.length === 0 &&
-        findings.length === 0) {
+    const acted = actions.some((action) => action.type === "launch" ||
+        action.type === "retry" ||
+        action.type === "start-fix" ||
+        action.type === "mark-feedback") ||
+        launches.length > 0 ||
+        delivers.length > 0 ||
+        findings.length > 0;
+    if (!acted)
         lines.push("nothing to launch");
-    }
     return `${lines.join("\n")}\n`;
 }

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,10 +26,28 @@ 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. */
 export const DEFAULT_MAX_ATTEMPTS = 3;
+/** Pull request fix rounds before the job is needs-human (`feedback-exhausted`). */
+export const DEFAULT_MAX_FIX_ROUNDS = 2;
 export const KilnConfigFileSchema = z.object({
     note: z.string().min(1).optional(),
     maxConcurrent: z.number().int().min(1).optional(),
@@ -40,7 +58,15 @@ export const KilnConfigFileSchema = z.object({
     stallTimeoutMs: z.number().int().optional(),
     /** Transient failures before the job is dead. Default 3. */
     maxAttempts: z.number().int().min(1).optional(),
+    /**
+     * Fix rounds for an open pull request before the job is needs-human with
+     * reason `feedback-exhausted`. Default 2. Kiln does not merge.
+     */
+    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(),
 });