harnery 0.36.0 → 0.38.0

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/web.ts

@@ -8,6 +8,11 @@ import type { EmitContext } from "../commander.ts";
 import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.ts";
 import { ensureSemanticServiceRunning } from "../core/semantic/service.ts";
 import { processLogDestination } from "../core/storage/process-log.ts";
+import { ensureSupervisorRunning } from "../core/supervisor/service.ts";
+import {
+  registerSupervisorConsumer,
+  unregisterSupervisorConsumer,
+} from "../core/supervisor/services.ts";
 import {
   parsePerformanceWindow,
   readWebPerformanceReport,
@@ -109,6 +114,16 @@ async function startSemanticServiceWithWeb(coordRoot: string, emit: EmitContext)
   }
 }
 
+async function startSupervisorWithWeb(coordRoot: string, emit: EmitContext): Promise<void> {
+  registerSupervisorConsumer(coordRoot, { id: "dashboard" });
+  const result = await ensureSupervisorRunning(coordRoot);
+  if (result.state === "started") emit.log("local supervisor · started automatically", "info");
+  if (result.state === "running") emit.log("local supervisor · already running", "info");
+  if (result.state === "unavailable") {
+    emit.log(`local supervisor · unavailable (${result.error})`, "warn");
+  }
+}
+
 /**
  * Resolve the web app root. A local `web/` (source checkout / submodule) wins.
  * Otherwise, on an npm install, lazy-fetch it (clone + install) unless the
@@ -233,6 +248,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
 
       if (!(await requireAvailablePort(emit, port))) return;
 
+      await startSupervisorWithWeb(coordRoot, emit);
       await startSemanticServiceWithWeb(coordRoot, emit);
 
       const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
@@ -264,6 +280,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       process.on("SIGTERM", () => cleanup("SIGTERM"));
 
       child.on("exit", (code, sig) => {
+        unregisterSupervisorConsumer(coordRoot, "dashboard");
         if (sig) {
           emit.log(`web exited on ${sig}`, "info");
         } else if (code !== 0) {
@@ -326,6 +343,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
         return;
       }
       if (!(await requireAvailablePort(emit, port))) return;
+      await startSupervisorWithWeb(coordRoot, emit);
       await startSemanticServiceWithWeb(coordRoot, emit);
       const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
       const nodeOptions = nodeOptionsWithWebDiagnostics(root, heapMb);
@@ -355,6 +373,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       process.on("SIGTERM", () => cleanup("SIGTERM"));
 
       child.on("exit", (code) => {
+        unregisterSupervisorConsumer(coordRoot, "dashboard");
         process.exitCode = code ?? 0;
       });
     });

package/src/commands/workflow.ts

@@ -28,6 +28,7 @@ import type { WorkspaceProvider } from "../core/workflow/index.ts";
 interface WorkflowRunOpts {
   maxAgents?: string;
   concurrency?: string;
+  observePressure?: boolean;
   cwd?: string;
   adapter?: string;
   resumeFrom?: string;
@@ -98,6 +99,10 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     )
     .option("--max-agents <n>", "Total-agent ceiling for the run (default 50)")
     .option("--concurrency <n>", "Concurrent-subagent cap (default 4)")
+    .option(
+      "--observe-pressure",
+      "Record observer-only local pressure before the first real child dispatch",
+    )
     .option("--cwd <dir>", "Working directory children spawn in (default: coord root)")
     .option(
       "--adapter <name>",
@@ -194,6 +199,9 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
           allowApiBilling: opts.allowApiBilling,
           maxAgents: opts.maxAgents ? Number.parseInt(opts.maxAgents, 10) : undefined,
           concurrency: opts.concurrency ? Number.parseInt(opts.concurrency, 10) : undefined,
+          diagnosticAdmission: opts.observePressure
+            ? { schema_version: 1, mode: "shadow" }
+            : undefined,
           cwd: opts.cwd,
           ...adapterProofInputs(
             registry.list().map((adapter) => adapter.profile),

package/src/core/agents/cli.ts

@@ -708,8 +708,10 @@ async function handleStaleSweep(root: string, _rest: string[]): Promise<number>
 }
 
 async function handleReconcileFinalization(root: string): Promise<number> {
-  const { reconcileSessionFinalizationV3 } = await import("./session-finalizer-v3.ts");
-  const result = reconcileSessionFinalizationV3(root);
+  // Shares the supervisor composition with `agents reconcile` so session start
+  // sweeps the stale cache in the same pass, as ADR 0077 specified.
+  const { reconcileCoordinationV3 } = await import("./reconcile-coordination-v3.ts");
+  const result = reconcileCoordinationV3(root);
   process.stdout.write(`${JSON.stringify(result)}\n`);
   return result.diagnostics.some((item) => item === "ledger_not_authority_safe") ? 2 : 0;
 }
@@ -759,6 +761,7 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
   const instanceId = args.instance;
   const sessionId = args.session ?? instanceId;
   const agentName = args.name;
+  const adapter = args.adapter;
   const sessionNameNudge = args["session-name-nudge"] === "true";
   const taskNudge = args["task-nudge"] === "true";
   const hostPromptReminder = args["host-prompt-reminder"] === "true";
@@ -769,7 +772,7 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
     args["turn-ritual-nudge"] === "true" ? "generic" : args["turn-ritual-nudge"];
   if (!instanceId) {
     process.stderr.write(
-      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--session-name-nudge] [--task-nudge] [--host-prompt-reminder] [--status-footer-nudge] [--turn-ritual-nudge <adapter>]\n",
+      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--adapter <id>] [--session-name-nudge] [--task-nudge] [--host-prompt-reminder] [--status-footer-nudge] [--turn-ritual-nudge <adapter>]\n",
     );
     return 2;
   }
@@ -784,6 +787,7 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
     hostPromptReminder,
     statusFooterNudge,
     turnRitualNudge,
+    adapter,
   });
   process.stdout.write(text);
   return 0;

package/src/core/agents/health.ts

@@ -0,0 +1,142 @@
+import { closeSync, existsSync, lstatSync, openSync, readSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { SupervisorCapability, SupervisorSourceReference } from "../supervisor/contract.ts";
+
+export interface CoordinationHealthDiagnostic {
+  code: "malformed_json" | "invalid_contract";
+  byte_offset: number;
+  segment_ordinal: number;
+  event_id?: string;
+}
+
+export interface CoordinationHealthSnapshot {
+  observed_at: string;
+  capability: SupervisorCapability;
+  recent_events: readonly SupervisorSourceReference[];
+  diagnostics: readonly CoordinationHealthDiagnostic[];
+  omitted_event_count: number;
+}
+
+const MAX_EVENT_REFERENCES = 64;
+const MAX_DIAGNOSTICS = 16;
+const MAX_TAIL_BYTES = 256 * 1_024;
+
+/** Read bounded V3 references without retaining event payloads or the full ledger reader. */
+export function collectCoordinationHealthSnapshot(
+  coordRoot: string,
+  now = new Date(),
+): CoordinationHealthSnapshot {
+  const observedAt = now.toISOString();
+  const active = join(resolve(coordRoot), ".harnery", "ledgers", "v3", "active.ndjson");
+  if (!existsSync(active)) return unavailable(observedAt, "ledger-missing");
+
+  let handle: number | undefined;
+  try {
+    const stat = lstatSync(active);
+    if (stat.isSymbolicLink() || !stat.isFile()) return unavailable(observedAt, "ledger-unsafe");
+    if (stat.size === 0) return available(observedAt, [], [], 0);
+    const start = Math.max(0, stat.size - MAX_TAIL_BYTES);
+    const bytes = Buffer.allocUnsafe(stat.size - start);
+    handle = openSync(active, "r");
+    const count = readSync(handle, bytes, 0, bytes.length, start);
+    const lines = bytes.subarray(0, count).toString("utf8").split("\n");
+    if (start > 0) lines.shift();
+    const completeLines = lines.filter((line) => line.length > 0);
+    const diagnostics: CoordinationHealthDiagnostic[] = [];
+    const references: SupervisorSourceReference[] = [];
+    let byteOffset = start;
+    for (const line of completeLines) {
+      const reference = parseReference(line);
+      if (reference) references.push(reference);
+      else if (diagnostics.length < MAX_DIAGNOSTICS) {
+        diagnostics.push({
+          code: line.trimStart().startsWith("{") ? "invalid_contract" : "malformed_json",
+          byte_offset: byteOffset,
+          segment_ordinal: 1,
+        });
+      }
+      byteOffset += Buffer.byteLength(line) + 1;
+    }
+    const recent = references.slice(-MAX_EVENT_REFERENCES);
+    return available(
+      observedAt,
+      recent,
+      diagnostics,
+      Math.max(0, references.length - recent.length) + (start > 0 ? 1 : 0),
+    );
+  } catch {
+    return unavailable(observedAt, "tail-read-failed", "error");
+  } finally {
+    if (handle !== undefined) closeSync(handle);
+  }
+}
+
+function parseReference(line: string): SupervisorSourceReference | undefined {
+  try {
+    const value = JSON.parse(line) as Record<string, unknown>;
+    const contract = object(value.contract);
+    const time = object(value.time);
+    const producer = object(value.producer);
+    if (
+      contract.major !== 3 ||
+      typeof value.event_id !== "string" ||
+      typeof value.event_type !== "string" ||
+      typeof time.observed_at !== "string" ||
+      typeof producer.sequence !== "number" ||
+      !Number.isSafeInteger(producer.sequence)
+    )
+      return undefined;
+    return {
+      id: `v3:${value.event_id}`,
+      source_kind: "coordination.v3",
+      source_id: value.event_type,
+      record_id: value.event_id,
+      sequence: producer.sequence,
+      schema_version: 3,
+      observed_at: time.observed_at,
+      capability: "supported",
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function object(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function available(
+  observedAt: string,
+  recentEvents: readonly SupervisorSourceReference[],
+  diagnostics: readonly CoordinationHealthDiagnostic[],
+  omittedEventCount: number,
+): CoordinationHealthSnapshot {
+  const state = diagnostics.length === 0 ? "supported" : "partial";
+  return {
+    observed_at: observedAt,
+    capability: {
+      source_kind: "coordination.v3.references",
+      state,
+      ...(state === "partial" ? { reason_code: diagnostics[0]?.code ?? "tail-invalid" } : {}),
+    },
+    recent_events: recentEvents.map((reference) => ({ ...reference, capability: state })),
+    diagnostics,
+    omitted_event_count: omittedEventCount,
+  };
+}
+
+function unavailable(
+  observedAt: string,
+  reasonCode: string,
+  state: "unsupported" | "error" = "unsupported",
+): CoordinationHealthSnapshot {
+  return {
+    observed_at: observedAt,
+    capability: { source_kind: "coordination.v3.references", state, reason_code: reasonCode },
+    recent_events: [],
+    diagnostics: [],
+    omitted_event_count: 0,
+  };
+}