harnery 0.35.0 → 0.36.0

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/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/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")

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);
+  }
+}