harnery 0.35.0 → 0.37.0

package/src/commands/storage.ts

@@ -0,0 +1,310 @@
+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 type {
+  HarneryStorageClass,
+  HarneryStorageInventoryReport,
+  HarneryStorageMeasurement,
+} from "../core/storage/contract.ts";
+import { storageHealth } from "../core/storage/health.ts";
+import { filterStorageInventory, inventoryStorage } from "../core/storage/inventory.ts";
+import {
+  DEFAULT_MAINTENANCE_BUDGET,
+  executeStorageMaintenance,
+  HARNERY_MAINTENANCE_PRESSURE_SCHEMA,
+  HarneryMaintenanceError,
+  type HarneryStoragePressureSummary,
+  listMaintenanceTransactions,
+  planStorageMaintenance,
+  readMaintenanceTransaction,
+} from "../core/storage/maintenance.ts";
+import { createStructuredLogMaintenanceProviders } from "../core/storage/maintenance-providers.ts";
+
+const STORAGE_CLASSES = new Set<HarneryStorageClass>([
+  "canonical-authority",
+  "recovery-state",
+  "operational-log",
+  "debug-log",
+  "durable-object-history",
+  "repairable-cache",
+  "managed-artifact",
+]);
+
+interface InventoryOptions {
+  family?: string;
+  class?: string;
+  json?: boolean;
+}
+
+interface HealthOptions {
+  json?: boolean;
+}
+
+interface MaintainOptions {
+  family?: string;
+  budget?: string;
+  transaction?: string;
+  yes?: boolean;
+  authorizeStructuredLogDeletion?: boolean;
+  json?: boolean;
+}
+
+interface StatusOptions {
+  transaction?: string;
+  json?: boolean;
+}
+
+export function registerStorageCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  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: InventoryOptions) => {
+      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: HealthOptions) => {
+      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: MaintainOptions) => {
+      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: StatusOptions) => {
+      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?: 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 parseStorageClass(value: string | undefined): HarneryStorageClass | undefined {
+  if (value === undefined) return undefined;
+  if (!STORAGE_CLASSES.has(value as HarneryStorageClass)) {
+    throw new StorageCommandError("unknown_storage_class", `unknown storage class: ${value}`);
+  }
+  return value as HarneryStorageClass;
+}
+
+async function pressureFor(
+  catalog: ReturnType<typeof createStorageCatalog>,
+): Promise<HarneryStoragePressureSummary> {
+  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: string | undefined): number {
+  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: HarneryStorageInventoryReport): Record<string, unknown>[] {
+  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: HarneryStorageMeasurement): number | string {
+  return measurement.state === "observed"
+    ? measurement.value
+    : `unavailable:${measurement.reason_code}`;
+}
+
+class StorageCommandError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+async function run(emit: EmitContext, action: () => Promise<void>): Promise<void> {
+  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/src/commands/supervisor.ts

@@ -0,0 +1,141 @@
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { readSupervisorHookHealth } from "../core/supervisor/hook-health-storage.ts";
+import {
+  requestSupervisorStop,
+  runSupervisor,
+  spawnSupervisor,
+} from "../core/supervisor/service.ts";
+import { readSupervisorStatus } from "../core/supervisor/status.ts";
+import {
+  readSupervisorFindings,
+  readSupervisorHistory,
+  readSupervisorLogFeed,
+  readSupervisorSnapshot,
+} from "../core/supervisor/storage.ts";
+
+export function registerSupervisorCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  const supervisor = program
+    .command("supervisor")
+    .description("Run Harnery's optional local diagnostic supervisor");
+
+  supervisor
+    .command("start")
+    .description("Start the detached local supervisor")
+    .option("--root <path>", "Explicit coordination root")
+    .option("--interval-ms <milliseconds>", "Collection interval from 500 to 60000 ms", integer)
+    .option(
+      "--idle-exit-ms <milliseconds>",
+      "Exit after this long without a live dashboard consumer or attributed agent",
+      integer,
+    )
+    .option("--keep-alive", "Remain resident until explicitly stopped")
+    .action(
+      async (options: {
+        root?: string;
+        intervalMs?: number;
+        idleExitMs?: number;
+        keepAlive?: boolean;
+      }) => {
+        try {
+          emit.data(
+            await spawnSupervisor(resolve(options.root ?? coordRoot(context)), {
+              intervalMs: options.intervalMs,
+              idleExitMs: options.idleExitMs,
+              keepAlive: options.keepAlive,
+            }),
+          );
+        } catch (error) {
+          fail(emit, "supervisor_start_failed", error);
+        }
+      },
+    );
+
+  supervisor
+    .command("status")
+    .description("Show supervisor liveness and its latest bounded projections")
+    .option("--root <path>", "Explicit coordination root")
+    .action((options: { root?: string }) => {
+      try {
+        const root = resolve(options.root ?? coordRoot(context));
+        emit.data({
+          service: readSupervisorStatus(root),
+          snapshot: readSupervisorSnapshot(root),
+          history: readSupervisorHistory(root),
+          findings: readSupervisorFindings(root),
+          hook_health: readSupervisorHookHealth(root),
+          log_feed: readSupervisorLogFeed(root),
+        });
+      } catch (error) {
+        fail(emit, "supervisor_status_failed", error);
+      }
+    });
+
+  supervisor
+    .command("stop")
+    .description("Request a graceful supervisor stop")
+    .option("--root <path>", "Explicit coordination root")
+    .action(async (options: { root?: string }) => {
+      try {
+        const root = resolve(options.root ?? coordRoot(context));
+        let status = requestSupervisorStop(root);
+        const deadline = Date.now() + 5_000;
+        while (status.running && Date.now() < deadline) {
+          await new Promise((done) => setTimeout(done, 50));
+          status = readSupervisorStatus(root);
+        }
+        emit.data(status);
+      } catch (error) {
+        fail(emit, "supervisor_stop_failed", error);
+      }
+    });
+
+  supervisor
+    .command("daemon", { hidden: true })
+    .description("Internal detached local supervisor entrypoint")
+    .option("--root <path>", "Explicit coordination root")
+    .option("--interval-ms <milliseconds>", "Collection interval", integer)
+    .option("--idle-exit-ms <milliseconds>", "Idle exit interval", integer)
+    .option("--keep-alive", "Remain resident until explicitly stopped")
+    .action(
+      async (options: {
+        root?: string;
+        intervalMs?: number;
+        idleExitMs?: number;
+        keepAlive?: boolean;
+      }) => {
+        try {
+          emit.data(
+            await runSupervisor({
+              coordRoot: resolve(options.root ?? coordRoot(context)),
+              intervalMs: options.intervalMs,
+              idleExitMs: options.idleExitMs,
+              keepAlive: options.keepAlive,
+            }),
+          );
+        } catch (error) {
+          fail(emit, "supervisor_daemon_failed", error);
+        }
+      },
+    );
+}
+
+function coordRoot(context?: HarneryProgramContext): string {
+  return context?.resolveCoordRoot?.() ?? context?.repoRoot ?? process.cwd();
+}
+
+function integer(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) throw new Error(`expected an integer, got ${value}`);
+  return parsed;
+}
+
+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/tunnel.ts

@@ -1,17 +1,15 @@
+import { type ChildProcess, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 
-// Inline cachePath; see lib/tunnel/state.ts for rationale.
-function cachePath(tool: string, filename: string): string {
-  const dir = resolve(process.cwd(), ".cache", tool);
-  return resolve(dir, filename);
-}
-
-import { type ChildProcess, spawn, spawnSync } from "node:child_process";
-import { existsSync, openSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-
 import { resolveBinName } from "../core/config.ts";
+import {
+  processLogDestination,
+  runRotatingProcessSync,
+  spawnRotatingProcess,
+} from "../core/storage/process-log.ts";
 import {
   clearState,
   DEFAULT_INSTANCE,
@@ -79,6 +77,27 @@ interface LogsOpts {
   provider?: boolean;
 }
 
+export function tunnelLogDestinations(
+  name: string,
+  provider: TunnelProvider,
+  env: NodeJS.ProcessEnv = process.env,
+  root = process.cwd(),
+): { gate: string; provider: string } {
+  const destination = (filename: string) =>
+    processLogDestination({
+      coord_root: root,
+      project_root: root,
+      family_id: "tunnel-process-log",
+      filename,
+      legacy_path: resolve(root, ".cache", "tunnel", filename),
+      env,
+    });
+  return {
+    gate: destination(gateLogFile(name)),
+    provider: destination(providerLogFile(name, provider)),
+  };
+}
+
 /**
  * Validate + normalize an instance name. Names become filename fragments
  * (state-<name>.json) and pgrep patterns, so they're restricted to a safe
@@ -348,7 +367,6 @@ function runTailscaleShare(
   httpsPort: number,
   logPath: string,
 ): void {
-  const fd = openSync(logPath, "a");
   const args = [
     tailscaleCommand(mode),
     "--bg",
@@ -357,31 +375,36 @@ function runTailscaleShare(
     `--set-path=${path}`,
     targetUrl,
   ];
-  const r = spawnSync("tailscale", args, {
-    stdio: ["ignore", fd, fd],
+  const status = runRotatingProcessSync({
+    path: logPath,
+    command: "tailscale",
+    arguments: args,
   });
-  if (r.status !== 0) {
+  if (status !== 0) {
     emit.error({
       code: "tunnel_tailscale_failed",
       message: `tailscale ${tailscaleCommand(mode)} failed. Check log: ${logPath}`,
     });
-    process.exit(r.status ?? 1);
+    process.exit(status ?? 1);
   }
 }
 
 function stopTailscaleShare(state: TunnelState): boolean {
   if (state.provider !== "tailscale" || !state.tailscale_mode) return true;
   const cmd = tailscaleCommand(state.tailscale_mode);
-  const logPath = cachePath("tunnel", providerLogFile(state.name, "tailscale"));
-  const fd = openSync(logPath, "a");
+  const logPath = tunnelLogDestinations(state.name, "tailscale").provider;
   const args = [
     cmd,
     `--https=${state.tailscale_https_port ?? 443}`,
     `--set-path=${state.tailscale_path ?? "/"}`,
     "off",
   ];
-  const r = spawnSync("tailscale", args, { stdio: ["ignore", fd, fd] });
-  if (r.status !== 0) {
+  const status = runRotatingProcessSync({
+    path: logPath,
+    command: "tailscale",
+    arguments: args,
+  });
+  if (status !== 0) {
     // The gate is torn down and its port is freed for reuse regardless, so a
     // surviving serve/funnel mapping could later re-expose whatever next binds
     // that port. Surface it loudly so the operator can clear it by hand.
@@ -432,26 +455,22 @@ interface GateSpawnOpts {
  * re-reads — that snapshot is precisely why `reload` has to exist.
  */
 function spawnGate(o: GateSpawnOpts): ChildProcess {
-  const gateFd = openSync(o.gateLogPath, "a");
   // `--name`/`--port` on argv mirror the env vars; they're what makes the gate
   // process distinguishable per-instance in `pgrep -f` (see sweepStrays).
-  const gateProc = spawn(
-    "bun",
-    ["run", gateScriptPath(), "--name", o.name, "--port", String(o.gatePort)],
-    {
-      detached: true,
-      stdio: ["ignore", gateFd, gateFd],
-      env: {
-        ...process.env,
-        HARNERY_TUNNEL_ALLOW: o.allowedIps.join(","),
-        HARNERY_TUNNEL_ACCESS:
-          o.provider === "cloudflare" ? "cloudflare-allowlist" : "trusted-local-proxy",
-        HARNERY_TUNNEL_TARGET: o.target,
-        HARNERY_TUNNEL_VHOST: o.vhost,
-        HARNERY_TUNNEL_PORT: String(o.gatePort),
-      },
+  const gateProc = spawnRotatingProcess({
+    path: o.gateLogPath,
+    command: "bun",
+    arguments: ["run", gateScriptPath(), "--name", o.name, "--port", String(o.gatePort)],
+    env: {
+      ...process.env,
+      HARNERY_TUNNEL_ALLOW: o.allowedIps.join(","),
+      HARNERY_TUNNEL_ACCESS:
+        o.provider === "cloudflare" ? "cloudflare-allowlist" : "trusted-local-proxy",
+      HARNERY_TUNNEL_TARGET: o.target,
+      HARNERY_TUNNEL_VHOST: o.vhost,
+      HARNERY_TUNNEL_PORT: String(o.gatePort),
     },
-  );
+  });
   gateProc.unref();
   return gateProc;
 }
@@ -521,10 +540,9 @@ async function up(opts: UpOpts): Promise<void> {
     process.exit(1);
   }
 
-  const gateLogPath = cachePath("tunnel", gateLogFile(name));
-  const providerLogPath = cachePath("tunnel", providerLogFile(name, provider));
-  writeFileSync(gateLogPath, "");
-  writeFileSync(providerLogPath, "");
+  const logPaths = tunnelLogDestinations(name, provider);
+  const gateLogPath = logPaths.gate;
+  const providerLogPath = logPaths.provider;
 
   const gateProc = spawnGate({
     name,
@@ -551,20 +569,16 @@ async function up(opts: UpOpts): Promise<void> {
   let cloudflaredPid: number | undefined;
 
   if (provider === "cloudflare") {
-    const cfdFd = openSync(providerLogPath, "a");
     // Force HTTP/2 transport. The default QUIC transport wedges at precheck on
     // constrained hosts (e.g. WSL, where UDP receive buffers can't grow and ICMP
     // is restricted): the URL prints but the edge never registers. HTTP/2 is
     // marginally higher-latency but registers reliably, which is what a dev
     // tunnel needs.
-    const cfdProc = spawn(
-      cloudflaredBin!,
-      ["tunnel", "--protocol", "http2", "--url", `http://localhost:${gatePort}`],
-      {
-        detached: true,
-        stdio: ["ignore", cfdFd, cfdFd],
-      },
-    );
+    const cfdProc = spawnRotatingProcess({
+      path: providerLogPath,
+      command: cloudflaredBin!,
+      arguments: ["tunnel", "--protocol", "http2", "--url", `http://localhost:${gatePort}`],
+    });
     cfdProc.unref();
     cloudflaredPid = cfdProc.pid!;
 
@@ -788,7 +802,7 @@ export async function reloadOne(state: TunnelState): Promise<{ ok: boolean; mess
     vhost: state.vhost,
     provider: state.provider,
     allowedIps: cfg.allowed_ips,
-    gateLogPath: cachePath("tunnel", gateLogFile(name)),
+    gateLogPath: tunnelLogDestinations(name, state.provider).gate,
   });
 
   await sleep(800);
@@ -952,8 +966,8 @@ function logs(opts: LogsOpts): void {
   const name = resolveName(opts.name);
   const state = readState(name);
   const provider = state?.provider ?? "cloudflare";
-  const which = opts.provider ? providerLogFile(name, provider) : gateLogFile(name);
-  const path = cachePath("tunnel", which);
+  const destinations = tunnelLogDestinations(name, provider);
+  const path = opts.provider ? destinations.provider : destinations.gate;
   if (!existsSync(path)) {
     emit.error({ code: "tunnel_no_log", message: `No log file at ${path}` });
     process.exit(1);