harnery 0.29.0 → 0.31.0

package/dist/commands/browse.js

@@ -2,7 +2,7 @@ import { mkdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, resolve } from "node:path";
 import { resolveBinName } from "../core/config.js";
-import { Browser, captureDevOverlay, wslHeadedLaunchArgs, } from "../lib/browser/index.js";
+import { Browser, captureDevOverlay, DEFAULT_CRITIQUE_RUBRIC, parseAssertSpec, runCritique, tilesFromFullPage, wslHeadedLaunchArgs, } from "../lib/browser/index.js";
 import { diffAgainstBaseline, saveBaseline, } from "../lib/browser/visual-diff.js";
 import { CookieJar } from "../lib/cookies/index.js";
 /**
@@ -125,6 +125,60 @@ export function registerBrowseCommand(program, emitParam, context) {
         .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-crowd <selector>", "Flag adjacent card panels (full border, modest corner radius, or box-shadow) " +
+        "that touch or nearly touch. Also treats wrappers that contain panels as " +
+        "peers, measuring the nearest face panels inside them so a card-grid " +
+        "flush against the next card is caught. Walks the whole subtree under the " +
+        "selector, so one --check-crowd .wrap catches nested cases. Fills the gap " +
+        "between --check-overlap (needs a 2D intersection) and --check-gap (flags " +
+        "uneven spacing, so a uniformly-flush stack passes). Repeatable.", (value, previous = []) => [...previous, value], [])
+        .option("--check-crowd-min <px>", "Minimum acceptable edge gap between adjacent panel faces in CSS px (default 6). " +
+        "Pairs closer than this are flagged; negative separation (overlap) always flags.", "6")
+        .option("--check-crowd-fail", "Exit 2 when a crowd target fails or is missing.")
+        .option("--no-check-crowd-annotate", "Skip crowd screenshot annotations.")
+        .option("--check-placeholder [selector]", "Scan rendered text for unrendered template tokens and bound-value tells: " +
+        "JS template literals, `{{x}}` handlebars, `[object Object]`, `Invalid Date`, " +
+        "`NaN`, or an element whose whole text is literally 'undefined' / 'null'. Optional selector " +
+        "scopes the sweep (default: whole body). Catches the most common generation " +
+        "bug on funnels and reports. Do not point it at a page that documents template " +
+        "syntax in prose.")
+        .option("--check-placeholder-fail", "Exit 2 if any placeholder tell is found.")
+        .option("--no-check-placeholder-annotate", "Skip placeholder screenshot annotations.")
+        .option("--check-images [selector]", "Audit <img> elements for load + aspect health: a failed load (naturalWidth 0), " +
+        "a still-loading image, or a stretched image (rendered aspect ratio far from the " +
+        "intrinsic one, with an object-fit that does not correct it). Optional selector " +
+        "scopes the sweep (default: whole body).")
+        .option("--check-images-tolerance <ratio>", "Aspect-ratio deviation above which an image counts as stretched (0–1, default 0.1 = 10%).", "0.1")
+        .option("--check-images-fail", "Exit 2 if any image failed to load or is stretched.")
+        .option("--no-check-images-annotate", "Skip image screenshot annotations.")
+        .option("--check-truncation [selector]", "Flag text actively cut off by an ellipsis or -webkit-line-clamp — the author asked " +
+        "to truncate AND the content overflows. High precision: it does not flag plain " +
+        "overflow:hidden clips. Optional selector scopes the sweep (default: whole body).")
+        .option("--check-truncation-tolerance <px>", "Overflow past the clip box, in CSS px, above which truncation counts (default 2).", "2")
+        .option("--check-truncation-fail", "Exit 2 if any text is actively truncated.")
+        .option("--no-check-truncation-annotate", "Skip truncation screenshot annotations.")
+        .option("--check-contrast [selector]", "Flag rendered text below the WCAG AA contrast ratio (4.5:1 normal, 3:1 large) against " +
+        "its effective background. Runs at whatever theme the page is in, so toggle the theme " +
+        "with --batch to cover light and dark. Text over an image or gradient is reported as " +
+        "`unknown`, not failed. Optional selector scopes the sweep (default: whole body).")
+        .option("--check-contrast-fail", "Exit 2 if any text fails the contrast ratio.")
+        .option("--no-check-contrast-annotate", "Skip contrast screenshot annotations.")
+        .option("--check-critique [selector]", "Hand the rendered page to a vision model for a visual-defect review, tile by " +
+        "tile. Catches the long tail heuristic checks can't enumerate. Default tiling " +
+        "cuts the page into overlapping vertical bands; pass a selector to tile one " +
+        "screenshot per matching element (semantic tiling). Requires the host to inject " +
+        "a critiqueProvider (harnery ships no model client) — without one the check " +
+        "reports `skipped`. Findings land under `critique` in the JSON envelope.")
+        .option("--check-critique-band <px>", "Band height for default tiling (default 1400).", "1400")
+        .option("--check-critique-overlap <px>", "Vertical overlap between bands so a finding at a seam stays visible (default 120).", "120")
+        .option("--check-critique-max-tiles <n>", "Cap on tiles sent to the model, to bound cost (default 24).", "24")
+        .option("--check-critique-rubric <text>", "Override the default critique rubric.")
+        .option("--check-critique-fail", "Exit 2 if the critique returns any high-severity finding.")
+        .option("--assert <expr>", "Assert a page value (repeatable). Grammar: '<op> <selector> => <expected>', where op is " +
+        "text (trimmed text equals), contains (text includes), matches (text matches a regex), " +
+        "count (match count vs a number or >=/<=/>/< comparator), exists / absent (no => needed). " +
+        "e.g. --assert 'text h1 => Welcome' --assert 'count .card => >=3' --assert 'absent .error'.", (value, previous = []) => [...previous, value], [])
+        .option("--assert-fail", "Exit 2 if any --assert fails.")
         .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,
@@ -163,6 +217,7 @@ async function runBrowse(url, opts, context) {
         : 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 crowdMin = parseNonNegativeNumber(opts.checkCrowdMin ?? "6", "--check-crowd-min");
     const hitProfile = parseTargetSizeProfile(opts.checkHitProfile ?? "wcag-aa");
     // Commander: `--no-cookies` turns `opts.cookies` into `false`. Default is `true`.
     const jar = opts.cookies === false
@@ -238,7 +293,8 @@ async function runBrowse(url, opts, context) {
         const hasLayoutLint = (opts.checkAlign?.length ?? 0) > 0 ||
             (opts.checkGap?.length ?? 0) > 0 ||
             (opts.checkClip?.length ?? 0) > 0 ||
-            (opts.checkOverlap?.length ?? 0) > 0;
+            (opts.checkOverlap?.length ?? 0) > 0 ||
+            (opts.checkCrowd?.length ?? 0) > 0;
         let layoutLint;
         if (hasLayoutLint) {
             layoutLint = await browser.checkLayoutLint({
@@ -261,12 +317,58 @@ async function runBrowse(url, opts, context) {
                     selector,
                     tolerancePx: overlapThreshold,
                 })),
+                crowd: (opts.checkCrowd ?? []).map((selector) => ({
+                    selector,
+                    minGapPx: crowdMin,
+                })),
             });
         }
         let hit;
         if (opts.checkHit && opts.checkHit.length > 0) {
             hit = await browser.checkTargetSize(opts.checkHit, hitProfile);
         }
+        const hasContentChecks = opts.checkPlaceholder !== undefined ||
+            opts.checkImages !== undefined ||
+            opts.checkTruncation !== undefined ||
+            opts.checkContrast !== undefined;
+        let content;
+        if (hasContentChecks) {
+            content = await browser.checkContent({
+                placeholder: opts.checkPlaceholder !== undefined
+                    ? { scope: contentScope(opts.checkPlaceholder) }
+                    : null,
+                image: opts.checkImages !== undefined
+                    ? {
+                        scope: contentScope(opts.checkImages),
+                        tolerance: parseNonNegativeNumber(opts.checkImagesTolerance ?? "0.1", "--check-images-tolerance"),
+                    }
+                    : null,
+                truncation: opts.checkTruncation !== undefined
+                    ? {
+                        scope: contentScope(opts.checkTruncation),
+                        tolerance: parseNonNegativeNumber(opts.checkTruncationTolerance ?? "2", "--check-truncation-tolerance"),
+                    }
+                    : null,
+                contrast: opts.checkContrast !== undefined ? { scope: contentScope(opts.checkContrast) } : null,
+            });
+        }
+        // Vision critique. Capture tiles BEFORE any annotation overlays are injected
+        // so the model sees the real page, not our boxes.
+        let critique;
+        if (opts.checkCritique !== undefined) {
+            const tiles = await captureCritiqueTiles(browser, opts);
+            critique = await runCritique({
+                url: navResult.url,
+                rubric: opts.checkCritiqueRubric ?? DEFAULT_CRITIQUE_RUBRIC,
+                tiles,
+                provider: context?.critiqueProvider,
+            });
+        }
+        let asserts;
+        if (opts.assert && opts.assert.length > 0) {
+            const specs = opts.assert.map(parseAssertSpec);
+            asserts = await browser.checkAsserts(specs);
+        }
         const widthThreshold = Number.parseFloat(opts.checkWidthThreshold ?? "0.9");
         const annotateWidth = widths && opts.checkWidthAnnotate !== false;
         const annotateOverflow = overflow && opts.checkOverflowAnnotate !== false;
@@ -287,19 +389,25 @@ async function runBrowse(url, opts, context) {
                 gap: opts.checkGapAnnotate === false ? [] : layoutLint.gap,
                 clip: opts.checkClipAnnotate === false ? [] : layoutLint.clip,
                 overlap: opts.checkOverlapAnnotate === false ? [] : layoutLint.overlap,
+                crowd: opts.checkCrowdAnnotate === false ? [] : layoutLint.crowd,
             }
             : undefined;
         if (annotateLayoutLint &&
             (annotateLayoutLint.align.length > 0 ||
                 annotateLayoutLint.gap.length > 0 ||
                 annotateLayoutLint.clip.length > 0 ||
-                annotateLayoutLint.overlap.length > 0)) {
+                annotateLayoutLint.overlap.length > 0 ||
+                annotateLayoutLint.crowd.length > 0)) {
             await browser.annotateLayoutLint(annotateLayoutLint);
         }
         const annotateHit = hit && opts.checkHitAnnotate !== false;
         if (annotateHit) {
             await browser.annotateTargetSize(hit);
         }
+        const contentBoxes = content ? collectContentBoxes(content, opts) : [];
+        if (contentBoxes.length > 0) {
+            await browser.annotateContent(contentBoxes);
+        }
         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");
@@ -319,10 +427,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, layoutLint, hit, devOverlay, batchResult);
+            await runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult);
         }
         else {
-            await runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, devOverlay, batchResult);
+            await runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult);
         }
         if (visibility && opts.checkVisibleAnnotate !== false) {
             await browser.clearVisibilityAnnotations();
@@ -339,6 +447,9 @@ async function runBrowse(url, opts, context) {
         if (annotateHit) {
             await browser.clearTargetSizeAnnotations();
         }
+        if (contentBoxes.length > 0) {
+            await browser.clearContentAnnotations();
+        }
         if (opts.checkVisibleFail && visibility) {
             const threshold = Number.parseFloat(opts.checkVisibleThreshold ?? "0.9");
             const failed = visibility.filter((r) => !r.found || !r.cssVisible || r.visibleRatio < threshold);
@@ -389,6 +500,20 @@ async function runBrowse(url, opts, context) {
             process.exitCode = 2;
         }
         applyLayoutLintFailGates(opts, layoutLint, hit);
+        applyContentFailGates(opts, content);
+        if (opts.checkCritiqueFail && critique && critique.outcome === "fail") {
+            const high = critique.findings.filter((f) => f.severity === "high").length;
+            emit.log(`check-critique FAIL: ${high} high-severity finding(s)`, "warn");
+            process.exitCode = 2;
+        }
+        if (opts.assertFail && asserts) {
+            const failed = asserts.filter((a) => a.outcome === "fail");
+            for (const a of failed) {
+                emit.log(`assert FAIL: ${a.op} ${a.selector} → "${a.actual}"${a.error ? ` (${a.error})` : ""}`, "warn");
+            }
+            if (failed.length > 0)
+                process.exitCode = 2;
+        }
     }
     finally {
         await browser.close();
@@ -488,7 +613,7 @@ function splitBatchSteps(input) {
 // ---------------------------------------------------------------------------
 // Print mode (--snapshot / --html / --json): stdout, no file writes
 // ---------------------------------------------------------------------------
-async function runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, devOverlay, batchResult) {
+async function runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult) {
     let body = null;
     if (opts.html) {
         body = await browser.htmlContent(opts.selector);
@@ -522,9 +647,16 @@ async function runPrintMode(browser, navResult, opts, evalResult, visibility, wi
             result.gap = layoutLint.gap;
             result.clip = layoutLint.clip;
             result.overlap = layoutLint.overlap;
+            result.crowd = layoutLint.crowd;
         }
         if (hit)
             result.hit = hit;
+        if (content)
+            assignContent(result, content);
+        if (critique)
+            result.critique = critique;
+        if (asserts)
+            result.asserts = asserts;
         if (devOverlay)
             result.devOverlay = devOverlay;
         if (batchResult && batchResult.clipboardReads.length > 0) {
@@ -548,7 +680,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, layoutLint, hit, devOverlay, batchResult) {
+async function runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult) {
     const prefix = resolveOutPrefix(opts.out);
     mkdirSync(dirname(prefix), { recursive: true });
     const written = [];
@@ -618,9 +750,16 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
         envelope.gap = layoutLint.gap;
         envelope.clip = layoutLint.clip;
         envelope.overlap = layoutLint.overlap;
+        envelope.crowd = layoutLint.crowd;
     }
     if (hit)
         envelope.hit = hit;
+    if (content)
+        assignContent(envelope, content);
+    if (critique)
+        envelope.critique = critique;
+    if (asserts)
+        envelope.asserts = asserts;
     if (devOverlay)
         envelope.devOverlay = devOverlay;
     if (batchResult && batchResult.clipboardReads.length > 0) {
@@ -719,6 +858,22 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
         });
         emit.log(`check-hit:\n${lines.join("\n")}`, "info");
     }
+    if (content) {
+        logContentSummary(content);
+    }
+    if (critique) {
+        logCritiqueSummary(critique);
+    }
+    if (asserts && asserts.length > 0) {
+        const lines = asserts.map((a) => {
+            const detail = a.error ??
+                (a.op === "count" || a.op === "exists" || a.op === "absent"
+                    ? `${a.selector} → ${a.actual}${a.expected ? ` (want ${a.expected})` : ""}`
+                    : `${a.selector} → "${a.actual.slice(0, 60)}"${a.expected ? ` (want ${a.op} "${a.expected}")` : ""}`);
+            return `  [${a.outcome.toUpperCase()}] ${a.op} ${detail}`;
+        });
+        emit.log(`asserts:\n${lines.join("\n")}`, "info");
+    }
     if (savedBaseline) {
         emit.log(`baseline saved: ${savedBaseline.name} → ${savedBaseline.path} (${savedBaseline.bytes} bytes)`, "info");
     }
@@ -775,6 +930,12 @@ function logLayoutLintSummary(result) {
         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²`);
     }
+    for (const check of result.crowd) {
+        const tightest = check.issues.length > 0
+            ? Math.min(...check.issues.map((issue) => issue.separationPx))
+            : check.minGapPx;
+        lines.push(`  [${check.outcome.toUpperCase()}] crowd ${check.selector}: ${check.issues.length} tight pair${check.issues.length === 1 ? "" : "s"} (min gap ${check.minGapPx}px, tightest ${tightest.toFixed(1)}px)`);
+    }
     if (lines.length > 0)
         emit.log(`layout-lint:\n${lines.join("\n")}`, "info");
 }
@@ -793,6 +954,7 @@ function applyLayoutLintFailGates(opts, layoutLint, hit) {
     gate(opts.checkGapFail, "gap", layoutLint?.gap);
     gate(opts.checkClipFail, "clip", layoutLint?.clip);
     gate(opts.checkOverlapFail, "overlap", layoutLint?.overlap);
+    gate(opts.checkCrowdFail, "crowd", layoutLint?.crowd);
     if (opts.checkHitFail && hit) {
         const failed = hit.filter((result) => !result.found || result.outcome === "fail" || result.outcome === "unknown");
         for (const result of failed) {
@@ -802,6 +964,147 @@ function applyLayoutLintFailGates(opts, layoutLint, hit) {
             process.exitCode = 2;
     }
 }
+// ---------------------------------------------------------------------------
+// Content checks (placeholder / image / truncation / contrast)
+// ---------------------------------------------------------------------------
+const CONTENT_COLORS = {
+    placeholder: "#dc2626",
+    image: "#f97316",
+    truncation: "#a855f7",
+    contrast: "#0891b2",
+};
+// Optional-selector flags resolve to a scope: a string selector, or null for
+// the whole body when the flag was passed bare.
+function contentScope(value) {
+    return typeof value === "string" ? value : null;
+}
+function assignContent(target, content) {
+    if (content.placeholder)
+        target.placeholder = content.placeholder;
+    if (content.image)
+        target.image = content.image;
+    if (content.truncation)
+        target.truncation = content.truncation;
+    if (content.contrast)
+        target.contrast = content.contrast;
+}
+function collectContentBoxes(content, opts) {
+    const boxes = [];
+    if (content.placeholder && opts.checkPlaceholderAnnotate !== false) {
+        for (const hit of content.placeholder.hits) {
+            boxes.push({
+                rect: hit.rect,
+                label: `placeholder ${hit.token}`,
+                color: CONTENT_COLORS.placeholder,
+            });
+        }
+    }
+    if (content.image && opts.checkImagesAnnotate !== false) {
+        for (const issue of content.image.issues) {
+            boxes.push({ rect: issue.rect, label: `image ${issue.reason}`, color: CONTENT_COLORS.image });
+        }
+    }
+    if (content.truncation && opts.checkTruncationAnnotate !== false) {
+        for (const hit of content.truncation.hits) {
+            boxes.push({
+                rect: hit.rect,
+                label: `truncated ${hit.how}`,
+                color: CONTENT_COLORS.truncation,
+            });
+        }
+    }
+    if (content.contrast && opts.checkContrastAnnotate !== false) {
+        for (const hit of content.contrast.hits) {
+            if (hit.outcome !== "fail")
+                continue;
+            boxes.push({
+                rect: hit.rect,
+                label: `contrast ${hit.ratio}:1 < ${hit.required}`,
+                color: CONTENT_COLORS.contrast,
+            });
+        }
+    }
+    return boxes;
+}
+function logContentSummary(content) {
+    const lines = [];
+    if (content.placeholder) {
+        const c = content.placeholder;
+        lines.push(`  [${c.outcome.toUpperCase()}] placeholder: ${c.hits.length} tell(s) in ${c.scanned} node(s)`);
+    }
+    if (content.image) {
+        const c = content.image;
+        const missing = c.issues.filter((i) => i.reason === "missing").length;
+        const stretched = c.issues.filter((i) => i.reason === "stretched").length;
+        lines.push(`  [${c.outcome.toUpperCase()}] image: ${missing} missing, ${stretched} stretched of ${c.scanned}`);
+    }
+    if (content.truncation) {
+        const c = content.truncation;
+        lines.push(`  [${c.outcome.toUpperCase()}] truncation: ${c.hits.length} clipped of ${c.scanned}`);
+    }
+    if (content.contrast) {
+        const c = content.contrast;
+        const fails = c.hits.filter((h) => h.outcome === "fail").length;
+        const unknown = c.hits.filter((h) => h.outcome === "unknown").length;
+        lines.push(`  [${c.outcome.toUpperCase()}] contrast: ${fails} fail, ${unknown} unknown of ${c.scanned}`);
+    }
+    if (lines.length > 0)
+        emit.log(`content-checks:\n${lines.join("\n")}`, "info");
+}
+function applyContentFailGates(opts, content) {
+    if (!content)
+        return;
+    const gate = (enabled, rule, result) => {
+        if (!enabled || !result)
+            return;
+        if (!result.found || result.outcome === "fail") {
+            emit.log(`check-${rule} FAIL: ${result.found ? "issues found" : "scope not found"}`, "warn");
+            process.exitCode = 2;
+        }
+    };
+    gate(opts.checkPlaceholderFail, "placeholder", content.placeholder);
+    gate(opts.checkImagesFail, "images", content.image);
+    gate(opts.checkTruncationFail, "truncation", content.truncation);
+    gate(opts.checkContrastFail, "contrast", content.contrast);
+}
+// ---------------------------------------------------------------------------
+// Vision critique tiling
+// ---------------------------------------------------------------------------
+async function captureCritiqueTiles(browser, opts) {
+    const maxTiles = Math.max(1, Number.parseInt(opts.checkCritiqueMaxTiles ?? "24", 10));
+    const band = Math.max(200, Number.parseInt(opts.checkCritiqueBand ?? "1400", 10));
+    const overlap = Math.max(0, Number.parseInt(opts.checkCritiqueOverlap ?? "120", 10));
+    // Capture the whole page ONCE, then crop tiles from the pixels. Playwright's
+    // clip is viewport-relative, so a below-fold band clip throws ("clipped area
+    // outside the resulting image") — cropping the full-page image sidesteps that
+    // and keeps every tile at full resolution.
+    const buffer = await browser.fullPageScreenshotBuffer();
+    const elementRects = typeof opts.checkCritique === "string"
+        ? await browser.elementTiles(opts.checkCritique)
+        : undefined;
+    const tiles = tilesFromFullPage(buffer, { elementRects, bandHeight: band, overlap, maxTiles });
+    if (elementRects && elementRects.length > maxTiles) {
+        emit.log(`check-critique: ${elementRects.length} elements matched, capped to ${maxTiles} tiles`, "warn");
+    }
+    else if (!elementRects && tiles.length >= maxTiles) {
+        emit.log(`check-critique: page banded to the ${maxTiles}-tile cap (raise --check-critique-max-tiles for full coverage)`, "warn");
+    }
+    return tiles;
+}
+function logCritiqueSummary(critique) {
+    if (critique.outcome === "skipped") {
+        emit.log(`check-critique: SKIPPED (${critique.error ?? "no provider"})`, "warn");
+        return;
+    }
+    const high = critique.findings.filter((f) => f.severity === "high").length;
+    const med = critique.findings.filter((f) => f.severity === "medium").length;
+    const low = critique.findings.filter((f) => f.severity === "low").length;
+    const lines = critique.findings
+        .slice(0, 20)
+        .map((f) => `  [${f.severity}] tile ${f.tile} ${f.category}: ${f.description}`);
+    emit.log(`check-critique [${critique.outcome.toUpperCase()}] ${critique.tiles} tiles → ${high} high / ${med} med / ${low} low` +
+        (lines.length ? `\n${lines.join("\n")}` : ""), critique.outcome === "fail" ? "warn" : "info");
+}
 function summarizeDiagnostics(diag) {
     return {
         viewport: diag.viewport,

package/dist/commands/checkpoint.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+/**
+ * `harn checkpoint`: durable context continuity across compaction.
+ *
+ * A checkpoint captures enough of the current work that a fresh generation of
+ * the same session can resume it after the adapter compacts or restarts.
+ * `create` writes a capsule, `show` prints the latest one, `status` reports the
+ * phase, generation, and whatever context telemetry the adapter supplied.
+ */
+export declare function registerCheckpointCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=checkpoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/commands/checkpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAU1E;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA2HN"}

package/dist/commands/checkpoint.js

@@ -0,0 +1,162 @@
+import { monorepoRoot, readHeartbeat, resolveOwner } from "../core/agents/index.js";
+import { checkpointContext, readContextState, readLatestCapsule, } from "../core/context/index.js";
+/**
+ * `harn checkpoint`: durable context continuity across compaction.
+ *
+ * A checkpoint captures enough of the current work that a fresh generation of
+ * the same session can resume it after the adapter compacts or restarts.
+ * `create` writes a capsule, `show` prints the latest one, `status` reports the
+ * phase, generation, and whatever context telemetry the adapter supplied.
+ */
+export function registerCheckpointCommand(program, emit, context) {
+    const command = program
+        .command("checkpoint")
+        .description("Durable context-continuity capsules: create one, show the latest, or report continuity phase.")
+        .option("--json", "Structured JSON output");
+    command
+        .command("status")
+        .description("Show context-continuity phase, generation, and latest telemetry")
+        .option("--session <id>", "Session id (defaults to the current agent heartbeat)")
+        .option("--instance <id>", "Agent instance id (defaults to the current owner)")
+        .option("--json", "Structured JSON output")
+        .action((opts) => {
+        try {
+            const json = opts.json || Boolean(command.opts().json);
+            const identity = resolveContinuityIdentity(context, opts);
+            const state = readContextState(identity.coordRoot, identity.sessionId);
+            if (json) {
+                emit.config({ format: "json" });
+                emit.data({ state, identity });
+                return;
+            }
+            if (!state) {
+                emit.text(`No context continuity state for session ${identity.sessionId}.\n`);
+                return;
+            }
+            const sample = state.latest_context;
+            const usage = sample
+                ? `${sample.used_tokens ?? "?"}/${sample.window_tokens ?? "?"} tokens${sample.used_percent === undefined ? "" : ` (${sample.used_percent}%)`}`
+                : "not reported by adapter";
+            emit.text(`${[
+                `Session:    ${state.session_id}`,
+                `Phase:      ${state.phase}`,
+                `Generation: ${state.generation}`,
+                `Telemetry:  ${usage}`,
+                `Capsule:    ${state.latest_capsule ?? "none"}`,
+                state.degraded_reason ? `Degraded:   ${state.degraded_reason}` : "",
+            ]
+                .filter(Boolean)
+                .join("\n")}\n`);
+        }
+        catch (err) {
+            emitCommandError(emit, "checkpoint_status_failed", err);
+        }
+    });
+    command
+        .command("create")
+        .description("Create a durable context-continuity capsule for the current work")
+        .option("--session <id>", "Session id (defaults to the current agent heartbeat)")
+        .option("--instance <id>", "Agent instance id (defaults to the current owner)")
+        .option("--adapter <id>", "claude-code, codex, or cursor (inferred from heartbeat)")
+        .option("--reason <reason>", "manual, pressure, pre_compact, or session_end", "manual")
+        .option("--note <text>", "Short continuation note for the recovered agent")
+        .option("--json", "Structured JSON output")
+        .action((opts) => {
+        try {
+            const json = opts.json || Boolean(command.opts().json);
+            const reason = parseCheckpointReason(opts.reason);
+            const identity = resolveContinuityIdentity(context, opts);
+            if (!identity.adapter) {
+                throw new Error("could not infer the adapter; pass --adapter claude-code|codex|cursor");
+            }
+            const result = checkpointContext(identity.coordRoot, {
+                sessionId: identity.sessionId,
+                instanceId: identity.instanceId,
+                adapter: identity.adapter,
+                cwd: context?.repoRoot ?? process.cwd(),
+                reason,
+                continuationNote: opts.note,
+            });
+            const output = {
+                capsule_id: result.capsule.capsule_id,
+                generation: result.capsule.generation,
+                path: result.state.latest_capsule,
+                phase: result.state.phase,
+                reused: result.reused,
+            };
+            if (json) {
+                emit.config({ format: "json" });
+                emit.data(output);
+                return;
+            }
+            emit.text(`Checkpointed context generation ${output.generation}: ${output.path ?? result.path}\n`);
+        }
+        catch (err) {
+            emitCommandError(emit, "checkpoint_create_failed", err);
+        }
+    });
+    command
+        .command("show")
+        .description("Show the latest durable context-continuity capsule")
+        .option("--session <id>", "Session id (defaults to the current agent heartbeat)")
+        .option("--instance <id>", "Agent instance id (defaults to the current owner)")
+        .option("--json", "Structured JSON output")
+        .action((opts) => {
+        try {
+            const json = opts.json || Boolean(command.opts().json);
+            const identity = resolveContinuityIdentity(context, opts);
+            const capsule = readLatestCapsule(identity.coordRoot, identity.sessionId);
+            if (!capsule) {
+                throw new Error(`no context capsule exists for session ${identity.sessionId}`);
+            }
+            if (json)
+                emit.config({ format: "json" });
+            emit.data(capsule);
+        }
+        catch (err) {
+            emitCommandError(emit, "checkpoint_show_failed", err);
+        }
+    });
+}
+function resolveContinuityIdentity(context, opts) {
+    const coordRoot = context?.resolveCoordRoot?.() ?? context?.repoRoot ?? monorepoRoot();
+    if (!coordRoot)
+        throw new Error("could not resolve a project containing .harnery/");
+    const instanceId = opts.instance ?? resolveOwner();
+    if (!instanceId) {
+        throw new Error("could not resolve the current agent; pass --instance and --session");
+    }
+    const heartbeat = readHeartbeat(instanceId);
+    const sessionId = opts.session ?? heartbeat?.session_id ?? instanceId;
+    const adapter = opts.adapter
+        ? parseAdapter(opts.adapter)
+        : adapterFromPlatform(heartbeat?.platform);
+    return { coordRoot, instanceId, sessionId, adapter };
+}
+function adapterFromPlatform(platform) {
+    if (platform === "claude_code" || platform === "claude-code")
+        return "claude-code";
+    if (platform === "cursor")
+        return "cursor";
+    if (platform === "codex")
+        return "codex";
+    return null;
+}
+function parseAdapter(value) {
+    if (value === "claude-code" || value === "codex" || value === "cursor")
+        return value;
+    throw new Error(`invalid adapter "${value}"; expected claude-code, codex, or cursor`);
+}
+function parseCheckpointReason(value) {
+    if (value === "manual" ||
+        value === "pressure" ||
+        value === "pre_compact" ||
+        value === "session_end") {
+        return value;
+    }
+    throw new Error(`invalid reason "${value}"; expected manual, pressure, pre_compact, or session_end`);
+}
+function emitCommandError(emit, code, err) {
+    emit.error({ code, message: err instanceof Error ? err.message : String(err) });
+    emit.setExitCode(1);
+}

package/dist/commands/context.d.ts

@@ -1,11 +1,11 @@
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.js";
 /**
- * `harn context`: one-shot orientation snapshot.
+ * `harn agents context`: one-shot orientation snapshot.
  *
  * Aggregates self / time / repo / commits / submodules / peers (default) plus
  * opt-in services. Useful at session start, post-compaction, or before
  * dispatching subagents. Fail-open per section.
  */
-export declare function registerContextCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+export declare function registerContextCommand(parent: Command, emit: EmitContext, context?: HarneryProgramContext): void;
 //# sourceMappingURL=context.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/commands/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiB1E;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAqKN"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/commands/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAS1E;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAiDN"}