harnery 0.36.0 → 0.38.0

package/src/commands/diagnostics.ts

@@ -0,0 +1,271 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { monorepoRoot, resolveOwner } from "../core/agents/index.ts";
+import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.ts";
+import type { ArtifactActor } from "../core/artifacts/index.ts";
+import {
+  buildDiagnosticAdvice,
+  captureDiagnosticBundle,
+  compareDiagnosticBundles,
+  DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+  listDiagnosticBundles,
+  renderDiagnosticBundleComparison,
+  replayDiagnosticBundle,
+  showDiagnosticBundle,
+} from "../core/diagnostics/index.ts";
+import {
+  buildSupervisorTimeline,
+  explainSupervisorFinding,
+  readSupervisorExplanation,
+  readSupervisorFindings,
+  readSupervisorStatus,
+  readSupervisorTimeline,
+  type SupervisorCapability,
+  type SupervisorFinding,
+} from "../core/supervisor/index.ts";
+
+export function registerDiagnosticsCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  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: string) => {
+      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: { bundle?: string; json?: boolean }) => {
+      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: { finding?: string; from?: string; to?: string; days?: string }) => {
+      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: string) => {
+      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: string, after: string, opts: { json?: boolean }) => {
+      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: string, reportPresent: boolean): SupervisorCapability {
+  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: string, id: string): SupervisorFinding | undefined {
+  const report = readSupervisorFindings(repoRoot);
+  return mergeFindings(report?.active ?? [], report?.transitions ?? []).find(
+    (finding) => finding.id === id,
+  );
+}
+
+function mergeFindings(
+  active: readonly SupervisorFinding[],
+  transitions: readonly SupervisorFinding[],
+): SupervisorFinding[] {
+  const byId = new Map<string, SupervisorFinding>();
+  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: string): ArtifactActor | undefined {
+  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?: HarneryProgramContext): string {
+  const root = context?.repoRoot ?? monorepoRoot();
+  if (!root) throw new Error("not inside a Git repository");
+  return root;
+}
+
+function parseDays(value: string): number {
+  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: EmitContext, fn: () => void): void {
+  try {
+    fn();
+  } catch (error) {
+    emit.error({
+      code: "diagnostics_failed",
+      message: error instanceof Error ? error.message : String(error),
+    });
+    emit.setExitCode(1);
+  }
+}

package/src/commands/fetch.ts

@@ -96,6 +96,7 @@ async function runFetch(
       redirect: opts.redirect as RequestRedirect,
       signal: ac.signal,
       extraHeaders: context?.extraHeaders,
+      extraCookies: context?.extraCookies,
       responseType: "bytes",
     });
   } finally {

package/src/commands/files.ts

@@ -4,6 +4,7 @@ import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { resolveCoordRoot } from "../core/agents/coord-client.ts";
 import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.ts";
+import { coordRootId, localCoordRootIdUrl } from "../lib/coord-root-id.ts";
 import { localFilesOriginUrl, localFileViewerUrl } from "../lib/local-file-url.ts";
 
 export { FILES_ORIGIN_HOST } from "../lib/local-file-url.ts";
@@ -22,6 +23,92 @@ export interface LocalFileUrl {
   mode: Exclude<LocalFileUrlMode, "auto">;
 }
 
+export type DashboardRootErrorCode =
+  | "dashboard_unreachable"
+  | "dashboard_identity_unavailable"
+  | "dashboard_root_mismatch";
+
+export class DashboardRootError extends Error {
+  constructor(
+    readonly code: DashboardRootErrorCode,
+    message: string,
+    readonly hint: string,
+  ) {
+    super(message);
+    this.name = "DashboardRootError";
+  }
+}
+
+interface DashboardRootPayload {
+  root_id?: unknown;
+}
+
+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 async function verifyDashboardRoot(
+  coordRoot: string,
+  port: number,
+  fetchImpl: DashboardRootFetch = fetch,
+): Promise<void> {
+  const url = localCoordRootIdUrl(port);
+  let response: 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: DashboardRootPayload;
+  try {
+    payload = (await response.json()) as DashboardRootPayload;
+  } 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: string): boolean {
   return relPath === "" || relPath === ".." || relPath.startsWith(`..${path.sep}`);
 }
@@ -92,10 +179,17 @@ export function registerFilesCommand(
     .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")
+    .option("--no-verify", "Mint without checking the running dashboard's repository identity")
     .action(
-      (
+      async (
         filePath: string,
-        opts: { port?: string; coordRoot?: string; raw?: boolean; viewer?: boolean },
+        opts: {
+          port?: string;
+          coordRoot?: string;
+          raw?: boolean;
+          viewer?: boolean;
+          verify?: boolean;
+        },
       ) => {
         if (opts.raw && opts.viewer) {
           emit.error({
@@ -129,8 +223,14 @@ export function registerFilesCommand(
             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/src/commands/governor.ts

@@ -62,6 +62,7 @@ interface CreateOpts {
 interface RunOpts {
   adapter?: string;
   cwd?: string;
+  observePressure?: boolean;
   subscriptionOnly?: boolean;
   allowApiBilling?: boolean;
   policy?: string;
@@ -438,6 +439,10 @@ function addServiceOptions(command: Command): 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")
@@ -596,6 +601,9 @@ function registerRunCommand(
             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,

package/src/commands/ledger-v3.ts

@@ -5,13 +5,16 @@ import { resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import {
+  compressSealedLegacyV1Segments,
   inventoryLegacyV1Segments,
   streamLegacyV1Rows,
   verifyLegacyV1HardFence,
   writeLegacyV1Canary,
 } from "../core/events/legacy-storage/index.ts";
 import {
+  cleanEventV3Archives,
   initializeEventLedgerV3,
+  inventoryEventV3Archives,
   readEventV3ControlState,
   recoverInvalidEventLedgerV3,
   sha256V3,
@@ -59,6 +62,39 @@ export function registerLedgerV3Command(
       }
     });
 
+  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: { root?: string }) => {
+      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: { root?: string; yes?: boolean }) => {
+      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")
@@ -355,6 +391,32 @@ export function registerLedgerV3Command(
       }
     });
 
+  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: { root?: string; yes?: boolean }) => {
+      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")
@@ -525,6 +587,26 @@ function sameSortedStrings(left: string[], right: string[]): boolean {
   );
 }
 
+function summarizeArchiveRows(
+  rows: Array<{ classification: string; action: string; bytes: number | null }>,
+): Record<string, unknown> {
+  const classifications: Record<string, number> = {};
+  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: EmitContext, code: string, error: unknown): never {
   emit.error({ code, message: error instanceof Error ? error.message : String(error) });
   throw error;