@lchase/kiln 0.6.1 → 0.7.0

package/dist/serve.js

@@ -1,12 +1,20 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
+import { AUTH_PREFLIGHT_PREFIX } from "./auth.js";
+import { loadKilnConfig } from "./config.js";
 import { answerJob, readStatus, retryJob, runTick, startupRecovery } from "./driver.js";
+import { browse } from "./fs-browse.js";
 import { defaultHost } from "./host.js";
 import { INVESTIGATION_WORKFLOW } from "./findings.js";
+import { intakeJobs } from "./intake-http.js";
 import { packageRoot } from "./paths.js";
 import { SANDBOX_PREFLIGHT_PREFIX } from "./sandbox.js";
 import { renderConsole, renderMessagePage, renderTextPage } from "./serve-page.js";
+import { readSettings, saveSettings } from "./settings.js";
+import { listWorkflowNames } from "./workflow.js";
 const BODY_LIMIT = 65_536;
 const TEXT_LIMIT = 100_000;
 const JOB_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
@@ -17,14 +25,15 @@ const JOB_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 export function startServe(options) {
     startupRecovery(options.config);
     const css = loadServeCss();
-    const secrets = secretValues(options.config);
+    const csrf = randomBytes(32).toString("hex");
+    const state = openLiveConfig(options.config);
     let port = options.port;
     return new Promise((resolvePromise, reject) => {
         const server = createServer((req, res) => {
-            void handle(req, res, options.config, () => port, css, secrets).catch((error) => {
+            void handle(req, res, state, () => port, css, csrf).catch((error) => {
                 const message = error instanceof Error ? error.message : String(error);
                 const status = statusCode(error) ?? 500;
-                sendJson(res, status, { error: redact(message, secrets) }, secrets);
+                sendJson(res, status, { error: redact(message, state.secrets) }, state.secrets);
             });
         });
         server.on("error", reject);
@@ -56,7 +65,8 @@ export function startServe(options) {
             const tick = () => {
                 if (stopped)
                     return;
-                safeTick(options.config, secrets, false);
+                refreshLiveConfig(state);
+                safeTick(state.config, state.secrets, false);
             };
             firstTick = setTimeout(tick, 0);
             timer = setInterval(tick, options.tickSeconds * 1000);
@@ -73,7 +83,7 @@ export function loadServeCss() {
 function safeTick(config, secrets, startup) {
     try {
         const report = runTick(config, defaultHost(), { startup });
-        if (report.startsWith(SANDBOX_PREFLIGHT_PREFIX)) {
+        if (report.startsWith(SANDBOX_PREFLIGHT_PREFIX) || report.startsWith(AUTH_PREFLIGHT_PREFIX)) {
             const tickAt = report.indexOf("\ntick ");
             const head = tickAt === -1 ? report : report.slice(0, tickAt);
             process.stderr.write(`${redact(head.trimEnd(), secrets)}\n`);
@@ -84,7 +94,10 @@ function safeTick(config, secrets, startup) {
         process.stderr.write(`tick: ${redact(message, secrets)}\n`);
     }
 }
-async function handle(req, res, config, boundPort, css, secrets) {
+async function handle(req, res, state, boundPort, css, csrf) {
+    refreshLiveConfig(state);
+    const config = state.config;
+    const secrets = state.secrets;
     const method = req.method ?? "GET";
     const url = new URL(req.url ?? "/", "http://127.0.0.1");
     const path = url.pathname;
@@ -93,12 +106,60 @@ async function handle(req, res, config, boundPort, css, secrets) {
         res.end();
         return;
     }
+    if (method === "GET" && path === "/api/settings") {
+        if (!originAllowed(req, boundPort())) {
+            sendJson(res, 403, { error: "Cross-origin request rejected." }, secrets);
+            return;
+        }
+        const result = readSettings(config.configPath);
+        if (!result.ok) {
+            sendJson(res, result.status, result.body, secrets);
+            return;
+        }
+        sendJson(res, 200, result.document, secrets);
+        return;
+    }
+    if (method === "GET" && path === "/api/fs") {
+        if (!originAllowed(req, boundPort())) {
+            sendJson(res, 403, { error: "Cross-origin request rejected." }, secrets);
+            return;
+        }
+        try {
+            sendJson(res, 200, browse(homedir(), url.searchParams.get("path") ?? undefined), secrets);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            sendJson(res, statusCode(error) ?? 500, { error: message }, secrets);
+        }
+        return;
+    }
+    if (method === "PUT" && path === "/api/settings") {
+        const raw = await readBody(req);
+        if (!originAllowed(req, boundPort())) {
+            sendJson(res, 403, { error: "Cross-origin request rejected." }, secrets);
+            return;
+        }
+        if (!csrfOk(csrf, req, raw)) {
+            sendJson(res, 403, { error: "CSRF token rejected." }, secrets);
+            return;
+        }
+        await putSettings(req, res, state, raw);
+        return;
+    }
     if (method === "POST") {
-        await drain(req);
+        const raw = await readBody(req);
         if (!originAllowed(req, boundPort())) {
             sendJson(res, 403, { error: "Cross-origin request rejected." }, secrets);
             return;
         }
+        if (!csrfOk(csrf, req, raw)) {
+            sendJson(res, 403, { error: "CSRF token rejected." }, secrets);
+            return;
+        }
+        if (path === "/api/jobs") {
+            await createJob(req, res, state, raw);
+            return;
+        }
         const action = /^\/api\/jobs\/([^/]+)\/(approve|reject|retry)$/.exec(path);
         if (!action?.[1] || (action[2] !== "approve" && action[2] !== "reject" && action[2] !== "retry")) {
             sendJson(res, 404, { error: "Not found." }, secrets);
@@ -121,11 +182,11 @@ async function handle(req, res, config, boundPort, css, secrets) {
         return;
     }
     if (path === "/" || path === "" || path === "/board") {
-        sendHtml(res, 200, renderConsole(css, readStatus(config).attention), secrets);
+        sendHtml(res, 200, renderConsole(css, readStatus(config).attention, pageOptions(state, csrf)), secrets);
         return;
     }
-    if (path === "/api/jobs") {
-        sendJson(res, 200, readStatus(config), secrets);
+    if (path === "/api/jobs" || path === "/api/status") {
+        sendJson(res, 200, statusDocument(state), secrets);
         return;
     }
     const apiJob = /^\/api\/jobs\/([^/]+)$/.exec(path);
@@ -238,12 +299,15 @@ function findJob(config, jobId) {
     }
 }
 /**
+ * Host must be localhost or 127.0.0.1 on the bound port.
  * Browsers send Origin on POST. A cross-site page cannot use this server:
- * the header has to be exactly `http://127.0.0.1:<bound port>`.
+ * Origin, when present, has to be `http://127.0.0.1:<port>` or `http://localhost:<port>`.
  * Curl and other non-browser clients omit Origin and are allowed.
  * `Sec-Fetch-Site: cross-site` is rejected even when Origin is absent.
  */
 export function originAllowed(req, port) {
+    if (!hostAllowed(req, port))
+        return false;
     const fetchSite = req.headers["sec-fetch-site"];
     if (fetchSite === "cross-site")
         return false;
@@ -252,7 +316,14 @@ export function originAllowed(req, port) {
         return false;
     if (origin === undefined)
         return true;
-    return origin === `http://127.0.0.1:${port}`;
+    return origin === `http://127.0.0.1:${port}` || origin === `http://localhost:${port}`;
+}
+function hostAllowed(req, port) {
+    const host = req.headers.host;
+    if (typeof host !== "string")
+        return false;
+    const value = host.trim().toLowerCase();
+    return value === `127.0.0.1:${port}` || value === `localhost:${port}`;
 }
 function redirectTarget(req) {
     const referer = req.headers.referer;
@@ -316,16 +387,178 @@ function readInside(kilnDir, target) {
         return text;
     return `showing the last ${TEXT_LIMIT} characters\n\n${text.slice(text.length - TEXT_LIMIT)}`;
 }
-async function drain(req) {
+async function readBody(req) {
+    const chunks = [];
     let size = 0;
     for await (const chunk of req) {
-        size += chunk.length;
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buf.length;
         if (size > BODY_LIMIT) {
             const error = new Error("Request body is too large.");
             error.statusCode = 413;
             throw error;
         }
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function csrfOk(expected, req, body) {
+    const header = req.headers["x-kiln-csrf"];
+    const fromHeader = typeof header === "string" ? header : undefined;
+    let fromForm;
+    if (headerValue(req.headers["content-type"]).includes("application/x-www-form-urlencoded")) {
+        fromForm = new URLSearchParams(body).get("csrf") ?? undefined;
+    }
+    const provided = fromHeader || fromForm;
+    if (!provided)
+        return false;
+    const left = Buffer.from(expected);
+    const right = Buffer.from(provided);
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
+}
+async function putSettings(req, res, state, raw) {
+    const secrets = state.secrets;
+    if (!headerValue(req.headers["content-type"]).includes("application/json")) {
+        sendJson(res, 400, { error: "Content-Type must be application/json." }, secrets);
+        return;
+    }
+    let parsed;
+    if (!raw.trim()) {
+        sendJson(res, 400, { error: "Request body must be a JSON object." }, secrets);
+        return;
+    }
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        sendJson(res, 400, { error: "Request body is not JSON." }, secrets);
+        return;
+    }
+    const result = saveSettings(state.config.configPath, parsed, homedir());
+    if (!result.ok) {
+        sendJson(res, result.status, result.body, secrets);
+        return;
+    }
+    state.mtimeMs = -1;
+    state.size = -1;
+    refreshLiveConfig(state);
+    sendJson(res, 200, result.document, state.secrets);
+}
+async function createJob(req, res, state, raw) {
+    const secrets = state.secrets;
+    if (!headerValue(req.headers["content-type"]).includes("application/json")) {
+        sendJson(res, 400, { error: "Content-Type must be application/json." }, secrets);
+        return;
+    }
+    let parsed;
+    if (!raw.trim()) {
+        sendJson(res, 400, { error: "Request body must be a JSON object." }, secrets);
+        return;
     }
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        sendJson(res, 400, { error: "Request body is not JSON." }, secrets);
+        return;
+    }
+    try {
+        const result = await intakeJobs(state.config, parsed);
+        sendJson(res, 200, result, state.secrets);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        sendJson(res, statusCode(error) ?? 400, { error: message }, state.secrets);
+    }
+}
+function openLiveConfig(config) {
+    const file = fileStamp(config.configPath);
+    return {
+        config,
+        secrets: secretValues(config),
+        mtimeMs: file?.mtimeMs ?? 0,
+        size: file?.size ?? -1,
+    };
+}
+/**
+ * Re-read the kiln config when the file's mtime or size changed.
+ * A file that does not parse keeps the last good config and records `configError`.
+ * The failed stamp is not stored, so the next request tries again.
+ */
+function refreshLiveConfig(state) {
+    const path = state.config.configPath;
+    const file = fileStamp(path);
+    if (!file) {
+        state.configError = redact(`Could not read kiln config ${path}: the file is missing.`, redactSecrets(state, path));
+        return;
+    }
+    if (file.mtimeMs === state.mtimeMs && file.size === state.size)
+        return;
+    try {
+        const next = loadKilnConfig(path);
+        state.config = next;
+        state.secrets = secretValues(next);
+        state.configError = undefined;
+        state.mtimeMs = file.mtimeMs;
+        state.size = file.size;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const named = message.includes(path) ? message : `${path}: ${message}`;
+        state.configError = redact(named, redactSecrets(state, path));
+    }
+}
+function fileStamp(path) {
+    try {
+        const stat = statSync(path);
+        return { mtimeMs: stat.mtimeMs, size: stat.size };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Last good secrets, plus a token sitting in a file that failed to load. */
+function redactSecrets(state, configPath) {
+    const secrets = [...state.secrets];
+    const disk = tokenFromDisk(configPath);
+    if (disk && !secrets.includes(disk))
+        secrets.push(disk);
+    return secrets;
+}
+function tokenFromDisk(configPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+        const token = parsed.jira?.apiToken;
+        if (typeof token !== "string")
+            return undefined;
+        const trimmed = token.trim();
+        return trimmed.length >= 8 ? trimmed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function repoList(config) {
+    return Object.entries(config.repos)
+        .map(([name, repo]) => ({ name, path: repo.path }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+function pageOptions(state, csrf) {
+    return {
+        csrf,
+        repos: repoList(state.config),
+        workflows: listWorkflowNames(),
+        ...(state.configError ? { configError: state.configError } : {}),
+    };
+}
+function statusDocument(state) {
+    return {
+        ...readStatus(state.config),
+        repos: repoList(state.config),
+        configError: state.configError ?? null,
+    };
 }
 function statusCode(error) {
     if (typeof error === "object" && error !== null && "statusCode" in error) {
@@ -362,7 +595,12 @@ function redirect(res, location) {
     res.end();
 }
 function secretValues(config) {
-    const values = [config.jira?.apiToken, process.env.JIRA_API_TOKEN];
+    const values = [
+        config.jira?.apiToken,
+        process.env.JIRA_API_TOKEN,
+        process.env.CLAUDE_CODE_OAUTH_TOKEN,
+        process.env.ANTHROPIC_API_KEY,
+    ];
     const found = [];
     for (const value of values) {
         const trimmed = value?.trim();

package/dist/settings.js

@@ -0,0 +1,204 @@
+import { createHash } from "node:crypto";
+import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { assertBranchName, assertCheckoutDirectory } from "./config.js";
+import { DEFAULT_BRANCH_TEMPLATE, DEFAULT_PR_TITLE } from "./pr-names.js";
+import { DEFAULT_MAX_ATTEMPTS, DEFAULT_MAX_FIX_ROUNDS, DEFAULT_STALL_TIMEOUT_MS, KilnConfigFileSchema, SettingsWriteSchema, } from "./schemas.js";
+const DEFAULTS = {
+    deliver: "local",
+    prTitle: DEFAULT_PR_TITLE,
+    branch: DEFAULT_BRANCH_TEMPLATE,
+    maxAttempts: DEFAULT_MAX_ATTEMPTS,
+    stallTimeoutMs: DEFAULT_STALL_TIMEOUT_MS,
+    maxFixRounds: DEFAULT_MAX_FIX_ROUNDS,
+    sandboxMode: "off",
+};
+export function readSettings(configPath) {
+    const read = readConfigFile(configPath);
+    if ("error" in read)
+        return fail(409, read.error);
+    const parsed = KilnConfigFileSchema.safeParse(read.raw);
+    if (!parsed.success)
+        return fail(409, `Kiln config ${configPath} is invalid.`);
+    return { ok: true, document: project(configPath, read.revision, parsed.data) };
+}
+/**
+ * Validate `body`, merge it into the file, and write atomically.
+ * Unknown keys already in the file stay. A revision that does not match the
+ * bytes on disk is a 409 and writes nothing.
+ */
+export function saveSettings(configPath, body, home = homedir()) {
+    if (!isRecord(body))
+        return fail(400, "Request body must be a JSON object.");
+    const read = readConfigFile(configPath);
+    if ("error" in read)
+        return fail(409, "The settings file changed on disk. Reload and try again.");
+    const claimed = body.revision;
+    if (typeof claimed !== "string" || claimed.length === 0) {
+        return fail(400, "Settings are invalid.", { revision: "Reload settings and try again." });
+    }
+    if (claimed !== read.revision) {
+        return fail(409, "The settings file changed on disk. Reload and try again.");
+    }
+    const parsed = SettingsWriteSchema.safeParse(body);
+    if (!parsed.success)
+        return fail(400, "Settings are invalid.", fieldErrors(parsed.error));
+    const { revision: _revision, ...editable } = parsed.data;
+    const fields = checkoutFields(dirname(configPath), editable, home);
+    if (Object.keys(fields).length > 0)
+        return fail(400, "Settings are invalid.", fields);
+    const next = mergeSettings(read.raw, editable);
+    const file = KilnConfigFileSchema.safeParse(next);
+    if (!file.success)
+        return fail(400, "Settings are invalid.", fieldErrors(file.error));
+    const again = readConfigFile(configPath);
+    if ("error" in again || again.revision !== read.revision) {
+        return fail(409, "The settings file changed on disk. Reload and try again.");
+    }
+    const contents = `${JSON.stringify(next, null, 2)}\n`;
+    writeAtomic(configPath, contents);
+    return { ok: true, document: project(configPath, hashContents(contents), file.data) };
+}
+function project(path, revision, file) {
+    const sandbox = editableSandbox(file.sandbox);
+    return {
+        path,
+        revision,
+        repos: file.repos,
+        ...(file.stallTimeoutMs !== undefined ? { stallTimeoutMs: file.stallTimeoutMs } : {}),
+        ...(file.maxAttempts !== undefined ? { maxAttempts: file.maxAttempts } : {}),
+        ...(file.maxFixRounds !== undefined ? { maxFixRounds: file.maxFixRounds } : {}),
+        ...(sandbox ? { sandbox } : {}),
+        defaults: DEFAULTS,
+    };
+}
+function editableSandbox(sandbox) {
+    if (!sandbox)
+        return undefined;
+    const mode = sandbox.mode;
+    const allowDomains = sandbox.allowDomains;
+    if (mode === undefined && allowDomains === undefined)
+        return undefined;
+    return {
+        ...(mode !== undefined ? { mode } : {}),
+        ...(allowDomains !== undefined ? { allowDomains } : {}),
+    };
+}
+function mergeSettings(raw, settings) {
+    const next = { ...raw };
+    const previousRepos = isRecord(raw.repos) ? raw.repos : {};
+    const repos = {};
+    for (const [name, entry] of Object.entries(settings.repos)) {
+        const prior = isRecord(previousRepos[name]) ? { ...previousRepos[name] } : {};
+        prior.path = entry.path;
+        setOptional(prior, "test", entry.test);
+        setOptional(prior, "deliver", entry.deliver);
+        setOptional(prior, "base", entry.base);
+        setOptional(prior, "prTitle", entry.prTitle);
+        setOptional(prior, "branch", entry.branch);
+        repos[name] = prior;
+    }
+    next.repos = repos;
+    setOptional(next, "stallTimeoutMs", settings.stallTimeoutMs);
+    setOptional(next, "maxAttempts", settings.maxAttempts);
+    setOptional(next, "maxFixRounds", settings.maxFixRounds);
+    if (settings.sandbox) {
+        const prior = isRecord(raw.sandbox) ? { ...raw.sandbox } : {};
+        setOptional(prior, "mode", settings.sandbox.mode);
+        setOptional(prior, "allowDomains", settings.sandbox.allowDomains);
+        if (Object.keys(prior).length === 0)
+            delete next.sandbox;
+        else
+            next.sandbox = prior;
+    }
+    return next;
+}
+function checkoutFields(configDir, settings, home) {
+    const fields = {};
+    for (const [name, entry] of Object.entries(settings.repos)) {
+        try {
+            assertCheckoutDirectory(name, configDir, entry.path, home);
+        }
+        catch (error) {
+            fields[`repos.${name}.path`] = error instanceof Error ? error.message : String(error);
+        }
+        if (entry.base === undefined)
+            continue;
+        try {
+            assertBranchName(entry.base);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            fields[`repos.${name}.base`] = message.replace(/^--base\s+\S+\s+/, "Base ");
+        }
+    }
+    return fields;
+}
+function fieldErrors(error) {
+    const fields = {};
+    for (const issue of error.issues) {
+        if (issue.code === "unrecognized_keys") {
+            const prefix = issue.path.length ? `${issue.path.map(String).join(".")}.` : "";
+            for (const key of issue.keys) {
+                const field = `${prefix}${key}`;
+                if (!fields[field])
+                    fields[field] = "Unknown field.";
+            }
+            continue;
+        }
+        const key = issue.path.length ? issue.path.map(String).join(".") : "body";
+        if (!fields[key])
+            fields[key] = issue.message;
+    }
+    return fields;
+}
+function setOptional(target, key, value) {
+    if (value === undefined)
+        delete target[key];
+    else
+        target[key] = value;
+}
+function readConfigFile(configPath) {
+    let text;
+    try {
+        text = readFileSync(configPath, "utf8");
+    }
+    catch {
+        return { error: "The settings file changed on disk. Reload and try again." };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { error: `Kiln config ${configPath} is invalid.` };
+    }
+    if (!isRecord(parsed))
+        return { error: `Kiln config ${configPath} must be a JSON object.` };
+    return { revision: hashContents(text), raw: parsed };
+}
+function hashContents(contents) {
+    return createHash("sha256").update(contents).digest("hex");
+}
+function writeAtomic(configPath, contents) {
+    const tmp = join(dirname(configPath), `.${basename(configPath)}.${process.pid}.tmp`);
+    try {
+        writeFileSync(tmp, contents, { mode: 0o600 });
+        renameSync(tmp, configPath);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+}
+function fail(status, error, fields) {
+    return {
+        ok: false,
+        status,
+        body: fields && Object.keys(fields).length > 0 ? { error, fields } : { error },
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/workflow.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, sep } from "node:path";
 import { jobBasename, packageRoot } from "./paths.js";
 const FACTORY_DIRECTIVE = /^<!--\s*factory:\s*(prompts\/factory\/[a-z0-9-]+\.md)\s*-->/;
@@ -26,6 +26,22 @@ const INPUT_VALUES = {
     description: (input) => input.specText,
     acceptance: (input) => input.specText,
 };
+/** Workflow names from `workflows/*.yaml`, sorted. */
+export function listWorkflowNames() {
+    const dir = join(packageRoot(), "workflows");
+    let names = [];
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((name) => name.endsWith(".yaml") && !name.startsWith("."))
+        .map((name) => name.slice(0, -".yaml".length))
+        .filter((name) => WORKFLOW_NAME.test(name))
+        .sort();
+}
 export function assertWorkflowName(name) {
     if (!WORKFLOW_NAME.test(name)) {
         throw new Error(`Workflow name ${JSON.stringify(name)} must start with a letter or digit and contain only letters, digits, dots, underscores, and hyphens.`);

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@lchase/kiln",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Run a workflow on any registered repo. A markdown spec is the input.",
+  "license": "MIT",
   "type": "module",
   "bin": {
     "kiln": "./dist/cli.js"

package/workflows/feature.yaml

@@ -125,10 +125,13 @@ steps:
 
         # Build and verify stay in order. These four do not need each other,
         # so concurrency 4 starts them together. They have no Write or Edit.
-        # Bash stays, because the factory prompts diff with git. Yak warns
-        # that concurrent Bash steps share one cwd. The preambles forbid
-        # re-running tests, builds, and any other write; git and file reads
-        # stay. input is inherited for baseRef; it is not in needs.
+        # Bash stays: the factory prompts run `git diff <main>...HEAD`. The
+        # kiln preambles allow read-only git and forbid re-running tests,
+        # builds, and writes. Yak 0.8.0 counts Bash as write-capable
+        # (WRITE_CAPABLE_TOOLS in src/ir/validate.ts) and has no read-only
+        # exemption, so tick prints a concurrency warning. Do not drop Bash
+        # or set concurrency to 1 to silence it. That needs a yak change.
+        # input is inherited for baseRef; it is not in needs.
         - id: security
           needs: [spec, build, verify]
           agent: