harnery 0.35.0 → 0.37.0

package/dist/commands/outline.d.ts

@@ -1,4 +1,4 @@
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.js";
-export declare function registerOutlineCommand(program: Command, emit: EmitContext): void;
+export declare function registerOutlineCommand(program: Command, emit: EmitContext, binName?: string): void;
 //# sourceMappingURL=outline.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../src/commands/outline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAqDnD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAwBhF"}
+{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../src/commands/outline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAqDnD,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,SAAmB,GACzB,IAAI,CAwBN"}

package/dist/commands/outline.js

@@ -16,10 +16,10 @@ async function loadTypeScript() {
         throw new Error("outlining TS/JS files needs the `typescript` package; install it (npm i -D typescript) or use outline on PHP/Python files");
     }
 }
-export function registerOutlineCommand(program, emit) {
+export function registerOutlineCommand(program, emit, binName = resolveBinName()) {
     program
         .command("outline <file>")
-        .description(`Print the structural skeleton of a code file (imports + top-level decls + line numbers). Supports TS/JS/TSX/JSX (AST), PHP/Python (regex). Use \`${resolveBinName()} toc\` for markdown.`)
+        .description(`Print the structural skeleton of a code file (imports + top-level decls + line numbers). Supports TS/JS/TSX/JSX (AST), PHP/Python (regex). Use \`${binName} toc\` for markdown.`)
         .option("--json", "Structured JSON envelope")
         .option("--exports-only", "Only show exported symbols")
         .option("--no-imports", "Skip the imports summary block")

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/read.d.ts

@@ -3,5 +3,5 @@ import type { EmitContext } from "../commander.js";
 /**
  * `harn read`: extract clean readable markdown from HTML.
  */
-export declare function registerReadCommand(program: Command, emitParam: EmitContext): void;
+export declare function registerReadCommand(program: Command, emitParam: EmitContext, binName?: string): void;
 //# sourceMappingURL=read.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/commands/read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAQnD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CAwBlF"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/commands/read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAQnD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,SAAmB,GACzB,IAAI,CAwBN"}

package/dist/commands/read.js

@@ -7,11 +7,11 @@ let emit;
 /**
  * `harn read`: extract clean readable markdown from HTML.
  */
-export function registerReadCommand(program, emitParam) {
+export function registerReadCommand(program, emitParam, binName = resolveBinName()) {
     emit = emitParam;
     program
         .command("read [html-file]")
-        .description(`Extract clean readable markdown from HTML. Reads from file or stdin (use '-'). Pair with \`${resolveBinName()} fetch\` or \`${resolveBinName()} browse\` for scrape-to-markdown.`)
+        .description(`Extract clean readable markdown from HTML. Reads from file or stdin (use '-'). Pair with \`${binName} fetch\` or \`${binName} browse\` for scrape-to-markdown.`)
         .option("-o, --output <file>", "Write markdown to file instead of stdout")
         .option("--url <url>", "Base URL: used to resolve relative links")
         .option("--selector <css>", "Use this CSS selector instead of Readability (fallback when extraction misses content)")

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/semantic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/commands/semantic.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAc1E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAiIN"}
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/commands/semantic.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiB1E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA8LN"}

package/dist/commands/semantic.js

@@ -1,5 +1,6 @@
+import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
-import { createSemanticAdapters, discoverSemanticReaders, inspectSemanticDocument, readSemanticManifest, readSemanticServiceStatus, requestSemanticServiceStop, runSemanticOnce, runSemanticServiceDaemon, semanticPaths, spawnSemanticService, } from "../core/semantic/index.js";
+import { createSemanticAdapters, discoverSemanticReaders, inspectSemanticDocument, prepareSemanticReviewStudy, readSemanticManifest, readSemanticServiceStatus, readSemanticSoakReport, requestSemanticServiceStop, runSemanticOnce, runSemanticServiceDaemon, semanticPaths, spawnSemanticService, storeSemanticReviewSubmission, } from "../core/semantic/index.js";
 export function registerSemanticCommand(program, emit, context) {
     const semantic = program
         .command("semantic")
@@ -40,7 +41,7 @@ export function registerSemanticCommand(program, emit, context) {
     });
     service
         .command("status")
-        .description("Show singleton liveness, pass metrics, and pending work")
+        .description("Show reader liveness, rolling calls, token usage, routes, and pending work")
         .option("--root <path>", "Explicit coordination root")
         .action((options) => {
         try {
@@ -101,6 +102,57 @@ export function registerSemanticCommand(program, emit, context) {
             emitFailure(emit, "semantic_inspect_failed", error);
         }
     });
+    semantic
+        .command("soak")
+        .description("Summarize recent reader outcomes, controlled cues, stability, and token usage")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--minutes <count>", "Lookback window in whole minutes", integer)
+        .action((options) => {
+        try {
+            emit.data(readSemanticSoakReport(resolve(options.root ?? coordRoot(context)), {
+                ...(options.minutes !== undefined ? { minutes: options.minutes } : {}),
+            }));
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_soak_failed", error);
+        }
+    });
+    const review = semantic
+        .command("review")
+        .description("Prepare and record a local human review of accepted semantic readings");
+    review
+        .command("prepare")
+        .description("Capture current accepted readings and return the next bounded review set")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--limit <count>", "Maximum candidates in this review set", integer)
+        .action((options) => {
+        try {
+            emit.data(prepareSemanticReviewStudy(resolve(options.root ?? coordRoot(context)), {
+                ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            }));
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_review_prepare_failed", error);
+        }
+    });
+    review
+        .command("submit")
+        .description("Validate one frozen review set and store its controlled-label receipt")
+        .requiredOption("--file <path>", "JSON submission file")
+        .option("--root <path>", "Explicit coordination root")
+        .action((options) => {
+        try {
+            const file = resolve(options.file);
+            const size = statSync(file).size;
+            if (size <= 0 || size > 128 * 1024) {
+                throw new Error("semantic review submission has invalid size");
+            }
+            emit.data(storeSemanticReviewSubmission(resolve(options.root ?? coordRoot(context)), JSON.parse(readFileSync(file, "utf8"))));
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_review_submit_failed", error);
+        }
+    });
     semantic
         .command("doctor")
         .description("Inspect semantic reader availability without making a model request")

package/dist/commands/storage.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/commands/storage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAwD1E,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA+IN"}

package/dist/commands/storage.js

@@ -0,0 +1,238 @@
+import { resolve } from "node:path";
+import { resolveCoordRoot as resolveCanonicalCoordRoot } from "../core/agents/coord-client.js";
+import { createStorageCatalog } from "../core/storage/catalog.js";
+import { storageHealth } from "../core/storage/health.js";
+import { filterStorageInventory, inventoryStorage } from "../core/storage/inventory.js";
+import { DEFAULT_MAINTENANCE_BUDGET, executeStorageMaintenance, HARNERY_MAINTENANCE_PRESSURE_SCHEMA, HarneryMaintenanceError, listMaintenanceTransactions, planStorageMaintenance, readMaintenanceTransaction, } from "../core/storage/maintenance.js";
+import { createStructuredLogMaintenanceProviders } from "../core/storage/maintenance-providers.js";
+const STORAGE_CLASSES = new Set([
+    "canonical-authority",
+    "recovery-state",
+    "operational-log",
+    "debug-log",
+    "durable-object-history",
+    "repairable-cache",
+    "managed-artifact",
+]);
+export function registerStorageCommand(program, emit, context) {
+    const storage = program
+        .command("storage")
+        .description("Inspect registered Harnery storage without reading file bodies");
+    storage
+        .command("inventory")
+        .description("Inventory .harnery and explicitly registered external storage roots")
+        .option("--family <id>", "Show one registered storage family")
+        .option("--class <class>", "Show one registered storage class")
+        .option("--json", "Emit the stable versioned inventory schema")
+        .action(async (options) => {
+        await run(emit, async () => {
+            const catalog = catalogFor(context);
+            if (options.family && !catalog.get(options.family)) {
+                throw new StorageCommandError("unknown_storage_family", `unknown storage family: ${options.family}`);
+            }
+            const storageClass = parseStorageClass(options.class);
+            const report = filterStorageInventory(await inventoryStorage(catalog), {
+                ...(options.family ? { family_id: options.family } : {}),
+                ...(storageClass ? { storage_class: storageClass } : {}),
+            });
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data(report);
+            }
+            else {
+                emit.rows(inventoryRows(report));
+            }
+        });
+    });
+    storage
+        .command("health")
+        .description("Report reason-coded health for every registered storage family")
+        .option("--json", "Emit the stable versioned health schema")
+        .action(async (options) => {
+        await run(emit, async () => {
+            const report = storageHealth(await inventoryStorage(catalogFor(context)));
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data(report);
+            }
+            else {
+                emit.text(`storage health: ${report.status}\n`);
+                emit.rows(report.families.map((family) => ({
+                    family_id: family.family_id,
+                    status: family.status,
+                    reasons: family.reason_codes.join(",") || "none",
+                    maintenance: family.maintenance.state,
+                    max_bytes: family.log_storage?.effective_policy?.max_bytes ?? "unavailable",
+                    max_age_days: family.log_storage?.effective_policy?.max_age_days ?? "unavailable",
+                    managed_bytes: family.log_storage?.usage.managed_bytes ?? "not-a-log",
+                    unmanaged_bytes: family.log_storage?.usage.unmanaged_bytes ?? "not-a-log",
+                    pressure: family.log_storage?.pressure.state ?? "not-a-log",
+                    enforcement: family.log_storage?.retention.enforcement ?? "not-a-log",
+                })));
+            }
+        });
+    });
+    storage
+        .command("maintain")
+        .description("Plan bounded maintenance, or execute one exact transaction")
+        .option("--family <id>", "Limit a new plan to one registered family")
+        .option("--budget <duration>", "Wall-time budget such as 500ms, 5s, or 1m")
+        .option("--dry-run", "Plan without mutating source storage", true)
+        .option("--transaction <id>", "Execute one previously planned exact transaction")
+        .option("--yes", "Confirm execution of the exact transaction")
+        .option("--authorize-structured-log-deletion", "Authorize deletion only for exact manifest-backed structured-log actions")
+        .option("--json", "Emit the versioned transaction schema")
+        .action(async (options) => {
+        await run(emit, async () => {
+            const catalog = catalogFor(context);
+            const providers = [
+                ...createStructuredLogMaintenanceProviders(catalog),
+                ...(context?.storageMaintenanceProviders ?? []),
+            ];
+            const transaction = options.transaction
+                ? await executeStorageMaintenance(catalog, providers, options.transaction, {
+                    yes: options.yes === true,
+                    authorize_structured_log_deletion: options.authorizeStructuredLogDeletion === true,
+                })
+                : await planStorageMaintenance(catalog, providers, await pressureFor(catalog), {
+                    ...(options.family ? { family_id: options.family } : {}),
+                    budget: {
+                        ...DEFAULT_MAINTENANCE_BUDGET,
+                        max_duration_ms: parseDuration(options.budget),
+                    },
+                    persist: true,
+                });
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data(transaction);
+            }
+            else {
+                emit.rows([
+                    {
+                        transaction_id: transaction.transaction_id,
+                        state: transaction.state,
+                        dry_run: transaction.dry_run,
+                        actions: transaction.actions.length,
+                        files: transaction.actions.reduce((sum, action) => sum + action.files, 0),
+                        bytes: transaction.actions.reduce((sum, action) => sum + action.bytes, 0),
+                        reasons: transaction.reason_codes.join(",") || "none",
+                    },
+                ]);
+            }
+        });
+    });
+    storage
+        .command("status")
+        .description("Inspect maintenance transactions without changing storage")
+        .option("--transaction <id>", "Show one exact transaction")
+        .option("--json", "Emit versioned transaction records")
+        .action(async (options) => {
+        await run(emit, async () => {
+            const catalog = catalogFor(context);
+            const transactions = options.transaction
+                ? [readMaintenanceTransaction(catalog.context.coord_root, options.transaction)]
+                : listMaintenanceTransactions(catalog.context.coord_root);
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data(transactions);
+            }
+            else {
+                emit.rows(transactions.map((transaction) => ({
+                    transaction_id: transaction.transaction_id,
+                    state: transaction.state,
+                    created_at: transaction.created_at,
+                    actions: transaction.actions.length,
+                    reasons: transaction.reason_codes.join(",") || "none",
+                })));
+            }
+        });
+    });
+}
+function catalogFor(context) {
+    const coordRoot = resolve(context?.resolveCoordRoot?.() ??
+        context?.repoRoot ??
+        process.env.HARNERY_COORD_ROOT ??
+        resolveCanonicalCoordRoot() ??
+        process.cwd());
+    return createStorageCatalog({ coord_root: coordRoot, project_root: resolve(context?.repoRoot ?? coordRoot) }, context?.storage);
+}
+function parseStorageClass(value) {
+    if (value === undefined)
+        return undefined;
+    if (!STORAGE_CLASSES.has(value)) {
+        throw new StorageCommandError("unknown_storage_class", `unknown storage class: ${value}`);
+    }
+    return value;
+}
+async function pressureFor(catalog) {
+    const inventory = await inventoryStorage(catalog);
+    return {
+        schema: HARNERY_MAINTENANCE_PRESSURE_SCHEMA,
+        captured_at: inventory.captured_at,
+        families: inventory.families.map((family) => ({
+            family_id: family.family_id,
+            logical_bytes: family.totals.logical_bytes.state === "observed" ? family.totals.logical_bytes.value : 0,
+            regular_files: family.totals.regular_files.state === "observed" ? family.totals.regular_files.value : 0,
+            needs_maintenance: family.maintenance.state === "eligible",
+            observed_at: inventory.captured_at,
+        })),
+    };
+}
+function parseDuration(value) {
+    if (value === undefined)
+        return DEFAULT_MAINTENANCE_BUDGET.max_duration_ms;
+    const match = /^(\d+)(ms|s|m)$/.exec(value);
+    if (!match)
+        throw new StorageCommandError("invalid_maintenance_budget", `invalid duration: ${value}`);
+    const amount = Number(match[1]);
+    const multiplier = match[2] === "ms" ? 1 : match[2] === "s" ? 1_000 : 60_000;
+    const result = amount * multiplier;
+    if (!Number.isSafeInteger(result) || result <= 0 || result > 60 * 60 * 1_000) {
+        throw new StorageCommandError("invalid_maintenance_budget", `invalid duration: ${value}`);
+    }
+    return result;
+}
+function inventoryRows(report) {
+    return report.families.map((family) => ({
+        family_id: family.family_id,
+        class: family.storage_class,
+        state: family.state,
+        regular_files: measurementValue(family.totals.regular_files),
+        logical_bytes: measurementValue(family.totals.logical_bytes),
+        allocated_bytes: measurementValue(family.totals.allocated_bytes),
+        maintenance: family.maintenance.state,
+        max_bytes: family.log_storage?.effective_policy?.max_bytes ?? "unavailable",
+        max_age_days: family.log_storage?.effective_policy?.max_age_days ?? "unavailable",
+        managed_bytes: family.log_storage?.usage.managed_bytes ?? "not-a-log",
+        unmanaged_bytes: family.log_storage?.usage.unmanaged_bytes ?? "not-a-log",
+        pressure: family.log_storage?.pressure.state ?? "not-a-log",
+        enforcement: family.log_storage?.retention.enforcement ?? "not-a-log",
+        reasons: family.reason_codes.join(",") || "none",
+    }));
+}
+function measurementValue(measurement) {
+    return measurement.state === "observed"
+        ? measurement.value
+        : `unavailable:${measurement.reason_code}`;
+}
+class StorageCommandError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+async function run(emit, action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        emit.error({
+            code: error instanceof StorageCommandError || error instanceof HarneryMaintenanceError
+                ? error.code
+                : "storage_inspection_failed",
+            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

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

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