harnery 0.35.0 → 0.37.0

package/src/core/agents/cli.ts

@@ -7,10 +7,31 @@
  * handlers; Phase 4 flips the default so `harn agents …` shims through here.
  */
 
+import { createHash } from "node:crypto";
 import { appendFileSync, existsSync } from "node:fs";
 import { appendFile, mkdir } from "node:fs/promises";
+import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { coordEnv } from "../../lib/env.ts";
+import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.ts";
+import { acquireNoClobberLease } from "../workflow/workspaces/leases.ts";
+
+function sharedDiagnostic(
+  root: string,
+  event: string,
+  fields: Record<string, unknown>,
+  error?: unknown,
+): boolean {
+  if (coordEnv("SHARED_LOGS") === "0") return false;
+  try {
+    const logger = processLogger(root, "agent-coord");
+    if (error === undefined) logger.debug(event, legacyLogFields(fields));
+    else logger.error(event, legacyLogFields(fields), error);
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 function findCoordRoot(start: string): string | null {
   // HARNERY_COORD_ROOT_OVERRIDE: the bash side's test-mode escape hatch. agent-coord
@@ -39,8 +60,6 @@ async function readStdin(): Promise<string> {
 }
 
 async function logNoop(root: string, subcommand: string, argv: string[]): Promise<void> {
-  const logPath = join(root, ".harnery", "debug", "agent-coord.ndjson");
-  await mkdir(dirname(logPath), { recursive: true });
   const entry = {
     ts: new Date().toISOString(),
     note: "called, no-op",
@@ -50,6 +69,9 @@ async function logNoop(root: string, subcommand: string, argv: string[]): Promis
     pid: process.pid,
     ppid: process.ppid,
   };
+  if (sharedDiagnostic(root, "agent_coord.noop", entry)) return;
+  const logPath = join(root, ".harnery", "debug", "agent-coord.ndjson");
+  await mkdir(dirname(logPath), { recursive: true });
   await appendFile(logPath, `${JSON.stringify(entry)}\n`, "utf8");
 }
 
@@ -63,8 +85,6 @@ async function logNoop(root: string, subcommand: string, argv: string[]): Promis
  */
 async function handleVerdict(root: string): Promise<number> {
   const raw = await readStdin();
-  const logPath = join(root, ".harnery", "debug", "agent-coord-verdict.ndjson");
-  await mkdir(dirname(logPath), { recursive: true });
 
   let parsed: { rule?: string } & Record<string, unknown> = {};
   let parseErr: string | null = null;
@@ -109,15 +129,16 @@ async function handleVerdict(root: string): Promise<number> {
     };
   }
 
-  await appendFile(
-    logPath,
-    `${JSON.stringify({
-      ts: new Date().toISOString(),
-      request_preview: raw.slice(0, 500),
-      verdict,
-    })}\n`,
-    "utf8",
-  );
+  const diagnostic = { request_preview: raw.slice(0, 500), verdict };
+  if (!sharedDiagnostic(root, "agent_coord.verdict", diagnostic)) {
+    const logPath = join(root, ".harnery", "debug", "agent-coord-verdict.ndjson");
+    await mkdir(dirname(logPath), { recursive: true });
+    await appendFile(
+      logPath,
+      `${JSON.stringify({ ts: new Date().toISOString(), ...diagnostic })}\n`,
+      "utf8",
+    );
+  }
 
   process.stdout.write(`${JSON.stringify(verdict)}\n`);
   return 0;
@@ -151,6 +172,64 @@ function adapterFromPlatform(platform: unknown): "claude-code" | "cursor" | "cod
   return "claude-code";
 }
 
+const coordinationRetryCell = new Int32Array(new SharedArrayBuffer(4));
+const COORDINATION_RETRY_ATTEMPTS = 240;
+const COORDINATION_RETRY_DELAY_MS = 25;
+
+function isRetryableCoordinationContention(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    error.message.includes(
+      "lease event-v3-coordination-producer is held by a live or unexpired owner",
+    )
+  );
+}
+
+function waitForCoordinationLease(): void {
+  Atomics.wait(coordinationRetryCell, 0, 0, COORDINATION_RETRY_DELAY_MS);
+}
+
+function pidIsAlive(pid: number): boolean {
+  if (!Number.isSafeInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+// The V3 producer lease begins after its caller has materialized and read the
+// disposable heartbeat. Serialize that larger registration boundary per owner
+// so overlapping first declarations cannot both derive state from an unnamed,
+// missing heartbeat and then strand a conflicting authority transaction.
+function acquireSetTaskLease(root: string, owner: string) {
+  const leasePath = join(root, ".harnery", "active", ".set-task-leases", `${owner}.lease`);
+  const authoritySha256 = createHash("sha256")
+    .update(resolve(root))
+    .update("\0")
+    .update(owner)
+    .digest("hex");
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return acquireNoClobberLease({
+        path: leasePath,
+        scope: "agent-set-task",
+        authoritySha256,
+        staleAfterMs: 5_000,
+        validateStaleOwner: (leaseOwner) =>
+          leaseOwner.host === hostname() && !pidIsAlive(leaseOwner.pid),
+      });
+    } catch (error) {
+      const busy =
+        error instanceof Error &&
+        error.message.includes("lease agent-set-task is held by a live or unexpired owner");
+      if (!busy || attempt >= COORDINATION_RETRY_ATTEMPTS - 1) throw error;
+      waitForCoordinationLease();
+    }
+  }
+}
+
 async function handleStateAction(root: string, action: string, rest: string[]): Promise<number> {
   const writer = await import("./state/heartbeat-writer.ts");
   const [owner, ...args] = rest;
@@ -162,36 +241,91 @@ async function handleStateAction(root: string, action: string, rest: string[]):
   switch (action) {
     case "set-task": {
       const task = args.join(" ");
-      const before = writer.readHeartbeat(root, owner);
-      let hb: ReturnType<typeof writer.setTask>;
+      let setTaskLease: ReturnType<typeof acquireSetTaskLease>;
       try {
-        const { recordLiveTaskChangeV3 } = await import("./live-authority-v3.ts");
-        recordLiveTaskChangeV3({
-          coordRoot: root,
-          owner,
-          nativeSessionId: before?.session_id ?? owner,
-          adapter: adapterFromPlatform(before?.platform),
-          task,
-        });
-        hb = writer.readHeartbeat(root, owner);
+        setTaskLease = acquireSetTaskLease(root, owner);
       } catch (error) {
         process.stderr.write(
-          `agent-coord set-task: V3 authority refused (${error instanceof Error ? error.message : String(error)})\n`,
+          `agent-coord set-task: registration lease refused (${error instanceof Error ? error.message : String(error)})\n`,
         );
         return 1;
       }
-      if (!hb) {
-        // Name the RESOLVED root: when a nested .harnery/ shadows the real
-        // coordination home, the full path is what makes that diagnosable.
-        process.stderr.write(
-          `agent-coord set-task: no heartbeat at ${root}/.harnery/active/${owner}.json\n`,
+      try {
+        let before = writer.readHeartbeat(root, owner);
+        const humanFacing =
+          before?.kind !== "subagent" && before?.kind !== "transient" && !before?.workflow_run_id;
+        // A mid-flight-onboarded generation can exist before SessionStart's
+        // assign-name step ran. Repair that private display metadata before the
+        // first non-empty task mints its operator-facing title. assignName is the
+        // same durable, idempotent pool path used by normal SessionStart.
+        if (task && before && humanFacing && !before.name?.trim()) {
+          const { assignName } = await import("./state/names.ts");
+          const name = assignName(root, owner, "session");
+          before = writer.setAssignedNameCache(root, owner, name, "session");
+          if (!before) {
+            process.stderr.write(
+              `agent-coord set-task: could not restore assigned name for ${owner}\n`,
+            );
+            return 1;
+          }
+        }
+        let hb: ReturnType<typeof writer.setTask>;
+        try {
+          const { recordLiveTaskChangeV3 } = await import("./live-authority-v3.ts");
+          for (let attempt = 0; ; attempt += 1) {
+            try {
+              recordLiveTaskChangeV3({
+                coordRoot: root,
+                owner,
+                nativeSessionId: before?.session_id ?? owner,
+                adapter: adapterFromPlatform(before?.platform),
+                task,
+              });
+              break;
+            } catch (error) {
+              if (
+                !isRetryableCoordinationContention(error) ||
+                attempt >= COORDINATION_RETRY_ATTEMPTS - 1
+              ) {
+                throw error;
+              }
+              waitForCoordinationLease();
+            }
+          }
+          hb = writer.readHeartbeat(root, owner);
+          const currentHumanFacing =
+            hb?.kind !== "subagent" && hb?.kind !== "transient" && !hb?.workflow_run_id;
+          if (
+            task &&
+            hb &&
+            currentHumanFacing &&
+            (!hb.name?.trim() || /^Agent unknown - /.test(hb.suggested_session_name ?? ""))
+          ) {
+            const { assignName } = await import("./state/names.ts");
+            const name = hb.name?.trim() || assignName(root, owner, "session");
+            hb = writer.setAssignedNameCache(root, owner, name, "session");
+          }
+        } catch (error) {
+          process.stderr.write(
+            `agent-coord set-task: V3 authority refused (${error instanceof Error ? error.message : String(error)})\n`,
+          );
+          return 1;
+        }
+        if (!hb) {
+          // Name the RESOLVED root: when a nested .harnery/ shadows the real
+          // coordination home, the full path is what makes that diagnosable.
+          process.stderr.write(
+            `agent-coord set-task: no heartbeat at ${root}/.harnery/active/${owner}.json\n`,
+          );
+          return 1;
+        }
+        process.stdout.write(
+          `${JSON.stringify({ instance_id: owner, task: hb.task ?? null, cleared: !task })}\n`,
         );
-        return 1;
+        return 0;
+      } finally {
+        setTaskLease.release();
       }
-      process.stdout.write(
-        `${JSON.stringify({ instance_id: owner, task: hb.task ?? null, cleared: !task })}\n`,
-      );
-      return 0;
     }
     case "release-claim": {
       const path = args[0];
@@ -271,10 +405,10 @@ async function handleStateAction(root: string, action: string, rest: string[]):
             adapter: adapterFromPlatform(adapter),
           });
         }
-        const { ensureLiveCoordinationHeartbeat } = await import(
-          "./state/live-coordination-view.ts"
+        const { repairLiveCoordinationHeartbeat } = await import(
+          "./state/live-coordination-writer.ts"
         );
-        hb = ensureLiveCoordinationHeartbeat(
+        hb = repairLiveCoordinationHeartbeat(
           root,
           owner,
           sessionId ?? owner,
@@ -290,6 +424,66 @@ async function handleStateAction(root: string, action: string, rest: string[]):
       process.stdout.write(`${JSON.stringify({ instance_id: owner, recreated: !!hb })}\n`);
       return hb ? 0 : 1;
     }
+    case "quarantine-authority-transaction": {
+      const adapter = args.find((a) => a.startsWith("--adapter="))?.slice("--adapter=".length);
+      const positional = args.filter((a) => !a.startsWith("--"));
+      const [transactionId, approvalRecordId, sessionId] = positional;
+      if (!transactionId || !approvalRecordId) {
+        process.stderr.write(
+          "agent-coord quarantine-authority-transaction: missing <transaction-id> or <approval-record-id>\n",
+        );
+        return 2;
+      }
+      try {
+        const { coordinationAuthorityStateDigestV3, liveCoordinationWriteModeV3 } = await import(
+          "./live-authority-v3.ts"
+        );
+        liveCoordinationWriteModeV3(root);
+        const { liveInstanceIdV3 } = await import("../events/v3/live-routing.ts");
+        const { repairLiveCoordinationHeartbeat } = await import(
+          "./state/live-coordination-writer.ts"
+        );
+        const heartbeat = repairLiveCoordinationHeartbeat(
+          root,
+          owner,
+          sessionId ?? owner,
+          adapterFromPlatform(adapter),
+        );
+        if (!heartbeat) {
+          throw new Error("authoritative coordination cache could not be materialized");
+        }
+        const { quarantineConflictingCoordinationTransactionV3 } = await import(
+          "../events/v3/coordination-transaction-recovery.ts"
+        );
+        const receipt = quarantineConflictingCoordinationTransactionV3(root, {
+          transaction_id: transactionId,
+          actor_instance_id: liveInstanceIdV3(owner),
+          observed_current_state_digest: coordinationAuthorityStateDigestV3(heartbeat),
+          approval_record_id: approvalRecordId,
+        });
+        const repaired = repairLiveCoordinationHeartbeat(
+          root,
+          owner,
+          sessionId ?? owner,
+          adapterFromPlatform(adapter),
+        );
+        process.stdout.write(
+          `${JSON.stringify({
+            instance_id: owner,
+            receipt,
+            heartbeat: repaired
+              ? { task_state: repaired.task_state, files_touched: repaired.files_touched }
+              : null,
+          })}\n`,
+        );
+        return repaired ? 0 : 1;
+      } catch (error) {
+        process.stderr.write(
+          `agent-coord quarantine-authority-transaction: recovery refused (${error instanceof Error ? error.message : String(error)})\n`,
+        );
+        return 1;
+      }
+    }
     default:
       process.stderr.write(`agent-coord: unknown state action ${action}\n`);
       return 2;
@@ -514,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;
 }
@@ -565,8 +761,10 @@ 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";
   const statusFooterNudge = args["status-footer-nudge"] === "true";
   // Value is the adapter id; a bare flag (parsed as "true") still enables the
   // reminder with the adapter-neutral wording.
@@ -574,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] [--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;
   }
@@ -586,8 +784,10 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
     agentName,
     sessionNameNudge,
     taskNudge,
+    hostPromptReminder,
     statusFooterNudge,
     turnRitualNudge,
+    adapter,
   });
   process.stdout.write(text);
   return 0;
@@ -804,12 +1004,15 @@ async function handleGitHook(fallbackRoot: string, rest: string[]): Promise<numb
       });
       // Forensics channel shared with the stdin `verdict` path.
       try {
-        const logPath = join(root, ".harnery", "debug", "agent-coord-verdict.ndjson");
-        await mkdir(dirname(logPath), { recursive: true });
-        await appendFile(
-          logPath,
-          `${JSON.stringify({ ts: new Date().toISOString(), via: "git-hook", staged, verdict: result })}\n`,
-        );
+        const diagnostic = { via: "git-hook", staged, verdict: result };
+        if (!sharedDiagnostic(root, "agent_coord.git_hook_verdict", diagnostic)) {
+          const logPath = join(root, ".harnery", "debug", "agent-coord-verdict.ndjson");
+          await mkdir(dirname(logPath), { recursive: true });
+          await appendFile(
+            logPath,
+            `${JSON.stringify({ ts: new Date().toISOString(), ...diagnostic })}\n`,
+          );
+        }
       } catch {
         /* diagnostics never break a verdict */
       }
@@ -894,7 +1097,8 @@ async function main(): Promise<number> {
     subcommand === "set-task" ||
     subcommand === "release-claim" ||
     subcommand === "heal-pidmap" ||
-    subcommand === "repair-coordination-cache"
+    subcommand === "repair-coordination-cache" ||
+    subcommand === "quarantine-authority-transaction"
   ) {
     return handleStateAction(root, subcommand, rest);
   }
@@ -961,19 +1165,25 @@ async function main(): Promise<number> {
 }
 
 main()
-  .then((code) => process.exit(code))
-  .catch((err) => {
+  .then(async (code) => {
+    await closeProcessLoggers();
+    process.exit(code);
+  })
+  .catch(async (err) => {
     try {
       const root = findCoordRoot(process.cwd());
       if (root) {
-        const path = join(root, ".harnery", "debug", "agent-coord.errors.ndjson");
-        appendFileSync(
-          path,
-          `${JSON.stringify({ ts: new Date().toISOString(), error: String(err) })}\n`,
-        );
+        if (!sharedDiagnostic(root, "agent_coord.error", {}, err)) {
+          const path = join(root, ".harnery", "debug", "agent-coord.errors.ndjson");
+          appendFileSync(
+            path,
+            `${JSON.stringify({ ts: new Date().toISOString(), error: String(err) })}\n`,
+          );
+        }
       }
     } catch {
       /* swallow */
     }
+    await closeProcessLoggers();
     process.exit(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,
+  };
+}