harnery 0.18.0 → 0.19.0

package/README.md

@@ -23,7 +23,7 @@
 - **Cross-machine presence:** sessions on every machine that shares a repo see each other, labeled by machine. Zero-config over the repo's own git remote (presence refs), with an optional live-socket upgrade via an end-to-end-encrypted relay — the public `relay.harnery.com`, or self-host with `harn relay serve` / the bundled Cloudflare Worker (`relay/worker/`). The relay sees only ciphertext in opaquely-named rooms.
 - **Coordination-aware workflows:** `harn workflow run <script>` executes bounded, schema-gated multi-subagent workflow scripts — plain JS stages fanning out to headless harness-CLI subagents that are born coordination-registered (heartbeats, events, claim guards), with deterministic code deciding the routing between stages. An optional host-owned policy gates dispatch and declared external mutations with `ALLOW`, `ASK`, and `DENY`; CLI `ASK` requests park durably for an explicit approve/deny and same-run resume, while library callers remain fail-closed by default.
 - **Durable work above attempts:** `harn work` preserves an objective across bounded workflow attempts, dependencies, approval parks, failures, and review. Its one-shot reconciler derives state from append-only local evidence and reports the next explicit action without silently spawning, retrying, or accepting work.
-- **Bounded goal supervision:** `harn supervisor` freezes a mission or existing root graph, specialist team, and safety limits, then runs scheduling cycles until reviewed mission success, human attention, no progress, or budget exhaustion. Its optional planner can create the first milestone, reassess accepted milestone proof, or recover a terminal graph using only a frozen workflow-template catalog. Proposals require review by default, old generations remain immutable evidence, and all attempts still consume the goal budget. Use explicit foreground ticks or enroll goals in the optional heartbeat-backed background service.
+- **Bounded goal supervision:** `harn supervisor` freezes a mission or existing root graph, specialist team, and safety limits, then runs scheduling cycles until reviewed mission success, human attention, no progress, or budget exhaustion. Its optional planner can create the first milestone, reassess accepted milestone proof, or recover a terminal graph using only a frozen workflow-template catalog. Plans can require independent bounded specialist review before ordinary approval or auto-apply authority, old generations remain immutable evidence, and all attempts still consume the goal budget. Use explicit foreground ticks or enroll goals in the optional heartbeat-backed background service.
 - **Standalone web UI:** `harn web up` boots a local Next.js dashboard for the coord layer, councils, per-project state, and a local coding-agent status view (Claude Code / Codex / Cursor usage, backed by `harn devtools`). Ships with the git clone, not the npm package (see [Install](#install)).
 - **Backup + sync:** `harn backup` snapshots `.harnery/` via [restic](https://restic.net/); `harn sync` keeps a curated subset live across machines via [rclone](https://rclone.org/) (Google Drive or any rclone remote).
 

package/dist/commands/browse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAmH1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAoLN"}
+{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAgJ1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA6PN"}

package/dist/commands/browse.js

@@ -105,6 +105,32 @@ export function registerBrowseCommand(program, emitParam, context) {
         .option("--check-runts-min-chars <n>", "Minimum block text length to scan (default 40; smaller labels can't meaningfully wrap).", "40")
         .option("--check-runts-fail", "Exit non-zero if any runt is detected.")
         .option("--no-check-runts-annotate", "Skip drawing runt boxes on the screenshot (JSON still emitted).")
+        .option("--check-align <selector>", "Check rendered child-content alignment inside this container (repeatable).", (value, previous = []) => [...previous, value], [])
+        .option("--check-align-axis <axis>", "Alignment axis: auto | x | y (default auto).", "auto")
+        .option("--check-align-threshold <px>", "Maximum rendered-center drift in CSS pixels (default 2).", "2")
+        .option("--check-align-fail", "Exit 2 when an alignment target fails or is missing.")
+        .option("--no-check-align-annotate", "Skip alignment screenshot annotations.")
+        .option("--check-gap <selector>", "Check adjacent rendered gaps inside this container (repeatable).", (value, previous = []) => [...previous, value], [])
+        .option("--check-gap-axis <axis>", "Gap axis: auto | x | y (default auto).", "auto")
+        .option("--check-gap-expected <px>", "Expected gap in CSS pixels. Without it, groups of 3+ infer the median gap.")
+        .option("--check-gap-threshold <px>", "Maximum gap deviation in CSS pixels (default 2).", "2")
+        .option("--check-gap-fail", "Exit 2 when a gap target fails or is missing.")
+        .option("--no-check-gap-annotate", "Skip gap screenshot annotations.")
+        .option("--check-clip <selector>", "Check descendants against this container's rectangular clipping chain (repeatable).", (value, previous = []) => [...previous, value], [])
+        .option("--check-clip-threshold <px>", "Allowed rectangular overrun in CSS pixels (default 0).", "0")
+        .option("--check-clip-fail", "Exit 2 when a clip target fails or is missing.")
+        .option("--no-check-clip-annotate", "Skip clip screenshot annotations.")
+        .option("--check-overlap <selector>", "Check measurable in-flow siblings for unintended overlap (repeatable).", (value, previous = []) => [...previous, value], [])
+        .option("--check-overlap-threshold <px>", "Allowed overlap depth on either axis in CSS pixels (default 0).", "0")
+        .option("--check-overlap-fail", "Exit 2 when an overlap target fails or is missing.")
+        .option("--no-check-overlap-annotate", "Skip overlap screenshot annotations.")
+        .option("--check-hit [selector]", "Check pointer-target size and spacing in the document or optional scope (repeatable).", (value, previous = []) => [
+        ...previous,
+        typeof value === "string" ? value : null,
+    ], [])
+        .option("--check-hit-profile <profile>", "Target profile: wcag-aa (24px) | comfortable (44px).", "wcag-aa")
+        .option("--check-hit-fail", "Exit 2 when target sizing fails, is incomplete, or a scope is missing.")
+        .option("--no-check-hit-annotate", "Skip target-size screenshot annotations.")
         .option("--baseline <name>", "Save the captured screenshot as a named baseline at " +
         "~/.cache/harnery/visual-baselines/<name>.png. Use --diff <name> later to " +
         "compare future captures against it (visual-regression check).")
@@ -127,6 +153,16 @@ export function registerBrowseCommand(program, emitParam, context) {
     });
 }
 async function runBrowse(url, opts, context) {
+    const alignAxis = parseLayoutAxis(opts.checkAlignAxis ?? "auto", "--check-align-axis");
+    const gapAxis = parseLayoutAxis(opts.checkGapAxis ?? "auto", "--check-gap-axis");
+    const alignThreshold = parseNonNegativeNumber(opts.checkAlignThreshold ?? "2", "--check-align-threshold");
+    const gapThreshold = parseNonNegativeNumber(opts.checkGapThreshold ?? "2", "--check-gap-threshold");
+    const gapExpected = opts.checkGapExpected === undefined
+        ? null
+        : parseNonNegativeNumber(opts.checkGapExpected, "--check-gap-expected");
+    const clipThreshold = parseNonNegativeNumber(opts.checkClipThreshold ?? "0", "--check-clip-threshold");
+    const overlapThreshold = parseNonNegativeNumber(opts.checkOverlapThreshold ?? "0", "--check-overlap-threshold");
+    const hitProfile = parseTargetSizeProfile(opts.checkHitProfile ?? "wcag-aa");
     // Commander: `--no-cookies` turns `opts.cookies` into `false`. Default is `true`.
     const jar = opts.cookies === false
         ? null
@@ -198,6 +234,38 @@ async function runBrowse(url, opts, context) {
                 minChars: Number.parseInt(opts.checkRuntsMinChars ?? "40", 10),
             });
         }
+        const hasLayoutLint = (opts.checkAlign?.length ?? 0) > 0 ||
+            (opts.checkGap?.length ?? 0) > 0 ||
+            (opts.checkClip?.length ?? 0) > 0 ||
+            (opts.checkOverlap?.length ?? 0) > 0;
+        let layoutLint;
+        if (hasLayoutLint) {
+            layoutLint = await browser.checkLayoutLint({
+                align: (opts.checkAlign ?? []).map((selector) => ({
+                    selector,
+                    axis: alignAxis,
+                    tolerancePx: alignThreshold,
+                })),
+                gap: (opts.checkGap ?? []).map((selector) => ({
+                    selector,
+                    axis: gapAxis,
+                    tolerancePx: gapThreshold,
+                    expectedGapPx: gapExpected,
+                })),
+                clip: (opts.checkClip ?? []).map((selector) => ({
+                    selector,
+                    tolerancePx: clipThreshold,
+                })),
+                overlap: (opts.checkOverlap ?? []).map((selector) => ({
+                    selector,
+                    tolerancePx: overlapThreshold,
+                })),
+            });
+        }
+        let hit;
+        if (opts.checkHit && opts.checkHit.length > 0) {
+            hit = await browser.checkTargetSize(opts.checkHit, hitProfile);
+        }
         const widthThreshold = Number.parseFloat(opts.checkWidthThreshold ?? "0.9");
         const annotateWidth = widths && opts.checkWidthAnnotate !== false;
         const annotateOverflow = overflow && opts.checkOverflowAnnotate !== false;
@@ -212,6 +280,25 @@ async function runBrowse(url, opts, context) {
         if (annotateRunts) {
             await browser.annotateRunts(runts);
         }
+        const annotateLayoutLint = layoutLint
+            ? {
+                align: opts.checkAlignAnnotate === false ? [] : layoutLint.align,
+                gap: opts.checkGapAnnotate === false ? [] : layoutLint.gap,
+                clip: opts.checkClipAnnotate === false ? [] : layoutLint.clip,
+                overlap: opts.checkOverlapAnnotate === false ? [] : layoutLint.overlap,
+            }
+            : undefined;
+        if (annotateLayoutLint &&
+            (annotateLayoutLint.align.length > 0 ||
+                annotateLayoutLint.gap.length > 0 ||
+                annotateLayoutLint.clip.length > 0 ||
+                annotateLayoutLint.overlap.length > 0)) {
+            await browser.annotateLayoutLint(annotateLayoutLint);
+        }
+        const annotateHit = hit && opts.checkHitAnnotate !== false;
+        if (annotateHit) {
+            await browser.annotateTargetSize(hit);
+        }
         if (opts.login) {
             await new Promise((res) => {
                 emit.log("[--login] Headed Chromium is open. Walk through your auth flow now. Press Enter here to close + persist cookies into the profile.", "info");
@@ -228,10 +315,10 @@ async function runBrowse(url, opts, context) {
             if (opts.baseline || opts.diff) {
                 throw new Error("--baseline / --diff require trio mode (screenshot file). Remove --snapshot/--html/--json or capture the screenshot first.");
             }
-            await runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, devOverlay, batchResult);
+            await runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, devOverlay, batchResult);
         }
         else {
-            await runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, devOverlay, batchResult);
+            await runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, devOverlay, batchResult);
         }
         if (visibility && opts.checkVisibleAnnotate !== false) {
             await browser.clearVisibilityAnnotations();
@@ -242,6 +329,12 @@ async function runBrowse(url, opts, context) {
         if (annotateRunts) {
             await browser.clearRuntsAnnotations();
         }
+        if (annotateLayoutLint) {
+            await browser.clearLayoutLintAnnotations();
+        }
+        if (annotateHit) {
+            await browser.clearTargetSizeAnnotations();
+        }
         if (opts.checkVisibleFail && visibility) {
             const threshold = Number.parseFloat(opts.checkVisibleThreshold ?? "0.9");
             const failed = visibility.filter((r) => !r.found || !r.cssVisible || r.visibleRatio < threshold);
@@ -291,6 +384,7 @@ async function runBrowse(url, opts, context) {
             emit.log(`check-overflow FAIL: documentScrollWidth ${overflow.documentScrollWidth}px > viewport ${overflow.viewport.width}px (+${overflow.overflowPx}px)${detail}`, "warn");
             process.exitCode = 2;
         }
+        applyLayoutLintFailGates(opts, layoutLint, hit);
     }
     finally {
         await browser.close();
@@ -390,7 +484,7 @@ function splitBatchSteps(input) {
 // ---------------------------------------------------------------------------
 // Print mode (--snapshot / --html / --json): stdout, no file writes
 // ---------------------------------------------------------------------------
-async function runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, devOverlay, batchResult) {
+async function runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, devOverlay, batchResult) {
     let body = null;
     if (opts.html) {
         body = await browser.htmlContent(opts.selector);
@@ -419,6 +513,14 @@ async function runPrintMode(browser, navResult, opts, evalResult, visibility, wi
             result.overflow = overflow;
         if (runts)
             result.runts = runts;
+        if (layoutLint) {
+            result.align = layoutLint.align;
+            result.gap = layoutLint.gap;
+            result.clip = layoutLint.clip;
+            result.overlap = layoutLint.overlap;
+        }
+        if (hit)
+            result.hit = hit;
         if (devOverlay)
             result.devOverlay = devOverlay;
         if (batchResult && batchResult.clipboardReads.length > 0) {
@@ -442,7 +544,7 @@ async function runPrintMode(browser, navResult, opts, evalResult, visibility, wi
 // ---------------------------------------------------------------------------
 // Trio mode (default): write <prefix>.{png,html,json}
 // ---------------------------------------------------------------------------
-async function runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, devOverlay, batchResult) {
+async function runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, devOverlay, batchResult) {
     const prefix = resolveOutPrefix(opts.out);
     mkdirSync(dirname(prefix), { recursive: true });
     const written = [];
@@ -485,6 +587,14 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
         envelope.overflow = overflow;
     if (runts)
         envelope.runts = runts;
+    if (layoutLint) {
+        envelope.align = layoutLint.align;
+        envelope.gap = layoutLint.gap;
+        envelope.clip = layoutLint.clip;
+        envelope.overlap = layoutLint.overlap;
+    }
+    if (hit)
+        envelope.hit = hit;
     if (devOverlay)
         envelope.devOverlay = devOverlay;
     if (batchResult && batchResult.clipboardReads.length > 0) {
@@ -572,6 +682,17 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
                 : ""}`;
         emit.log(`check-overflow: [${ok ? "OK" : "FAIL"}] ${detail}`, ok ? "info" : "warn");
     }
+    if (layoutLint) {
+        logLayoutLintSummary(layoutLint);
+    }
+    if (hit) {
+        const lines = hit.map((result) => {
+            const failed = result.nodes.filter((node) => node.outcome === "fail").length;
+            const unknown = result.nodes.filter((node) => node.outcome === "unknown").length;
+            return `  [${result.outcome.toUpperCase()}] ${result.selector ?? "document"}: ${failed} failed, ${unknown} unknown, ${result.nodes.length} evaluated (${result.minSizePx}px)`;
+        });
+        emit.log(`check-hit:\n${lines.join("\n")}`, "info");
+    }
     if (savedBaseline) {
         emit.log(`baseline saved: ${savedBaseline.name} → ${savedBaseline.path} (${savedBaseline.bytes} bytes)`, "info");
     }
@@ -593,6 +714,68 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+function parseNonNegativeNumber(value, flag) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`${flag} must be a finite non-negative number (got: ${value})`);
+    }
+    return parsed;
+}
+function parseLayoutAxis(value, flag) {
+    if (value === "auto" || value === "x" || value === "y")
+        return value;
+    throw new Error(`${flag} must be auto, x, or y (got: ${value})`);
+}
+function parseTargetSizeProfile(value) {
+    if (value === "wcag-aa" || value === "comfortable")
+        return value;
+    throw new Error(`--check-hit-profile must be wcag-aa or comfortable (got: ${value})`);
+}
+function logLayoutLintSummary(result) {
+    const lines = [];
+    for (const check of result.align) {
+        const worst = Math.max(0, ...check.clusters.flatMap((cluster) => cluster.children.map((child) => Math.abs(child.deltaPx))));
+        lines.push(`  [${check.outcome.toUpperCase()}] align ${check.selector}: worst ${worst.toFixed(1)}px (${check.axis})`);
+    }
+    for (const check of result.gap) {
+        const worst = Math.max(0, ...check.clusters.flatMap((cluster) => cluster.pairs.map((pair) => Math.abs(pair.deltaPx ?? 0))));
+        lines.push(`  [${check.outcome.toUpperCase()}] gap ${check.selector}: worst ${worst.toFixed(1)}px (${check.axis})`);
+    }
+    for (const check of result.clip) {
+        const worst = Math.max(0, ...check.issues.map((issue) => issue.maxOverrunPx));
+        lines.push(`  [${check.outcome.toUpperCase()}] clip ${check.selector}: ${check.issues.length} issues, worst ${worst.toFixed(1)}px, ${check.unsupported.length} unknown shapes`);
+    }
+    for (const check of result.overlap) {
+        const worst = Math.max(0, ...check.issues.map((issue) => issue.areaPx));
+        lines.push(`  [${check.outcome.toUpperCase()}] overlap ${check.selector}: ${check.issues.length} collisions, worst ${worst.toFixed(0)}px²`);
+    }
+    if (lines.length > 0)
+        emit.log(`layout-lint:\n${lines.join("\n")}`, "info");
+}
+function applyLayoutLintFailGates(opts, layoutLint, hit) {
+    const gate = (enabled, rule, results) => {
+        if (!enabled || !results)
+            return;
+        const failed = results.filter((result) => !result.found || result.outcome === "fail");
+        for (const result of failed) {
+            emit.log(`check-${rule} FAIL ${result.selector}: ${result.found ? "rendered relation failed" : "element not found"}`, "warn");
+        }
+        if (failed.length > 0)
+            process.exitCode = 2;
+    };
+    gate(opts.checkAlignFail, "align", layoutLint?.align);
+    gate(opts.checkGapFail, "gap", layoutLint?.gap);
+    gate(opts.checkClipFail, "clip", layoutLint?.clip);
+    gate(opts.checkOverlapFail, "overlap", layoutLint?.overlap);
+    if (opts.checkHitFail && hit) {
+        const failed = hit.filter((result) => !result.found || result.outcome === "fail" || result.outcome === "unknown");
+        for (const result of failed) {
+            emit.log(`check-hit FAIL ${result.selector ?? "document"}: ${result.found ? result.outcome : "element not found"}`, "warn");
+        }
+        if (failed.length > 0)
+            process.exitCode = 2;
+    }
+}
 function summarizeDiagnostics(diag) {
     return {
         viewport: diag.viewport,

package/dist/commands/supervisor.js

@@ -468,6 +468,7 @@ function readReplanningFile(path) {
             },
         ];
     }));
+    const review = readReplanningReview(config.review);
     return {
         plannerSpecialist: config.planner_specialist,
         autoApply: jsonBoolean(config.auto_apply, "replanning auto_apply"),
@@ -475,6 +476,24 @@ function readReplanningFile(path) {
         maxWorkItemsPerPlan: jsonInteger(config.max_work_items_per_plan, "replanning max_work_items_per_plan"),
         maxTotalWorkItems: jsonInteger(config.max_total_work_items, "replanning max_total_work_items"),
         templates,
+        ...(review ? { review } : {}),
+    };
+}
+function readReplanningReview(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("supervisor replanning review must be a JSON object");
+    }
+    const review = raw;
+    if (!Array.isArray(review.reviewer_specialists) ||
+        review.reviewer_specialists.some((item) => typeof item !== "string")) {
+        throw new Error("supervisor replanning review reviewer_specialists must be an array of strings");
+    }
+    return {
+        reviewerSpecialists: review.reviewer_specialists,
+        maxRevisionRounds: jsonNonNegativeInteger(review.max_revision_rounds, "replanning review max_revision_rounds") ??
+            0,
     };
 }
 function readMissionFile(path) {
@@ -528,6 +547,9 @@ function emitSupervisor(record, json, emit, detail = false) {
     ];
     if (record.intent.replanning) {
         lines.push(`replanning: generation=${projection.plan_generation}, used=${projection.replans_used}/${record.intent.replanning.max_replans}, auto_apply=${record.intent.replanning.auto_apply}`);
+        if (record.intent.replanning.review) {
+            lines.push(`plan review: reviewers=${record.intent.replanning.review.reviewer_specialists.join(", ")}, max_revision_rounds=${record.intent.replanning.review.max_revision_rounds}`);
+        }
         if (projection.root_work_id !== record.intent.root_work_id) {
             lines.push(`original root: ${record.intent.root_work_id}`);
         }
@@ -575,6 +597,14 @@ function jsonInteger(value, field) {
     }
     return value;
 }
+function jsonNonNegativeInteger(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`${field} must be a non-negative integer`);
+    }
+    return value;
+}
 function jsonBoolean(value, field) {
     if (value === undefined)
         return undefined;
@@ -604,6 +634,10 @@ function emitPlan(plan, json, emit) {
             lines.push(`milestone: ${plan.proposal.milestone.sequence} ${plan.proposal.milestone.title}`);
         }
     }
+    if (plan.review) {
+        lines.push(`review: ${plan.review.status}, rounds=${plan.review.rounds}, blocking=${plan.review.blocking_findings}, advisory=${plan.review.advisory_findings}`);
+        lines.push(`review candidate: ${plan.review.candidate_sha256}`);
+    }
     if (plan.root_work_id)
         lines.push(`applied root: ${plan.root_work_id}`);
     if (plan.approval_id)
@@ -621,7 +655,8 @@ function emitPlanOutcome(outcome, json, emit) {
         `${outcome.root_work_id ? `root: ${outcome.root_work_id}\n` : ""}`);
 }
 function renderPlanRow(plan) {
-    return `${plan.request.id}  ${plan.status.padEnd(18)}  ${plan.request.prior_root_work_id}`;
+    const review = plan.review ? `  review:${plan.review.status}` : "";
+    return `${plan.request.id}  ${plan.status.padEnd(18)}  ${plan.request.prior_root_work_id}${review}`;
 }
 function delay(ms) {
     return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));

package/dist/core/supervisor/index.d.ts

@@ -1,6 +1,6 @@
 export { approveSupervisorPlan, rejectSupervisorPlan } from "./plan-api.js";
-export { readSupervisorPlan, readSupervisorPlans } from "./plan-read.js";
-export { type CreateSupervisorPlanTemplateInput, type CreateSupervisorReplanningInput, SUPERVISOR_PLAN_SCHEMA_VERSION, type SupervisorPlanEvent, type SupervisorPlanEventType, type SupervisorPlanHistory, type SupervisorPlanMilestone, type SupervisorPlanOutcome, type SupervisorPlanProposal, type SupervisorPlanRecord, type SupervisorPlanRequest, type SupervisorPlanStatus, type SupervisorPlanTemplate, type SupervisorPlanWorkSpec, type SupervisorReplanningPolicy, } from "./plan-types.js";
+export { readSupervisorPlan, readSupervisorPlanReviewReceipt, readSupervisorPlans, } from "./plan-read.js";
+export { type CreateSupervisorPlanTemplateInput, type CreateSupervisorReplanningInput, MAX_SUPERVISOR_PLAN_REVIEWERS, MAX_SUPERVISOR_PLAN_REVISION_ROUNDS, SUPERVISOR_PLAN_SCHEMA_VERSION, type SupervisorPlanEvent, type SupervisorPlanEventType, type SupervisorPlanHistory, type SupervisorPlanMilestone, type SupervisorPlanOutcome, type SupervisorPlanProposal, type SupervisorPlanRecord, type SupervisorPlanRequest, type SupervisorPlanReviewFinding, type SupervisorPlanReviewReceipt, type SupervisorPlanReviewReviewer, type SupervisorPlanReviewRound, type SupervisorPlanReviewStatus, type SupervisorPlanReviewSummary, type SupervisorPlanReviewVerdict, type SupervisorPlanStatus, type SupervisorPlanTemplate, type SupervisorPlanWorkSpec, type SupervisorReplanningPolicy, } from "./plan-types.js";
 export { type RunSupervisorInput, runSupervisor, type SupervisorDispatchOutcome, type SupervisorRunReport, type SupervisorStopReason, } from "./runner.js";
 export { type ConfigureSupervisorServiceInput, configureSupervisorService, type RunSupervisorServiceDaemonInput, type RunSupervisorServiceSweepInput, readSupervisorServiceConfig, readSupervisorServiceRuntime, readSupervisorServiceStatus, requestSupervisorServiceStop, runSupervisorServiceDaemon, runSupervisorServiceSweep, SUPERVISOR_SERVICE_CONFIG_SCHEMA_VERSION, SUPERVISOR_SERVICE_RUNTIME_SCHEMA_VERSION, SUPERVISOR_SERVICE_STATUS_SCHEMA_VERSION, type SupervisorServiceConfig, type SupervisorServiceEngineConfig, type SupervisorServiceGoalRuntime, type SupervisorServiceGoalState, type SupervisorServiceProcessState, type SupervisorServiceRuntime, type SupervisorServiceStatus, type SupervisorServiceStatusRecord, type SupervisorServiceSweepOutcome, type SupervisorServiceSweepReport, spawnSupervisorService, supervisorServiceLogPath, } from "./service.js";
 export { assertSupervisorId, type CreateSupervisorInput, type CreateSupervisorMissionInput, collectSupervisorWork, createSupervisor, listSupervisors, newSupervisorId, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, type SupervisorAutomationPolicy, type SupervisorIntent, type SupervisorLimits, type SupervisorMission, type SupervisorNextAction, type SupervisorProjection, type SupervisorRecord, type SupervisorState, } from "./state.js";

package/dist/core/supervisor/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EACL,KAAK,iCAAiC,EACtC,KAAK,+BAA+B,EACpC,8BAA8B,EAC9B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,GAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,kBAAkB,EACvB,aAAa,EACb,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,+BAA+B,EACpC,0BAA0B,EAC1B,KAAK,+BAA+B,EACpC,KAAK,8BAA8B,EACnC,2BAA2B,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,wCAAwC,EACxC,yCAAyC,EACzC,wCAAwC,EACxC,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,EAC/B,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,EACjC,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,EACd,gCAAgC,EAChC,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EACL,kBAAkB,EAClB,+BAA+B,EAC/B,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,iCAAiC,EACtC,KAAK,+BAA+B,EACpC,6BAA6B,EAC7B,mCAAmC,EACnC,8BAA8B,EAC9B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,GAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,kBAAkB,EACvB,aAAa,EACb,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,+BAA+B,EACpC,0BAA0B,EAC1B,KAAK,+BAA+B,EACpC,KAAK,8BAA8B,EACnC,2BAA2B,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,wCAAwC,EACxC,yCAAyC,EACzC,wCAAwC,EACxC,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,EAC/B,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,EACjC,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,EACd,gCAAgC,EAChC,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC"}

package/dist/core/supervisor/index.js

@@ -1,6 +1,6 @@
 export { approveSupervisorPlan, rejectSupervisorPlan } from "./plan-api.js";
-export { readSupervisorPlan, readSupervisorPlans } from "./plan-read.js";
-export { SUPERVISOR_PLAN_SCHEMA_VERSION, } from "./plan-types.js";
+export { readSupervisorPlan, readSupervisorPlanReviewReceipt, readSupervisorPlans, } from "./plan-read.js";
+export { MAX_SUPERVISOR_PLAN_REVIEWERS, MAX_SUPERVISOR_PLAN_REVISION_ROUNDS, SUPERVISOR_PLAN_SCHEMA_VERSION, } from "./plan-types.js";
 export { runSupervisor, } from "./runner.js";
 export { configureSupervisorService, readSupervisorServiceConfig, readSupervisorServiceRuntime, readSupervisorServiceStatus, requestSupervisorServiceStop, runSupervisorServiceDaemon, runSupervisorServiceSweep, SUPERVISOR_SERVICE_CONFIG_SCHEMA_VERSION, SUPERVISOR_SERVICE_RUNTIME_SCHEMA_VERSION, SUPERVISOR_SERVICE_STATUS_SCHEMA_VERSION, spawnSupervisorService, supervisorServiceLogPath, } from "./service.js";
 export { assertSupervisorId, collectSupervisorWork, createSupervisor, listSupervisors, newSupervisorId, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, } from "./state.js";

package/dist/core/supervisor/plan-read.d.ts

@@ -1,4 +1,5 @@
-import { type SupervisorPlanHistory, type SupervisorPlanRecord } from "./plan-types.js";
+import { type SupervisorPlanHistory, type SupervisorPlanRecord, type SupervisorPlanReviewReceipt } from "./plan-types.js";
 export declare function readSupervisorPlans(coordRootRaw: string, goalId: string, originalRootWorkId: string): SupervisorPlanHistory;
 export declare function readSupervisorPlan(coordRootRaw: string, goalId: string, planId: string): SupervisorPlanRecord;
+export declare function readSupervisorPlanReviewReceipt(coordRootRaw: string, goalId: string, planId: string): SupervisorPlanReviewReceipt | undefined;
 //# sourceMappingURL=plan-read.d.ts.map

package/dist/core/supervisor/plan-read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-read.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/plan-read.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,qBAAqB,EAE1B,KAAK,oBAAoB,EAE1B,MAAM,iBAAiB,CAAC;AAuBzB,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,MAAM,GACzB,qBAAqB,CAwEvB;AAED,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,oBAAoB,CAetB"}
+{"version":3,"file":"plan-read.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/plan-read.ts"],"names":[],"mappings":"AAIA,OAAO,EAML,KAAK,qBAAqB,EAE1B,KAAK,oBAAoB,EAGzB,KAAK,2BAA2B,EAMjC,MAAM,iBAAiB,CAAC;AAwBzB,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,MAAM,GACzB,qBAAqB,CAwEvB;AAED,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,oBAAoB,CAsBtB;AAED,wBAAgB,+BAA+B,CAC7C,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,2BAA2B,GAAG,SAAS,CAWzC"}

package/dist/core/supervisor/plan-read.js

@@ -1,7 +1,8 @@
+import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { readWorkItem } from "../work/read.js";
-import { SUPERVISOR_PLAN_SCHEMA_VERSION, } from "./plan-types.js";
+import { MAX_SUPERVISOR_PLAN_REVIEWERS, MAX_SUPERVISOR_PLAN_REVISION_ROUNDS, SUPERVISOR_PLAN_SCHEMA_VERSION, } from "./plan-types.js";
 const PLAN_ID = /^plan-[0-9]{4}-[a-f0-9]{8}$/;
 const GOAL_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
 const WORK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
@@ -15,6 +16,7 @@ const MAX_EVENTS = 100;
 const EVENT_TYPES = new Set([
     "plan.awaiting_approval",
     "plan.resumed",
+    "plan.reviewed",
     "plan.proposed",
     "plan.applied",
     "plan.completed",
@@ -107,9 +109,30 @@ export function readSupervisorPlan(coordRootRaw, goalId, planId) {
         : undefined;
     if (proposal)
         validateProposalEnvelope(proposal, planId);
+    const review = readSupervisorPlanReviewReceipt(coordRootRaw, goalId, planId);
     const events = readEvents(join(dir, "events.jsonl"), planId);
     const derived = deriveStatus(coordRoot, events, proposal);
-    return { request, proposal, events, ...derived };
+    return {
+        request,
+        proposal,
+        review: review ? summarizeReview(review) : undefined,
+        events,
+        ...derived,
+    };
+}
+export function readSupervisorPlanReviewReceipt(coordRootRaw, goalId, planId) {
+    assertId(goalId, GOAL_ID, "supervisor id");
+    assertId(planId, PLAN_ID, "supervisor plan id");
+    const coordRoot = resolve(coordRootRaw);
+    const path = join(planDir(coordRoot, goalId, planId), "review.json");
+    if (!existsSync(path))
+        return undefined;
+    const receipt = readJson(path, "plan review receipt");
+    validateReviewReceipt(receipt, planId);
+    const reviewPolicy = readFrozenReviewPolicy(coordRoot, goalId);
+    if (reviewPolicy)
+        validateReviewReceiptMatchesPolicy(receipt, planId, reviewPolicy);
+    return receipt;
 }
 function deriveStatus(coordRoot, events, proposal) {
     const latest = events.at(-1);
@@ -249,6 +272,156 @@ function validateProposalEnvelope(proposal, planId) {
         }
     }
 }
+function validateReviewReceipt(receipt, planId) {
+    if (!receipt ||
+        typeof receipt !== "object" ||
+        receipt.schema_version !== SUPERVISOR_PLAN_SCHEMA_VERSION ||
+        receipt.plan_id !== planId ||
+        !["passed", "revision_exhausted", "attention", "failed"].includes(receipt.status) ||
+        !/^[a-f0-9]{64}$/.test(receipt.candidate_sha256) ||
+        !Array.isArray(receipt.rounds) ||
+        receipt.rounds.length < 1 ||
+        receipt.rounds.length > MAX_SUPERVISOR_PLAN_REVISION_ROUNDS + 1) {
+        throw new Error(`supervisor plan review ${planId} has an unsupported schema`);
+    }
+    validateProposalEnvelope(receipt.final_candidate, planId);
+    if (receipt.candidate_sha256 !== candidateDigest(receipt.final_candidate)) {
+        throw new Error(`supervisor plan review ${planId} has invalid candidate digest`);
+    }
+    receipt.rounds.forEach((round, index) => {
+        validateReviewRound(round, planId, index + 1);
+    });
+    const finalRound = receipt.rounds.at(-1);
+    if (finalRound?.candidate_sha256 !== receipt.candidate_sha256) {
+        throw new Error(`supervisor plan review ${planId} final round does not match its candidate`);
+    }
+    if (receipt.status === "passed" && finalRound?.outcome !== "approved") {
+        throw new Error(`supervisor plan review ${planId} passed without approval`);
+    }
+    if (receipt.status === "attention" && finalRound?.outcome === "approved") {
+        throw new Error(`supervisor plan review ${planId} attention conflicts with approval`);
+    }
+}
+function readFrozenReviewPolicy(coordRoot, goalId) {
+    const path = join(coordRoot, ".harnery", "supervisors", goalId, "intent.json");
+    if (!existsSync(path))
+        return undefined;
+    const intent = readJson(path, "supervisor intent");
+    return intent.replanning?.review;
+}
+function validateReviewReceiptMatchesPolicy(receipt, planId, review) {
+    if (receipt.rounds.length > review.max_revision_rounds + 1) {
+        throw new Error(`supervisor plan review ${planId} exceeds the frozen review policy`);
+    }
+    for (const round of receipt.rounds) {
+        if (round.reviewers.length !== review.reviewer_specialists.length) {
+            throw new Error(`supervisor plan review ${planId} does not match the frozen review policy`);
+        }
+        round.reviewers.forEach((reviewer, index) => {
+            if (reviewer.specialist !== review.reviewer_specialists[index]) {
+                throw new Error(`supervisor plan review ${planId} does not match the frozen review policy`);
+            }
+        });
+        const outcome = aggregateReviewers(round.reviewers);
+        if (round.outcome !== outcome) {
+            throw new Error(`supervisor plan review ${planId} has an invalid reviewer outcome`);
+        }
+    }
+    const finalRound = receipt.rounds.at(-1);
+    if (receipt.status === "passed" && finalRound.outcome !== "approved") {
+        throw new Error(`supervisor plan review ${planId} passed without policy approval`);
+    }
+    if (receipt.status === "revision_exhausted" && finalRound.round <= review.max_revision_rounds) {
+        throw new Error(`supervisor plan review ${planId} exhausted before the frozen review limit`);
+    }
+}
+function aggregateReviewers(reviewers) {
+    if (reviewers.length < 1)
+        return "failed";
+    if (reviewers.some((reviewer) => reviewer.verdict === "attention"))
+        return "attention";
+    if (reviewers.some((reviewer) => reviewer.verdict === "revise" ||
+        reviewer.findings.some((finding) => finding.severity === "blocking"))) {
+        return "revise";
+    }
+    return "approved";
+}
+function candidateDigest(candidate) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalCandidate(candidate)))
+        .digest("hex");
+}
+function canonicalCandidate(candidate) {
+    return {
+        schema_version: candidate.schema_version,
+        plan_id: candidate.plan_id,
+        decision: candidate.decision,
+        rationale: candidate.rationale,
+        root: candidate.root,
+        work: candidate.work,
+        milestone: candidate.milestone,
+    };
+}
+function validateReviewRound(round, planId, sequence) {
+    if (!round ||
+        typeof round !== "object" ||
+        round.round !== sequence ||
+        !/^[a-f0-9]{64}$/.test(round.candidate_sha256) ||
+        !Array.isArray(round.reviewers) ||
+        round.reviewers.length < 1 ||
+        round.reviewers.length > MAX_SUPERVISOR_PLAN_REVIEWERS ||
+        !["approved", "revise", "attention", "failed"].includes(round.outcome) ||
+        (round.revision_workflow_run_id !== undefined &&
+            !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(round.revision_workflow_run_id))) {
+        throw new Error(`supervisor plan review ${planId} round ${sequence} is invalid`);
+    }
+    round.reviewers.forEach((reviewer, index) => {
+        validateReviewReviewer(reviewer, planId, sequence, index);
+    });
+}
+function validateReviewReviewer(reviewer, planId, round, index) {
+    if (!reviewer ||
+        typeof reviewer !== "object" ||
+        typeof reviewer.specialist !== "string" ||
+        reviewer.specialist.length < 1 ||
+        reviewer.specialist.length > 100 ||
+        !["approve", "revise", "attention"].includes(reviewer.verdict) ||
+        typeof reviewer.rationale !== "string" ||
+        reviewer.rationale.length < 1 ||
+        reviewer.rationale.length > 2_000 ||
+        !Array.isArray(reviewer.findings) ||
+        reviewer.findings.length > 50) {
+        throw new Error(`supervisor plan review ${planId} round ${round} reviewer ${index} is invalid`);
+    }
+    reviewer.findings.forEach((finding, findingIndex) => {
+        validateReviewFinding(finding, planId, round, index, findingIndex);
+    });
+}
+function validateReviewFinding(finding, planId, round, reviewerIndex, findingIndex) {
+    if (!finding ||
+        typeof finding !== "object" ||
+        typeof finding.code !== "string" ||
+        !/^[a-z][a-z0-9._-]{0,99}$/.test(finding.code) ||
+        !["blocking", "advisory"].includes(finding.severity) ||
+        typeof finding.summary !== "string" ||
+        finding.summary.length < 1 ||
+        finding.summary.length > 1_000 ||
+        typeof finding.recommendation !== "string" ||
+        finding.recommendation.length < 1 ||
+        finding.recommendation.length > 1_000) {
+        throw new Error(`supervisor plan review ${planId} round ${round} reviewer ${reviewerIndex} finding ${findingIndex} is invalid`);
+    }
+}
+function summarizeReview(receipt) {
+    const findings = receipt.rounds.flatMap((round) => round.reviewers.flatMap((reviewer) => reviewer.findings));
+    return {
+        status: receipt.status,
+        candidate_sha256: receipt.candidate_sha256,
+        rounds: receipt.rounds.length,
+        blocking_findings: findings.filter((finding) => finding.severity === "blocking").length,
+        advisory_findings: findings.filter((finding) => finding.severity === "advisory").length,
+    };
+}
 function validateEvent(event, planId, sequence) {
     if (event.schema_version !== SUPERVISOR_PLAN_SCHEMA_VERSION ||
         event.plan_id !== planId ||