patchwork-os 0.2.0-beta.1 → 0.2.0-beta.10.canary.95

package/dist/recipes/idempotencyKey.js

@@ -0,0 +1,322 @@
+/**
+ * Idempotency keys for write-tool calls.
+ *
+ * PR5a of the Val-inspired plan. Foundation for safe retry + safe resume.
+ *
+ * Two pieces:
+ *
+ *   `deriveIdempotencyKey(toolId, params)`
+ *     A stable, deterministic hash over `(toolId, canonicalised params)`.
+ *     Canonicalisation = JSON.stringify with sorted keys, recursive — so
+ *     `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` hash identically. Returns a
+ *     hex SHA-256 prefix (first 16 chars; collisions vanishingly small
+ *     within a single run scope).
+ *
+ *   `WriteEffectLedger`
+ *     Per-run in-memory map of key → cached output. The runner constructs
+ *     one per recipe run and threads it through `StepDeps` / `ToolContext`.
+ *     `toolRegistry.executeTool` checks the ledger before invoking write
+ *     tools; if the key is present, returns the cached output instead of
+ *     re-executing — preventing duplicate side effects when two parallel
+ *     branches of a chained recipe both call the same write tool with the
+ *     same params.
+ *
+ * Scope of this PR (deliberately narrow):
+ *   - In-run dedup only (Map lives for one recipe run, discarded after).
+ *   - Records only on successful execution; errors don't pollute the
+ *     ledger, so retry-after-failure still re-executes (correct: if the
+ *     tool errored, we can't assume the side effect happened).
+ *   - No cross-run persistence — that's PR5b (disk-backed effect ledger).
+ *   - No retry-time idempotency on partial-failure cases (Slack posted
+ *     but HTTP timed out); that needs tool-side support and is a future
+ *     PR.
+ *
+ * The protection this DOES provide today: a `parallel:` block (or a
+ * recipe that calls a write tool from two different chained steps with
+ * identical params) cannot duplicate the side effect. Concretely, this
+ * was a footgun that pre-dated PR5a: `chainedRunner.ts` schedules steps
+ * with dependency-graph parallelism; if two branches happen to call
+ * `slack.postMessage` with the same payload, the message went twice.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, lstatSync, mkdirSync, readFileSync, statSync, } from "node:fs";
+import path from "node:path";
+import { writeFileAtomicSync } from "../writeFileAtomic.js";
+/**
+ * Stable canonical-JSON serialiser. Recursively sorts object keys so two
+ * params records with the same shape but different key order produce the
+ * same string. Plain objects only — falls back to `JSON.stringify` for
+ * arrays / primitives / null.
+ */
+function canonicalise(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalise).join(",")}]`;
+    }
+    const entries = Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const body = entries
+        .map(([k, v]) => `${JSON.stringify(k)}:${canonicalise(v)}`)
+        .join(",");
+    return `{${body}}`;
+}
+/**
+ * Derive a stable idempotency key for a write-tool invocation. 16 hex
+ * chars is 64 bits of entropy — far more than enough for in-run dedup
+ * (a single recipe with even 10⁵ steps has ~5×10⁻¹⁰ collision risk).
+ */
+export function deriveIdempotencyKey(toolId, params) {
+    const payload = `${toolId}|${canonicalise(params)}`;
+    return createHash("sha256").update(payload).digest("hex").slice(0, 16);
+}
+/**
+ * Compose a collision-safe scope key from `(recipeName, manualRunId)`.
+ *
+ * Naive `${recipeName}:${manualRunId}` is ambiguous: recipe `a:b` +
+ * attempt `c` and recipe `a` + attempt `b:c` both produce `a:b:c` and
+ * would share a ledger scope, letting one attempt read another's
+ * cached write-tool outputs. We hash both fields separately as a JSON
+ * array so the encoding is unambiguous regardless of either field's
+ * contents.
+ *
+ * Returned as a 32-hex-char SHA-256 prefix — long enough that
+ * collisions across a realistic ledger are effectively impossible
+ * (~2^128 birthday bound), short enough to scan in a JSONL row.
+ */
+export function deriveScopeKey(recipeName, manualRunId) {
+    const payload = JSON.stringify([recipeName, manualRunId]);
+    return createHash("sha256").update(payload).digest("hex").slice(0, 32);
+}
+/**
+ * `manualRunId` charset validation — caller-supplied id from the CLI
+ * (`--attempt`), HTTP routes, or SDK. Rejects null bytes, control
+ * characters, path-traversal slugs (`/`, `\`, `..`), and anything
+ * longer than 64 chars. Returns the id verbatim when valid; throws
+ * with a descriptive message otherwise.
+ *
+ * Why strict: this string is hashed into the disk-ledger scope key,
+ * appended to `runs.jsonl` rows (capped audit-row size depends on it),
+ * and rendered into dashboard pills + CLI output. A 10 MB id would
+ * inflate every row past `MAX_PERSIST_BYTES` and erase audit during
+ * rotation; control characters break line-delimited persistence.
+ */
+const MANUAL_RUN_ID_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+export function assertValidManualRunId(id) {
+    if (typeof id !== "string" || !MANUAL_RUN_ID_PATTERN.test(id)) {
+        throw new Error(`manualRunId must match ${MANUAL_RUN_ID_PATTERN} (1-64 chars of [A-Za-z0-9_.-]); got: ${JSON.stringify(id).slice(0, 80)}`);
+    }
+    return id;
+}
+const LEDGER_FILENAME = "effect_ledger.jsonl";
+const MAX_PERSIST_BYTES = 1024 * 1024; // 1 MB — same posture as runLog
+const MAX_PERSIST_LINES = 10_000;
+/**
+ * Validate a caller-supplied ledger directory before any filesystem IO.
+ *
+ * The dir argument flows from the CLI (`--ledger-dir`) and (if/when
+ * exposed) HTTP-runner inputs; we'd rather fail loudly than write JSONL
+ * to whatever path is handed in. Three checks:
+ *
+ *  - **No null bytes** — would short-circuit C string handling in older
+ *    libc paths and confuse logs / audit tooling.
+ *  - **Absolute** — relative paths resolve against `process.cwd()`,
+ *    which for recipe runs is the workspace; an `--ledger-dir foo`
+ *    silently scattering ledger files under recipe sources is the
+ *    wrong default. Caller can pass `path.resolve(...)` explicitly if
+ *    they want relative resolution.
+ *  - **Not a symlink** — if the directory already exists and is a
+ *    symlink, an attacker who can write to the symlink's owning dir
+ *    can swap the target and redirect appends. Rejecting up front
+ *    means a fresh dir is created (via mkdirSync) or an existing real
+ *    dir is used; symlink-replacement on the JSONL file itself is
+ *    handled separately on each read in `loadExisting`.
+ */
+function assertSafeLedgerDir(dir) {
+    if (typeof dir !== "string" || dir.length === 0) {
+        throw new Error("ledgerDir must be a non-empty string");
+    }
+    if (dir.includes("\0")) {
+        throw new Error("ledgerDir must not contain null bytes");
+    }
+    if (!path.isAbsolute(dir)) {
+        throw new Error(`ledgerDir must be an absolute path; got: ${dir}`);
+    }
+    try {
+        const st = lstatSync(dir);
+        if (st.isSymbolicLink()) {
+            throw new Error(`ledgerDir must not be a symlink: ${dir}`);
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return; // dir will be created later — fine
+        throw err;
+    }
+}
+export class WriteEffectLedger {
+    cache = new Map();
+    inFlight = new Map();
+    disk;
+    file;
+    constructor(disk) {
+        if (disk) {
+            // Validate + normalise the directory before any IO. Rejects null
+            // bytes (would short-circuit C string handling in libc paths),
+            // requires absolute paths (relative paths resolve against cwd
+            // which is the recipe workspace — surprising and racy), and
+            // refuses symlinks (a symlink swap on the ledger directory after
+            // construction could redirect appends to an attacker-chosen
+            // path).
+            assertSafeLedgerDir(disk.dir);
+        }
+        this.disk = disk ?? null;
+        this.file = disk ? path.join(disk.dir, LEDGER_FILENAME) : null;
+        if (this.disk && this.file) {
+            try {
+                mkdirSync(this.disk.dir, { recursive: true, mode: 0o700 });
+            }
+            catch (err) {
+                this.disk.logger?.warn?.(`[effect-ledger] could not create ${this.disk.dir}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            this.loadExisting();
+        }
+    }
+    has(key) {
+        return this.cache.has(key);
+    }
+    /**
+     * Return the previously-cached output for `key`, or `undefined` if not
+     * recorded. `null` is a legitimate cached value (= the tool returned
+     * `null` originally), so callers must use `has()` to distinguish "not
+     * present" from "present and null".
+     */
+    get(key) {
+        return this.cache.get(key);
+    }
+    record(key, output) {
+        this.cache.set(key, output);
+        if (this.disk && this.file) {
+            this.append({
+                scopeKey: this.disk.scopeKey,
+                idemKey: key,
+                output,
+                recordedAt: Date.now(),
+            });
+        }
+    }
+    /**
+     * Atomically check cache + in-flight map, then execute `fn` at most once
+     * per key. Concurrent callers with the same key share a single Promise —
+     * fixing the TOCTOU window that existed between `has()` and `record()`.
+     * Failures are not cached so retry-after-failure still re-executes.
+     */
+    getOrExecute(key, fn) {
+        if (this.cache.has(key)) {
+            return Promise.resolve(this.cache.get(key) ?? null);
+        }
+        const existing = this.inFlight.get(key);
+        if (existing)
+            return existing;
+        const work = fn().then((result) => {
+            this.record(key, result);
+            this.inFlight.delete(key);
+            return result;
+        }, (err) => {
+            this.inFlight.delete(key);
+            throw err;
+        });
+        this.inFlight.set(key, work);
+        return work;
+    }
+    /** Test-only inspection of the current key set. */
+    keys() {
+        return Array.from(this.cache.keys());
+    }
+    size() {
+        return this.cache.size;
+    }
+    loadExisting() {
+        if (!this.disk || !this.file)
+            return;
+        let raw;
+        try {
+            // `lstat` (not `stat`) so we see the symlink, not its target.
+            // A swapped symlink at `${dir}/effect_ledger.jsonl` would
+            // otherwise let an attacker substitute another file's contents
+            // as cached tool outputs.
+            const st = lstatSync(this.file);
+            if (st.isSymbolicLink()) {
+                this.disk.logger?.warn?.(`[effect-ledger] refusing to load ${this.file}: file is a symlink`);
+                return;
+            }
+            raw = readFileSync(this.file, "utf-8");
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT") {
+                this.disk.logger?.warn?.(`[effect-ledger] read failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return;
+        }
+        for (const line of raw.split("\n")) {
+            if (!line)
+                continue;
+            try {
+                const row = JSON.parse(line);
+                if (typeof row.scopeKey !== "string" ||
+                    typeof row.idemKey !== "string") {
+                    continue;
+                }
+                if (row.scopeKey === this.disk.scopeKey) {
+                    this.cache.set(row.idemKey, row.output ?? null);
+                }
+            }
+            catch {
+                /* skip malformed row */
+            }
+        }
+    }
+    append(row) {
+        if (!this.disk || !this.file)
+            return;
+        try {
+            try {
+                const st = statSync(this.file);
+                if (st.size > MAX_PERSIST_BYTES)
+                    this.rotate();
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== "ENOENT")
+                    throw err;
+            }
+            appendFileSync(this.file, `${JSON.stringify(row)}\n`, { mode: 0o600 });
+        }
+        catch (err) {
+            this.disk.logger?.warn?.(`[effect-ledger] append failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Trim `effect_ledger.jsonl` to the most recent MAX_PERSIST_LINES.
+     * Best-effort — failure logs and the next append proceeds against the
+     * un-rotated file. Same pattern as RecipeRunLog / DecisionTraceLog.
+     */
+    rotate() {
+        if (!this.file || !this.disk)
+            return;
+        try {
+            const raw = readFileSync(this.file, "utf-8");
+            let lines = raw.split("\n").filter((l) => l.trim());
+            if (lines.length > MAX_PERSIST_LINES) {
+                lines = lines.slice(-MAX_PERSIST_LINES);
+            }
+            writeFileAtomicSync(this.file, lines.length > 0 ? `${lines.join("\n")}\n` : "", { mode: 0o600 });
+        }
+        catch (err) {
+            this.disk.logger?.warn?.(`[effect-ledger] rotate failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+//# sourceMappingURL=idempotencyKey.js.map

package/dist/recipes/idempotencyKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotencyKey.js","sourceRoot":"","sources":["../../src/recipes/idempotencyKey.ts"],"names":[],"mappings":"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"}

package/dist/recipes/installer.js

@@ -1,8 +1,40 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import crypto from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { compileRecipeFull } from "./compiler.js";
 import { parseRecipe } from "./parser.js";
+/**
+ * Atomic temp+rename for the default install write. Audit 2026-05-17:
+ * two concurrent installs of the same recipe (cross-process, e.g.
+ * dashboard + CLI racing) used to interleave bytes within the JSON
+ * payload because the previous `writeFileSync(destPath, ...)` is not
+ * atomic for sub-page writes. A torn JSON file fails to parse and the
+ * recipe becomes invisible to the scheduler.
+ *
+ * `rename` is atomic at the FS layer on every platform we ship on
+ * (apfs / ext4 / ntfs / xfs). With temp+rename, two concurrent writers
+ * each end up with their own intact file → last `rename` wins, but
+ * the file on disk is ALWAYS a valid JSON document.
+ */
+function atomicWriteSync(target, content) {
+    const tmp = `${target}.tmp.${process.pid}.${crypto
+        .randomBytes(6)
+        .toString("hex")}`;
+    try {
+        writeFileSync(tmp, content);
+        renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* already gone or never created */
+        }
+        throw err;
+    }
+}
 export function installRecipeFromFile(sourcePath, opts) {
     const ext = path.extname(sourcePath).toLowerCase();
     if (ext !== ".json" && ext !== ".yaml" && ext !== ".yml") {
@@ -10,7 +42,10 @@ export function installRecipeFromFile(sourcePath, opts) {
     }
     const fs = opts.fs ?? {};
     const readFile = fs.readFile ?? ((p) => readFileSync(p, "utf-8"));
-    const writeFile = fs.writeFile ?? ((p, c) => writeFileSync(p, c));
+    // Default writer is atomic (temp+rename). Callers may inject their
+    // own writeFile (tests, in-memory fs); they are responsible for
+    // their own atomicity guarantees.
+    const writeFile = fs.writeFile ?? atomicWriteSync;
     const mkdir = fs.mkdir ?? ((p) => mkdirSync(p, { recursive: true }));
     const text = readFile(sourcePath);
     const raw = ext === ".json"
@@ -39,6 +74,17 @@ export function installRecipeFromFile(sourcePath, opts) {
         : compileRecipeFull(recipe);
     mkdir(opts.recipesDir);
     const destPath = path.join(opts.recipesDir, `${recipe.name}.json`);
+    // Belt-and-braces: parseRecipe already constrains `name` to the
+    // RECIPE_NAME_RE charset, but assert the resolved path stays inside
+    // recipesDir before writing. Defends against any future parser bypass
+    // and against callers reaching this function with a pre-parsed object
+    // that skipped parseRecipe.
+    const resolvedDir = path.resolve(opts.recipesDir);
+    const resolvedDest = path.resolve(destPath);
+    if (resolvedDest !== resolvedDir &&
+        !resolvedDest.startsWith(resolvedDir + path.sep)) {
+        throw new Error(`installRecipeFromFile: refusing to write outside recipesDir (dest=${resolvedDest} dir=${resolvedDir})`);
+    }
     let action = "created";
     try {
         readFile(destPath);

package/dist/recipes/installer.js.map

@@ -1 +1 @@
-{"version":3,"file":"installer.js","sourceRoot":"","sources":["../../src/recipes/installer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"installer.js","sourceRoot":"","sources":["../../src/recipes/installer.ts"],"names":[],"mappings":"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"}

package/dist/recipes/judgeSummary.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Judge-verdict aggregation — PR3b.
+ *
+ * Parallel to haltCategory.summariseHalts: walks a window of runs and
+ * counts judge-step verdicts (`approve` / `request_changes` /
+ * `unparseable`). Surfaces through:
+ *
+ *  - `/metrics` as `bridge_recipe_judgments{verdict="..."}` gauge
+ *  - (later) dashboard panel + session-start digest in PR3c
+ *
+ * Augment-only invariant (see judgeVerdict.ts): a `request_changes`
+ * verdict never appears as a HaltCategory and never causes
+ * `status: "error"`. This module is the *separate* channel that makes
+ * cold-eyes review visible without re-introducing gate semantics.
+ */
+import type { JudgeVerdict, JudgeVerdictKind } from "./judgeVerdict.js";
+export interface JudgeSummary {
+    /** Total step results scanned that carry a `judgeVerdict`. */
+    total: number;
+    /** Per-verdict counts; verdicts with zero hits are omitted. */
+    byVerdict: Partial<Record<JudgeVerdictKind, number>>;
+    /** Most recent 5 verdicts (with first reason) for UI surfacing. */
+    recent: Array<{
+        verdict: JudgeVerdictKind;
+        firstReason?: string;
+        runSeq: number;
+        stepId: string;
+    }>;
+}
+interface JudgeSummaryInputRun {
+    seq: number;
+    stepResults?: Array<{
+        id: string;
+        judgeVerdict?: JudgeVerdict;
+    }>;
+}
+/**
+ * Aggregate judge verdicts across a set of runs. Runs are expected to
+ * be sorted newest-first so `recent` reflects the most recent
+ * verdicts.
+ */
+export declare function summariseJudgments(runs: JudgeSummaryInputRun[]): JudgeSummary;
+/**
+ * Format a `JudgeSummary` as Prometheus text-exposition lines for the
+ * `bridge_recipe_judgments{verdict="..."} N` gauge. Returns an empty
+ * array when the summary is empty (no HELP/TYPE block so Prom scrapers
+ * don't see an orphan declaration).
+ */
+export declare function judgeSummaryToPrometheus(summary: JudgeSummary): string[];
+export {};

package/dist/recipes/judgeSummary.js

@@ -0,0 +1,47 @@
+/**
+ * Aggregate judge verdicts across a set of runs. Runs are expected to
+ * be sorted newest-first so `recent` reflects the most recent
+ * verdicts.
+ */
+export function summariseJudgments(runs) {
+    const byVerdict = {};
+    const recent = [];
+    let total = 0;
+    for (const run of runs) {
+        for (const step of run.stepResults ?? []) {
+            const v = step.judgeVerdict;
+            if (!v)
+                continue;
+            total++;
+            byVerdict[v.verdict] = (byVerdict[v.verdict] ?? 0) + 1;
+            if (recent.length < 5) {
+                recent.push({
+                    verdict: v.verdict,
+                    ...(v.reasons[0] !== undefined && { firstReason: v.reasons[0] }),
+                    runSeq: run.seq,
+                    stepId: step.id,
+                });
+            }
+        }
+    }
+    return { total, byVerdict, recent };
+}
+/**
+ * Format a `JudgeSummary` as Prometheus text-exposition lines for the
+ * `bridge_recipe_judgments{verdict="..."} N` gauge. Returns an empty
+ * array when the summary is empty (no HELP/TYPE block so Prom scrapers
+ * don't see an orphan declaration).
+ */
+export function judgeSummaryToPrometheus(summary) {
+    if (summary.total === 0)
+        return [];
+    const lines = [
+        "# HELP bridge_recipe_judgments Recipe judge-step verdicts in the in-memory run-log window, by verdict",
+        "# TYPE bridge_recipe_judgments gauge",
+    ];
+    for (const [verdict, count] of Object.entries(summary.byVerdict)) {
+        lines.push(`bridge_recipe_judgments{verdict="${verdict}"} ${count}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=judgeSummary.js.map

package/dist/recipes/judgeSummary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"judgeSummary.js","sourceRoot":"","sources":["../../src/recipes/judgeSummary.ts"],"names":[],"mappings":"AAuCA;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA4B;IAC7D,MAAM,SAAS,GAA8C,EAAE,CAAC;IAChE,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC;YAC5B,IAAI,CAAC,CAAC;gBAAE,SAAS;YACjB,KAAK,EAAE,CAAC;YACR,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACvD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,MAAM,CAAC,IAAI,CAAC;oBACV,OAAO,EAAE,CAAC,CAAC,OAAO;oBAClB,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChE,MAAM,EAAE,GAAG,CAAC,GAAG;oBACf,MAAM,EAAE,IAAI,CAAC,EAAE;iBAChB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAqB;IAC5D,IAAI,OAAO,CAAC,KAAK,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,KAAK,GAAa;QACtB,uGAAuG;QACvG,sCAAsC;KACvC,CAAC;IACF,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACjE,KAAK,CAAC,IAAI,CAAC,oCAAoC,OAAO,MAAM,KAAK,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/recipes/judgeVerdict.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Judge verdict — PR3a.
+ *
+ * Parses a free-form agent response into a structured `JudgeVerdict`.
+ * The judge prompt convention asks the model to end its response with
+ * a JSON object of the form:
+ *
+ *   {"verdict": "approve" | "request_changes",
+ *    "reasons": ["..."],
+ *    "fixList": ["..."]}
+ *
+ * The parser walks back from the end of the string, finds the last
+ * JSON object, and validates its shape. On any failure we record the
+ * verdict as `unparseable` and keep the raw text — the runner *never*
+ * throws on a malformed judge response.
+ *
+ * **Augment-only invariant** — see the file-level comment in
+ * yamlRunner.ts. The verdict shape is intentionally separate from
+ * `StepResult.status`: a `request_changes` verdict produces
+ * `status: "ok"` with a stashed verdict, never `status: "error"`.
+ * That separation is what prevents the judge step from quietly
+ * becoming a gate.
+ */
+export type JudgeVerdictKind = "approve" | "request_changes" | "unparseable";
+export interface JudgeVerdict {
+    verdict: JudgeVerdictKind;
+    /** Short bullet points; empty when unparseable. */
+    reasons: string[];
+    /** Optional fix-list when `verdict: "request_changes"`. */
+    fixList?: string[];
+    /** Original model text when parsing failed (or for audit). */
+    raw?: string;
+}
+/**
+ * Append to the judge prompt to elicit the structured tail. Kept short
+ * so it doesn't crowd out the user-provided prompt body.
+ */
+export declare const JUDGE_PROMPT_SUFFIX = "\n\nYou are a cold-eyes reviewer. Respond with a brief assessment, then end\nwith a single JSON object on its own line:\n\n{\"verdict\": \"approve\" | \"request_changes\", \"reasons\": [\"...\"], \"fixList\": [\"...\"]}\n\nThe \"fixList\" is optional and only relevant when requesting changes.\nOutput only the JSON object as the final line.";
+/**
+ * Build the artefact-injection block for a judge step that has a
+ * `reviews: <stepId>` reference. Returns an empty string when no
+ * artefact is available; the judge then sees the prompt as-is.
+ */
+export declare function buildJudgeArtefactBlock(artefact: unknown): string;
+/**
+ * Parse an agent response into a `JudgeVerdict`. Never throws.
+ */
+export declare function parseJudgeVerdict(text: string): JudgeVerdict;