harnery 0.36.0 → 0.38.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/fetch.js

@@ -63,6 +63,7 @@ async function runFetch(url, opts, emit, context) {
             redirect: opts.redirect,
             signal: ac.signal,
             extraHeaders: context?.extraHeaders,
+            extraCookies: context?.extraCookies,
             responseType: "bytes",
         });
     }

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-record.d.ts

@@ -0,0 +1,144 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+import { type QaRunContext, type QaRunResult } from "../lib/browser/qa-run-contracts.js";
+export declare const QA_RECORD_EVIDENCE_SCHEMA_VERSION: 1;
+/** The evidence document is copied into the run directory beside the result:
+ * the run identity's job_digest is taken over it, so without the copy nothing
+ * downstream could re-derive the digest. qa-run writes `job.json` for the same
+ * reason; the manual name keeps the two from being confused. */
+export declare const QA_RECORD_EVIDENCE_FILENAME = "manual-evidence.json";
+/** argv marker for a hand-performed check. The contract types argv as a string
+ * array and consumers print it, so an empty array would render as a command
+ * that ran with no arguments. A single explicit marker reads as "no process
+ * executed" and can never be mistaken for a re-runnable command line. */
+export declare const QA_RECORD_MANUAL_ARGV: readonly ["<manual>"];
+export type QaManualOutcome = "passed" | "failed" | "unknown";
+/** One check a human or agent performed by hand. */
+export interface QaManualCheck {
+    /** Context the check was performed in; matches a `contexts[].id` when the
+     * document declares contexts. */
+    context_id: string;
+    /** Stable check identifier. Prefix with `manual:` by convention. */
+    check_id: string;
+    outcome: QaManualOutcome;
+    /** What the recorder observed. Carried into the result's `failures` field. */
+    notes?: string[];
+    /** Files that back the observation. Every path must exist on disk. */
+    artifacts?: {
+        png?: string;
+        html?: string;
+        json?: string;
+    };
+    /** Time the check took, when the recorder measured it. */
+    wall_time_ms?: number;
+}
+export interface QaManualEvidence {
+    schema_version: typeof QA_RECORD_EVIDENCE_SCHEMA_VERSION;
+    /** Who performed the checks (agent name or operator identity). */
+    recorded_by: string;
+    /** Why the runner could not be used. Required: a hand record with no stated
+     * reason is an assertion, not evidence. */
+    reason: string;
+    checks: QaManualCheck[];
+    /** Declared contexts. Absent: derived from the checks' context IDs. */
+    contexts?: QaRunContext[];
+}
+export type QaManualEvidenceValidation = {
+    ok: true;
+    evidence: QaManualEvidence;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** Artifact paths are resolved against the directory holding the evidence
+ * document, not the working directory: an evidence file names the captures
+ * sitting beside it, and that stays true wherever it is recorded from. */
+export declare function resolveArtifactPath(baseDir: string, path: string): string;
+/**
+ * Validate an untrusted evidence document. Every structural problem, every
+ * missing artifact, and every secret-bearing field is reported at once, before
+ * anything is written: a caller fixes the document in one pass, and a
+ * half-valid record never reaches disk.
+ */
+export declare function validateManualEvidence(value: unknown, options: {
+    baseDir: string;
+}): QaManualEvidenceValidation;
+/** Contexts the result reports: the document's own declarations when it has
+ * them, otherwise one derived per distinct check context ID. Derivation reads
+ * the runner's `<viewport>-<theme>-<state>` convention when the ID follows it
+ * and records `unknown` rather than guessing when it does not. */
+export declare function deriveContexts(evidence: QaManualEvidence): QaRunContext[];
+/** One git probe for the identity block, matching qa-run. Failure is not an
+ * error: work outside any repository legitimately records "unknown". */
+export declare function probeRevision(): {
+    tested_revision?: string;
+    worktree_dirty?: boolean;
+} | undefined;
+export interface BuildManualResultInput {
+    evidence: QaManualEvidence;
+    target: string;
+    mode: "signoff" | "review";
+    /** Parent directory; the result lands in `<outParent>/run-<run_id>/`. */
+    outParent: string;
+    /** Pre-minted run ID (tests); default crypto.randomUUID. */
+    runId?: string;
+    /** Directory the artifact paths resolve against (the evidence file's dir). */
+    baseDir: string;
+    revisionProbe?: {
+        tested_revision?: string;
+        worktree_dirty?: boolean;
+    };
+    /** Completion instant (tests); default now. */
+    completedAt?: Date;
+}
+/**
+ * Build the QaRunResult for a validated evidence document. Pure apart from the
+ * host sample and the clock, so the shape is testable without touching disk.
+ */
+export declare function buildManualResult(input: BuildManualResultInput): QaRunResult;
+export interface QaRecordWritePaths {
+    runDir: string;
+    resultPath: string;
+    evidencePath: string;
+    statusPath: string;
+    latestPath: string;
+}
+/**
+ * Write the run directory exactly the way the runner does: the result, the
+ * source document, a terminal status document, and the parent's latest.json
+ * pointer written temp-then-rename so a reader never sees a torn write.
+ */
+export declare function writeManualRun(result: QaRunResult, evidence: QaManualEvidence): QaRecordWritePaths;
+export interface QaRecordOutcome {
+    /** 1 usage or validation error · 2 verdict failed · 4 verdict incomplete.
+     * Never 0: a hand-recorded result cannot report a pass. */
+    exit: 1 | 2 | 4;
+    result?: QaRunResult;
+    paths?: QaRecordWritePaths;
+    error?: string;
+    /** Individual validation errors, all of them, when the document was bad. */
+    evidenceErrors?: string[];
+}
+export interface QaRecordInput {
+    target: string;
+    evidencePath: string;
+    mode?: string;
+    outDir?: string;
+    /** Lazy default so invalid evidence does not create an empty artifact workspace. */
+    defaultOutDir?: () => string;
+    runId?: string;
+    completedAt?: Date;
+    /** Injectable for tests; default: the real git probe. */
+    revisionProbe?: () => {
+        tested_revision?: string;
+        worktree_dirty?: boolean;
+    } | undefined;
+}
+/**
+ * Pure core of qa-record: read the evidence document, validate it completely,
+ * build the result, and write the run directory. The commander action is a
+ * thin wrapper over this so the whole path tests without a CLI harness.
+ */
+export declare function recordManualQa(input: QaRecordInput): QaRecordOutcome;
+export declare function registerQaRecordCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=qa-record.d.ts.map

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

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

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

@@ -0,0 +1,8 @@
+import { type Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+/** Machine-wide admission resource that qa-run queues on by default. */
+export declare const QA_ADMISSION_RESOURCE = "browser-qa";
+/** Default concurrent browser-QA runs per machine. */
+export declare const QA_ADMISSION_DEFAULT_CAPACITY = 2;
+export declare function registerQaRunCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): 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":"AAQA,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AA0B1E,wEAAwE;AACxE,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD,sDAAsD;AACtD,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAmB/C,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAwbN"}