harnery 0.35.0 → 0.37.0

package/src/commands/logs.ts

@@ -0,0 +1,224 @@
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { resolveCoordRoot as resolveCanonicalCoordRoot } from "../core/agents/coord-client.ts";
+import { createStorageCatalog } from "../core/storage/catalog.ts";
+import {
+  HARNERY_STRUCTURED_LOG_PROVIDER_ID,
+  type HarneryLogLevel,
+  type HarneryRegisteredStorageFamily,
+} from "../core/storage/contract.ts";
+import { inspectStructuredLogRetention } from "../core/storage/log-retention.ts";
+import { queryLogs, rotationFollowCursor } from "../core/storage/query.ts";
+import { familyLogDirectory } from "../core/storage/segments.ts";
+
+interface QueryOptions {
+  family?: string[];
+  level?: HarneryLogLevel;
+  event?: string;
+  since?: string;
+  until?: string;
+  maxRecords: number;
+  maxBytes: number;
+  json?: boolean;
+}
+
+export function registerLogsCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  const logs = program.command("logs").description("List and query bounded Harnery log families");
+  logs
+    .command("list")
+    .option("--json", "Emit structured output")
+    .action((options: { json?: boolean }) =>
+      run(emit, async () => {
+        const catalog = catalogFor(context);
+        const capturedAt = new Date();
+        const rows = logFamilies(catalog.families).map((family) =>
+          logFamilyRow(family, capturedAt),
+        );
+        if (options.json) {
+          emit.config({ format: "json" });
+          emit.data({
+            schema: "harnery.logs-list/v2",
+            captured_at: capturedAt.toISOString(),
+            diagnostics: catalog.log_storage_diagnostics,
+            dormant_families: catalog.dormant_log_storage_families,
+            families: rows,
+          });
+        } else emit.rows(rows.map(logFamilyTableRow));
+      }),
+    );
+
+  const configureQuery = (command: Command) =>
+    command
+      .option("--family <id...>", "Restrict to named families")
+      .option("--level <level>", "Minimum severity")
+      .option("--event <event>", "Exact event name")
+      .option("--since <timestamp>", "Earliest timestamp")
+      .option("--until <timestamp>", "Latest timestamp")
+      .option("--max-records <n>", "Global record scan budget", integer, 10_000)
+      .option("--max-bytes <n>", "Global byte scan budget", integer, 10 * 1024 * 1024)
+      .option("--json", "Emit structured output");
+
+  configureQuery(logs.command("query").description("Query sealed and active log segments")).action(
+    (options: QueryOptions) =>
+      run(emit, async () => {
+        const result = await queryLogs(
+          logFamilies(catalogFor(context).families),
+          queryFrom(options),
+        );
+        if (options.json) {
+          emit.config({ format: "json" });
+          emit.data({ schema: "harnery.logs-query/v1", ...result });
+        } else emit.rows(result.records as unknown as Record<string, unknown>[]);
+      }),
+  );
+
+  configureQuery(logs.command("export").description("Export matching records as JSONL")).action(
+    (options: QueryOptions) =>
+      run(emit, async () => {
+        const result = await queryLogs(
+          logFamilies(catalogFor(context).families),
+          queryFrom(options),
+        );
+        for (const record of result.records) emit.text(JSON.stringify(record));
+        if (result.truncated)
+          emit.log("log export stopped at the configured global scan budget", "warn");
+      }),
+  );
+
+  logs
+    .command("tail")
+    .argument("<family>")
+    .description("Read recent records and a rotation-aware follow cursor")
+    .option("-n, --lines <n>", "Number of recent records", integer, 50)
+    .option("--max-bytes <n>", "Global byte scan budget", integer, 10 * 1024 * 1024)
+    .action((familyId: string, options: { lines: number; maxBytes: number }) =>
+      run(emit, async () => {
+        const family = catalogFor(context).require(familyId);
+        if (!isLogFamily(family)) throw new Error(`storage family is not a log: ${familyId}`);
+        const result = await queryLogs([family], {
+          max_records: 10_000,
+          max_bytes: options.maxBytes,
+        });
+        emit.data({
+          schema: "harnery.logs-tail-cursor/v1",
+          records: result.records.slice(-options.lines),
+          truncated: result.truncated,
+          cursor: rotationFollowCursor(family),
+        });
+      }),
+    );
+}
+
+function logFamilyRow(family: HarneryRegisteredStorageFamily, now: Date) {
+  const inspection = inspectStructuredLogRetention(family, now);
+  const effective = family.effective_log_retention;
+  return {
+    family_id: family.id,
+    class: family.storage_class,
+    directory: structuredLogDirectory(family),
+    registered_roots: family.resolved_roots,
+    policy_version: family.policy.policy_version,
+    effective_policy: effective
+      ? {
+          state: effective.state,
+          max_bytes: effective.max_bytes,
+          max_age_days: effective.max_age_days,
+          max_age_ms: effective.max_age_ms,
+          fingerprint: effective.effective_policy_fingerprint,
+          provenance: effective.provenance,
+          diagnostics: effective.diagnostics,
+        }
+      : null,
+    usage: inspection.usage,
+    pressure: inspection.pressure,
+    retention: inspection.retention,
+    sealed_segments: inspection.sealed_segments.length,
+    obsolete_manifest_snapshots: inspection.obsolete_snapshots.length,
+  };
+}
+
+function structuredLogDirectory(family: HarneryRegisteredStorageFamily): string | null {
+  if (
+    family.provider.provider_id !== HARNERY_STRUCTURED_LOG_PROVIDER_ID ||
+    family.format !== "jsonl"
+  ) {
+    return null;
+  }
+  const root = family.resolved_roots.find(
+    (candidate) => candidate.match === "provider-partition" && candidate.ownership !== "external",
+  );
+  return root?.partition ? familyLogDirectory(family) : null;
+}
+
+function logFamilyTableRow(row: ReturnType<typeof logFamilyRow>): Record<string, unknown> {
+  return {
+    family_id: row.family_id,
+    class: row.class,
+    max_bytes: row.effective_policy?.max_bytes ?? "unavailable",
+    max_age_days: row.effective_policy?.max_age_days ?? "unavailable",
+    managed_bytes: row.usage.managed_bytes,
+    unmanaged_bytes: row.usage.unmanaged_bytes,
+    pressure: row.pressure.state,
+    pressure_ratio:
+      row.pressure.ratio === null ? "unavailable" : Number(row.pressure.ratio.toFixed(3)),
+    retention: row.retention.state,
+    enforcement: row.retention.enforcement,
+    reasons: row.retention.reason_codes.join(",") || "none",
+  };
+}
+
+function catalogFor(context?: HarneryProgramContext) {
+  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 logFamilies(
+  families: readonly HarneryRegisteredStorageFamily[],
+): HarneryRegisteredStorageFamily[] {
+  return families.filter(isLogFamily);
+}
+function isLogFamily(family: HarneryRegisteredStorageFamily): boolean {
+  return family.storage_class === "operational-log" || family.storage_class === "debug-log";
+}
+function integer(value: string): number {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0)
+    throw new Error(`invalid positive integer: ${value}`);
+  return parsed;
+}
+function queryFrom(options: QueryOptions) {
+  return {
+    ...(options.family ? { family_ids: options.family } : {}),
+    ...(options.level ? { minimum_level: options.level } : {}),
+    ...(options.event ? { event: options.event } : {}),
+    ...(options.since ? { since: options.since } : {}),
+    ...(options.until ? { until: options.until } : {}),
+    max_records: options.maxRecords,
+    max_bytes: options.maxBytes,
+  };
+}
+async function run(emit: EmitContext, action: () => Promise<void>): Promise<void> {
+  try {
+    await action();
+  } catch (error) {
+    emit.error({
+      code: "logs_query_failed",
+      message: error instanceof Error ? error.message : String(error),
+    });
+    emit.setExitCode(1);
+  }
+}

package/src/commands/messages.ts

@@ -0,0 +1,61 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import type { HarneryInboxService } from "../core/inbox/service.ts";
+
+export function registerMessagesCommand(
+  program: Command,
+  emit: EmitContext,
+  service?: HarneryInboxService,
+): void {
+  program
+    .command("messages")
+    .description("Queue a durable coordination message; dry-run unless --yes")
+    .requiredOption("--from <instance>")
+    .requiredOption("--from-name <name>")
+    .requiredOption("--to <instance>")
+    .requiredOption("--to-name <name>")
+    .requiredOption("--body <text>")
+    .option("--yes", "Append and sync the message")
+    .option("--json", "Emit stable JSON")
+    .action(
+      (options: {
+        from: string;
+        fromName: string;
+        to: string;
+        toName: string;
+        body: string;
+        yes?: boolean;
+        json?: boolean;
+      }) => {
+        try {
+          const result = options.yes
+            ? requireInboxService(service).send({
+                sender_instance_id: options.from,
+                sender_display_name: options.fromName,
+                recipient_instance_id: options.to,
+                recipient_display_name: options.toName,
+                body: options.body,
+              })
+            : {
+                state: "dry-run" as const,
+                recipient_instance_id: options.to,
+                body_bytes: Buffer.byteLength(options.body),
+                writes: false,
+              };
+          if (options.json) emit.config({ format: "json" });
+          emit.data({ schema: "harnery.message-send/v1", ...result });
+        } catch (error) {
+          emit.error({
+            code: "message_send_failed",
+            message: error instanceof Error ? error.message : String(error),
+          });
+          emit.setExitCode(1);
+        }
+      },
+    );
+}
+
+function requireInboxService(service?: HarneryInboxService): HarneryInboxService {
+  if (!service) throw new Error("coordination inbox is not configured by this host");
+  return service;
+}

package/src/commands/outline.ts

@@ -55,11 +55,15 @@ interface OutlineResult {
   symbols: SymbolEntry[];
 }
 
-export function registerOutlineCommand(program: Command, emit: EmitContext): void {
+export function registerOutlineCommand(
+  program: Command,
+  emit: EmitContext,
+  binName = resolveBinName(),
+): void {
   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.`,
+      `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")

package/src/commands/qa-run.ts

@@ -0,0 +1,184 @@
+// `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 type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import { QA_RUN_RESULT_FILENAME, runQaMatrix } from "../lib/browser/qa-run.ts";
+import {
+  QA_RUN_JOB_SCHEMA_VERSION,
+  type QaRunJob,
+  validateQaRunJob,
+} from "../lib/browser/qa-run-contracts.ts";
+
+interface QaRunOpts {
+  job?: string;
+  mode: string;
+  concurrency?: string;
+  allowMetered?: boolean;
+  outDir?: string;
+  json?: boolean;
+}
+
+export function registerQaRunCommand(program: Command, emit: EmitContext): void {
+  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: string, opts: QaRunOpts, command: 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: unknown;
+      if (opts.job) {
+        let rawText: string;
+        try {
+          rawText = readFileSync(opts.job, "utf8");
+        } catch (err: unknown) {
+          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: unknown;
+        try {
+          parsed = JSON.parse(rawText);
+        } catch (err: unknown) {
+          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 as Record<string, unknown>;
+          // 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: QaRunJob = { ...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/src/commands/read.ts

@@ -11,12 +11,16 @@ let emit: EmitContext;
 /**
  * `harn read`: extract clean readable markdown from HTML.
  */
-export function registerReadCommand(program: Command, emitParam: EmitContext): void {
+export function registerReadCommand(
+  program: Command,
+  emitParam: EmitContext,
+  binName = resolveBinName(),
+): void {
   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.`,
+      `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")

package/src/commands/resources.ts

@@ -0,0 +1,38 @@
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { sampleResources } from "../core/resources/index.ts";
+
+export function registerResourcesCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  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: { root?: string }) => {
+      try {
+        emit.data(sampleResources(resolve(options.root ?? coordRoot(context))).snapshot);
+      } catch (error) {
+        fail(emit, "resource_snapshot_failed", error);
+      }
+    });
+}
+
+function coordRoot(context?: HarneryProgramContext): string {
+  return context?.resolveCoordRoot?.() ?? context?.repoRoot ?? process.cwd();
+}
+
+function fail(emit: EmitContext, code: string, error: unknown): void {
+  emit.error({
+    code,
+    message: error instanceof Error ? error.message : String(error),
+  });
+  emit.setExitCode(1);
+}

package/src/commands/semantic.ts

@@ -1,3 +1,4 @@
+import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
@@ -5,13 +6,16 @@ import {
   createSemanticAdapters,
   discoverSemanticReaders,
   inspectSemanticDocument,
+  prepareSemanticReviewStudy,
   readSemanticManifest,
   readSemanticServiceStatus,
+  readSemanticSoakReport,
   requestSemanticServiceStop,
   runSemanticOnce,
   runSemanticServiceDaemon,
   semanticPaths,
   spawnSemanticService,
+  storeSemanticReviewSubmission,
 } from "../core/semantic/index.ts";
 
 export function registerSemanticCommand(
@@ -64,7 +68,7 @@ export function registerSemanticCommand(
 
   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: { root?: string }) => {
       try {
@@ -129,6 +133,67 @@ export function registerSemanticCommand(
       }
     });
 
+  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: { root?: string; minutes?: number }) => {
+      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: { root?: string; limit?: number }) => {
+      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: { file: string; root?: string }) => {
+      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")