harnery 0.36.0 → 0.37.0

package/dist/commands/diagnostics.js

@@ -0,0 +1,229 @@
+import { monorepoRoot, resolveOwner } from "../core/agents/index.js";
+import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.js";
+import { buildDiagnosticAdvice, captureDiagnosticBundle, compareDiagnosticBundles, DIAGNOSTIC_COMMAND_SCHEMA_VERSION, listDiagnosticBundles, renderDiagnosticBundleComparison, replayDiagnosticBundle, showDiagnosticBundle, } from "../core/diagnostics/index.js";
+import { buildSupervisorTimeline, explainSupervisorFinding, readSupervisorExplanation, readSupervisorFindings, readSupervisorStatus, readSupervisorTimeline, } from "../core/supervisor/index.js";
+export function registerDiagnosticsCommand(program, emit, context) {
+    const root = program
+        .command("diagnostics")
+        .description("Capture, inspect, and replay sanitized local diagnostic bundles.");
+    root
+        .command("list")
+        .description("List live findings and managed diagnostic bundles.")
+        .action(() => {
+        run(emit, () => {
+            const repoRoot = requireRepoRoot(context);
+            const report = readSupervisorFindings(repoRoot);
+            const findings = mergeFindings(report?.active ?? [], report?.transitions ?? []);
+            const bundles = listDiagnosticBundles(repoRoot);
+            const capability = liveFindingsCapability(repoRoot, report !== undefined);
+            emit.data({
+                schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+                kind: "diagnostic_list",
+                findings,
+                bundles,
+                capability,
+                total_findings: findings.length,
+                total_bundles: bundles.length,
+            });
+        });
+    });
+    root
+        .command("show <ref>")
+        .description("Show one finding or validate one diagnostic bundle.")
+        .action((ref) => {
+        run(emit, () => {
+            const repoRoot = requireRepoRoot(context);
+            const finding = findFinding(repoRoot, ref);
+            if (finding) {
+                emit.data({
+                    schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+                    kind: "diagnostic_finding",
+                    finding,
+                    timeline: readSupervisorTimeline(repoRoot, finding.id) ?? buildSupervisorTimeline(finding),
+                    explanation: readSupervisorExplanation(repoRoot, finding.id) ?? explainSupervisorFinding(finding),
+                });
+                return;
+            }
+            const bundle = showDiagnosticBundle(repoRoot, ref);
+            emit.data({
+                schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+                kind: "diagnostic_bundle",
+                bundle: {
+                    path: bundle.path,
+                    manifest: bundle.manifest,
+                    summary: bundle.summary,
+                },
+            });
+        });
+    });
+    root
+        .command("explain")
+        .description("Report bounded local pressure advice without taking action.")
+        .option("--bundle <artifact-ref>", "Use a frozen diagnostic bundle instead of live state")
+        .option("--json", "Emit structured JSON")
+        .action((opts) => {
+        run(emit, () => {
+            if (opts.json)
+                emit.config({ format: "json" });
+            const repoRoot = requireRepoRoot(context);
+            if (opts.bundle) {
+                const bundle = showDiagnosticBundle(repoRoot, opts.bundle);
+                emit.data({
+                    schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+                    kind: "diagnostic_advice",
+                    source: {
+                        mode: "frozen",
+                        artifact_id: bundle.manifest.artifact_id,
+                        captured_at: bundle.manifest.captured_at,
+                    },
+                    advice: bundle.expected.advice,
+                });
+                return;
+            }
+            const report = readSupervisorFindings(repoRoot);
+            const findings = mergeFindings(report?.active ?? [], report?.transitions ?? []);
+            const sourceCapability = liveFindingsCapability(repoRoot, report !== undefined);
+            emit.data({
+                schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+                kind: "diagnostic_advice",
+                source: { mode: "live" },
+                advice: buildDiagnosticAdvice({
+                    findings,
+                    sourceCapability,
+                    evaluatedAt: new Date().toISOString(),
+                }),
+            });
+        });
+    });
+    root
+        .command("capture")
+        .description("Capture sanitized supervisor inputs into a frozen managed bundle.")
+        .option("--finding <id>", "Capture the time range for one finding")
+        .option("--from <timestamp>", "Capture observations from this ISO timestamp")
+        .option("--to <timestamp>", "Capture observations through this ISO timestamp")
+        .option("--days <n>", "Managed artifact retention in days")
+        .action((opts) => {
+        run(emit, () => {
+            const repoRoot = requireRepoRoot(context);
+            const captured = captureDiagnosticBundle(repoRoot, {
+                findingId: opts.finding,
+                startAt: opts.from,
+                endAt: opts.to,
+                retentionDays: opts.days === undefined ? undefined : parseDays(opts.days),
+                actor: currentActor(repoRoot),
+            });
+            emit.data({
+                schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+                kind: "diagnostic_bundle_capture",
+                bundle: {
+                    path: captured.path,
+                    artifact_id: captured.manifest.artifact_id,
+                    captured_at: captured.manifest.captured_at,
+                    finding_id: captured.manifest.finding_id,
+                    summary: captured.summary,
+                },
+            });
+        });
+    });
+    root
+        .command("replay <artifact-ref>")
+        .description("Replay a frozen bundle without reading live supervisor state.")
+        .action((ref) => {
+        run(emit, () => {
+            emit.data({
+                schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+                kind: "diagnostic_bundle_replay",
+                replay: replayDiagnosticBundle(requireRepoRoot(context), ref),
+            });
+        });
+    });
+    root
+        .command("compare <before> <after>")
+        .description("Compare two frozen bundles without reading live supervisor state.")
+        .option("--json", "Emit structured JSON")
+        .action((before, after, opts) => {
+        run(emit, () => {
+            const comparison = compareDiagnosticBundles(requireRepoRoot(context), before, after);
+            if (opts.json) {
+                emit.config({ format: "json" });
+                emit.data({
+                    schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+                    kind: "diagnostic_bundle_comparison",
+                    comparison,
+                });
+                return;
+            }
+            emit.text(renderDiagnosticBundleComparison(comparison));
+        });
+    });
+}
+function liveFindingsCapability(repoRoot, reportPresent) {
+    if (!reportPresent) {
+        return {
+            source_kind: "supervisor.findings",
+            state: "unsupported",
+            reason_code: "source_missing",
+        };
+    }
+    const status = readSupervisorStatus(repoRoot);
+    if (status.running)
+        return { source_kind: "supervisor.findings", state: "supported" };
+    return {
+        source_kind: "supervisor.findings",
+        state: "expired",
+        reason_code: status.stale
+            ? "supervisor_status_stale"
+            : status.record
+                ? "supervisor_not_running"
+                : "supervisor_status_missing",
+    };
+}
+function findFinding(repoRoot, id) {
+    const report = readSupervisorFindings(repoRoot);
+    return mergeFindings(report?.active ?? [], report?.transitions ?? []).find((finding) => finding.id === id);
+}
+function mergeFindings(active, transitions) {
+    const byId = new Map();
+    for (const finding of transitions)
+        byId.set(finding.id, finding);
+    for (const finding of active)
+        byId.set(finding.id, finding);
+    return [...byId.values()].sort((left, right) => Date.parse(right.observed_at) - Date.parse(left.observed_at) ||
+        left.id.localeCompare(right.id));
+}
+function currentActor(repoRoot) {
+    const instanceId = resolveOwner();
+    if (!instanceId)
+        return undefined;
+    const heartbeat = readLiveCoordinationRow(repoRoot, instanceId);
+    return {
+        instance_id: instanceId,
+        session_id: heartbeat?.session_id,
+        name: heartbeat?.name,
+    };
+}
+function requireRepoRoot(context) {
+    const root = context?.repoRoot ?? monorepoRoot();
+    if (!root)
+        throw new Error("not inside a Git repository");
+    return root;
+}
+function parseDays(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 3_650) {
+        throw new Error("--days must be between 1 and 3650");
+    }
+    return parsed;
+}
+function run(emit, fn) {
+    try {
+        fn();
+    }
+    catch (error) {
+        emit.error({
+            code: "diagnostics_failed",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        emit.setExitCode(1);
+    }
+}

package/dist/commands/files.d.ts

@@ -12,6 +12,18 @@ export interface LocalFileUrl {
     relPath: string;
     mode: Exclude<LocalFileUrlMode, "auto">;
 }
+export type DashboardRootErrorCode = "dashboard_unreachable" | "dashboard_identity_unavailable" | "dashboard_root_mismatch";
+export declare class DashboardRootError extends Error {
+    readonly code: DashboardRootErrorCode;
+    readonly hint: string;
+    constructor(code: DashboardRootErrorCode, message: string, hint: string);
+}
+export type DashboardRootFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/**
+ * Prove that the dashboard on the selected port serves the same canonical
+ * coordination root used to mint the file URL.
+ */
+export declare function verifyDashboardRoot(coordRoot: string, port: number, fetchImpl?: DashboardRootFetch): Promise<void>;
 /**
  * Mint the local browser URL for a file under the dashboard's coord root.
  * HTML defaults to the isolated files origin so scripts and relative assets

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

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/commands/files.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAK1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEzD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;CACzC;AAuCD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAS1F;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA6DN"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/commands/files.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAM1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEzD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,MAAM,MAAM,sBAAsB,GAC9B,uBAAuB,GACvB,gCAAgC,GAChC,yBAAyB,CAAC;AAE9B,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,IAAI,EAAE,sBAAsB;IAErC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAFZ,IAAI,EAAE,sBAAsB,EACrC,OAAO,EAAE,MAAM,EACN,IAAI,EAAE,MAAM;CAKxB;AAMD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC7B,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,kBAA0B,GACpC,OAAO,CAAC,IAAI,CAAC,CAmDf;AAuCD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAS1F;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA0EN"}

package/dist/commands/files.js

@@ -2,8 +2,53 @@ import { realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { resolveCoordRoot } from "../core/agents/coord-client.js";
 import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.js";
+import { coordRootId, localCoordRootIdUrl } from "../lib/coord-root-id.js";
 import { localFilesOriginUrl, localFileViewerUrl } from "../lib/local-file-url.js";
 export { FILES_ORIGIN_HOST } from "../lib/local-file-url.js";
+export class DashboardRootError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.name = "DashboardRootError";
+    }
+}
+/**
+ * Prove that the dashboard on the selected port serves the same canonical
+ * coordination root used to mint the file URL.
+ */
+export async function verifyDashboardRoot(coordRoot, port, fetchImpl = fetch) {
+    const url = localCoordRootIdUrl(port);
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(5_000),
+        });
+    }
+    catch {
+        throw new DashboardRootError("dashboard_unreachable", `dashboard is not reachable at http://localhost:${port}`, "Start the dashboard for this repository, then retry.");
+    }
+    if (!response.ok) {
+        throw new DashboardRootError("dashboard_identity_unavailable", `dashboard at http://localhost:${port} cannot report its repository identity (HTTP ${response.status})`, "Update and restart the dashboard, then retry.");
+    }
+    let payload;
+    try {
+        payload = (await response.json());
+    }
+    catch {
+        throw new DashboardRootError("dashboard_identity_unavailable", `dashboard at http://localhost:${port} returned an invalid repository identity`, "Update and restart the dashboard, then retry.");
+    }
+    if (typeof payload.root_id !== "string") {
+        throw new DashboardRootError("dashboard_identity_unavailable", `dashboard at http://localhost:${port} returned an invalid repository identity`, "Update and restart the dashboard, then retry.");
+    }
+    const expected = coordRootId(coordRoot);
+    if (payload.root_id !== expected) {
+        throw new DashboardRootError("dashboard_root_mismatch", `dashboard at http://localhost:${port} serves a different repository`, "Stop that dashboard and start this repository's dashboard, then retry.");
+    }
+}
 function isOutsideRoot(relPath) {
     return relPath === "" || relPath === ".." || relPath.startsWith(`..${path.sep}`);
 }
@@ -66,7 +111,8 @@ export function registerFilesCommand(program, emit, context) {
         .option("--coord-root <dir>", "Override the coord root")
         .option("--raw", "Use the isolated files origin, regardless of extension")
         .option("--viewer", "Use the dashboard file viewer, regardless of extension")
-        .action((filePath, opts) => {
+        .option("--no-verify", "Mint without checking the running dashboard's repository identity")
+        .action(async (filePath, opts) => {
         if (opts.raw && opts.viewer) {
             emit.error({
                 code: "conflicting_url_modes",
@@ -99,9 +145,16 @@ export function registerFilesCommand(program, emit, context) {
                 port,
                 mode: opts.raw ? "raw" : opts.viewer ? "viewer" : "auto",
             });
+            if (opts.verify !== false)
+                await verifyDashboardRoot(coordRoot, port);
             emit.text(`${result.url}\n`);
         }
         catch (error) {
+            if (error instanceof DashboardRootError) {
+                emit.error({ code: error.code, message: error.message, hint: error.hint });
+                emit.setExitCode(1);
+                return;
+            }
             emit.error({
                 code: "invalid_local_file",
                 message: error instanceof Error ? error.message : "invalid local file path",

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

@@ -1 +1 @@
-{"version":3,"file":"governor.d.ts","sourceRoot":"","sources":["../../src/commands/governor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA6EnD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA6HjF"}
+{"version":3,"file":"governor.d.ts","sourceRoot":"","sources":["../../src/commands/governor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA8EnD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA6HjF"}

package/dist/commands/governor.js

@@ -302,6 +302,7 @@ function addServiceOptions(command) {
         .option("--error-backoff-max-ms <n>", "Maximum service-error backoff (default 300000)")
         .option("--adapter <name>", "Fallback adapter for agent calls without a specialist")
         .option("--cwd <dir>", "Working directory for child agents")
+        .option("--observe-pressure", "Record observer-only local pressure before each workflow's first real child dispatch")
         .option("--subscription-only", "Require stored adapter-login billing")
         .option("--allow-api-billing", "Permit API-key override billing")
         .option("--policy <file>", "Host policy JSON/JSONC")
@@ -431,6 +432,9 @@ function registerRunCommand(governor, mode, registry, emit) {
                     spawners: registry.spawners(),
                     defaultAdapter: opts.adapter,
                     cwd: opts.cwd,
+                    diagnosticAdmission: opts.observePressure
+                        ? { schema_version: 1, mode: "shadow" }
+                        : undefined,
                     subscriptionOnly: opts.subscriptionOnly === true ? true : workflowSubscriptionOnly(coordRoot),
                     allowApiBilling: opts.allowApiBilling,
                     ...adapterProofInputs(registry.list().map((adapter) => adapter.profile), { versionProbe: probeBinaryVersion }),

package/dist/commands/ledger-v3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ledger-v3.d.ts","sourceRoot":"","sources":["../../src/commands/ledger-v3.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAmC1E,2DAA2D;AAC3D,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAsWN"}
+{"version":3,"file":"ledger-v3.d.ts","sourceRoot":"","sources":["../../src/commands/ledger-v3.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAsC1E,2DAA2D;AAC3D,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAiaN"}

package/dist/commands/ledger-v3.js

@@ -2,8 +2,8 @@ import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { inventoryLegacyV1Segments, streamLegacyV1Rows, verifyLegacyV1HardFence, writeLegacyV1Canary, } from "../core/events/legacy-storage/index.js";
-import { initializeEventLedgerV3, readEventV3ControlState, recoverInvalidEventLedgerV3, sha256V3, } from "../core/events/v3/index.js";
+import { compressSealedLegacyV1Segments, inventoryLegacyV1Segments, streamLegacyV1Rows, verifyLegacyV1HardFence, writeLegacyV1Canary, } from "../core/events/legacy-storage/index.js";
+import { cleanEventV3Archives, initializeEventLedgerV3, inventoryEventV3Archives, readEventV3ControlState, recoverInvalidEventLedgerV3, sha256V3, } from "../core/events/v3/index.js";
 import { authorizeEventV3SupportReplacement, inventoryEventV3Support, planEventV3SupportReplacement, planEventV3SupportTransaction, readEventV3SupportPackManifest, readEventV3SupportTransaction, streamEventV3SupportPackRecords, unpackEventV3SupportPack, verifyEventV3SupportTransactionShadow, writeEventV3SupportTransactionShadow, } from "../core/events/v3/support-storage/index.js";
 /** Inspect or initialize the universal V3 event ledger. */
 export function registerLedgerV3Command(program, emit, context) {
@@ -21,6 +21,38 @@ export function registerLedgerV3Command(program, emit, context) {
             emitFailure(emit, "ledger_v3_status_failed", error);
         }
     });
+    const archives = command
+        .command("archives")
+        .description("Inventory and enforce bounded retention for complete closed V3 epochs");
+    archives
+        .command("list")
+        .description("Show closed epochs, retention classifications, and planned actions")
+        .option("--root <path>", "Explicit coordination root")
+        .action((options) => {
+        try {
+            const rows = inventoryEventV3Archives(resolve(options.root ?? coordRoot(context)));
+            emit.data({ rows, meta: summarizeArchiveRows(rows) });
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v3_archive_inventory_failed", error);
+        }
+    });
+    archives
+        .command("clean")
+        .description("Preview closed-epoch deletion; pass --yes to execute the exact current plan")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--yes", "Delete only epochs still classified expired or over-budget")
+        .action((options) => {
+        try {
+            const rows = cleanEventV3Archives(resolve(options.root ?? coordRoot(context)), {
+                yes: options.yes,
+            });
+            emit.data({ rows, meta: summarizeArchiveRows(rows) });
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v3_archive_cleanup_failed", error);
+        }
+    });
     command
         .command("initialize")
         .description("Create V3 control state, or archive and replace the current V3 epoch")
@@ -279,6 +311,29 @@ export function registerLedgerV3Command(program, emit, context) {
             emitFailure(emit, "ledger_v1_inventory_failed", error);
         }
     });
+    command
+        .command("legacy-compress")
+        .description("Preview verified gzip replacement of sealed non-terminal V1 shards")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--yes", "Replace only unchanged shards after exact logical-row parity")
+        .action(async (options) => {
+        try {
+            const rows = await compressSealedLegacyV1Segments(resolve(options.root ?? coordRoot(context)), { yes: options.yes });
+            emit.data({
+                rows,
+                meta: {
+                    total: rows.length,
+                    would_compress: rows.filter((row) => row.action === "would-compress").length,
+                    compressed: rows.filter((row) => row.action === "compressed").length,
+                    bytes_before: rows.reduce((sum, row) => sum + row.bytes_before, 0),
+                    bytes_after: rows.reduce((sum, row) => sum + (row.bytes_after ?? row.bytes_before), 0),
+                },
+            });
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v1_compression_failed", error);
+        }
+    });
     command
         .command("verify-legacy")
         .description("Stream and validate one loose or manifest-bound gzip legacy segment")
@@ -431,6 +486,20 @@ function sameSortedStrings(left, right) {
     return (leftSorted.length === rightSorted.length &&
         leftSorted.every((value, index) => value === rightSorted[index]));
 }
+function summarizeArchiveRows(rows) {
+    const classifications = {};
+    for (const row of rows) {
+        classifications[row.classification] = (classifications[row.classification] ?? 0) + 1;
+    }
+    return {
+        total: rows.length,
+        bytes: rows.reduce((sum, row) => sum + (row.bytes ?? 0), 0),
+        classifications,
+        would_delete: rows.filter((row) => row.action === "would-delete").length,
+        would_delete_bytes: rows.reduce((sum, row) => sum + (row.action === "would-delete" ? (row.bytes ?? 0) : 0), 0),
+        deleted: rows.filter((row) => row.action === "deleted").length,
+    };
+}
 function emitFailure(emit, code, error) {
     emit.error({ code, message: error instanceof Error ? error.message : String(error) });
     throw error;

package/dist/commands/qa-run.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+export declare function registerQaRunCommand(program: Command, emit: EmitContext): void;
+//# sourceMappingURL=qa-run.d.ts.map

package/dist/commands/qa-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qa-run.d.ts","sourceRoot":"","sources":["../../src/commands/qa-run.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAiBnD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA+J9E"}

package/dist/commands/qa-run.js

@@ -0,0 +1,141 @@
+// `qa-run <target>`: run the whole page-QA matrix (planner, deterministic
+// gates, interactions, critique, snapshot) in one command. The agent's loop
+// collapses to: build the job, run this, read page-qa-result.json.
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { QA_RUN_RESULT_FILENAME, runQaMatrix } from "../lib/browser/qa-run.js";
+import { QA_RUN_JOB_SCHEMA_VERSION, validateQaRunJob, } from "../lib/browser/qa-run-contracts.js";
+export function registerQaRunCommand(program, emit) {
+    program
+        .command("qa-run <target>")
+        .description("Run the whole page-QA matrix in one command: QA planner, deterministic " +
+        "gates per viewport/theme/state through a bounded process pool, serial " +
+        "interaction assertions, manifest-required vision critique, and the QA " +
+        "snapshot. Writes page-qa-result.json with a fail-closed verdict.")
+        .option("--job <file>", "QA job document (JSON). Validated before any browser starts — secret-bearing " +
+        "fields are refused, and the job may widen but never narrow the planner's coverage. " +
+        "Absent: a minimal implicit job for <target> is used.")
+        .option("--mode <mode>", "signoff persists a QA snapshot on a passing run; review never does.", "signoff")
+        .option("--concurrency <n>", "Concurrent deterministic captures (1-8; default 2). Interactions and critique " +
+        "always run serially.")
+        .option("--allow-metered", "Permit the critique provider's metered-API fallback. Default: subscription-backed " +
+        "headless harnesses only — exhaustion becomes an incomplete blocker, never a metered call.")
+        .option("--out-dir <dir>", "Artifact + result directory (default: .qa-run/<timestamp> under the current directory).")
+        .option("--json", "Print the full QaRunResult JSON to stdout.")
+        .addHelpText("after", "\nExit codes: 0 verdict passed · 1 usage or job-validation error · " +
+        "2 verdict failed · 4 verdict incomplete.")
+        .action(async (target, opts, command) => {
+        if (opts.mode !== "signoff" && opts.mode !== "review") {
+            emit.error({
+                code: "qa_run_invalid_mode",
+                message: '--mode must be "signoff" or "review"',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        const modeExplicit = command.getOptionValueSource("mode") === "cli";
+        let jobDocument;
+        if (opts.job) {
+            let rawText;
+            try {
+                rawText = readFileSync(opts.job, "utf8");
+            }
+            catch (err) {
+                emit.error({
+                    code: "qa_run_job_unreadable",
+                    message: `cannot read --job file ${opts.job}: ${err instanceof Error ? err.message : String(err)}`,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(rawText);
+            }
+            catch (err) {
+                emit.error({
+                    code: "qa_run_job_invalid_json",
+                    message: `--job file ${opts.job} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                const raw = parsed;
+                // The CLI target argument is authoritative; a job file may omit
+                // target and mode. An explicit --mode overrides the job's mode.
+                jobDocument = {
+                    ...raw,
+                    target,
+                    ...(raw.mode === undefined || modeExplicit ? { mode: opts.mode } : {}),
+                };
+            }
+            else {
+                jobDocument = parsed;
+            }
+        }
+        else {
+            jobDocument = { schema_version: QA_RUN_JOB_SCHEMA_VERSION, target, mode: opts.mode };
+        }
+        // All validation errors print at once, before any browser starts.
+        const validation = validateQaRunJob(jobDocument);
+        if (!validation.ok) {
+            for (const message of validation.errors)
+                emit.log(`job: ${message}`, "error");
+            emit.error({
+                code: "qa_run_invalid_job",
+                message: `job validation failed with ${validation.errors.length} error${validation.errors.length === 1 ? "" : "s"}`,
+            });
+            process.exitCode = 1;
+            return;
+        }
+        const policy = { ...validation.job.policy };
+        if (opts.concurrency !== undefined) {
+            const n = Number.parseInt(opts.concurrency, 10);
+            if (!Number.isInteger(n) || n < 1 || n > 8) {
+                emit.error({
+                    code: "qa_run_invalid_concurrency",
+                    message: "--concurrency must be an integer between 1 and 8",
+                });
+                process.exitCode = 1;
+                return;
+            }
+            policy.command_concurrency = n;
+        }
+        if (opts.allowMetered)
+            policy.allow_metered_critique = true;
+        const job = { ...validation.job, policy };
+        const outDir = resolve(opts.outDir ?? join(".qa-run", new Date().toISOString().replace(/[:.]/g, "-")));
+        const cliScript = process.argv[1];
+        if (!cliScript) {
+            emit.error({
+                code: "qa_run_no_cli_script",
+                message: "cannot resolve the host CLI script path for child browse invocations",
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // Children run the same host CLI, so they inherit the host's browse
+        // wiring (critique provider, cookie jar, profiles) unchanged.
+        const browseArgv = [process.execPath, cliScript, "browse"];
+        const result = await runQaMatrix({
+            job,
+            outDir,
+            browseArgv,
+            onLog: (message) => emit.log(message, "info"),
+        });
+        if (opts.json)
+            emit.data(result);
+        const resultPath = join(outDir, QA_RUN_RESULT_FILENAME);
+        for (const blocker of result.blockers) {
+            emit.log(`blocker [${blocker.stage}${blocker.context_id ? ` ${blocker.context_id}` : ""}]: ${blocker.reason}`, "warn");
+        }
+        emit.log(`verdict: ${result.verdict} — ${result.contexts.length} context${result.contexts.length === 1 ? "" : "s"}, ` +
+            `${result.commands.length} command${result.commands.length === 1 ? "" : "s"}, ` +
+            `${result.blockers.length} blocker${result.blockers.length === 1 ? "" : "s"}; result: ${resultPath}`, result.verdict === "passed" ? "info" : "warn");
+        if (result.verdict === "failed")
+            process.exitCode = 2;
+        else if (result.verdict === "incomplete")
+            process.exitCode = 4;
+    });
+}

package/dist/commands/resources.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+export declare function registerResourcesCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=resources.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/commands/resources.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG1E,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAgBN"}

package/dist/commands/resources.js

@@ -0,0 +1,29 @@
+import { resolve } from "node:path";
+import { sampleResources } from "../core/resources/index.js";
+export function registerResourcesCommand(program, emit, context) {
+    const resources = program
+        .command("resources")
+        .description("Observe local CPU and memory pressure by agent and process tree");
+    resources
+        .command("snapshot")
+        .description("Capture one machine and process-resource snapshot")
+        .option("--root <path>", "Explicit coordination root")
+        .action((options) => {
+        try {
+            emit.data(sampleResources(resolve(options.root ?? coordRoot(context))).snapshot);
+        }
+        catch (error) {
+            fail(emit, "resource_snapshot_failed", error);
+        }
+    });
+}
+function coordRoot(context) {
+    return context?.resolveCoordRoot?.() ?? context?.repoRoot ?? process.cwd();
+}
+function fail(emit, code, error) {
+    emit.error({
+        code,
+        message: error instanceof Error ? error.message : String(error),
+    });
+    emit.setExitCode(1);
+}

package/dist/commands/supervisor.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+export declare function registerSupervisorCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=supervisor.d.ts.map