harnery 0.35.0 → 0.36.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;
@@ -567,6 +761,7 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
   const agentName = args.name;
   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 +769,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>] [--session-name-nudge] [--task-nudge] [--host-prompt-reminder] [--status-footer-nudge] [--turn-ritual-nudge <adapter>]\n",
     );
     return 2;
   }
@@ -586,6 +781,7 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
     agentName,
     sessionNameNudge,
     taskNudge,
+    hostPromptReminder,
     statusFooterNudge,
     turnRitualNudge,
   });
@@ -804,12 +1000,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 +1093,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 +1161,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);
   });