harnery 0.17.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 specialist team and safety limits around a root durable-work graph, then runs scheduling cycles until success, human attention, no progress, or budget exhaustion. An optional planner can propose a schema-gated replacement graph from a frozen workflow-template catalog when the active graph has no legal move; proposals require review by default, old graphs remain immutable evidence, and their 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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/commands/supervisor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAmEnD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA8FnF"}
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/commands/supervisor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAqEnD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAgGnF"}

package/dist/commands/supervisor.js

@@ -11,8 +11,8 @@ export function registerSupervisorCommand(program, emit) {
         .command("supervisor")
         .description("Run a bounded specialist team over a durable-work dependency graph.");
     supervisor
-        .command("create <root-work-id>")
-        .description("Freeze a goal, specialist team, automation policy, and execution limits.")
+        .command("create [root-work-id]")
+        .description("Freeze an existing-root goal or an objective-first bounded mission.")
         .requiredOption("--team <file>", "JSON object mapping specialist ids to profiles")
         .option("--id <goal-id>", "Stable goal id (generated by default)")
         .option("--title <text>", "Goal title (defaults to root work title)")
@@ -26,6 +26,7 @@ export function registerSupervisorCommand(program, emit) {
         .option("--no-resume-approved", "Stop after an approval instead of resuming its parked run")
         .option("--retry-blocked", "Allow bounded retry of blocked work")
         .option("--replanning <file>", "Frozen planner policy and allowed workflow-template catalog")
+        .option("--mission <file>", "Frozen objective, acceptance criteria, and milestone bound")
         .option("--json", "Emit the complete supervisor record as JSON")
         .action((rootWorkId, opts) => {
         withSupervisorRoot(emit, (coordRoot) => {
@@ -54,6 +55,7 @@ export function registerSupervisorCommand(program, emit) {
                     resume_approved: opts.resumeApproved,
                     retry_blocked: opts.retryBlocked,
                 },
+                mission: opts.mission ? readMissionFile(opts.mission) : undefined,
                 replanning: opts.replanning ? readReplanningFile(opts.replanning) : undefined,
             }), opts.json, emit, true);
         });
@@ -466,6 +468,7 @@ function readReplanningFile(path) {
             },
         ];
     }));
+    const review = readReplanningReview(config.review);
     return {
         plannerSpecialist: config.planner_specialist,
         autoApply: jsonBoolean(config.auto_apply, "replanning auto_apply"),
@@ -473,6 +476,50 @@ 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) {
+    const absolute = resolve(path);
+    let value;
+    try {
+        value = JSON.parse(readFileSync(absolute, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`cannot read supervisor mission at ${absolute}: ${error.message}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("supervisor mission must be a JSON object");
+    }
+    const config = value;
+    if (typeof config.objective !== "string") {
+        throw new Error("supervisor mission objective must be a string");
+    }
+    if (!Array.isArray(config.acceptance) ||
+        config.acceptance.some((item) => typeof item !== "string")) {
+        throw new Error("supervisor mission acceptance must be an array of strings");
+    }
+    return {
+        objective: config.objective,
+        acceptance: config.acceptance,
+        maxMilestones: jsonInteger(config.max_milestones, "mission max_milestones"),
     };
 }
 function emitSupervisor(record, json, emit, detail = false) {
@@ -489,7 +536,7 @@ function emitSupervisor(record, json, emit, detail = false) {
     const lines = [
         `${record.intent.id}: ${record.intent.title}`,
         `state: ${projection.state}`,
-        `root: ${projection.root_work_id}`,
+        `root: ${projection.root_materialized ? projection.root_work_id : "pending initial plan"}`,
         `reason: ${projection.reason}`,
         `next: ${projection.next_action}`,
         `work: ${projection.work_ids.length}`,
@@ -500,12 +547,20 @@ 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}`);
         }
         if (projection.pending_plan_id)
             lines.push(`pending plan: ${projection.pending_plan_id}`);
     }
+    if (record.intent.mission) {
+        lines.push(`mission: ${record.intent.mission.objective}`);
+        lines.push(`milestones: ${projection.milestones_completed}/${record.intent.mission.max_milestones}`);
+        lines.push(`mission acceptance: ${record.intent.mission.acceptance.length}`);
+    }
     if (projection.attention_work.length) {
         lines.push(`attention: ${projection.attention_work.join(", ")}`);
     }
@@ -542,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;
@@ -559,6 +622,7 @@ function emitPlan(plan, json, emit) {
         `${plan.request.id}: ${plan.status}`,
         `goal: ${plan.request.goal_id}`,
         `sequence: ${plan.request.sequence}`,
+        `trigger: ${plan.request.trigger ?? "recovery"}`,
         `prior root: ${plan.request.prior_root_work_id}`,
         `planner run: ${plan.request.workflow_run_id}`,
     ];
@@ -566,6 +630,13 @@ function emitPlan(plan, json, emit) {
         lines.push(`decision: ${plan.proposal.decision}`);
         lines.push(`rationale: ${plan.proposal.rationale}`);
         lines.push(`proposed work: ${plan.proposal.work.length}`);
+        if (plan.proposal.milestone) {
+            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}`);
@@ -584,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,7 +1,7 @@
 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 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, collectSupervisorWork, createSupervisor, listSupervisors, newSupervisorId, readSupervisor, SUPERVISOR_INTENT_SCHEMA_VERSION, type SupervisorAutomationPolicy, type SupervisorIntent, type SupervisorLimits, type SupervisorNextAction, type SupervisorProjection, type SupervisorRecord, type SupervisorState, } from "./state.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";
 //# sourceMappingURL=index.d.ts.map

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,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,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,EACd,gCAAgC,EAChC,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,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":"AAEA,OAAO,EAIL,KAAK,qBAAqB,EAE1B,KAAK,oBAAoB,EAE1B,MAAM,iBAAiB,CAAC;AAsBzB,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,MAAM,GACzB,qBAAqB,CAoDvB;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"}