@lchase/kiln 0.9.0 → 0.10.0

package/dist/project.js

@@ -3,6 +3,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { basename, join, relative, sep } from "node:path";
 import { appendEvent } from "./events.js";
+import { costFromJournal, decideFailure } from "./failure.js";
 import { jobBasename, packageRoot } from "./paths.js";
 /**
  * Project a yak journal into the kiln event log. Called when a run is
@@ -186,25 +187,40 @@ function recordGateResolved(input, event) {
     });
 }
 function recordRunFinished(input, event) {
+    const cost = costFromJournal(input.events);
     if (event.status === "ok") {
         appendEvent(input.kilnDir, {
             job_id: input.jobId,
             run_id: input.runId,
             event: "run.finished",
-            properties: { status: "ok", once: "run.finished" },
+            properties: { status: "ok", tokens: cost.tokens, usd: cost.usd, once: "run.finished" },
         });
         return;
     }
-    if (event.status !== "failed")
+    // A normal failure is classified in recoverRuns, which owns the retry decision.
+    // A cancelled run is not recovered, so the class is recorded here.
+    if (event.status !== "failed" || event.reason !== "cancelled")
         return;
-    const reason = typeof event.reason === "string" ? clip(event.reason) : undefined;
+    const decision = decideFailure({
+        text: "cancelled",
+        operational: false,
+        blocked: true,
+        attempt: 1,
+        maxAttempts: Number.MAX_SAFE_INTEGER,
+        sameFingerprint: 1,
+        maxSameFingerprint: Number.MAX_SAFE_INTEGER,
+    });
     appendEvent(input.kilnDir, {
         job_id: input.jobId,
         run_id: input.runId,
         event: "run.failed",
         properties: {
             status: "failed",
-            ...(reason ? { reason } : {}),
+            reason: "cancelled",
+            class: decision.class,
+            fingerprint: decision.fingerprint,
+            tokens: cost.tokens,
+            usd: cost.usd,
             once: `run.failed:${input.runId}`,
         },
     });

package/dist/rails.js

@@ -0,0 +1,164 @@
+import { appendEvent, readEvents } from "./events.js";
+export function localDay(now) {
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, "0");
+    const day = String(now.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+export function isPaused(kilnDir) {
+    return pausedFrom(readEvents(kilnDir, { warn: () => { } }));
+}
+export function pausedFrom(events) {
+    let paused = false;
+    for (const event of events) {
+        if (event.event === "kiln.paused")
+            paused = true;
+        else if (event.event === "kiln.resumed")
+            paused = false;
+    }
+    return paused;
+}
+/** Append a pause event when the factory is running. Already paused is a no-op. */
+export function pauseFactory(kilnDir, now = new Date()) {
+    if (pausedFrom(readEvents(kilnDir, { warn: () => { } })))
+        return false;
+    appendEvent(kilnDir, {
+        job_id: null,
+        event: "kiln.paused",
+        properties: {},
+        ts: now.toISOString(),
+    });
+    return true;
+}
+/** Append a resume event when the factory is paused. Already running is a no-op. */
+export function resumeFactory(kilnDir, now = new Date()) {
+    if (!pausedFrom(readEvents(kilnDir, { warn: () => { } })))
+        return false;
+    appendEvent(kilnDir, {
+        job_id: null,
+        event: "kiln.resumed",
+        properties: {},
+        ts: now.toISOString(),
+    });
+    return true;
+}
+export function spendSnapshot(events, cap, now = new Date()) {
+    const day = localDay(now);
+    let usd = 0;
+    for (const event of events) {
+        if (localDay(new Date(event.ts)) !== day)
+            continue;
+        const amount = dollarCost(event);
+        if (amount === undefined)
+            continue;
+        usd += amount;
+    }
+    const limit = cap === undefined ? null : cap;
+    return {
+        day,
+        usd,
+        cap: limit,
+        blocked: limit !== null && usd >= limit,
+    };
+}
+export function spendFor(kilnDir, cap, now = new Date()) {
+    return spendSnapshot(readEvents(kilnDir, { warn: () => { } }), cap, now);
+}
+/** One event per local day when the dollar cap is blocking new runs. */
+export function recordDailyCap(kilnDir, spend, now = new Date()) {
+    if (!spend.blocked || spend.cap === null)
+        return;
+    appendEvent(kilnDir, {
+        job_id: null,
+        event: "budget.blocked",
+        properties: {
+            day: spend.day,
+            usd: spend.usd,
+            cap: spend.cap,
+            once: `daily-cap:${spend.day}`,
+        },
+        ts: now.toISOString(),
+    });
+}
+export function formatSpend(spend) {
+    const cap = spend.cap === null ? "no cap" : `$${spend.cap.toFixed(2)}`;
+    return `today ${spend.day}  $${spend.usd.toFixed(2)} / ${cap}`;
+}
+export function holdDetail(paused, spend) {
+    if (paused)
+        return "Paused. New runs wait until kiln resume.";
+    if (spend.blocked && spend.cap !== null) {
+        return `Daily cap reached ($${spend.usd.toFixed(2)} of $${spend.cap.toFixed(2)}). New runs wait until the local day rolls over.`;
+    }
+    return undefined;
+}
+/**
+ * Revise notes written since the latest `run.started` for this job.
+ * The next launch appends them to the spec, which is the next prompt's input.
+ */
+export function reviseNotesSinceRun(events, jobId) {
+    const notes = [];
+    for (const event of events) {
+        if (event.job_id !== jobId)
+            continue;
+        if (event.event === "run.started") {
+            notes.length = 0;
+            continue;
+        }
+        if (event.event === "gate.resolved" && event.properties.decision === "revise" && event.properties.note) {
+            notes.push(event.properties.note);
+        }
+    }
+    return notes;
+}
+export function withReviseNotes(spec, notes) {
+    if (notes.length === 0)
+        return spec;
+    return [
+        spec.trimEnd(),
+        "",
+        "## Human note",
+        "",
+        "Apply every note below on this round. A person typed it at the gate.",
+        "",
+        notes.join("\n\n"),
+        "",
+    ].join("\n");
+}
+/** Fingerprint or attempt-cap stop that a later manual retry has not cleared. */
+export function stopReasonFromEvents(events, jobId) {
+    let reason;
+    for (const event of events) {
+        if (event.job_id !== jobId)
+            continue;
+        if (event.event === "job.retried") {
+            reason = undefined;
+            continue;
+        }
+        if (event.event !== "needs-human")
+            continue;
+        if (event.properties.reason === "fingerprint" || event.properties.reason === "attempt-cap") {
+            reason = event.properties.reason;
+        }
+    }
+    return reason;
+}
+/** How many `run.failed` lines for this job already carry `fingerprint`. */
+export function fingerprintCount(events, jobId, fingerprint) {
+    let count = 0;
+    for (const event of events) {
+        if (event.job_id !== jobId || event.event !== "run.failed")
+            continue;
+        if (event.properties.fingerprint === fingerprint)
+            count += 1;
+    }
+    return count;
+}
+function dollarCost(event) {
+    if (event.event !== "run.finished" && event.event !== "run.failed")
+        return undefined;
+    const usd = event.properties.usd;
+    if (typeof usd !== "number" || !Number.isFinite(usd) || usd < 0)
+        return undefined;
+    return usd;
+}

package/dist/reconcile.js

@@ -10,10 +10,32 @@ export function inFlightCount(observation) {
 function inFlight(job, observation) {
     if (job.error || job.feedbackExhausted || job.feedbackAmbiguous)
         return false;
+    // A cap or fingerprint stop is waiting on a person. It does not hold a slot.
+    if (job.retriesExhausted || job.stopReason)
+        return false;
     const state = jobState(job, observation);
     return state === "running" || state === "needs-human" || state === "approved";
 }
 /**
+ * The only job-state transition. First match wins.
+ *
+ * | when | state |
+ * | fix awaiting publish | in-review |
+ * | launching, and the selected run is absent, retired, or a fix | running |
+ * | feedback exhausted or ambiguous, landed, pull request merged | done |
+ * | feedback exhausted or ambiguous, landed, pull request closed | failed |
+ * | feedback exhausted or ambiguous, landed, pull request still open | needs-human |
+ * | selected run not retired | that run: landed, rejected, failed, dead, needs-human, approved, running |
+ * | retired run that landed | done, in-review, or failed from the pull request |
+ * | retired run whose gate rejected | rejected |
+ * | retired suspended run | needs-human |
+ * | attempt cap or fingerprint breaker | needs-human |
+ * | retired, failed, or dead run | failed |
+ * | launching breadcrumb | running |
+ * | dependencies unmet | blocked |
+ * | launch error | failed |
+ * | otherwise | queued |
+ *
  * `deliver=local`: `done` is a finished run whose gate says approve.
  * `deliver=pr`: that landed run is `in-review` while the pull request is open
  * (and in the gap before tick opens it) and `done` only once it has merged.
@@ -21,6 +43,7 @@ function inFlight(job, observation) {
  * a slot and does not unblock dependents. An ok run with no readable
  * decision is `failed`, so a missing artifact cannot unblock the next job.
  * An investigation is `done` on approve and never `in-review`.
+ * A cap or fingerprint stop is `needs-human` and does not hold a slot.
  */
 export function jobState(job, observation) {
     if (job.fixAwaitingPublish)
@@ -42,8 +65,8 @@ export function jobState(job, observation) {
         return "rejected";
     if (job.run?.status === "suspended")
         return "needs-human";
-    if (job.retriesExhausted)
-        return "dead";
+    if ((job.retriesExhausted || job.stopReason) && !job.launching)
+        return "needs-human";
     if (job.runRetired || job.run?.status === "failed" || job.run?.status === "dead")
         return "failed";
     if (job.launching)
@@ -150,7 +173,7 @@ function canStartFix(job) {
 }
 /** 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)
+    if (job.error || job.launching || job.retriesExhausted || job.stopReason || job.ledgerError)
         return false;
     if (job.run && !job.runRetired)
         return false;
@@ -192,6 +215,9 @@ export function decide(observation, now = new Date()) {
     }
     if (inFlightCount(observation) >= observation.maxConcurrent)
         return actions;
+    // Pause and the daily dollar cap stop new runs. In-flight work is not touched.
+    if (observation.paused || observation.spendBlocked)
+        return actions;
     const retry = observation.jobs.find((job) => canRetry(job, observation, now));
     if (retry) {
         actions.push({ type: "retry", jobId: retry.jobId, repo: retry.repo });

package/dist/reliability.js

@@ -4,7 +4,10 @@ import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync
 import { dirname, join, resolve, sep } from "node:path";
 import { z } from "zod";
 import { authenticationFailureLine } from "./auth.js";
-import { appendEvent } from "./events.js";
+import { attemptsFor } from "./config.js";
+import { appendEvent, readEvents } from "./events.js";
+import { decideFailure, failureFingerprint, isSandboxStartFlake } from "./failure.js";
+import { fingerprintCount } from "./rails.js";
 import { jobBasename } from "./paths.js";
 import { FAILURE_REASONS } from "./reconcile.js";
 /**
@@ -88,25 +91,23 @@ export function resetAttemptLedger(kilnDir, jobId, runId) {
  */
 export function recoverRuns(config, jobs, options) {
     const notes = [];
+    const events = readEvents(config.kilnDir, { warn: () => { } });
     for (const job of jobs) {
         if (job.error)
             continue;
         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;
         if (pending.killPid !== undefined && !killTree(pending.killPid))
             continue;
-        const recorded = recordFailure(config, job.jobId, existing, pending, options.now);
+        const recorded = recordFailure(config, job, existing, pending, options.now, events);
         if (recorded.created) {
             appendLog(job.logPath, recorded.ledger.attempts.at(-1));
             const runId = pending.runId ?? job.run?.runId;
+            const cost = job.run?.cost ?? { tokens: null, usd: null };
             appendEvent(config.kilnDir, {
                 job_id: job.jobId,
                 run_id: runId ?? null,
@@ -114,15 +115,31 @@ export function recoverRuns(config, jobs, options) {
                 properties: {
                     reason: pending.reason,
                     ...(pending.detail ? { detail: pending.detail } : {}),
+                    class: recorded.decision.class,
+                    fingerprint: recorded.decision.fingerprint,
+                    tokens: cost.tokens,
+                    usd: cost.usd,
                     once: runId ? `run.failed:${runId}` : `run.failed:launch:${recorded.ledger.attempts.length}`,
                 },
             });
+            if (recorded.decision.needsHuman) {
+                appendEvent(config.kilnDir, {
+                    job_id: job.jobId,
+                    run_id: runId ?? null,
+                    event: "needs-human",
+                    properties: {
+                        reason: recorded.decision.needsHuman,
+                        once: `needs-human:${recorded.decision.needsHuman}:${runId ?? recorded.ledger.attempts.length}`,
+                    },
+                });
+            }
             notes.push({
                 jobId: job.jobId,
                 kind: kindFor(pending.reason),
                 reason: pending.reason,
                 attempt: recorded.ledger.attempts.length,
                 ...(recorded.ledger.nextRetryAt ? { nextRetryAt: recorded.ledger.nextRetryAt } : {}),
+                ...(recorded.decision.needsHuman ? { needsHuman: true } : {}),
             });
         }
         const checkout = job.run?.checkout ?? config.repos[job.repo]?.path;
@@ -141,18 +158,6 @@ 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;
@@ -261,10 +266,24 @@ function readAuthLog(logPath) {
             closeSync(fd);
     }
 }
-function recordFailure(config, jobId, existing, pending, now) {
-    const ledger = existing ?? { jobId, attempts: [] };
+function recordFailure(config, job, existing, pending, now, events) {
+    const ledger = existing ?? { jobId: job.jobId, attempts: [] };
+    const text = failureText(job, pending);
+    const decision = decideFailure({
+        text,
+        operational: pending.reason === "stalled" ||
+            pending.reason === "orphaned" ||
+            pending.reason === "crashed" ||
+            pending.reason === "failed",
+        blocked: pending.reason === "auth-failed" ||
+            (Boolean(job.run?.sandboxError) && !isSandboxStartFlake(text)),
+        attempt: ledger.attempts.length + 1,
+        maxAttempts: attemptsFor(config, job.repo),
+        sameFingerprint: fingerprintCount(events, job.jobId, failureFingerprint(text)) + 1,
+        maxSameFingerprint: config.maxSameFingerprint,
+    });
     if (alreadyRecorded(ledger, pending))
-        return { ledger, created: false };
+        return { ledger, created: false, decision };
     const attempt = {
         n: ledger.attempts.length + 1,
         at: now.toISOString(),
@@ -274,16 +293,25 @@ function recordFailure(config, jobId, existing, pending, now) {
         detail: pending.detail,
     };
     const attempts = [...ledger.attempts, attempt];
-    const exhausted = attempts.length >= config.maxAttempts || pending.reason === "auth-failed";
-    const next = exhausted ? undefined : new Date(now.getTime() + retryDelayMs(attempts.length)).toISOString();
+    const next = decision.retry ? new Date(now.getTime() + retryDelayMs(attempts.length)).toISOString() : undefined;
     const written = {
-        jobId,
+        jobId: job.jobId,
         attempts,
         ...(next ? { nextRetryAt: next } : {}),
         ...(ledger.ignoredRunIds && ledger.ignoredRunIds.length > 0 ? { ignoredRunIds: ledger.ignoredRunIds } : {}),
     };
     writeLedger(config.kilnDir, written);
-    return { ledger: written, created: true };
+    return { ledger: written, created: true, decision };
+}
+function failureText(job, pending) {
+    const parts = [pending.detail];
+    if (job.run?.sandboxError)
+        parts.push(job.run.sandboxError);
+    for (const event of job.run?.stepEvents ?? []) {
+        if (event.detail)
+            parts.push(event.detail);
+    }
+    return parts.filter((part) => part.length > 0).join("\n");
 }
 function alreadyRecorded(ledger, pending) {
     if (pending.runId)

package/dist/report.js

@@ -159,6 +159,10 @@ export function statusDetails(job) {
         lines.push(`feedback ${job.feedbackRounds?.length}`);
     if (job.state === "needs-human" && job.feedbackReason)
         lines.push(`reason ${job.feedbackReason}`);
+    if (job.stopReason)
+        lines.push(`reason ${job.stopReason}`);
+    if (job.waitReason)
+        lines.push(job.waitReason);
     if (job.attemptCount > 0)
         lines.push(`attempts ${job.attemptCount}`);
     if (job.lastFailureReason)
@@ -167,8 +171,9 @@ export function statusDetails(job) {
         lines.push(AUTH_FAILED_LINE);
     if (job.nextRetryAt)
         lines.push(`next retry ${job.nextRetryAt}`);
-    if (job.state === "dead" && job.attemptCount > 0)
+    if ((job.state === "dead" || job.stopReason) && job.attemptCount > 0 && job.gates.length === 0) {
         lines.push(`retry: kiln retry ${job.jobId}`);
+    }
     if (job.noReadableApproval)
         lines.push("no readable approval decision");
     if (job.cancelCommand)
@@ -186,6 +191,9 @@ export function statusDetails(job) {
                 lines.push(`approve: kiln approve ${job.jobId}`);
             if (gate.choices.includes("reject"))
                 lines.push(`reject: kiln reject ${job.jobId}`);
+            if (gate.choices.includes("approve") || gate.choices.includes("revise")) {
+                lines.push(`revise: kiln revise ${job.jobId} --note <text>`);
+            }
         }
     }
     return lines;
@@ -216,7 +224,7 @@ function toStatusJob(job, observation) {
             ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
             launchFailed: job.launchFailed,
             attemptCount: job.attemptCount ?? 0,
-            maxAttempts: observation.maxAttempts,
+            maxAttempts: job.attemptCap ?? observation.maxAttempts,
             ...(job.lastFailureReason ? { lastFailureReason: job.lastFailureReason } : {}),
             ...(job.nextRetryAt ? { nextRetryAt: job.nextRetryAt } : {}),
             invalidReason: job.error,
@@ -226,6 +234,7 @@ function toStatusJob(job, observation) {
             gates: [],
             canApprove: false,
             canReject: false,
+            canRevise: false,
             steps: progressFor(job),
             ...(job.deliver ? { deliver: job.deliver } : {}),
             ...(job.createdAt ? { createdAt: job.createdAt } : {}),
@@ -239,7 +248,7 @@ function toStatusJob(job, observation) {
         : job.feedbackAmbiguous
             ? "feedback-ambiguous"
             : undefined;
-    const gates = state === "needs-human" && job.run && !feedbackReason ? job.run.gates.map(toGateView) : [];
+    const gates = state === "needs-human" && job.run && !feedbackReason && !job.stopReason ? job.run.gates.map(toGateView) : [];
     const prNumber = job.delivery?.prNumber;
     const runId = job.run?.runId;
     const showBranch = runId !== undefined && (state === "done" || state === "in-review" || feedbackReason !== undefined);
@@ -263,8 +272,12 @@ function toStatusJob(job, observation) {
         ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
         launchFailed: job.launchFailed,
         attemptCount: job.attemptCount ?? 0,
-        maxAttempts: observation.maxAttempts,
+        maxAttempts: job.attemptCap ?? observation.maxAttempts,
         ...(job.lastFailureReason ? { lastFailureReason: job.lastFailureReason } : {}),
+        ...(job.stopReason ? { stopReason: job.stopReason } : {}),
+        ...(observation.holdDetail && (state === "queued" || state === "blocked" || state === "failed")
+            ? { waitReason: observation.holdDetail }
+            : {}),
         ...(job.nextRetryAt && !job.retriesExhausted ? { nextRetryAt: job.nextRetryAt } : {}),
         ...(job.ledgerError ? { ledgerError: job.ledgerError } : {}),
         ...(job.feedbackLedgerError ? { feedbackLedgerError: job.feedbackLedgerError } : {}),
@@ -281,6 +294,7 @@ function toStatusJob(job, observation) {
         gates,
         canApprove: gates.some((gate) => gate.choices.includes("approve")),
         canReject: gates.some((gate) => gate.choices.includes("reject")),
+        canRevise: gates.some((gate) => gate.choices.includes("approve") || gate.choices.includes("revise")),
         steps: progressFor(job),
         ...(job.createdAt ? { createdAt: job.createdAt } : {}),
         ...(job.run?.startedAt ? { startedAt: job.run.startedAt } : {}),
@@ -402,7 +416,7 @@ export function renderTick(observation, actions, launches, delivers = [], findin
             : `findings ${recorded.jobId}  missing`);
     }
     for (const note of notes) {
-        const next = note.nextRetryAt ? `  next ${note.nextRetryAt}` : note.reason === "auth-failed" ? "" : "  dead";
+        const next = note.nextRetryAt ? `  next ${note.nextRetryAt}` : note.needsHuman ? "  needs human" : "";
         lines.push(`${note.kind} ${note.jobId}  ${note.reason}  attempt ${note.attempt}${next}`);
     }
     for (const note of feedbackNotes) {

package/dist/schemas.js

@@ -36,6 +36,18 @@ export const RepoEntrySchema = z.object({
      * The local branch stays `yak/<run-id>`.
      */
     branch: z.string().min(1, "Branch template is empty.").optional(),
+    /** Overrides the global attempt cap for jobs in this repo. */
+    maxAttempts: z
+        .number()
+        .int("Max attempts must be a whole number.")
+        .min(1, "Max attempts must be at least 1.")
+        .optional(),
+    /** Overrides the global fix-round cap for jobs in this repo. */
+    maxFixRounds: z
+        .number()
+        .int("Max fix rounds must be a whole number.")
+        .min(1, "Max fix rounds must be at least 1.")
+        .optional(),
 });
 /** Repo map shared by the config file and the settings API. */
 export const KilnReposSchema = z.record(z.string().regex(REPO_NAME, "must start with a letter or digit and contain only letters, digits, dots, underscores, and hyphens"), RepoEntrySchema);
@@ -75,21 +87,34 @@ export const EditableSandboxSchema = SandboxSettingsSchema.pick({
 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. */
+/** Transient failures retry until this many attempts, then the job needs a person. */
 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;
+/** Identical failure fingerprints before the job needs a person. */
+export const DEFAULT_MAX_SAME_FINGERPRINT = 3;
 /**
  * Milliseconds without a yak event or log output before a running job is
  * killed and retried. Default 15 minutes. `0` or negative disables stall detection.
  */
 const stallTimeoutMs = z.number().int("Stall timeout must be a whole number of milliseconds.").optional();
-/** Transient failures before the job is dead. Default 3. */
+/** Transient failures before the job needs a person. Default 3. Hitting the cap is a budget failure. */
 const maxAttempts = z
     .number()
     .int("Max attempts must be a whole number.")
     .min(1, "Max attempts must be at least 1.")
     .optional();
+/** Same failure fingerprint before Needs human. Default 3. */
+const maxSameFingerprint = z
+    .number()
+    .int("Fingerprint limit must be a whole number.")
+    .min(1, "Fingerprint limit must be at least 1.")
+    .optional();
+/**
+ * Dollars of recorded run cost allowed on the local calendar day.
+ * Omitted means no cap. `0` blocks new runs immediately.
+ */
+const dailyDollarCap = z.number().nonnegative("Daily dollar cap cannot be negative.").optional();
 /**
  * Fix rounds for an open pull request before the job is needs-human with
  * reason `feedback-exhausted`. Default 2. Kiln does not merge.
@@ -109,6 +134,8 @@ export const EditableKilnSettingsSchema = z.object({
     stallTimeoutMs,
     maxAttempts,
     maxFixRounds,
+    maxSameFingerprint,
+    dailyDollarCap,
     sandbox: EditableSandboxSchema.optional(),
 });
 /** PUT /api/settings body. `revision` is the sha256 of the file the client loaded. */
@@ -121,6 +148,8 @@ export const KilnConfigFileSchema = z.object({
     stallTimeoutMs,
     maxAttempts,
     maxFixRounds,
+    maxSameFingerprint,
+    dailyDollarCap,
     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. */
@@ -176,9 +205,10 @@ export const JobSchema = z.object({
  * `deliver=pr`. It does not enter `in-review`. A reject, a failure, a dead
  * process, and an ok run with no readable approval do not unblock an
  * after-merged dependent. A stacked job unblocks when its one upstream has
- * landed, which includes `in-review`. `dead` is also a job whose transient
- * failures have used `maxAttempts`. Those attempts live under the kiln
- * directory, not in this file.
+ * landed, which includes `in-review`. A job that has used its attempt cap,
+ * fix-round cap, or fingerprint breaker is `needs-human`. `dead` is a run
+ * whose process died and has not been recorded yet. Attempts live under
+ * the kiln directory, not in this file.
  */
 export const JOB_STATES = [
     "queued",