@lchase/kiln 0.9.0 → 0.10.0

package/dist/driver.js

@@ -4,16 +4,20 @@ import { closeSync, existsSync, linkSync, mkdirSync, openSync, readdirSync, read
 import { basename, dirname, isAbsolute, join } from "node:path";
 import { claudeCredentialPreflight } from "./auth.js";
 import { buildAttention } from "./attention.js";
+import { attemptsFor, fixRoundsFor } from "./config.js";
 import { clearLaunchError, deliverJob, plannedRemoteBranch, readDelivery, readLaunchError, resolveLaunchBase, writeDelivery, writeLaunchError, isMerged, } from "./delivery.js";
 import { feedbackSpec, openFeedbackRound, planFeedback, readFeedbackLedger, writeFeedbackLedger, } from "./feedback.js";
-import { appendEvent } from "./events.js";
+import { appendEvent, readEvents } from "./events.js";
+import { costFromJournal } from "./failure.js";
+import { ensureFixTrailers } from "./fix-commit.js";
+import { holdDetail, pausedFrom, recordDailyCap, reviseNotesSinceRun, spendSnapshot, stopReasonFromEvents, withReviseNotes, } from "./rails.js";
 import { appendInvestigationFindings, existingFindingsPath, findingsFilePath, INVESTIGATION_WORKFLOW, readFindingsMarkdown, writeFindings, } from "./findings.js";
 import { defaultHost } from "./host.js";
 import { readJobSpec, resolveJobSpec } from "./jobs.js";
 import { jobBasename, packageRoot } from "./paths.js";
 import { decide, isLanded, jobState, } from "./reconcile.js";
 import { fileMtimeMs, isPidAlive, readAttemptLedger, recoverRuns, resetAttemptLedger, } from "./reliability.js";
-import { projectRunJournal } from "./project.js";
+import { projectRunJournal, promptsHash } from "./project.js";
 import { gateAnswerCommand, renderStatus, renderTick, statusView, yakCliPath, sandboxFailureDetail, } from "./report.js";
 import { AGENT_SANDBOX_IMAGE, injectAgentSandbox, jobIsSandboxed, probeSandboxEnvironment, PROXY_SANDBOX_IMAGE, requiredSandboxImages, resolveSandbox, sandboxIsEnabled, sandboxPreflight, sandboxPreflightFor, } from "./sandbox.js";
 import { JobSchema } from "./schemas.js";
@@ -42,16 +46,19 @@ export function runTick(config, host = defaultHost(), options = {}) {
     const startup = options.startup ?? true;
     const now = options.now ?? new Date();
     return withTickLock(config.kilnDir, () => {
-        const notes = recoverRuns(config, observe(config, host).observation.jobs, { startup, now });
+        const notes = recoverRuns(config, observe(config, host, now).observation.jobs, { startup, now });
         const facts = sandboxIsEnabled(config)
             ? (options.sandboxFacts ?? probeSandboxEnvironment(process.env, requiredSandboxImages(config)))
             : undefined;
-        const midway = observe(config, host);
+        const midway = observe(config, host, now);
         bindOpenFixRuns(config, midway);
         const published = publishReadyFixes(config, host, midway);
-        const world = observe(config, host);
+        const world = observe(config, host, now);
         const feedbackNotes = watchPullRequests(config, world, host);
         const actions = decide(world.observation, now);
+        if (world.observation.spendBlocked) {
+            recordDailyCap(config.kilnDir, spendSnapshot(readEvents(config.kilnDir, { warn: () => { } }), config.dailyDollarCap, now), now);
+        }
         const body = apply(config, world, actions, host, notes, now, [...published, ...feedbackNotes], facts);
         const heads = [
             claudeCredentialPreflight(process.env, config.adapter),
@@ -63,7 +70,7 @@ export function runTick(config, host = defaultHost(), options = {}) {
 /** Startup pass shared by `kiln tick` (via `runTick`) and `kiln serve`. Idempotent. */
 export function startupRecovery(config, host = defaultHost(), now = new Date()) {
     withTickLock(config.kilnDir, () => {
-        recoverRuns(config, observe(config, host).observation.jobs, { startup: true, now });
+        recoverRuns(config, observe(config, host, now).observation.jobs, { startup: true, now });
     });
 }
 export function answerJob(config, jobId, choice, host = defaultHost()) {
@@ -126,8 +133,8 @@ export function retryJob(config, jobId, host = defaultHost()) {
         if (observed.error)
             throw new Error(`Job ${jobId} is invalid: ${observed.error}`);
         const state = jobState(observed, world.observation);
-        if (state !== "failed" && state !== "dead") {
-            throw new Error(`Job ${jobId} is ${state}, not failed or dead.`);
+        if (!canManualRetry(state, observed)) {
+            throw new Error(`Job ${jobId} is ${state}, not failed, dead, or stopped for a person.`);
         }
         const job = world.jobs.get(jobId);
         if (!job)
@@ -154,7 +161,7 @@ export function retryJob(config, jobId, host = defaultHost()) {
             const detail = report.detail.endsWith("\n") || report.detail.length === 0 ? report.detail : `${report.detail}\n`;
             return `retry ${jobId}  ${job.repo}\n${clearedLine}${detail}`;
         }
-        if (state === "dead" && observed.run) {
+        if ((state === "dead" || observed.stopReason) && observed.run) {
             try {
                 spawnSync(process.execPath, [yakCliPath(), "cancel", observed.run.runId], {
                     cwd: observed.run.checkout,
@@ -174,6 +181,64 @@ export function retryJob(config, jobId, host = defaultHost()) {
         return `retry ${report.jobId}  ${report.repo}\n${clearedLine}${output}`;
     });
 }
+function canManualRetry(state, job) {
+    if (state === "failed" || state === "dead")
+        return true;
+    return state === "needs-human" && Boolean(job.stopReason) && (job.run?.gates.length ?? 0) === 0;
+}
+/**
+ * Send a gated job back for another round. The note is stored on a
+ * `gate.resolved` event (redacted, otherwise verbatim) and appended to the
+ * spec the next launch passes into the prompt.
+ */
+export function reviseJob(config, jobId, note, host = defaultHost()) {
+    const trimmed = note.trim();
+    if (!trimmed)
+        throw new Error("A revise note is required.");
+    if (trimmed.length > 8_000)
+        throw new Error("A revise note must be 8000 characters or fewer.");
+    return withTickLock(config.kilnDir, () => {
+        const world = observe(config, host);
+        const observed = world.observation.jobs.find((candidate) => candidate.jobId === jobId);
+        if (!observed)
+            throw new Error(`No job ${jobId}.`);
+        if (observed.error)
+            throw new Error(`Job ${jobId} is invalid: ${observed.error}`);
+        const state = jobState(observed, world.observation);
+        const gate = observed.run?.gates[0];
+        if (state !== "needs-human" || !observed.run || !gate) {
+            throw new Error(`Job ${jobId} is ${state}, not waiting on a gate.`);
+        }
+        const job = world.jobs.get(jobId);
+        if (!job)
+            throw new Error(`No job ${jobId}.`);
+        appendEvent(config.kilnDir, {
+            job_id: jobId,
+            run_id: observed.run.runId,
+            event: "gate.resolved",
+            step: gate.stepId,
+            properties: {
+                decision: "revise",
+                by: "human",
+                repo: job.repo,
+                note: trimmed,
+            },
+        });
+        resetAttemptLedger(config.kilnDir, jobId, observed.run.runId);
+        rmSync(breadcrumbPath(config.kilnDir, jobId), { force: true });
+        clearLaunchError(config.kilnDir, jobId);
+        const events = readEvents(config.kilnDir, { warn: () => { } });
+        const spend = spendSnapshot(events, config.dailyDollarCap);
+        const paused = pausedFrom(events);
+        const hold = holdDetail(paused, spend);
+        if (hold)
+            return `revised ${jobId}\n${hold}\n`;
+        const again = observe(config, host);
+        const report = launchJob(config, again, job, host);
+        const output = report.output.endsWith("\n") || report.output.length === 0 ? report.output : `${report.output}\n`;
+        return `revised ${jobId}  ${report.repo}\n${output}`;
+    });
+}
 function shouldRedeliver(job) {
     if (!isLanded(job))
         return false;
@@ -185,9 +250,13 @@ function gateForChoice(gates, choice) {
     return (gates.find((gate) => gate.choices?.includes(choice)) ??
         gates.find((gate) => !gate.choices?.length));
 }
-function observe(config, host) {
+function observe(config, host, now = new Date()) {
     const loaded = loadJobs(config);
     const runs = scanRuns(config);
+    const events = readEvents(config.kilnDir, { warn: () => { } });
+    const paused = pausedFrom(events);
+    const spend = spendSnapshot(events, config.dailyDollarCap, now);
+    const waiting = holdDetail(paused, spend);
     const breadcrumbs = readBreadcrumbs(config.kilnDir);
     const jobs = [];
     const records = new Map();
@@ -234,10 +303,13 @@ function observe(config, host) {
         const launchActivityMs = later(crumb ? fileMtimeMs(crumb.path) : undefined, logPath ? fileMtimeMs(logPath) : undefined);
         const attemptCount = ledger?.attempts.length ?? 0;
         const lastFailure = ledger?.attempts.at(-1);
-        const exhausted = attemptCount >= config.maxAttempts &&
+        const attemptCap = attemptsFor(config, entry.job?.repo ?? "");
+        const exhausted = attemptCount >= attemptCap &&
             attemptCount > 0 &&
             !launching &&
             (picked.retired || !run || run.status === "dead" || run.status === "failed");
+        const eventStop = entry.job ? stopReasonFromEvents(events, entry.job.id) : undefined;
+        const stopReason = eventStop ?? (exhausted ? "attempt-cap" : undefined);
         const specPath = entry.job ? resolveJobSpec(config.kilnDir, entry.job.spec) : undefined;
         const findingsPath = entry.job?.workflow === INVESTIGATION_WORKFLOW
             ? existingFindingsPath(config.kilnDir, entry.job.id)
@@ -276,6 +348,8 @@ function observe(config, host) {
             ...(lastFailure ? { lastFailureReason: lastFailure.reason } : {}),
             ...(ledger?.nextRetryAt && !exhausted ? { nextRetryAt: ledger.nextRetryAt } : {}),
             ...(exhausted ? { retriesExhausted: true } : {}),
+            ...(stopReason ? { stopReason } : {}),
+            attemptCap,
             ...(picked.retired ? { runRetired: true } : {}),
             ...(ledgerResult === "corrupt" ? { ledgerError: "attempt ledger is unreadable" } : {}),
             ...(entry.job ? { sandboxed: jobIsSandboxed(config, entry.job.id, entry.job.workflow) } : {}),
@@ -296,6 +370,9 @@ function observe(config, host) {
             maxAttempts: config.maxAttempts,
             jobs,
             breadcrumbsToClear,
+            ...(paused ? { paused: true } : {}),
+            ...(spend.blocked ? { spendBlocked: true } : {}),
+            ...(waiting ? { holdDetail: waiting } : {}),
         },
         jobs: records,
     };
@@ -438,7 +515,8 @@ function specHandedToYak(config, world, job) {
         }
         sections.push({ title: dep.title, markdown: readFileSync(path, "utf8") });
     }
-    return appendInvestigationFindings(base, sections);
+    const noted = withReviseNotes(appendInvestigationFindings(base, sections), reviseNotesSinceRun(readEvents(config.kilnDir, { warn: () => { } }), job.id));
+    return noted;
 }
 /** Remote name the stacked pull request targets. Falls back to the local yak ref. */
 function upstreamBranch(world, job) {
@@ -550,6 +628,15 @@ function publishReadyFixes(config, host, world) {
         const record = readDelivery(config.kilnDir, job.jobId);
         const checkout = job.run.checkout;
         const source = `yak/${job.run.runId}`;
+        const worktree = join(checkout, ".yak", "worktrees", job.run.runId);
+        if (existsSync(worktree)) {
+            ensureFixTrailers(worktree, {
+                jobId: job.jobId,
+                round: open.round,
+                promptsHash: hashForRun(config.kilnDir, job.jobId, job.run.runId),
+                title: job.title,
+            }, open.headSha);
+        }
         if (!record?.branch) {
             notes.push(`feedback ${job.jobId} failed: no pull request branch to publish`);
             continue;
@@ -607,6 +694,14 @@ function publishReadyFixes(config, host, world) {
     }
     return notes;
 }
+function hashForRun(kilnDir, jobId, runId) {
+    for (const event of readEvents(kilnDir, { warn: () => { } })) {
+        if (event.job_id === jobId && event.run_id === runId && event.event === "run.started") {
+            return event.properties.prompts_hash;
+        }
+    }
+    return promptsHash("fix", kilnDir, jobId);
+}
 function isNonFastForward(message) {
     return /non-fast-forward|\[rejected\]|failed to push some refs/i.test(message);
 }
@@ -676,7 +771,7 @@ function watchPullRequests(config, world, host) {
             continue;
         }
         job.feedbackPlan = planFeedback({
-            maxFixRounds: config.maxFixRounds,
+            maxFixRounds: fixRoundsFor(config, job.repo),
             ledger,
             snapshot,
         });
@@ -769,7 +864,7 @@ function startFix(config, world, job, host, now, sandboxFacts) {
         writeBreadcrumb(breadcrumbPath(config.kilnDir, job.id), { jobId: job.id, pid: 0, logPath });
         return { jobId: job.id, repo: job.repo, kind: "fix", output: message };
     }
-    const report = launchFixRun(config, job, host, repo.path, headSha, specText, sandboxFacts);
+    const report = launchFixRun(config, job, host, repo.path, headSha, specText, round, sandboxFacts);
     return { ...report, output: `round ${round}\n${report.output}` };
 }
 /** Relaunch the open fix round. Does not append a round. Failures become a dead launch so retry can see them. */
@@ -790,7 +885,7 @@ function launchOpenFix(config, world, job, host, checkout, open, sandboxFacts) {
         writeBreadcrumb(breadcrumbPath(config.kilnDir, job.id), { jobId: job.id, pid: 0, logPath });
         return { jobId: job.id, repo: job.repo, kind: "fix", output: message };
     }
-    return launchFixRun(config, job, host, checkout, headSha, specText, sandboxFacts);
+    return launchFixRun(config, job, host, checkout, headSha, specText, open.round, sandboxFacts);
 }
 function resolveCommit(host, checkout, sha) {
     try {
@@ -802,7 +897,7 @@ function resolveCommit(host, checkout, sha) {
     }
 }
 /** `workflows/fix.yaml` on `headSha`. Commits on `yak/<run-id>`. Does not push. */
-function launchFixRun(config, job, host, checkout, headSha, specText, sandboxFacts) {
+function launchFixRun(config, job, host, checkout, headSha, specText, round, sandboxFacts) {
     const refused = claudeCredentialPreflight(process.env, config.adapter);
     if (refused)
         return { jobId: job.id, repo: job.repo, kind: "fix", output: refused };
@@ -814,6 +909,7 @@ function launchFixRun(config, job, host, checkout, headSha, specText, sandboxFac
     const blocked = commitAgentSandbox(config, job.id, "fix", workflow, logPath, sandboxFacts);
     if (blocked)
         return { jobId: job.id, repo: job.repo, kind: "fix", output: blocked };
+    const hash = promptsHash("fix", config.kilnDir, job.id);
     ensureCheckoutExcludes(checkout);
     const input = workflowInputs(sourceWorkflow, {
         title: job.title,
@@ -826,6 +922,9 @@ function launchFixRun(config, job, host, checkout, headSha, specText, sandboxFac
         ...process.env,
         ...(repo?.test ? { KILN_TEST: repo.test } : {}),
         KILN_TASK_TITLE: job.title,
+        KILN_JOB: job.id,
+        KILN_ROUND: String(round),
+        KILN_PROMPTS_HASH: hash,
         KILN_VERIFY_WRAPPER: join(packageRoot(), "dist", "truncate-output.js"),
     };
     return spawnLogged(config, host, {
@@ -1056,6 +1155,7 @@ function scanRuns(config) {
             const stepPlan = readRunStepPlan(runDir);
             const stepEvents = stepEventsFrom(events);
             const sandboxError = sandboxFailureDetail(stepEvents);
+            const cost = costFromJournal(events);
             const pid = livePid(events);
             const activityMs = eventActivityMs(events) ?? fileMtimeMs(join(runDir, "journal.jsonl"));
             const finishedReason = finished && typeof finished.reason === "string" ? finished.reason : undefined;
@@ -1074,6 +1174,7 @@ function scanRuns(config) {
                 ...(activityMs !== undefined ? { activityMs } : {}),
                 ...(finishedReason ? { finishedReason } : {}),
                 ...(sandboxError ? { sandboxError } : {}),
+                cost,
             };
             const list = byTag.get(started.tag) ?? [];
             list.push(run);

package/dist/events.js

@@ -9,7 +9,8 @@ import { redactDeep } from "./redact.js";
  * parses it. A write failure is reported and does not escape to the caller.
  *
  * `run_id` and `step` are null when the moment has none. `job_id` is null
- * only for `config.reloaded`, which is not a job.
+ * for `config.reloaded`, `kiln.paused`, `kiln.resumed`, and `budget.blocked`,
+ * which are not a job.
  */
 export const EVENT_NAMES = [
     "job.added",
@@ -27,6 +28,9 @@ export const EVENT_NAMES = [
     "worktree.kept",
     "config.reloaded",
     "needs-human",
+    "kiln.paused",
+    "kiln.resumed",
+    "budget.blocked",
 ];
 const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
 const once = z.string().min(1).optional();
@@ -80,14 +84,24 @@ const GateResolved = z.object({
     edit: z.string().min(1).optional(),
     once,
 });
+const costFields = {
+    /** Sum of yak `budget.consumed` tokens. Null when the journal did not report any. */
+    tokens: z.number().nonnegative().nullable().optional(),
+    /** Sum of reported dollars. Null when the journal did not report any. Never invented. */
+    usd: z.number().nonnegative().nullable().optional(),
+};
 const RunFailed = z.object({
     reason: z.string().min(1).optional(),
     detail: z.string().min(1).optional(),
     status: z.string().min(1).optional(),
+    class: z.enum(["transient", "deterministic", "budget"]).optional(),
+    fingerprint: z.string().min(1).optional(),
+    ...costFields,
     once,
 });
 const RunFinished = z.object({
     status: z.literal("ok"),
+    ...costFields,
     once,
 });
 const PrOpened = z.object({
@@ -110,6 +124,13 @@ const NeedsHuman = z.object({
     reason: z.string().min(1),
     once,
 });
+const FactoryToggle = z.object({ once });
+const BudgetBlocked = z.object({
+    day: z.string().min(1),
+    usd: z.number().nonnegative(),
+    cap: z.number().nonnegative(),
+    once,
+});
 const envelope = {
     id: z.string().min(1),
     ts: z.string().regex(ISO_UTC, "ts must be ISO-8601 UTC"),
@@ -137,6 +158,24 @@ export const EventSchema = z.discriminatedUnion("event", [
         properties: ConfigReloaded,
     }),
     z.object({ ...envelope, event: z.literal("needs-human"), job_id: z.string().min(1), properties: NeedsHuman }),
+    z.object({
+        ...envelope,
+        event: z.literal("kiln.paused"),
+        job_id: z.string().min(1).nullable(),
+        properties: FactoryToggle,
+    }),
+    z.object({
+        ...envelope,
+        event: z.literal("kiln.resumed"),
+        job_id: z.string().min(1).nullable(),
+        properties: FactoryToggle,
+    }),
+    z.object({
+        ...envelope,
+        event: z.literal("budget.blocked"),
+        job_id: z.string().min(1).nullable(),
+        properties: BudgetBlocked,
+    }),
 ]);
 const LOCK_WAIT_MS = 5_000;
 const pauseBuf = new Int32Array(new SharedArrayBuffer(4));

package/dist/failure.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import { redact } from "./redact.js";
+/**
+ * One failed run is transient, deterministic, or budget.
+ * Transient may retry with backoff inside the attempt cap.
+ * Deterministic does not. A cap hit is budget and stops in Needs human.
+ */
+export const FAILURE_CLASSES = ["transient", "deterministic", "budget"];
+const TRANSIENT = [
+    /\b429\b/,
+    /rate limit/i,
+    /too many requests/i,
+    /\b5\d\d\b/,
+    /internal server error/i,
+    /bad gateway/i,
+    /service unavailable/i,
+    /gateway timeout/i,
+    /ECONNRESET|ECONNREFUSED|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|EPIPE/i,
+    /socket hang up/i,
+    /network (?:error|unreachable|is down)/i,
+    /fetch failed/i,
+    /connection (?:reset|refused|timed out|closed)/i,
+    /container never started/i,
+    /failed to start (?:the )?(?:container|sandbox)/i,
+    /docker daemon/i,
+    /cannot connect to the docker/i,
+    /OCI runtime/i,
+    /error creating container/i,
+    /sandbox (?:start|flake)/i,
+];
+const DETERMINISTIC = [
+    /\berror TS\d+\b/,
+    /type error/i,
+    /cannot find name/i,
+    /is not assignable/i,
+    /syntax error/i,
+    /\bAssertionError\b/,
+    /\b(?:tests?|assertion) failed\b/i,
+    /\bfailing tests?\b/i,
+    /\bbuild failed\b/i,
+    /\bcompilation failed\b/i,
+    /\bcompile error\b/i,
+    /npm ERR!/i,
+];
+/** A container or sandbox that did not start. Those are transient. */
+export function isSandboxStartFlake(text) {
+    return /container never started|failed to start (?:the )?(?:container|sandbox)|docker daemon|cannot connect to the docker|OCI runtime|error creating container|sandbox (?:start|flake)/i.test(text);
+}
+/**
+ * Strip timestamps, temp and worktree paths, hex ids, and line numbers so
+ * the same failure hashes the same way across runs.
+ */
+export function normalizeFailureText(text) {
+    let out = redact(text).replace(/\r\n/g, "\n").trim();
+    out = out.replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?/g, "<ts>");
+    out = out.replace(/\b\d{2}:\d{2}:\d{2}(?:\.\d+)?\b/g, "<ts>");
+    out = out.replace(/(?:\/private)?\/(?:tmp|var\/folders)\/[^\s'")\]:]+/g, "<tmp>");
+    out = out.replace(/[^\s'")\]]*[/\\]\.yak[/\\]worktrees[/\\][^\s'")\]:]+/g, "<worktree>");
+    out = out.replace(/[^\s'")\]]+[/\\]worktrees[/\\][^\s'")\]:]+/g, "<worktree>");
+    out = out.replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, "<id>");
+    out = out.replace(/\b[0-9a-f]{8,}\b/gi, "<id>");
+    out = out.replace(/:(\d+)(?::\d+)?\b/g, ":<line>");
+    out = out.replace(/\bline\s+\d+\b/gi, "line <line>");
+    out = out.replace(/[ \t]+/g, " ");
+    out = out.replace(/\n{3,}/g, "\n\n");
+    return out.toLowerCase();
+}
+/** Stable id for one normalized failure. */
+export function failureFingerprint(text) {
+    return createHash("sha256").update(normalizeFailureText(text)).digest("hex");
+}
+/**
+ * Transient when the text is a network, rate-limit, 5xx, or start flake.
+ * A test, build, or type error is deterministic and wins over a transient
+ * pattern in the same text. Anything else is deterministic.
+ */
+export function classifyFailureText(text) {
+    if (DETERMINISTIC.some((pattern) => pattern.test(text)))
+        return "deterministic";
+    if (TRANSIENT.some((pattern) => pattern.test(text)))
+        return "transient";
+    return "deterministic";
+}
+/**
+ * The only decision for what a recorded failure does next.
+ * Attempt cap wins over the fingerprint breaker when both trip on the same run.
+ */
+export function decideFailure(input) {
+    const fingerprint = failureFingerprint(input.text);
+    const deterministicHit = DETERMINISTIC.some((pattern) => pattern.test(input.text));
+    const transientHit = TRANSIENT.some((pattern) => pattern.test(input.text));
+    // Stall, crash, orphan, and a bare non-zero exit stay transient unless the
+    // text is a test, build, or type error, or the failure is blocked.
+    let failureClass = deterministicHit
+        ? "deterministic"
+        : transientHit || (input.operational && !input.blocked)
+            ? "transient"
+            : "deterministic";
+    let retry = failureClass === "transient" && !input.blocked;
+    let needsHuman;
+    if (input.attempt >= input.maxAttempts) {
+        failureClass = "budget";
+        retry = false;
+        needsHuman = "attempt-cap";
+    }
+    else if (input.sameFingerprint >= input.maxSameFingerprint) {
+        retry = false;
+        needsHuman = "fingerprint";
+    }
+    else if (input.blocked || failureClass === "deterministic") {
+        retry = false;
+    }
+    return { class: failureClass, fingerprint, retry, ...(needsHuman ? { needsHuman } : {}) };
+}
+/** Sum yak `budget.consumed` lines. Missing numbers stay null. Never invents a figure. */
+export function costFromJournal(events) {
+    let tokens = 0;
+    let usd = 0;
+    let sawTokens = false;
+    let sawUsd = false;
+    for (const event of events) {
+        if (!event || typeof event !== "object")
+            continue;
+        const record = event;
+        if (record.t !== "budget.consumed")
+            continue;
+        if (typeof record.tokens === "number" && Number.isFinite(record.tokens) && record.tokens >= 0) {
+            tokens += record.tokens;
+            sawTokens = true;
+        }
+        if (typeof record.usd === "number" && Number.isFinite(record.usd) && record.usd >= 0) {
+            usd += record.usd;
+            sawUsd = true;
+        }
+    }
+    return {
+        tokens: sawTokens ? tokens : null,
+        usd: sawUsd ? usd : null,
+    };
+}

package/dist/fix-commit.js

@@ -0,0 +1,73 @@
+import { spawnSync } from "node:child_process";
+export function fixTrailerLines(input) {
+    return [`Kiln-Job: ${input.jobId}`, `Kiln-Round: ${input.round}`, `Kiln-Prompts-Hash: ${input.promptsHash}`];
+}
+/**
+ * The fix workflow `land` step. `workflows/fix.yaml` keeps the same command.
+ * Launch sets `KILN_JOB`, `KILN_ROUND`, and `KILN_PROMPTS_HASH`.
+ */
+export const FIX_LAND_COMMAND = 'git add -A && git diff --cached --quiet || git commit -m "kiln: $KILN_TASK_TITLE" --trailer "Kiln-Job: $KILN_JOB" --trailer "Kiln-Round: $KILN_ROUND" --trailer "Kiln-Prompts-Hash: $KILN_PROMPTS_HASH"';
+/**
+ * Make the tip of `dir` carry the fix-round trailers.
+ * A dirty tree is committed. A tip that already moved and lacks the trailers
+ * is amended. A clean tree still on `baseSha` is left alone.
+ */
+export function ensureFixTrailers(dir, input, baseSha) {
+    if (!hasTrailers(dir, input)) {
+        if (isDirty(dir)) {
+            commit(dir, input, false);
+            return "committed";
+        }
+        const head = revParse(dir, "HEAD");
+        if (!head || (baseSha && head === baseSha))
+            return "clean";
+        commit(dir, input, true);
+        return "amended";
+    }
+    return "present";
+}
+export function commitMessageHasTrailers(message, input) {
+    return fixTrailerLines(input).every((line) => message.split("\n").some((entry) => entry.trim() === line));
+}
+function hasTrailers(dir, input) {
+    const message = git(dir, ["log", "-1", "--format=%B"]);
+    if (message.status !== 0)
+        return false;
+    return commitMessageHasTrailers(message.stdout, input);
+}
+function isDirty(dir) {
+    const status = git(dir, ["status", "--porcelain"]);
+    if (status.status !== 0)
+        return false;
+    return status.stdout.trim().length > 0;
+}
+function revParse(dir, ref) {
+    const result = git(dir, ["rev-parse", ref]);
+    if (result.status !== 0)
+        return undefined;
+    const sha = result.stdout.trim();
+    return sha || undefined;
+}
+function commit(dir, input, amend) {
+    if (!amend) {
+        const added = git(dir, ["add", "-A"]);
+        if (added.status !== 0)
+            return;
+    }
+    const args = ["commit"];
+    if (amend)
+        args.push("--amend", "--no-edit");
+    else
+        args.push("-m", `kiln: ${input.title}`);
+    for (const line of fixTrailerLines(input))
+        args.push("--trailer", line);
+    git(dir, args);
+}
+function git(cwd, args) {
+    const result = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    return { status: result.status ?? 1, stdout: result.stdout ?? "" };
+}

package/dist/ledger.js

@@ -1,5 +1,6 @@
 import { readEvents } from "./events.js";
 import { redact } from "./redact.js";
+import { formatSpend, spendSnapshot } from "./rails.js";
 /**
  * Interventions are derived from the event log. Nothing is stored beside it.
  * A human had to act when a gate was rejected, a job was retried by hand,
@@ -64,9 +65,14 @@ export function ledgerRows(events, options = {}) {
     return rows;
 }
 export function renderLedger(events, options = {}) {
+    const spend = options.spend ??
+        (options.dailyDollarCap !== undefined || options.now
+            ? spendSnapshot(events, options.dailyDollarCap, options.now ?? new Date())
+            : undefined);
+    const head = spend ? `${formatSpend(spend)}\n` : "";
     const rows = ledgerRows(events, options);
     if (rows.length === 0)
-        return redact("0 interventions\n");
+        return redact(`${head}0 interventions\n`);
     const lines = [];
     let grand = 0;
     let index = 0;
@@ -90,10 +96,12 @@ export function renderLedger(events, options = {}) {
     }
     lines.push("");
     lines.push(`${grand} ${grand === 1 ? "intervention" : "interventions"}`);
-    return redact(`${lines.join("\n")}\n`);
+    return redact(`${head}${lines.join("\n")}\n`);
 }
 export function renderLedgerFile(kilnDir, options = {}) {
-    return renderLedger(readEvents(kilnDir), options);
+    const events = readEvents(kilnDir);
+    const spend = spendSnapshot(events, options.dailyDollarCap, options.now ?? new Date());
+    return renderLedger(events, { ...options, spend });
 }
 function reasonsFor(event) {
     const reasons = [];