@lchase/kiln 0.4.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
@@ -68,7 +122,7 @@ npm run kiln -- repo list
 
 ## Add a job
 
-A job is one workflow run. The workflow name is a file `workflows/<name>.yaml`. `feature` is the factory loop. `investigation` answers a spike and stops for a person to approve the findings. Bug and security workflows are next. A later `pr-review` workflow is not in this repo yet.
+A job is one workflow run. The workflow name is a file `workflows/<name>.yaml`. `feature` is the factory loop. `investigation` answers a spike and stops for a person to approve the findings. `fix` is the pull request feedback run: the same builder, on the open pull request head, committing onto a new `yak/<run-id>` that Kiln fast-forwards onto the existing branch. Bug and security workflows are next.
 
 ```bash
 npm run kiln -- add feature --repo web --spec spec.md --title "Show a Sunday summary"
@@ -166,7 +220,7 @@ kiln serve --no-tick
 
 `kiln serve` listens on `127.0.0.1` only (port 4100 unless `--port` is set). It reads the same derived state as `kiln status` and calls the same approve, reject, and retry functions. Nothing new is stored.
 
-`/` is the operator board, using the factory dashboard's dark charcoal layout. Columns are workflow stages taken from the job's yaml steps and the current yak step. Queued is first: jobs whose derived state is queued or blocked, with the subtitle `waiting · deps` and dimmer text. A blocked card names the jobs it is waiting on. Spec holds a job only while the spec step is the one running. Then Build (`builder · opus`), Review (`sec · ux · ui · code`), Approve (`approver · opus`), Land, PR review, Merged, and Needs human. An investigation adds Explore. Needs human stays at the right and holds open gates, dead runs, failures that are not waiting on an automatic retry, invalid job files, and rejections. A failed job with `nextRetryAt` still set stays in the column of the step it was on (Build, Review, and so on), dimmer, with one line `retrying 7:35 PM · attempt 1/3 · stalled` in the browser's local time. It is not in the needs-you count. When that retry starts, the card is a normal running card again. An empty column is a narrow strip with the name written down it. The header clock and any timestamps in the drawer use the browser's local time; stored values stay ISO UTC. The bottom toolbar switches between that and always-expanded columns; the choice is stored in `localStorage`. Repo chips across the top filter the cards. A card shows the job id, repo, title, branch, pull request, and one row per review round (security, ux, ui, code). A blocked card names what it is waiting on. Clicking a card opens a drawer. Approve, Reject, and Retry sit in the drawer header when the job is gated or failed. The drawer lists the spec, build, decision, each review, and investigation findings, and the selected file is rendered on the right. `/board` is the same page. The document title is `(N) Kiln`, where N is the needs-you count from the attention view (gates, dead runs, failures with no automatic retry left, and open pull requests). A job waiting out its backoff is not included, and it does not fire the desktop notification. The page polls every 3 seconds. After you opt in from the toolbar, a desktop notification fires when that count goes up. Kiln does not record factory quality averages, so the header does not invent round or human-fix numbers.
+`/` is the operator board, using the factory dashboard's dark charcoal layout. Columns are workflow stages taken from the job's yaml steps and the current yak step. Queued is first: jobs whose derived state is queued or blocked, with the subtitle `waiting · deps` and dimmer text. A blocked card names the jobs it is waiting on. Spec holds a job only while the spec step is the one running. Then Build (`builder · opus`), Review (`sec · ux · ui · code`), Approve (`approver · opus`), Land, PR review, Merged, and Needs human. An investigation adds Explore. Needs human stays at the right and holds open gates, dead runs, failures that are not waiting on an automatic retry, invalid job files, and rejections. A failed job with `nextRetryAt` still set stays in the column of the step it was on (Build, Review, and so on), dimmer, with one line `retrying 7:35 PM · attempt 1/3 · stalled` in the browser's local time. It is not in the needs-you count. When that retry starts, the card is a normal running card again. An empty column is a narrow strip with the name written down it. The header clock and any timestamps in the drawer use the browser's local time; stored values stay ISO UTC. The bottom toolbar switches between that and always-expanded columns; the choice is stored in `localStorage`. Repo chips across the top filter the cards. A card shows the job id, repo, title, branch, pull request, and one row per review round (security, ux, ui, code). A card in PR review also shows each feedback round as its own row: `CI failed`, `changes requested`, then `pushed` or `fixed` once that round lands. A fix that is still running is a normal running card. Only `feedback-exhausted` (and feedback Kiln could not classify) moves to Needs human, with your call. The drawer lists each feedback round's checks and comments, with links. A blocked card names what it is waiting on. Clicking a card opens a drawer. Approve, Reject, and Retry sit in the drawer header when the job is gated or failed. The drawer lists the spec, build, decision, each review, and investigation findings, and the selected file is rendered on the right. `/board` is the same page. The document title is `(N) Kiln`, where N is the needs-you count from the attention view (gates, dead runs, failures with no automatic retry left, and open pull requests). A job waiting out its backoff is not included, and it does not fire the desktop notification. The page polls every 3 seconds. After you opt in from the toolbar, a desktop notification fires when that count goes up. Kiln does not record factory quality averages, so the header does not invent round or human-fix numbers.
 
 `GET /jobs/<id>/findings` renders the approved findings markdown as text. HTML in that file is escaped. The page is read-only.
 
@@ -195,7 +249,9 @@ while true; do npm run kiln -- tick; sleep 30; done
 
 A job is ready when its dependencies are met and the number of jobs in flight is under `maxConcurrent`. The default is after merged: every job in `dependsOn` is `done`. `--stack` is met when that one upstream has landed. A rejected gate does not unblock the next job. An ok run with no readable approval does not either.
 
-`stallTimeoutMs` (default `900000`, 15 minutes) and `maxAttempts` (default `3`) live in the kiln config. `stallTimeoutMs` of `0` or below turns stall detection off. A running job with no yak journal event and no log output for that long is killed, process tree included, and marked failed with reason `stalled`. A process that is already gone when `kiln tick` or `kiln serve` starts is `orphaned`. An agent or launch crash is `crashed`. A non-zero exit that is not a gate rejection is `failed`. Those four retry on their own after `10s × 2^(n-1)`, capped at 5 minutes. A rejected gate, a cancelled run, and an ok run with no readable approval do not. After `maxAttempts` the job is `dead`. Each attempt is a file under `<kiln-dir>/attempts/<job-id>.json`, so state stays derived. Status prints `attempts`, `reason`, and `next retry` from the same view `readStatus` returns. On the board, a dead card in Needs human shows `attempt N/M` and the reason. A failure that still has a scheduled retry stays in its stage column instead, with `retrying` and the local time.
+`stallTimeoutMs` (default `900000`, 15 minutes), `maxAttempts` (default `3`), and `maxFixRounds` (default `2`) live in the kiln config. `stallTimeoutMs` of `0` or below turns stall detection off. A running job with no yak journal event and no log output for that long is killed, process tree included, and marked failed with reason `stalled`. A process that is already gone when `kiln tick` or `kiln serve` starts is `orphaned`. An agent or launch crash is `crashed`. A non-zero exit that is not a gate rejection is `failed`. Those four retry on their own after `10s × 2^(n-1)`, capped at 5 minutes. A rejected gate, a cancelled run, and an ok run with no readable approval do not. After `maxAttempts` the job is `dead`. Each attempt is a file under `<kiln-dir>/attempts/<job-id>.json`, so state stays derived. Status prints `attempts`, `reason`, and `next retry` from the same view `readStatus` returns. On the board, a dead card in Needs human shows `attempt N/M` and the reason. A failure that still has a scheduled retry stays in its stage column instead, with `retrying` and the local time.
+
+While a `deliver=pr` job is `in-review`, tick reads that pull request with `gh`: check runs for the head, reviews, and unresolved review comments. The operator's inline comments and unresolved threads count; a top-level note counts only when it starts with `/kiln`, and that prefix is left out of the fix prompt. Comments from `kiln` or a `[bot]` login are ignored, and a resolved thread does not start a round. Pending checks are ignored. A completed failing check on a head that no round has recorded, or review feedback newer than the last round, starts `workflows/fix.yaml` with `yak run --from` that head. The prompt is the original spec plus the failing check names (with a short log excerpt) and the review comment bodies, including file and line. The agent commits on `yak/<run-id>` and does not push. Kiln fast-forwards the open pull request branch. It does not open a second pull request, force-push, merge, approve, or comment. The same head and the same feedback do not start two runs. Each round is a file under `<kiln-dir>/feedback/<job-id>.json`. A stall or crash during a fix uses the attempt ledger above. After `maxFixRounds` the job is `needs-human` with reason `feedback-exhausted`. Feedback Kiln cannot classify is `needs-human` with reason `feedback-ambiguous`. The person merges the pull request.
 
 `npm run kiln -- status` lists jobs across repos. When a job has `source`, status prints `source <kind> <ref>`. For `needs-human` it prints `approve: kiln approve <id>` and `reject: kiln reject <id>`. Run those as `npm run kiln -- approve <id>` and `npm run kiln -- reject <id>`. For `done` and `in-review` it prints `branch yak/<run-id>`. For `deliver=pr` it also prints the pull request url once one exists. For an investigation whose findings file exists, it prints `findings <path>`. That path is `findingsPath` on the same status view `kiln serve` renders, and the console links it. For `blocked` on a dependency id that has no job file, it prints `blocked on missing job <id>`. While an upstream pull request is open, it prints `waiting for PR #N to merge`. `npm run kiln -- retry <id>` relaunches a failed or dead job, or delivers again when the only failure is opening the pull request, and clears the attempt ledger.
 
@@ -206,7 +262,7 @@ State is derived from the yak journal, the gate files, and (for `deliver=pr`) `g
 | `queued` | Dependencies are met, and the job has not started |
 | `blocked` | An after-merged dependency is not `done`, or a stacked dependency has not landed. A missing job id is named |
 | `running` | Yak is alive, or the launch process is alive and has not written a journal |
-| `needs-human` | The run is suspended on an open gate |
+| `needs-human` | The run is suspended on an open gate, or pull request feedback is exhausted (`feedback-exhausted`) or ambiguous (`feedback-ambiguous`) |
 | `approved` | The gate says approve and the run has not finished. This still holds a slot |
 | `rejected` | The run finished ok and the gate says reject |
 | `failed` | The run failed, the launch died before a journal, the run finished ok with no readable approval, a pull request could not be opened, or a transient failure is waiting to retry |
@@ -265,4 +321,4 @@ npm run kiln -- import ./tickets --repo web --stack
 
 ## Not included
 
-No requirement refinement. Bug, security, and pr-review workflows are not in this repo yet. Kiln does not merge pull requests and does not push the base branch.
+No requirement refinement. Bug and security workflows are not in this repo yet. Kiln does not merge, approve, or comment on pull requests, and it does not push the base branch.

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.
@@ -97,13 +98,17 @@ function toItem(job) {
 export function attentionReason(job, tail = errorTail(job)) {
     switch (job.state) {
         case "needs-human": {
+            if (job.feedbackReason)
+                return job.feedbackReason;
             const question = gateQuestion(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":
@@ -225,6 +230,8 @@ function attentionRevision(needsYou, inFlight, doneRecently, graph) {
             item.job.attemptCount,
             item.job.lastFailureReason ?? "",
             item.job.nextRetryAt ?? "",
+            feedbackStamp(item.job),
+            item.job.sandboxed ? "sandbox" : "",
         ]),
         inFlight: inFlight.map((item) => [
             item.job.jobId,
@@ -234,12 +241,20 @@ function attentionRevision(needsYou, inFlight, doneRecently, graph) {
             item.job.attemptCount,
             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]),
     });
     return createHash("sha256").update(body).digest("hex").slice(0, 16);
 }
+function feedbackStamp(job) {
+    const rounds = (job.feedbackRounds ?? [])
+        .map((round) => `${round.round}:${round.trigger}:${round.outcome ?? ""}:${round.headSha}`)
+        .join("|");
+    return `${job.feedbackReason ?? ""}:${rounds}`;
+}
 function oneLine(text, max = 180) {
     const flat = text.replace(/\s+/g, " ").trim();
     if (flat.length <= max)
@@ -252,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",
@@ -59,12 +61,21 @@ function usage() {
         "after 10s, 20s, 40s, and so on, capped at 5 minutes, up to maxAttempts",
         "(default 3). The job is then dead. A rejected gate is not retried.",
         "Attempts are files under the kiln home, not fields on the job.",
+        "Once a pull request is open, tick watches it. A failed check or a review",
+        "that requests changes starts a fix on that same branch, up to maxFixRounds",
+        "(default 2). Kiln does not merge, approve, or comment. Past that bound the",
+        "job is needs-human with reason feedback-exhausted.",
         "",
         "serve listens on 127.0.0.1. The page is a board of workflow stages:",
         "queued, spec, build, review, approve, land, PR review, merged, and needs human.",
         "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);
 }
@@ -311,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);
@@ -418,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

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "no
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { KilnConfigError } from "./errors.js";
-import { DEFAULT_MAX_ATTEMPTS, DEFAULT_STALL_TIMEOUT_MS, KilnConfigFileSchema, } from "./schemas.js";
+import { DEFAULT_MAX_ATTEMPTS, DEFAULT_MAX_FIX_ROUNDS, DEFAULT_STALL_TIMEOUT_MS, KilnConfigFileSchema, } from "./schemas.js";
 const CONFIG_NAME = "kiln.config.json";
 const REPO_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 export function loadKilnConfig(configPath, options = {}) {
@@ -47,7 +47,10 @@ export function loadKilnConfig(configPath, options = {}) {
         maxConcurrent: parsed.data.maxConcurrent ?? 2,
         stallTimeoutMs: parsed.data.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS,
         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 } : {}),
     };
 }
@@ -234,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;