harnery 0.9.0 → 0.11.0

package/src/core/agents/render/session-context.ts

@@ -12,6 +12,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { resolveBinName, resolveHooksSetupHint } from "../../config.ts";
 import { harneryVersion, loadHarnessWiring } from "../../hooks/harness/wiring.ts";
+import { readRemoteMachines } from "../../presence/index.ts";
 
 interface HeartbeatRow {
   instance_id?: string;
@@ -48,7 +49,9 @@ export function renderSessionContext(opts: RenderOpts): string {
 
   // 1. Self-name line + peer table (folded if peers present)
   const peers = readActivePeers(coordRoot, instanceId);
-  const peerTable = formatPeerTable(peers, sessionId);
+  const localTable = formatPeerTable(peers, sessionId);
+  // Cross-machine presence (ADR 0016): sessions on other machines (advisory).
+  const peerTable = [localTable, formatRemoteMachines(coordRoot)].filter(Boolean).join("\n\n");
   if (agentName) {
     const suffix = platformLabel ? ` (${platformLabel})` : "";
     const selfLine = `You are agent-${agentName}${suffix}.`;
@@ -107,6 +110,29 @@ export function renderSessionContext(opts: RenderOpts): string {
   return messages.join("\n\n");
 }
 
+/** One-line-per-agent view of sessions on other machines (presence refs). */
+function formatRemoteMachines(coordRoot: string): string {
+  try {
+    const remote = readRemoteMachines(coordRoot);
+    if (remote.length === 0) return "";
+    const lines: string[] = [];
+    for (const m of remote) {
+      for (const a of m.agents.slice(0, 10)) {
+        const task = a.task ? ` "${a.task.slice(0, 60)}"` : "";
+        const files = a.files_touched?.length
+          ? `holds: ${a.files_touched.slice(0, 3).join(", ")}${a.files_touched.length > 3 ? `, +${a.files_touched.length - 3} more` : ""}`
+          : "nothing held";
+        lines.push(
+          `  - agent-${a.name ?? a.instance_id.slice(0, 8)} @${m.machine}${task} (${files})`,
+        );
+      }
+    }
+    return `Sessions on other machines (advisory, via presence refs):\n${lines.join("\n")}`;
+  } catch {
+    return "";
+  }
+}
+
 /** Read all peer heartbeats from .harnery/active/, excluding self. */
 function readActivePeers(coordRoot: string, selfInstanceId: string): HeartbeatRow[] {
   const out: HeartbeatRow[] = [];

package/src/core/agents/rules/commit-conflict.ts

@@ -23,9 +23,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { coordEnv } from "../../../lib/env.ts";
-
-const DEFAULT_FRESHNESS_SECS = 600;
+import { coordFreshnessSeconds } from "../../config.ts";
+import { instanceHasLivePid } from "../state/pidmap.ts";
 
 interface PeerHeartbeat {
   instance_id: string;
@@ -86,7 +85,7 @@ export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): Co
   }
 
   const peers = readActivePeers(coordRoot);
-  const cutoffMs = Date.now() - freshnessSecs() * 1000;
+  const cutoffMs = Date.now() - coordFreshnessSeconds(coordRoot) * 1000;
   const stagedSet = new Set(req.staged_paths);
   const gitlinkSet = new Set(req.staged_gitlinks ?? []);
 
@@ -233,28 +232,7 @@ function isHolderSelfAttributed(
 }
 
 function holderHasLiveForeignPid(coordRoot: string, holderId: string): boolean {
-  const dir = join(coordRoot, ".harnery", "pid-map");
-  if (!existsSync(dir)) return false;
-  for (const f of readdirSync(dir)) {
-    let row = "";
-    try {
-      row = readFileSync(join(dir, f), "utf8").trim();
-    } catch {
-      continue;
-    }
-    const owner = row.split("\t")[0]?.trim() ?? "";
-    if (owner !== holderId) continue;
-    // Process still alive?
-    const pid = Number.parseInt(f, 10);
-    if (!Number.isFinite(pid)) continue;
-    try {
-      process.kill(pid, 0); // signal 0 = liveness probe
-      return true; // live foreign pid found
-    } catch {
-      // ESRCH (no such process): pid-map entry is stale, skip
-    }
-  }
-  return false;
+  return instanceHasLivePid(coordRoot, holderId);
 }
 
 function isPathCleanInHead(coordRoot: string, relPath: string): boolean {
@@ -290,13 +268,6 @@ function readActivePeers(coordRoot: string): PeerHeartbeat[] {
   return out;
 }
 
-function freshnessSecs(): number {
-  const raw = coordEnv("AGENT_FRESHNESS");
-  if (!raw) return DEFAULT_FRESHNESS_SECS;
-  const n = Number.parseInt(raw, 10);
-  return Number.isFinite(n) && n > 0 ? n : DEFAULT_FRESHNESS_SECS;
-}
-
 function shortName(peer: PeerHeartbeat): string {
   if (peer.name && peer.name.length > 0) return `agent-${peer.name}`;
   return `agent-${peer.instance_id.slice(0, 8)}`;

package/src/core/agents/session-events.ts

@@ -9,10 +9,10 @@
  */
 
 import { randomBytes } from "node:crypto";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 // Kept dependency-light: vendored verbatim into a downstream consumer, so no coordEnv import.
-import { normalizeHarness } from "./canonical-emit.ts";
+import { normalizeHarness, resolveEmitRoot } from "./canonical-emit.ts";
 import { emit } from "./events/emit.ts";
 
 /** Event types accepted by `writeSessionEvent`. Only the command stream +
@@ -38,25 +38,14 @@ export function sessionEventsPath(): string {
   // Explicit override (tests + non-monorepo invocations).
   const explicit = process.env.HARNERY_OUTPUT_SESSION_EVENTS;
   if (explicit) return explicit;
-  // Walk up looking for an EXISTING .harnery/ directory; only match dirs
-  // (submodule .git is a file/gitlink, and CLAUDE.md / AGENTS.md can
-  // proliferate per-subdirectory in many monorepos, so neither is a safe
-  // anchor). Don't reintroduce CLAUDE.md / .git as anchors, which creates
+  // Superproject-aware root resolution (git first, cwd walk fallback) via
+  // resolveEmitRoot. A plain cwd walk here mis-anchored to a NESTED
+  // `.harnery/` when the shell sat inside a submodule carrying its own
+  // (e.g. an embedded harnery checkout), silently splitting the event
+  // stream. Don't reintroduce CLAUDE.md / .git as anchors, which creates
   // stray .harnery/ dirs under submodule subtrees.
-  let dir = process.cwd();
-  for (let i = 0; i < 10; i++) {
-    const candidate = resolve(dir, ".harnery");
-    try {
-      if (existsSync(candidate) && statSync(candidate).isDirectory()) {
-        return resolve(candidate, "session-events.ndjson");
-      }
-    } catch {
-      /* keep walking */
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
+  const root = resolveEmitRoot();
+  if (root) return resolve(root, ".harnery", "session-events.ndjson");
   return resolve(process.env.HOME || "/tmp", ".harnery", "session-events.ndjson");
 }
 
@@ -75,25 +64,12 @@ export function newCmdId(): string {
  */
 export function readLastIntent(instanceId?: string): string | null {
   if (!instanceId) return null;
-  // Walk up from cwd looking for .harnery/, same resolution as
-  // sessionEventsPath() (only match existing directories).
-  let dir = process.cwd();
-  let agentsDir: string | null = null;
-  for (let i = 0; i < 10; i++) {
-    const candidate = resolve(dir, ".harnery");
-    try {
-      if (existsSync(candidate) && statSync(candidate).isDirectory()) {
-        agentsDir = candidate;
-        break;
-      }
-    } catch {
-      /* keep walking */
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  if (!agentsDir) return null;
+  // Same superproject-aware root resolution as sessionEventsPath(): the
+  // intent stamp is written by the PreToolUse hook into the SUPERPROJECT's
+  // .harnery/, so a nested-`.harnery/` cwd must not redirect the read.
+  const root = resolveEmitRoot();
+  if (!root) return null;
+  const agentsDir = resolve(root, ".harnery");
   const intentPath = resolve(agentsDir, `.last-intent.${instanceId}`);
   if (!existsSync(intentPath)) return null;
   try {

package/src/core/agents/state/heartbeat-projector.ts

@@ -146,7 +146,8 @@ function seed(ev: CanonicalEvent, coordRoot: string): V2Heartbeat {
     if (resolved) {
       hb.name = resolved.name;
       hb.kind = resolved.kind;
-      if (resolved.kind === "subagent") hb.agent_id = ev.instance_id;
+      hb.agent_id =
+        resolved.agent_id ?? (resolved.kind === "subagent" ? ev.instance_id : undefined);
     }
   } catch {
     /* name-history unavailable: seed stays nameless; sweep + render guards cope */
@@ -287,6 +288,14 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
       hb.last_status_at = ev.ts;
       break;
 
+    case "identity.assumed": {
+      const name = pickStr(d, "name");
+      const agentId = pickStr(d, "agent_id");
+      if (name) hb.name = name;
+      if (agentId) hb.agent_id = agentId;
+      break;
+    }
+
     case "state.presence_change": {
       const to = pickStr(d, "to");
       if (to === "mobile" || to === "office") hb.presence = to;

package/src/core/agents/state/heartbeat-writer.ts

@@ -311,8 +311,9 @@ export function healHeartbeat(
     if (resolved) {
       name = resolved.name;
       kind = resolved.kind;
-      // subagent kind: agent_id == instance_id. Else (session/transient): no id stamp.
-      if (resolved.kind === "subagent") agentId = instanceId;
+      // An explicitly assumed session carries its durable persona UUID in
+      // name-history. Native subagents continue to use instance_id.
+      agentId = resolved.agent_id ?? (resolved.kind === "subagent" ? instanceId : "");
     }
   } catch {
     /* names module unavailable, fall back to empty */

package/src/core/agents/state/names.ts

@@ -8,9 +8,14 @@
  * Durable persistence: `.harnery/.name-history` (JSONL, one row per assignment)
  * + `.harnery/.name-counter` (current counter, atomic temp+rename).
  *
- * Recreation rule (mirrors v1):
- *   1. Own instance_id in name-history → (original name, original kind)
- *   2. session_id in name-history (owner != session) → (parent's name, "transient")
+ * Recreation rule:
+ *   1. Own instance_id in name-history → latest (name, kind, agent_id)
+ *   2. session_id in name-history (owner != session) → latest parent's
+ *      (name, agent_id) with kind="transient"
+ *
+ * Multiple rows for one instance are intentional. `identity assume` appends a
+ * new binding instead of rewriting history; readers therefore resolve from the
+ * end of the file. Older one-row histories retain their original behavior.
  *   3. Else: new assignment, consume a counter slot.
  */
 
@@ -297,11 +302,16 @@ if (COORD_NAMES.length !== 260) {
 
 export type NameKind = "session" | "subagent" | "transient";
 
-interface NameHistoryRow {
+export interface NameHistoryRow {
   instance_id: string;
   name: string;
   kind: NameKind;
   ts: string;
+  /** Durable persona UUID. Present after `agents identity assume`. */
+  agent_id?: string;
+  /** Audit marker distinguishing an explicit role adoption from pool assignment. */
+  source?: "pool" | "identity.assume";
+  previous_name?: string;
 }
 
 function atomicWrite(path: string, content: string): void {
@@ -351,19 +361,29 @@ export function resolveName(
   coordRoot: string,
   instanceId: string,
   sessionId?: string,
-): { name: string; kind: NameKind } | null {
+): { name: string; kind: NameKind; agent_id?: string } | null {
   const history = readHistory(coordRoot);
 
-  for (const row of history) {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const row = history[i]!;
     if (row.instance_id === instanceId) {
-      return { name: row.name, kind: row.kind };
+      return {
+        name: row.name,
+        kind: row.kind,
+        ...(row.agent_id ? { agent_id: row.agent_id } : {}),
+      };
     }
   }
 
   if (sessionId && sessionId !== instanceId) {
-    for (const row of history) {
+    for (let i = history.length - 1; i >= 0; i--) {
+      const row = history[i]!;
       if (row.instance_id === sessionId) {
-        return { name: row.name, kind: "transient" };
+        return {
+          name: row.name,
+          kind: "transient",
+          ...(row.agent_id ? { agent_id: row.agent_id } : {}),
+        };
       }
     }
   }
@@ -371,6 +391,44 @@ export function resolveName(
   return null;
 }
 
+export interface NameAssumptionResult {
+  changed: boolean;
+  previous: { name: string; kind: NameKind; agent_id?: string } | null;
+  current: { name: string; kind: NameKind; agent_id: string };
+}
+
+/**
+ * Append an explicit instance → durable-persona binding. Latest-row-wins makes
+ * this auditable and retry-safe without mutating prior assignment history.
+ */
+export function recordNameAssumption(
+  coordRoot: string,
+  instanceId: string,
+  name: string,
+  agentId: string,
+  kind: NameKind = "session",
+): NameAssumptionResult {
+  const previous = resolveName(coordRoot, instanceId);
+  const current = { name, kind, agent_id: agentId };
+  if (
+    previous?.name === current.name &&
+    previous.kind === current.kind &&
+    previous.agent_id === current.agent_id
+  ) {
+    return { changed: false, previous, current };
+  }
+  appendHistory(coordRoot, {
+    instance_id: instanceId,
+    name,
+    kind,
+    agent_id: agentId,
+    source: "identity.assume",
+    previous_name: previous?.name,
+    ts: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+  });
+  return { changed: true, previous, current };
+}
+
 /**
  * Assign a name to <instanceId> with the given <kind>. Counter-consuming when
  * the owner is new. Idempotent: returns existing name on resume.
@@ -393,6 +451,7 @@ export function assignName(coordRoot: string, instanceId: string, kind: NameKind
     instance_id: instanceId,
     name,
     kind,
+    source: "pool",
     ts: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
   });
   return name;

package/src/core/agents/state/pidmap.ts

@@ -1,5 +1,5 @@
 /**
- * Pid-map writer.
+ * Pid-map writer + liveness helpers.
  *
  * Per-harness pid-map at `.harnery/pid-map/<pid>` containing
  * `<instance_id>\t<platform>`. `harn agents whoami` walks ppid up 20 hops looking
@@ -8,7 +8,15 @@
  * Atomic temp+rename. Idempotent: re-writing the same row is a no-op.
  */
 
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join } from "node:path";
 
 function atomicWrite(path: string, content: string): void {
@@ -36,3 +44,52 @@ export function writePidmapRow(
   }
   atomicWrite(path, row);
 }
+
+/** True when any pid-map row for `instanceId` still belongs to a live process. */
+export function instanceHasLivePid(coordRoot: string, instanceId: string): boolean {
+  const dir = join(coordRoot, ".harnery", "pid-map");
+  if (!existsSync(dir)) return false;
+  for (const f of readdirSync(dir)) {
+    let row = "";
+    try {
+      row = readFileSync(join(dir, f), "utf8").trim();
+    } catch {
+      continue;
+    }
+    const owner = row.split("\t")[0]?.trim() ?? "";
+    if (owner !== instanceId) continue;
+    const pid = Number.parseInt(f, 10);
+    if (!Number.isFinite(pid)) continue;
+    try {
+      process.kill(pid, 0); // signal 0 = liveness probe
+      return true;
+    } catch {
+      // ESRCH (no such process): pid-map entry is stale, keep scanning
+    }
+  }
+  return false;
+}
+
+/** Drop every pid-map row owned by `instanceId`. Returns how many files were removed. */
+export function removePidmapRowsForInstance(coordRoot: string, instanceId: string): number {
+  const dir = join(coordRoot, ".harnery", "pid-map");
+  if (!existsSync(dir)) return 0;
+  let removed = 0;
+  for (const f of readdirSync(dir)) {
+    let row = "";
+    try {
+      row = readFileSync(join(dir, f), "utf8").trim();
+    } catch {
+      continue;
+    }
+    const owner = row.split("\t")[0]?.trim() ?? "";
+    if (owner !== instanceId) continue;
+    try {
+      unlinkSync(join(dir, f));
+      removed += 1;
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
+  return removed;
+}

package/src/core/agents/state/stale-sweep.ts

@@ -5,17 +5,16 @@
  * Fires at session.start to clean up crashed-peer detritus before the new
  * session's UX layer reads peer state.
  *
- * Freshness threshold defaults to 600s; configurable via
- * HARNERY_AGENT_COORD_FRESHNESS env var.
+ * Freshness threshold defaults to 600s; configurable via the
+ * HARNERY_AGENT_COORD_FRESHNESS env var or `.harnery/config.jsonc`
+ * `coord.freshness_seconds` (see `coordFreshnessSeconds`).
  */
 
 import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { coordEnv } from "../../../lib/env.ts";
+import { coordFreshnessSeconds } from "../../config.ts";
 import { emit } from "../events/emit.ts";
 
-const DEFAULT_FRESHNESS_SECS = 600;
-
 /** platform → harness, for the swept-event envelope (mirrors heartbeat-writer's harnessOf). */
 function harnessFromPlatform(platform: unknown): "claude-code" | "cursor" | "codex" {
   if (platform === "cursor") return "cursor";
@@ -65,13 +64,9 @@ export function staleSweep(coordRoot: string): {
   let pidmapsRemoved = 0;
   let peerHashesRemoved = 0;
 
-  const freshness = Number.parseInt(
-    coordEnv("AGENT_COORD_FRESHNESS") ?? String(DEFAULT_FRESHNESS_SECS),
-    10,
-  );
+  const freshness = coordFreshnessSeconds(coordRoot);
   const nowSec = Math.floor(Date.now() / 1000);
-  const cutoff =
-    nowSec - (Number.isFinite(freshness) && freshness > 0 ? freshness : DEFAULT_FRESHNESS_SECS);
+  const cutoff = nowSec - freshness;
 
   // 1. Prune stale heartbeats from the canonical `.harnery/active/` dir.
   //