harnery 0.34.1 → 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);
   });

package/src/core/agents/coord-client.ts

@@ -347,9 +347,10 @@ function readPidmapRow(pidmapDir: string, pid: number): string | null {
  * Prefer a row whose platform matches `HARNERY_AGENT_COORD_PLATFORM` (default
  * `claude-code`); otherwise return the first owner seen on the walk.
  *
- * Subagents intentionally do not write pid-map entries; a Bash-tool ppid-walk
- * from inside a subagent therefore resolves to the *parent's* pid-map entry.
- * v1 ships this behavior; a real subagent-aware bridge is out of scope.
+ * Subagents intentionally do not write pid-map entries; a bare Bash-tool
+ * ppid-walk from inside an unbridged child therefore resolves to the parent's
+ * pid-map entry. Native hook bridges supersede this fallback through the
+ * child session environment.
  */
 export function resolveOwner(): string | null {
   return resolveOwnerWithSource().owner;
@@ -381,9 +382,36 @@ export function resolveOwnerWithSource(): {
   // Every supported adapter exports its native session id into subprocesses.
   // Match it against the live V3 producer state, never a disposable cache.
   if (shouldPreferSessionEnv()) {
-    const bySession = resolveOwnerBySessionEnv(root);
+    const bySession = resolveOwnerBySessionEnvDetailed(root);
     if (bySession) {
-      return { owner: bySession, source: "session_env" };
+      // Env vars cross process boundaries that session identity does not: a
+      // nested different-adapter child inherits its spawner's exported id (a
+      // Codex session's CODEX_THREAD_ID survives into a `claude -p` child's
+      // shells untouched), and that stale statement joins the spawner's live
+      // producer. The nearest token-verified pid-map anchor names the session
+      // whose tool environment this process actually runs in, so on a
+      // CROSS-adapter conflict the anchor wins — the anchoring adapter never
+      // stamps another adapter's variable, so a foreign-adapter id here is
+      // inherited context, while the anchor row is re-healed on every tool
+      // call. A SAME-adapter conflict keeps the env: the adapter stamps its
+      // own variable fresh per tool call, and the row may lag one heal (e.g.
+      // a session id change inside one process). Only per-session-process
+      // adapters may anchor (claude-code, codex) — Cursor sessions share one
+      // terminal process, so a verified Cursor row can belong to a sibling
+      // session. Unverified rows keep losing to the env too: without a start
+      // token the row is the guess the env ordering was introduced to beat.
+      // Never for bridge-marked children: a connector crosses a process-tree
+      // boundary, so an anchor in THIS tree is someone else's by definition.
+      const anchor = bridge ? null : nearestVerifiedSessionAnchor(root);
+      if (
+        anchor &&
+        anchor.owner !== bySession.owner &&
+        !bySession.adapters.includes(anchor.platform) &&
+        (anchor.platform === "claude-code" || anchor.platform === "codex")
+      ) {
+        return { owner: anchor.owner, source: "pidmap" };
+      }
+      return { owner: bySession.owner, source: "session_env" };
     }
   }
 
@@ -410,6 +438,42 @@ export function resolveOwnerWithSource(): {
   return { owner: null, source: "none" };
 }
 
+/**
+ * The nearest pid-map anchor on our own ppid chain whose start token PROVES the
+ * row still describes the process holding that pid, or null when the nearest
+ * row is unverified, recycled, or absent.
+ *
+ * Nearest matters: in a nested-agent tree (session A spawns a headless session
+ * B whose shell runs this code), both A's and B's adapter processes are
+ * ancestors, and only the innermost one owns this process's tool environment.
+ * Exported for unit testing with an injectable root.
+ */
+export function nearestVerifiedSessionAnchor(
+  root: string,
+): { owner: string; platform: string } | null {
+  const pidmapDir = resolve(root, ".harnery", "pid-map");
+  if (!existsSync(pidmapDir)) return null;
+  let pid: number | null = process.pid;
+  for (let hop = 0; hop < 20; hop++) {
+    if (pid === null) break;
+    const row = readPidmapRow(pidmapDir, pid);
+    if (row) {
+      const owner = parsePidmapRowOwner(row);
+      if (owner && !pidWasRecycled(pid, row)) {
+        // A recycled row is about a dead process's tenure of this pid — walk
+        // past it like the owner walk does. A live row without a provable
+        // token match is the nearest anchor but not a VERIFIED one: stop and
+        // report none, so the session env keeps outranking guesses.
+        const token = parsePidmapRowStartToken(row);
+        if (!token || !pidStartToken(pid)) return null;
+        return { owner, platform: parsePidmapRowPlatform(row) };
+      }
+    }
+    pid = readPpid(pid);
+  }
+  return null;
+}
+
 /**
  * Walk our own ppid chain for a pid-map row in ONE given root.
  *
@@ -524,17 +588,37 @@ function shouldPreferSessionEnv(): boolean {
  * Exported for unit testing with an injectable root.
  */
 export function resolveOwnerBySessionEnv(root: string): string | null {
+  return resolveOwnerBySessionEnvDetailed(root)?.owner ?? null;
+}
+
+/**
+ * `resolveOwnerBySessionEnv` plus WHICH adapter's producer state the session id
+ * joined. The caller uses the adapter to tell a same-adapter conflict (the env
+ * var is stamped fresh per tool call and outranks a possibly-lagging pid-map
+ * row) from a cross-adapter one (the var is inherited context from an outer
+ * session and the verified row wins).
+ */
+export function resolveOwnerBySessionEnvDetailed(
+  root: string,
+): { owner: string; adapters: string[] } | null {
   const sessionIds = sessionIdsFromEnv();
   if (sessionIds.length === 0) return null;
   const adapters = adapterCandidatesFromEnv();
-  const matches = new Set<string>();
+  const matches = new Map<string, Set<string>>();
   for (const sessionId of sessionIds) {
     for (const adapter of adapters) {
       const state = readHookProducerStateV3(root, adapter, sessionId);
-      if (state && !state.terminal) matches.add(nativeOwnerForV3Instance(root, state.instance_id));
+      if (state && !state.terminal) {
+        const owner = nativeOwnerForV3Instance(root, state.instance_id);
+        const set = matches.get(owner) ?? new Set<string>();
+        set.add(adapter);
+        matches.set(owner, set);
+      }
     }
   }
-  return matches.size === 1 ? [...matches][0]! : null;
+  if (matches.size !== 1) return null;
+  const [owner, adapterSet] = [...matches.entries()][0]!;
+  return { owner, adapters: [...adapterSet] };
 }
 
 /**