patchwork-os 0.2.0-beta.2 → 0.2.0-beta.3

package/dist/recipes/idempotencyKey.js

@@ -0,0 +1,298 @@
+/**
+ * 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, writeFileSync, } from "node:fs";
+import path from "node:path";
+/**
+ * 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();
+    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(),
+            });
+        }
+    }
+    /** 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);
+            }
+            writeFileSync(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/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;

package/dist/recipes/judgeVerdict.js

@@ -0,0 +1,174 @@
+/**
+ * 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.
+ */
+/**
+ * Append to the judge prompt to elicit the structured tail. Kept short
+ * so it doesn't crowd out the user-provided prompt body.
+ */
+export const JUDGE_PROMPT_SUFFIX = `
+
+You are a cold-eyes reviewer. Respond with a brief assessment, then end
+with a single JSON object on its own line:
+
+{"verdict": "approve" | "request_changes", "reasons": ["..."], "fixList": ["..."]}
+
+The "fixList" is optional and only relevant when requesting changes.
+Output 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 function buildJudgeArtefactBlock(artefact) {
+    if (artefact === undefined || artefact === null)
+        return "";
+    let body;
+    if (typeof artefact === "string") {
+        body = artefact;
+    }
+    else {
+        try {
+            body = JSON.stringify(artefact, null, 2);
+            // `JSON.stringify` returns `undefined` for functions / symbols /
+            // top-level BigInt — the artefact block becomes
+            // `<artefact>\nundefined\n</artefact>` which is misleading. Fall
+            // back to a marker so downstream readers can spot the gap.
+            if (body === undefined)
+                body = "[unserialisable artefact]";
+        }
+        catch {
+            // Circular references, BigInt inside the object graph, or any
+            // toJSON throwing. The judge step must never propagate this out
+            // of the prompt builder — augment-only invariant.
+            body = "[unserialisable artefact]";
+        }
+    }
+    return `\n\n<artefact>\n${body}\n</artefact>`;
+}
+/**
+ * Walk `text` forward and emit `[start, endInclusive]` ranges for every
+ * balanced top-level `{...}` block, respecting JSON string syntax so a
+ * `}` inside a string doesn't offset the brace depth.
+ *
+ * The original implementation walked back from `lastIndexOf("}")` and
+ * counted braces literally. A judge response of the shape
+ * `Consider this snippet: { x: "} oops" }` would be miscounted — the
+ * `}` inside the string would close depth too early and the candidate
+ * slice would JSON.parse-fail, returning `unparseable` for an
+ * otherwise-legitimate verdict trailer.
+ */
+function findBalancedObjectRanges(text) {
+    const ranges = [];
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (ch === "\\") {
+                escaped = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "{") {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0 && start !== -1) {
+                ranges.push([start, i]);
+                start = -1;
+            }
+            if (depth < 0) {
+                // Stray closing brace — reset so we don't underflow.
+                depth = 0;
+                start = -1;
+            }
+        }
+    }
+    return ranges;
+}
+/**
+ * Parse an agent response into a `JudgeVerdict`. Never throws.
+ */
+export function parseJudgeVerdict(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0) {
+        return {
+            verdict: "unparseable",
+            reasons: [],
+            raw: text,
+        };
+    }
+    // Collect every balanced `{...}` range, then try them last-to-first
+    // so the JSON tail wins over an in-prose snippet earlier in the
+    // response.
+    const ranges = findBalancedObjectRanges(trimmed);
+    for (let i = ranges.length - 1; i >= 0; i--) {
+        const range = ranges[i];
+        if (!range)
+            continue;
+        const [s, e] = range;
+        const candidate = trimmed.slice(s, e + 1);
+        let parsed;
+        try {
+            parsed = JSON.parse(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object")
+            continue;
+        const obj = parsed;
+        const verdictRaw = obj.verdict;
+        if (verdictRaw !== "approve" && verdictRaw !== "request_changes") {
+            continue;
+        }
+        const reasons = Array.isArray(obj.reasons)
+            ? obj.reasons.filter((r) => typeof r === "string")
+            : [];
+        const fixList = Array.isArray(obj.fixList)
+            ? obj.fixList.filter((r) => typeof r === "string")
+            : undefined;
+        return {
+            verdict: verdictRaw,
+            reasons,
+            ...(fixList && fixList.length > 0 && { fixList }),
+        };
+    }
+    return { verdict: "unparseable", reasons: [], raw: text };
+}
+//# sourceMappingURL=judgeVerdict.js.map

package/dist/recipes/judgeVerdict.js.map

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

package/dist/recipes/migrations/index.d.ts

@@ -1,6 +1,14 @@
 import type { WarnFn } from "./types.js";
 export type { RecipeMigration, WarnFn } from "./types.js";
 export { v1Migration } from "./v1.js";
+/**
+ * Default deprecation-warning sink for the runtime/validation/fmt callers.
+ * Forwards to `console.warn` outside of tests so users see migration
+ * prompts in CLI output, but stays silent under vitest so the dozens of
+ * intentional legacy-shape regression fixtures don't flood stderr. Tests
+ * that need to assert warnings still pass their own `vi.fn()` directly.
+ */
+export declare const defaultDeprecationWarn: WarnFn;
 /** apiVersion produced by the most recent migration. */
 export declare const CURRENT_API_VERSION = "patchwork.sh/v1";
 export interface MigrationResult {
@@ -22,3 +30,4 @@ export interface MigrationResult {
  *   through unchanged so downstream schema lint can flag it).
  */
 export declare function migrateRecipeToCurrent(recipe: unknown, warn?: WarnFn): MigrationResult;
+export declare function normalizeRecipeForRuntime(recipe: unknown, warn?: WarnFn): unknown;