harnery 0.9.0 → 0.10.0

package/src/commands/presence.ts

@@ -1,11 +1,19 @@
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
+import { monorepoRoot } from "../core/agents/coord-client.ts";
 import {
   emitCanonical,
   normalizeHarness,
   readHeartbeat,
   resolveOwner,
 } from "../core/agents/index.ts";
+import {
+  fetchPresence,
+  publishPresence,
+  readRemoteMachines,
+  relayDaemonStatus,
+  runRelayDaemon,
+} from "../core/presence/index.ts";
 import {
   ageSeconds,
   applyDetection,
@@ -18,17 +26,24 @@ import {
 } from "../lib/presence.ts";
 
 /**
- * `presence`: mobile/office state for agents (~/.claude/presence).
+ * `presence`: two related surfaces under one name.
+ *
+ *   1. Mobile/office state for agents (~/.claude/presence): get / set /
+ *      clear / detect. The state file path is Claude-Code-specific but the
+ *      logic is generic.
+ *   2. Cross-machine session presence (ADR 0016): publish / fetch / peers —
+ *      the git-refs transport that lets sessions on other machines show up
+ *      in the peer table via `refs/harnery/presence/<machine>` on origin.
  *
  * Uses the injected EmitContext so composed and standalone consumers share
- * one code path. The state file path is Claude-Code-specific (lives under
- * ~/.claude/) but the detect/set/clear logic is generic: any agent harness
- * can adopt the same convention.
+ * one code path.
  */
 export function registerPresenceCommand(program: Command, emit: EmitContext): void {
   const cmd = program
     .command("presence")
-    .description("Mobile/office state for agents (~/.claude/presence)")
+    .description(
+      "Presence: mobile/office state (get/set/clear/detect) + cross-machine session presence (publish/fetch/peers)",
+    )
     .action(() => {
       printStatus(emit);
     });
@@ -83,6 +98,88 @@ export function registerPresenceCommand(program: Command, emit: EmitContext): vo
       });
     });
 
+  // ---- cross-machine session presence (ADR 0016) ----
+
+  cmd
+    .command("publish")
+    .description(
+      "Publish this machine's live sessions to refs/harnery/presence/<machine> on origin. " +
+        "Change-batched with a keepalive; --force pushes regardless. Synchronous (errors report).",
+    )
+    .option("--force", "Push even if unchanged / within throttle windows")
+    .action((opts: { force?: boolean }) => {
+      const root = requireRoot(emit);
+      const r = publishPresence(root, { force: opts.force, sync: true });
+      if (r.status === "error") {
+        emit.error({ code: "publish_failed", message: r.error });
+        process.exit(1);
+      }
+      emit.data(r);
+    });
+
+  cmd
+    .command("fetch")
+    .description(
+      "Fetch peer machines' presence refs from origin (throttled; --force bypasses). Synchronous.",
+    )
+    .option("--force", "Fetch even within the throttle interval")
+    .action((opts: { force?: boolean }) => {
+      const root = requireRoot(emit);
+      const r = fetchPresence(root, { force: opts.force, sync: true });
+      if (r.status === "error") {
+        emit.error({ code: "fetch_failed", message: r.error });
+        process.exit(1);
+      }
+      emit.data(r);
+    });
+
+  cmd
+    .command("relay-daemon")
+    .description(
+      "Run the relay client daemon in the foreground (normally spawned detached by the hooks " +
+        "when presence.relay is configured; holds the WebSocket, publishes on heartbeat change, " +
+        "caches peers' blobs for the renderers, exits when the machine goes idle).",
+    )
+    .action(async () => {
+      const root = requireRoot(emit);
+      process.exit(await runRelayDaemon(root));
+    });
+
+  cmd
+    .command("peers")
+    .description(
+      "Show sessions on other machines (merged from presence refs + the relay daemon's cache)",
+    )
+    .option("--json", "JSON output")
+    .option("--stale", "Include machines past the stale window")
+    .action((opts: { json?: boolean; stale?: boolean }) => {
+      const root = requireRoot(emit);
+      const machines = readRemoteMachines(root, { includeStale: opts.stale });
+      const daemon = relayDaemonStatus(root);
+      if (opts.json) emit.config({ format: "json" });
+      if (opts.json || !process.stdout.isTTY) {
+        emit.data({ machines, relay_daemon: daemon });
+        return;
+      }
+      emit.text(
+        daemon.running
+          ? `relay daemon: running (pid ${daemon.pid}, ${daemon.url})\n`
+          : "relay daemon: not running (git-refs transport only)\n",
+      );
+      if (machines.length === 0) {
+        emit.text("no remote sessions known (try `presence fetch --force`)\n");
+        return;
+      }
+      for (const m of machines) {
+        emit.text(`${m.machine}  (published ${formatAge(m.age_secs)} ago)\n`);
+        for (const a of m.agents) {
+          const task = a.task ? `  "${a.task.slice(0, 70)}"` : "";
+          const files = a.files_touched?.length ? `  [${a.files_touched.length} files]` : "";
+          emit.text(`  agent-${a.name ?? a.instance_id.slice(0, 8)}${task}${files}\n`);
+        }
+      }
+    });
+
   cmd
     .command("detect")
     .description(
@@ -111,6 +208,15 @@ export function registerPresenceCommand(program: Command, emit: EmitContext): vo
     });
 }
 
+function requireRoot(emit: EmitContext): string {
+  const root = monorepoRoot();
+  if (!root) {
+    emit.error({ code: "not_in_repo", message: "coord root not found (no .harnery/ upward)" });
+    process.exit(1);
+  }
+  return root;
+}
+
 function printStatus(emit: EmitContext): void {
   const r = readPresence();
   emit.data({

package/src/commands/relay.ts

@@ -0,0 +1,160 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import { MAX_FRAME_BYTES } from "../core/presence/relay-protocol.ts";
+
+/**
+ * `relay serve`: the Bun self-host of the presence relay (ADR 0016 phase 2).
+ * Same wire protocol as the Cloudflare Durable Objects host in relay/worker/ —
+ * one in-memory room per opaque room id, warm-join cache, fan-out, rate
+ * limits. For teams who'd rather run their own box than use the public
+ * relay.harnery.com; point clients at it via `.harnery/config.jsonc` →
+ * `{ "presence": { "relay": "ws://host:port" } }`.
+ *
+ * Bun-only (Bun.serve WebSockets), like `harn tunnel` — fails fast with a
+ * clear message on a Bun-free host.
+ */
+
+const MAX_SOCKETS_PER_ROOM = 64;
+const RATE_BURST = 10;
+const RATE_REFILL_MS = 2000;
+const CACHE_TTL_MS = 15 * 60 * 1000;
+const ROOM_ID_RE = /^[0-9a-f]{32}$/;
+
+interface RoomState {
+  sockets: Set<unknown>;
+  cache: Map<string, { raw: string; at: number }>;
+}
+
+interface SocketData {
+  roomId: string;
+  bucketTokens: number;
+  bucketAt: number;
+}
+
+/** Start the relay server. Exported for in-process integration tests. */
+export function startRelayServer(port: number): { port: number; stop: () => void } {
+  if (typeof Bun === "undefined" || typeof Bun.serve !== "function") {
+    throw new Error("relay serve requires Bun (Bun.serve WebSockets)");
+  }
+  const rooms = new Map<string, RoomState>();
+
+  const roomOf = (roomId: string): RoomState => {
+    let r = rooms.get(roomId);
+    if (!r) {
+      r = { sockets: new Set(), cache: new Map() };
+      rooms.set(roomId, r);
+    }
+    return r;
+  };
+
+  const server = Bun.serve<SocketData>({
+    port,
+    fetch(req, srv) {
+      const url = new URL(req.url);
+      if (url.pathname === "/" || url.pathname === "/healthz") {
+        return Response.json({ ok: true, service: "harnery-presence-relay", v: 1 });
+      }
+      const m = /^\/v1\/room\/([0-9a-f]{32})$/.exec(url.pathname);
+      if (!m || !ROOM_ID_RE.test(m[1]!)) return new Response("not found", { status: 404 });
+      const room = roomOf(m[1]!);
+      if (room.sockets.size >= MAX_SOCKETS_PER_ROOM) {
+        return new Response("room full", { status: 429 });
+      }
+      const ok = srv.upgrade(req, {
+        data: { roomId: m[1]!, bucketTokens: RATE_BURST, bucketAt: Date.now() },
+      });
+      return ok ? undefined : new Response("expected websocket", { status: 426 });
+    },
+    websocket: {
+      open(ws) {
+        const room = roomOf(ws.data.roomId);
+        room.sockets.add(ws);
+        const now = Date.now();
+        for (const [sender, entry] of room.cache) {
+          if (now - entry.at > CACHE_TTL_MS) {
+            room.cache.delete(sender);
+            continue;
+          }
+          ws.send(entry.raw);
+        }
+        ws.send(JSON.stringify({ t: "hello", peers: room.sockets.size }));
+      },
+      message(ws, message) {
+        if (typeof message !== "string" || message.length > MAX_FRAME_BYTES) return;
+        // Rate limit (token bucket per socket).
+        const d = ws.data;
+        const now = Date.now();
+        const refill = Math.floor((now - d.bucketAt) / RATE_REFILL_MS);
+        if (refill > 0) {
+          d.bucketTokens = Math.min(RATE_BURST, d.bucketTokens + refill);
+          d.bucketAt = now;
+        }
+        if (d.bucketTokens <= 0) return;
+        d.bucketTokens -= 1;
+
+        let frame: { t?: unknown; sender?: unknown };
+        try {
+          frame = JSON.parse(message) as typeof frame;
+        } catch {
+          return;
+        }
+        if (
+          frame.t !== "pub" ||
+          typeof frame.sender !== "string" ||
+          !/^[0-9a-f]+$/.test(frame.sender) ||
+          frame.sender.length > 64
+        ) {
+          return;
+        }
+        const room = roomOf(d.roomId);
+        room.cache.set(frame.sender, { raw: message, at: now });
+        for (const peer of room.sockets) {
+          if (peer === ws) continue;
+          try {
+            (peer as { send(m: string): void }).send(message);
+          } catch {
+            /* dead socket */
+          }
+        }
+      },
+      close(ws) {
+        const room = rooms.get(ws.data.roomId);
+        if (!room) return;
+        room.sockets.delete(ws);
+        if (room.sockets.size === 0 && room.cache.size === 0) rooms.delete(ws.data.roomId);
+      },
+    },
+  });
+
+  return {
+    port: server.port ?? port,
+    stop: () => server.stop(true),
+  };
+}
+
+export function registerRelayCommand(program: Command, emit: EmitContext): void {
+  const cmd = program
+    .command("relay")
+    .description("Self-host the presence relay (see also relay/worker/ for the Cloudflare host)");
+
+  cmd
+    .command("serve")
+    .description(
+      "Run the presence relay on this machine (Bun-only; same protocol as relay/worker/)",
+    )
+    .option("--port <n>", "Port to listen on", "8787")
+    .action((opts: { port: string }) => {
+      let server: { port: number; stop: () => void };
+      try {
+        server = startRelayServer(Number.parseInt(opts.port, 10));
+      } catch (e) {
+        emit.error({
+          code: "relay_serve_failed",
+          message: e instanceof Error ? e.message : String(e),
+        });
+        process.exit(1);
+      }
+      emit.log(`presence relay listening on :${server.port} (ws path: /v1/room/<room-id>)`, "info");
+      // Foreground service: run until interrupted.
+    });
+}

package/src/commands/sync.ts

@@ -25,6 +25,7 @@ import os from "node:os";
 import path from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
+import { syncJsoncConfig } from "../core/config.ts";
 
 // What we sync. Anything matching one of these (relative to .harnery/) is
 // considered part of the sync set. Everything else stays local-only.
@@ -40,9 +41,12 @@ function configPath(): string {
 }
 
 function loadConfig(): SyncConfig | null {
+  // Precedence: env → .harnery/config.jsonc `sync` → ~/.config/harnery/sync.json.
   const envRemote = process.env.HARNERY_SYNC_REMOTE;
   const envPrefix = process.env.HARNERY_SYNC_PREFIX ?? "harnery";
   if (envRemote) return { remote: envRemote, prefix: envPrefix };
+  const jsonc = syncJsoncConfig();
+  if (jsonc) return jsonc;
   const p = configPath();
   if (!existsSync(p)) return null;
   try {

package/src/commands/workflow.ts

@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { workflowSubscriptionOnly } from "../core/config.ts";
+import { createBuiltinHarnessRegistry } from "../core/harnesses/index.ts";
 import { findCoordRoot } from "../core/hooks/resolve/coord-root.ts";
 
 /**
@@ -24,9 +25,9 @@ interface WorkflowRunOpts {
   json?: boolean;
 }
 
-const HARNESSES = ["claude-code", "codex", "cursor"] as const;
-
 export function registerWorkflowCommand(program: Command, emit: EmitContext): void {
+  const registry = createBuiltinHarnessRegistry();
+  const harnesses = registry.ids();
   const workflow = program
     .command("workflow")
     .description("Run bounded, schema-gated multi-subagent workflow scripts.");
@@ -42,7 +43,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
     .option("--cwd <dir>", "Working directory children spawn in (default: coord root)")
     .option(
       "--harness <name>",
-      `Default harness for agent() calls: ${HARNESSES.join(" | ")} (default claude-code); scripts can override per agent via opts.harness`,
+      `Default harness for agent() calls: ${harnesses.join(" | ")} (default claude-code); scripts can override per agent via opts.harness`,
     )
     .option(
       "--resume-from <run-id>",
@@ -68,10 +69,10 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
         });
         process.exit(1);
       }
-      if (opts.harness && !HARNESSES.includes(opts.harness as (typeof HARNESSES)[number])) {
+      if (opts.harness && !registry.get(opts.harness)) {
         emit.error({
           code: "bad_harness",
-          message: `unknown harness "${opts.harness}" (expected: ${HARNESSES.join(" | ")})`,
+          message: `unknown harness "${opts.harness}" (expected: ${harnesses.join(" | ")})`,
         });
         process.exit(1);
       }
@@ -87,21 +88,11 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
         process.exit(1);
       }
       try {
-        const [{ runWorkflow }, { claudeCodeSpawner }, { codexSpawner }, { cursorSpawner }] =
-          await Promise.all([
-            import("../core/workflow/engine.ts"),
-            import("../core/workflow/spawn-claude.ts"),
-            import("../core/workflow/spawn-codex.ts"),
-            import("../core/workflow/spawn-cursor.ts"),
-          ]);
+        const { runWorkflow } = await import("../core/workflow/engine.ts");
         const report = await runWorkflow(script, {
           coordRoot,
-          spawners: {
-            "claude-code": claudeCodeSpawner,
-            codex: codexSpawner,
-            cursor: cursorSpawner,
-          },
-          defaultHarness: opts.harness as "claude-code" | "codex" | "cursor" | undefined,
+          spawners: registry.spawners(),
+          defaultHarness: opts.harness,
           resumeFrom: opts.resumeFrom,
           subscriptionOnly,
           allowApiBilling: opts.allowApiBilling,

package/src/core/agents/canonical-emit.ts

@@ -12,6 +12,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { monorepoRoot } from "./coord-client.ts";
 
 export interface CanonicalEmitInput {
   type: string;
@@ -24,8 +25,37 @@ export interface CanonicalEmitInput {
   parentTurnId?: string;
 }
 
+/**
+ * Resolve the coord root for a canonical emit.
+ *
+ * Order: explicit `HARNERY_COORD_ROOT_OVERRIDE` → git-superproject-aware
+ * `monorepoRoot()` (must actually carry `.harnery/`) → cwd walk (non-git
+ * hosts). The git-aware step is load-bearing: a shell cd'd into a nested
+ * directory that carries its own `.harnery/` (e.g. an embedded harnery
+ * checkout) made the old cwd-walk resolve the NESTED root, from which
+ * `<root>/harnery/bin/agent-coord` doesn't exist — so `agents status` /
+ * `set-task` emits silently vanished and the Stop-hook's rule 1/3
+ * (`state.status_checked` in-turn) blocked turns that had done the ritual.
+ * Same bug class as the coordHelperOpts root-pin fix; this closes the
+ * emitCanonical instance of it.
+ */
+export function resolveEmitRoot(start: string = process.cwd()): string | null {
+  const override = process.env.HARNERY_COORD_ROOT_OVERRIDE;
+  if (override) return override;
+  // Memoized per start-dir: the session-tee middleware resolves once per
+  // emitted event, and monorepoRoot() spawns git — cache so a streaming
+  // command doesn't pay 1-3 subprocess spawns per output line.
+  if (cachedRoot && cachedRoot.start === start) return cachedRoot.root;
+  const gitRoot = monorepoRoot();
+  const root = gitRoot && existsSync(join(gitRoot, ".harnery")) ? gitRoot : findRepoRoot(start);
+  cachedRoot = { start, root };
+  return root;
+}
+
+let cachedRoot: { start: string; root: string | null } | undefined;
+
 export function emitCanonical(input: CanonicalEmitInput): void {
-  const root = findRepoRoot();
+  const root = resolveEmitRoot();
   if (!root) return;
   const binary = resolve(root, "harnery", "bin", "agent-coord");
   if (!existsSync(binary)) return;
@@ -46,11 +76,19 @@ export function emitCanonical(input: CanonicalEmitInput): void {
     if (input.turnId) args.push("--turn-id", input.turnId);
     if (input.parentSessionId) args.push("--parent-session-id", input.parentSessionId);
     if (input.parentTurnId) args.push("--parent-turn-id", input.parentTurnId);
-    spawnSync(binary, args, {
+    // Pin cwd + HARNERY_COORD_ROOT_OVERRIDE so the child writes to the SAME
+    // stream we resolved, regardless of where the caller's shell is cd'd.
+    const result = spawnSync(binary, args, {
       encoding: "utf8",
       stdio: "ignore",
       timeout: 3000,
+      cwd: root,
+      env: { ...process.env, HARNERY_COORD_ROOT_OVERRIDE: root },
     });
+    if (result.error || result.status !== 0) {
+      const why = result.error ? result.error.message : `exit ${result.status}`;
+      process.stderr.write(`emitCanonical: ${input.type} emit failed (${why})\n`); // lint-ok-emission: soft-fail diagnostic promised by the module doc; silent drops cost blocked turns
+    }
   } catch {
     /* never break the caller */
   }
@@ -66,7 +104,7 @@ export function normalizeHarness(platform: string | undefined): "claude-code" |
   return "claude-code";
 }
 
-function findRepoRoot(start: string = process.cwd()): string | null {
+function findRepoRoot(start: string): string | null {
   let dir = resolve(start);
   while (true) {
     if (existsSync(join(dir, ".harnery"))) return dir;

package/src/core/agents/cli.ts

@@ -210,8 +210,10 @@ async function handleStateAction(root: string, action: string, rest: string[]):
       const task = args.join(" ");
       const hb = writer.setTask(root, owner, task);
       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 .harnery/active/${owner}.json\n`,
+          `agent-coord set-task: no heartbeat at ${root}/.harnery/active/${owner}.json\n`,
         );
         return 1;
       }
@@ -716,7 +718,7 @@ async function handleResolveName(root: string, rest: string[]): Promise<number>
     return 0;
   }
   process.stdout.write(
-    `${JSON.stringify({ instance_id: owner, name: resolved.name, kind: resolved.kind })}\n`,
+    `${JSON.stringify({ instance_id: owner, name: resolved.name, kind: resolved.kind, agent_id: resolved.agent_id ?? null })}\n`,
   );
   return 0;
 }

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

@@ -36,6 +36,7 @@ import {
 import { join } from "node:path";
 
 import { coordEnv } from "../../../lib/env.ts";
+import { type RemoteMachine, readRemoteMachines } from "../../presence/index.ts";
 import { formatPendingCouncils } from "./session-context.ts";
 
 interface HeartbeatRow {
@@ -170,7 +171,10 @@ function computePeerTableIfChanged(
     if (!hb?.instance_id || hb.instance_id === selfInstanceId) continue;
     peers.push(hb);
   }
-  if (peers.length === 0) return "";
+  // Cross-machine presence (ADR 0016): sessions on other machines, from the
+  // locally-fetched presence refs. Advisory (no claim blocking in v1).
+  const remote = readRemoteMachinesSafe(coordRoot);
+  if (peers.length === 0 && remote.length === 0) return "";
 
   // Build hash basis: sorted-by-instance_id projection of semantically-relevant fields.
   const basis = peers
@@ -184,14 +188,27 @@ function computePeerTableIfChanged(
       platform: p.platform ?? null,
     }))
     .sort((a, b) => (a.instance_id ?? "").localeCompare(b.instance_id ?? ""));
-  const newHash = sha256Hex16(JSON.stringify(basis));
+  // Remote basis: machine + per-agent identity/task/files (published_at is
+  // excluded — a keepalive re-publish alone shouldn't re-emit the table).
+  const remoteBasis = remote.map((m) => ({
+    machine: m.machine,
+    agents: m.agents.map((a) => ({
+      instance_id: a.instance_id,
+      name: a.name ?? null,
+      task: a.task ?? null,
+      files_touched: Array.from(a.files_touched ?? []).sort(),
+    })),
+  }));
+  const newHash = sha256Hex16(JSON.stringify({ local: basis, remote: remoteBasis }));
 
   const hashFile = join(coordRoot, ".harnery", `.last-peer-hash.${selfInstanceId}`);
   const oldHash = safeRead(hashFile);
   if (oldHash && oldHash === newHash) return "";
 
   // Render peer table via the same formatter used at SessionStart.
-  const table = formatPeerTable(peers, mySessionId);
+  const local = formatPeerTable(peers, mySessionId);
+  const remoteTable = formatRemoteTable(remote);
+  const table = [local, remoteTable].filter(Boolean).join("\n\n");
   if (!table) return "";
 
   // Persist hash atomically (temp + rename, same convention as other coord writes).
@@ -199,6 +216,34 @@ function computePeerTableIfChanged(
   return table;
 }
 
+/** readRemoteMachines with a local failure guard (rendering must never throw). */
+function readRemoteMachinesSafe(coordRoot: string): RemoteMachine[] {
+  try {
+    return readRemoteMachines(coordRoot);
+  } catch {
+    return [];
+  }
+}
+
+/** Render sessions on other machines (presence transport) as a subtable. */
+function formatRemoteTable(remote: RemoteMachine[]): string {
+  if (remote.length === 0) return "";
+  const nowSec = Math.floor(Date.now() / 1000);
+  const lines: string[] = [];
+  for (const m of remote) {
+    for (const a of m.agents.slice(0, 10)) {
+      lines.push(
+        formatRow(
+          { ...a, display_files: Array.from(a.files_touched ?? []).sort() },
+          nowSec,
+        ).replace(/^ {2}- (agent-[^ ]+)/, `  - $1 @${m.machine}`),
+      );
+    }
+  }
+  if (lines.length === 0) return "";
+  return `Sessions on other machines (advisory, via presence refs):\n${lines.join("\n")}`;
+}
+
 function computeCouncilPendingIfChanged(
   coordRoot: string,
   selfInstanceId: string,

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[] = [];