@lchase/kiln 0.8.0 → 0.9.0

package/README.md

@@ -277,6 +277,8 @@ While a `deliver=pr` job is `in-review`, tick reads that pull request with `gh`:
 
 `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 the branch. `deliver=local` prints `branch yak/<run-id>`. `deliver=pr` prints the remote branch name recorded on the delivery, and the pull request url once one exists. `auth-failed` prints `Claude login rejected (401) — check CLAUDE_CODE_OAUTH_TOKEN / claude login, then Retry`. 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.
 
+`npm run kiln -- ledger` counts human interventions from `<kiln-home>/events.jsonl`: a rejected gate, a job retried by hand, an edit noted on a gate answer, and a needs-human stop. `--since 7d` (also `12h`, `30m`, `45s`, or an ISO time) keeps events at or after that instant. `--repo <name>` limits the count to one repo. A failed append is reported and does not fail the job. `GET /api/events?job_id=` on `kiln serve` returns that job's lines. A pull request body gains a short Evidence section from the same lines, with tokens and secret env values masked.
+
 State is derived from the yak journal, the gate files, and (for `deliver=pr`) `gh pr view`:
 
 | State | Meaning |

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { addRepo, renderRepoList, resolveKilnConfig } from "./config.js";
 import { renderSandboxStatus, runSandboxBuild } from "./sandbox.js";
 import { answerJob, retryJob, runStatus, runTick } from "./driver.js";
+import { parseSince, renderLedgerFile } from "./ledger.js";
 import { startServe } from "./serve.js";
 import { addFromFile } from "./intake/file.js";
 import { addFromJira } from "./intake/jira.js";
@@ -19,6 +20,7 @@ function usage() {
         "       kiln approve <jobId> [--config <file>]",
         "       kiln reject <jobId> [--config <file>]",
         "       kiln retry <jobId> [--config <file>]",
+        "       kiln ledger [--since 7d] [--repo <name>] [--config <file>]",
         "       kiln sandbox [build] [--config <file>]",
         "       kiln serve [--port 4100] [--tick <seconds>|--no-tick] [--config <file>]",
         "",
@@ -27,7 +29,7 @@ function usage() {
         "A relative path is stored absolute, resolved from the working directory.",
         "~ is expanded from the home directory.",
         "",
-        "Config, jobs, logs, and deliveries live in one kiln home: --config <file>",
+        "Config, jobs, logs, events, and deliveries live in one kiln home: --config <file>",
         "if given, otherwise $KILN_HOME/kiln.config.json when KILN_HOME is set,",
         "otherwise ~/.kiln/kiln.config.json. repo add creates that directory.",
         "Run kiln repo add <name> <path> from any directory. A leftover",
@@ -66,6 +68,12 @@ function usage() {
         "A rejected Claude login (401 or an invalid bearer token) is auth-failed and is not retried.",
         "(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.",
+        "Events are one JSON line each in <kiln-home>/events.jsonl. A write",
+        "failure is reported and does not stop the job. kiln ledger counts",
+        "human interventions from that log: a rejected gate, a manual retry,",
+        "an edit noted on a gate, and a needs-human stop. --since 7d (or 12h,",
+        "30m, 45s, or an ISO time) keeps events at or after that time. --repo",
+        "limits the count to one registered repo name.",
         "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",
@@ -219,6 +227,13 @@ function parseFlags(argv) {
             bag.noTick = true;
             continue;
         }
+        if (flag === "--since") {
+            if (!next || next.startsWith("--"))
+                usage();
+            bag.since = next;
+            i += 1;
+            continue;
+        }
         if (flag?.startsWith("--"))
             usage();
         if (flag !== undefined)
@@ -226,9 +241,11 @@ function parseFlags(argv) {
     }
     return bag;
 }
-function rejectServeFlags(flags) {
+function rejectServeFlags(flags, options = {}) {
     if (flags.port !== undefined || flags.tickSeconds !== undefined || flags.noTick)
         usage();
+    if (options.since !== false && flags.since)
+        usage();
 }
 function repoCommand(argv) {
     const sub = argv[0];
@@ -388,6 +405,32 @@ function retryCommand(argv) {
     const config = resolveKilnConfig({ configPath: flags.configPath });
     process.stdout.write(retryJob(config, jobId));
 }
+function ledgerCommand(argv) {
+    const flags = parseFlags(argv);
+    rejectServeFlags(flags, { since: false });
+    if (flags.positionals.length !== 0 ||
+        flags.test ||
+        flags.spec ||
+        flags.prompt ||
+        flags.jira ||
+        flags.title ||
+        flags.issue ||
+        flags.workflow ||
+        flags.context ||
+        flags.dryRun ||
+        flags.stack ||
+        flags.after.length > 0 ||
+        flags.deliver ||
+        flags.base) {
+        usage();
+    }
+    const config = resolveKilnConfig({ configPath: flags.configPath });
+    const since = flags.since ? parseSince(flags.since) : undefined;
+    process.stdout.write(renderLedgerFile(config.kilnDir, {
+        ...(since ? { since } : {}),
+        ...(flags.repo ? { repo: flags.repo } : {}),
+    }));
+}
 function gateCommand(choice, argv) {
     const flags = parseFlags(argv);
     rejectServeFlags(flags);
@@ -468,6 +511,10 @@ async function main() {
         retryCommand(argv.slice(1));
         return;
     }
+    if (command === "ledger") {
+        ledgerCommand(argv.slice(1));
+        return;
+    }
     if (command === "sandbox") {
         sandboxCommand(argv.slice(1));
         return;

package/dist/delivery.js

@@ -1,6 +1,8 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
+import { evidenceSectionFor } from "./evidence.js";
+import { appendEvent } from "./events.js";
 import { HostError } from "./host.js";
 import { readJobSpec } from "./jobs.js";
 import { jobBasename } from "./paths.js";
@@ -181,6 +183,20 @@ export function deliverJob(request) {
             prNumber: pr.number,
             prUrl: pr.url,
         });
+        if (!sameRun?.prNumber && remoteName) {
+            appendEvent(request.config.kilnDir, {
+                job_id: request.job.id,
+                run_id: request.runId,
+                event: "pr.opened",
+                properties: {
+                    number: pr.number,
+                    url: pr.url,
+                    branch: remoteName,
+                    base: request.baseBranch,
+                    once: `pr.opened:${pr.number}`,
+                },
+            });
+        }
         return { ok: true, detail: pr.url, prUrl: pr.url, prNumber: pr.number };
     }
     catch (error) {
@@ -213,6 +229,8 @@ export function pullRequestBody(request) {
         "## Reviewers",
         ...(reviews.length > 0 ? reviews : ["- (no reviewer artifacts)"]),
         "",
+        evidenceSectionFor(request.config.kilnDir, request.job.id).trimEnd(),
+        "",
     ].join("\n");
 }
 export function specSummary(specText) {

package/dist/driver.js

@@ -6,12 +6,14 @@ import { claudeCredentialPreflight } from "./auth.js";
 import { buildAttention } from "./attention.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 { 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 { 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";
@@ -87,6 +89,20 @@ export function answerJob(config, jobId, choice, host = defaultHost()) {
     if (result.status !== 0) {
         throw new Error(output.trim() || `Could not ${choice} job ${jobId}.`);
     }
+    const noted = gateEdit(job.run.checkout, job.run.runId, gate.stepId);
+    appendEvent(config.kilnDir, {
+        job_id: jobId,
+        run_id: job.run.runId,
+        event: "gate.resolved",
+        step: gate.stepId,
+        properties: {
+            decision: choice,
+            by: "human",
+            repo: job.repo,
+            ...noted,
+            once: `gate.resolved:${gate.stepId}`,
+        },
+    });
     if (choice === "approve") {
         recordInvestigationFindings(config, observe(config, host), jobId);
     }
@@ -120,6 +136,11 @@ export function retryJob(config, jobId, host = defaultHost()) {
         if (crumb && pidAlive(crumb.pid)) {
             throw new Error(`Job ${jobId} is already launching.`);
         }
+        appendEvent(config.kilnDir, {
+            job_id: jobId,
+            event: "job.retried",
+            properties: { by: "human", repo: job.repo },
+        });
         const cleared = observed.attemptCount ?? 0;
         resetAttemptLedger(config.kilnDir, jobId, observed.run?.runId);
         rmSync(breadcrumbPath(config.kilnDir, jobId), { force: true });
@@ -545,6 +566,7 @@ function publishReadyFixes(config, host, world) {
         if (sha === open.headSha) {
             open.outcome = "fixed";
             writeFeedbackLedger(config.kilnDir, ledger);
+            recordFeedbackOutcome(config.kilnDir, job.jobId, job.run.runId, open, "fixed");
             notes.push(`fixed ${job.jobId}  ${sha}`);
             continue;
         }
@@ -580,6 +602,7 @@ function publishReadyFixes(config, host, world) {
         });
         open.outcome = "pushed";
         writeFeedbackLedger(config.kilnDir, ledger);
+        recordFeedbackOutcome(config.kilnDir, job.jobId, job.run.runId, open, "pushed");
         notes.push(`pushed ${job.jobId}  ${record.branch}  ${sha}`);
     }
     return notes;
@@ -587,6 +610,46 @@ function publishReadyFixes(config, host, world) {
 function isNonFastForward(message) {
     return /non-fast-forward|\[rejected\]|failed to push some refs/i.test(message);
 }
+function recordFeedbackOutcome(kilnDir, jobId, runId, round, outcome) {
+    appendEvent(kilnDir, {
+        job_id: jobId,
+        run_id: runId,
+        event: "pr.feedback",
+        properties: {
+            round: round.round,
+            trigger: round.trigger,
+            outcome,
+            items: round.items.length,
+            once: `pr.feedback:${round.round}:${outcome}`,
+        },
+    });
+}
+/** An edit note the human left on the gate answer, when the answer file has one. */
+function gateEdit(checkout, runId, stepId) {
+    const paths = [
+        join(checkout, ".runs", runId, "pending", `${stepId}.answer.json`),
+        join(checkout, ".runs", runId, "artifacts", "approval.json"),
+    ];
+    for (const path of paths) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            const note = typeof parsed.note === "string" ? parsed.note.trim() : "";
+            const edit = typeof parsed.edit === "string" ? parsed.edit.trim() : "";
+            if (!note && !edit)
+                continue;
+            return {
+                ...(note ? { note: note.slice(0, 240) } : {}),
+                ...(edit ? { edit: edit.slice(0, 240) } : {}),
+            };
+        }
+        catch {
+            // An unreadable answer is not an edit note.
+        }
+    }
+    return {};
+}
 /**
  * Read each open pull request once per tick and attach a plan.
  * `readStatus` does not call this. A host with no feedback reader does not watch.
@@ -641,6 +704,11 @@ function markFeedback(kilnDir, jobId, reason) {
     else
         ledger.ambiguous = true;
     writeFeedbackLedger(kilnDir, ledger);
+    appendEvent(kilnDir, {
+        job_id: jobId,
+        event: "needs-human",
+        properties: { reason, once: `needs-human:${reason}` },
+    });
 }
 /**
  * Open one feedback round and start the fix workflow on the pull request head.
@@ -678,6 +746,16 @@ function startFix(config, world, job, host, now, sandboxFacts) {
         at: now.toISOString(),
     });
     writeFeedbackLedger(config.kilnDir, ledger);
+    appendEvent(config.kilnDir, {
+        job_id: job.id,
+        event: "pr.feedback",
+        properties: {
+            round,
+            trigger: plan.trigger,
+            items: plan.items.length,
+            once: `pr.feedback:${round}:open`,
+        },
+    });
     let specText;
     try {
         specText = feedbackSpec(specHandedToYak(config, world, job), plan.items);
@@ -943,6 +1021,11 @@ function loadJobFile(file) {
     return { meta: { jobId: job.id }, job };
 }
 function scanRuns(config) {
+    const jobs = new Map();
+    for (const entry of loadJobs(config)) {
+        if (entry.job)
+            jobs.set(entry.job.id, entry.job);
+    }
     const byTag = new Map();
     for (const repo of Object.values(config.repos)) {
         for (const runDir of listRunDirs(repo.path)) {
@@ -951,6 +1034,21 @@ function scanRuns(config) {
             if (!started?.tag || !parseJobTag(started.tag))
                 continue;
             const runId = basename(runDir);
+            const jobId = parseJobTag(started.tag);
+            if (jobId) {
+                const job = jobs.get(jobId);
+                const testCommand = job ? config.repos[job.repo]?.test : undefined;
+                projectRunJournal({
+                    kilnDir: config.kilnDir,
+                    jobId,
+                    runId,
+                    runDir,
+                    workflow: job?.workflow ?? "",
+                    repo: job?.repo ?? "",
+                    ...(testCommand ? { testCommand } : {}),
+                    events,
+                });
+            }
             const status = classify(events);
             const gateDecision = readApproveDecision(runDir);
             const title = readRunTitle(runDir);

package/dist/events.js

@@ -0,0 +1,354 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, writeSync, } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { redactDeep } from "./redact.js";
+/**
+ * Append-only event log at `<kilnDir>/events.jsonl` (`~/.kiln/events.jsonl`
+ * when that directory is the kiln home). One module writes it. One reader
+ * 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.
+ */
+export const EVENT_NAMES = [
+    "job.added",
+    "job.retried",
+    "run.started",
+    "phase.started",
+    "phase.finished",
+    "gate.opened",
+    "gate.resolved",
+    "run.failed",
+    "run.finished",
+    "pr.opened",
+    "pr.feedback",
+    "worktree.cleaned",
+    "worktree.kept",
+    "config.reloaded",
+    "needs-human",
+];
+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();
+const JobAdded = z.object({
+    repo: z.string().min(1),
+    workflow: z.string().min(1),
+    title: z.string().min(1),
+    source_kind: z.string().min(1).optional(),
+    once,
+});
+const JobRetried = z.object({
+    by: z.literal("human"),
+    repo: z.string().min(1),
+    once,
+});
+const RunStarted = z.object({
+    kiln_version: z.string().min(1),
+    yak_version: z.string().min(1),
+    workflow: z.string().min(1),
+    prompts_hash: z.string().min(1),
+    repo: z.string().min(1),
+    once,
+});
+const PhaseStarted = z.object({
+    iteration: z.number().int().nonnegative().optional(),
+    once,
+});
+const PhaseFinished = z.object({
+    outcome: z.enum(["completed", "failed"]),
+    iteration: z.number().int().nonnegative().optional(),
+    cached: z.boolean().optional(),
+    skipped: z.boolean().optional(),
+    reason: z.string().min(1).optional(),
+    detail: z.string().min(1).optional(),
+    verdict: z.string().min(1).optional(),
+    test_command: z.string().min(1).optional(),
+    exit_code: z.number().int().optional(),
+    once,
+});
+const GateOpened = z.object({
+    prompt: z.string().min(1).optional(),
+    note: z.string().min(1).optional(),
+    edit: z.string().min(1).optional(),
+    once,
+});
+const GateResolved = z.object({
+    decision: z.string().min(1),
+    by: z.string().min(1),
+    repo: z.string().min(1).optional(),
+    note: z.string().min(1).optional(),
+    edit: z.string().min(1).optional(),
+    once,
+});
+const RunFailed = z.object({
+    reason: z.string().min(1).optional(),
+    detail: z.string().min(1).optional(),
+    status: z.string().min(1).optional(),
+    once,
+});
+const RunFinished = z.object({
+    status: z.literal("ok"),
+    once,
+});
+const PrOpened = z.object({
+    number: z.number().int().positive(),
+    url: z.string().min(1),
+    branch: z.string().min(1),
+    base: z.string().min(1),
+    once,
+});
+const PrFeedback = z.object({
+    round: z.number().int().positive(),
+    trigger: z.enum(["ci", "review"]),
+    outcome: z.enum(["fixed", "pushed"]).optional(),
+    items: z.number().int().nonnegative().optional(),
+    once,
+});
+const Worktree = z.object({ once });
+const ConfigReloaded = z.object({ once });
+const NeedsHuman = z.object({
+    reason: z.string().min(1),
+    once,
+});
+const envelope = {
+    id: z.string().min(1),
+    ts: z.string().regex(ISO_UTC, "ts must be ISO-8601 UTC"),
+    run_id: z.string().min(1).nullable(),
+    step: z.string().min(1).nullable(),
+};
+export const EventSchema = z.discriminatedUnion("event", [
+    z.object({ ...envelope, event: z.literal("job.added"), job_id: z.string().min(1), properties: JobAdded }),
+    z.object({ ...envelope, event: z.literal("job.retried"), job_id: z.string().min(1), properties: JobRetried }),
+    z.object({ ...envelope, event: z.literal("run.started"), job_id: z.string().min(1), properties: RunStarted }),
+    z.object({ ...envelope, event: z.literal("phase.started"), job_id: z.string().min(1), properties: PhaseStarted }),
+    z.object({ ...envelope, event: z.literal("phase.finished"), job_id: z.string().min(1), properties: PhaseFinished }),
+    z.object({ ...envelope, event: z.literal("gate.opened"), job_id: z.string().min(1), properties: GateOpened }),
+    z.object({ ...envelope, event: z.literal("gate.resolved"), job_id: z.string().min(1), properties: GateResolved }),
+    z.object({ ...envelope, event: z.literal("run.failed"), job_id: z.string().min(1), properties: RunFailed }),
+    z.object({ ...envelope, event: z.literal("run.finished"), job_id: z.string().min(1), properties: RunFinished }),
+    z.object({ ...envelope, event: z.literal("pr.opened"), job_id: z.string().min(1), properties: PrOpened }),
+    z.object({ ...envelope, event: z.literal("pr.feedback"), job_id: z.string().min(1), properties: PrFeedback }),
+    z.object({ ...envelope, event: z.literal("worktree.cleaned"), job_id: z.string().min(1), properties: Worktree }),
+    z.object({ ...envelope, event: z.literal("worktree.kept"), job_id: z.string().min(1), properties: Worktree }),
+    z.object({
+        ...envelope,
+        event: z.literal("config.reloaded"),
+        job_id: z.string().min(1).nullable(),
+        properties: ConfigReloaded,
+    }),
+    z.object({ ...envelope, event: z.literal("needs-human"), job_id: z.string().min(1), properties: NeedsHuman }),
+]);
+const LOCK_WAIT_MS = 5_000;
+const pauseBuf = new Int32Array(new SharedArrayBuffer(4));
+export function eventsPath(kilnDir) {
+    return join(kilnDir, "events.jsonl");
+}
+/**
+ * Append one JSON line. Concurrent callers in this process take a file lock
+ * and each lock holder performs one `write` of the full line, so lines do
+ * not interleave. A failure is printed and swallowed.
+ *
+ * `properties.once` is an idempotency key. A later append with the same
+ * job, run, event, step, and `once` is a no-op. Moments that should repeat
+ * (a second manual retry, a second config reload) omit it.
+ */
+export function appendEvent(kilnDir, draft) {
+    let line;
+    let event;
+    try {
+        event = buildEvent(draft);
+        line = `${JSON.stringify(event)}\n`;
+    }
+    catch (error) {
+        report(error);
+        return;
+    }
+    try {
+        withEventsLock(kilnDir, () => {
+            if (alreadyRecorded(kilnDir, event))
+                return;
+            writeLine(eventsPath(kilnDir), line);
+        });
+    }
+    catch (error) {
+        report(error);
+    }
+}
+/** Parse the log. A blank line is ignored. Any other bad line is skipped. */
+export function readEvents(kilnDir, options = {}) {
+    const warn = options.warn ?? ((message) => console.error(message));
+    const path = eventsPath(kilnDir);
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        warn(`kiln: event log unreadable: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+    const events = [];
+    const lines = raw.split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line === undefined || line.trim() === "")
+            continue;
+        const parsed = parseLine(line);
+        if (!parsed) {
+            warn(`kiln: skipped event log line ${index + 1}`);
+            continue;
+        }
+        events.push(parsed);
+    }
+    return events;
+}
+export function eventsForJob(kilnDir, jobId, options) {
+    return readEvents(kilnDir, options).filter((event) => event.job_id === jobId);
+}
+function buildEvent(draft) {
+    const properties = redactDeep(draft.properties);
+    const candidate = {
+        id: draft.id ?? randomUUID(),
+        ts: draft.ts ?? new Date().toISOString(),
+        job_id: draft.job_id,
+        run_id: draft.run_id ?? null,
+        event: draft.event,
+        step: draft.step ?? null,
+        properties,
+    };
+    const parsed = EventSchema.safeParse(candidate);
+    if (!parsed.success) {
+        throw new Error(`refused ${draft.event}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+    }
+    return parsed.data;
+}
+function parseLine(line) {
+    try {
+        const parsed = EventSchema.safeParse(JSON.parse(line));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function alreadyRecorded(kilnDir, event) {
+    const key = event.properties.once;
+    if (!key)
+        return false;
+    const path = eventsPath(kilnDir);
+    if (!existsSync(path))
+        return false;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return false;
+    }
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed.job_id === event.job_id &&
+                parsed.run_id === event.run_id &&
+                parsed.event === event.event &&
+                parsed.step === event.step &&
+                parsed.properties?.once === key) {
+                return true;
+            }
+        }
+        catch {
+            // A corrupt line does not count as a recorded event.
+        }
+    }
+    return false;
+}
+/** One `write` of the whole line, including the newline. */
+function writeLine(path, line) {
+    const fd = openSync(path, "a");
+    try {
+        const buf = Buffer.from(line);
+        const wrote = writeSync(fd, buf, 0, buf.length);
+        if (wrote !== buf.length) {
+            throw new Error(`short write (${wrote} of ${buf.length})`);
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Exclusive append across threads in this process. The lock file holds the
+ * pid. Another thread in the same process shares that pid and waits. A
+ * later process may remove a lock whose pid is gone.
+ */
+function withEventsLock(kilnDir, fn) {
+    mkdirSync(kilnDir, { recursive: true });
+    const lockPath = join(kilnDir, "events.lock");
+    const tmp = `${lockPath}.${process.pid}.${randomBytes(4).toString("hex")}`;
+    writeFileSync(tmp, String(process.pid));
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    let held = false;
+    try {
+        while (!held) {
+            try {
+                linkSync(tmp, lockPath);
+                held = true;
+            }
+            catch (error) {
+                if (!isErrno(error, "EEXIST"))
+                    throw error;
+                if (lockHolderDead(lockPath)) {
+                    rmSync(lockPath, { force: true });
+                    continue;
+                }
+                if (Date.now() > deadline)
+                    throw new Error("timed out waiting for the event log lock");
+                Atomics.wait(pauseBuf, 0, 0, 5);
+            }
+        }
+        fn();
+    }
+    finally {
+        if (held)
+            rmSync(lockPath, { force: true });
+        rmSync(tmp, { force: true });
+    }
+}
+function lockHolderDead(lockPath) {
+    let holder = Number.NaN;
+    try {
+        holder = Number(readFileSync(lockPath, "utf8").trim());
+    }
+    catch {
+        return true;
+    }
+    if (holder === process.pid)
+        return false;
+    return !pidAlive(holder);
+}
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isErrno(error, code) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function report(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    try {
+        console.error(`kiln: event log: ${message}`);
+    }
+    catch {
+        // The caller still continues when stderr itself fails.
+    }
+}