harnery 0.42.0 → 0.44.0

package/src/commands/web-fetch.ts

@@ -16,9 +16,11 @@ import type { EmitContext } from "../commander.ts";
  * harnery repo at the *matching version tag* into a cache dir and install the
  * web app's deps. Subsequent runs reuse the cache.
  *
- * The only thing `web/` pulls from `src/` is `harnery/core/journal` (a single,
- * dependency-free module), so the install is `web/` deps only: no root install,
- * no Playwright browser download.
+ * `web/` imports readers from `src/`, and `web/next.config.ts` resolves the
+ * root `playwright` package, so the install covers the repository root and
+ * then `web/`. Installing the `playwright` package downloads no browsers.
+ * Installing `web/` alone left `harn web up` failing with
+ * `Cannot find module 'playwright/package.json'`.
  */
 
 const DEFAULT_REPO_URL = "https://github.com/ryanjkelly/harnery.git";
@@ -53,8 +55,8 @@ function webCacheRoot(ref: string): string {
 }
 
 /** bun if available (preferred), else npm. Both support `<runner> install` and `<runner> run <script>`. */
-export function webRunner(): "bun" | "npm" {
-  const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
+export function webRunner(spawn: typeof spawnSync = spawnSync): "bun" | "npm" {
+  const r = spawn("bun", ["--version"], { stdio: "ignore" });
   return r.status === 0 ? "bun" : "npm";
 }
 
@@ -63,14 +65,20 @@ export function webRunner(): "bun" | "npm" {
  * its path, fetching (clone + install) on first use. Returns null on failure
  * (after emitting an actionable error).
  */
-export function lazyFetchWebRoot(emit: EmitContext): string | null {
+export function lazyFetchWebRoot(
+  emit: EmitContext,
+  spawn: typeof spawnSync = spawnSync,
+): string | null {
   const { version, repoUrl } = readPkg();
   const ref = resolveRef(version);
   const cacheRoot = webCacheRoot(ref);
   const webDir = path.join(cacheRoot, "web");
 
-  // node_modules in the cached web/ is the "fetched + installed" marker.
-  if (existsSync(path.join(webDir, "node_modules"))) {
+  // node_modules in both the cached root and web/ is the "fetched + installed" marker.
+  if (
+    existsSync(path.join(cacheRoot, "node_modules")) &&
+    existsSync(path.join(webDir, "node_modules"))
+  ) {
     emit.log(`harn web · using cached dashboard (${ref})`, "info");
     return webDir;
   }
@@ -85,7 +93,7 @@ export function lazyFetchWebRoot(emit: EmitContext): string | null {
   if (existsSync(cacheRoot)) rmSync(cacheRoot, { recursive: true, force: true });
   mkdirSync(path.dirname(cacheRoot), { recursive: true });
 
-  const clone = spawnSync("git", ["clone", "--depth", "1", "--branch", ref, repoUrl, cacheRoot], {
+  const clone = spawn("git", ["clone", "--depth", "1", "--branch", ref, repoUrl, cacheRoot], {
     stdio: "inherit",
   });
   if (clone.status !== 0) {
@@ -100,16 +108,19 @@ export function lazyFetchWebRoot(emit: EmitContext): string | null {
     return null;
   }
 
-  const runner = webRunner();
-  emit.log(`harn web · installing dashboard deps (${runner} install in web/)`, "info");
-  const install = spawnSync(runner, ["install"], { cwd: webDir, stdio: "inherit" });
-  if (install.status !== 0) {
-    emit.error({
-      code: "web_fetch_failed",
-      message: `${runner} install in ${webDir} failed (status ${install.status})`,
-      hint: `Try manually: cd ${webDir} && ${runner} install`,
-    });
-    return null;
+  const runner = webRunner(spawn);
+  for (const dir of [cacheRoot, webDir]) {
+    const where = dir === webDir ? "web/" : "the harnery root";
+    emit.log(`harn web · installing dashboard deps (${runner} install in ${where})`, "info");
+    const install = spawn(runner, ["install"], { cwd: dir, stdio: "inherit" });
+    if (install.status !== 0) {
+      emit.error({
+        code: "web_fetch_failed",
+        message: `${runner} install in ${dir} failed (status ${install.status})`,
+        hint: `Try manually: cd ${dir} && ${runner} install`,
+      });
+      return null;
+    }
   }
 
   emit.log(`harn web · dashboard ready (cached at ${webDir})`, "info");

package/src/commands/web.ts

@@ -82,11 +82,17 @@ export function nodeOptionsWithHeapCap(mb: number): string | undefined {
   return `${inherited} --max-old-space-size=${mb}`.trim();
 }
 
-/** Preload the request diagnostics hook without replacing Next's HTTP server. */
+/**
+ * Preload the dashboard's server hooks (keep-alive and request diagnostics)
+ * without replacing Next's HTTP server. NODE_OPTIONS reaches the child that
+ * `next dev` forks, but Next re-parses every `--import` into one value, so
+ * this names the single combined preload; a second, different `--import`
+ * would collapse into an unloadable path (web/server-preload.mjs).
+ */
 export function nodeOptionsWithWebDiagnostics(webDir: string, mb: number): string {
   const inherited = nodeOptionsWithHeapCap(mb) ?? "";
-  if (inherited.includes("server-performance.mjs")) return inherited;
-  const preload = pathToFileURL(path.join(webDir, "server-performance.mjs")).href;
+  if (inherited.includes("server-preload.mjs")) return inherited;
+  const preload = pathToFileURL(path.join(webDir, "server-preload.mjs")).href;
   return `${inherited} --import=${preload}`.trim();
 }
 

package/src/commands/workflow.ts

@@ -618,11 +618,11 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
   workflow
     .command("reclaim <run-id>")
     .description(
-      "Resolve a workspace preserved because it was dirty: salvage the work to its branch, then release.",
+      "Preview reclaim of an inactive owned workspace, or confirm salvage or discard and release.",
     )
     .option("--yes", "Confirm that this commits or discards uncommitted work, then releases")
     .option("--discard", "Throw the uncommitted work away instead of salvaging it")
-    .option("--json", "Emit the reclaim preparation and cleanup result as JSON")
+    .option("--json", "Emit the reclaim preview or confirmed result as JSON")
     .action(async (runId: string, opts: WorkflowReclaimOpts) => {
       const coordRoot = resolveCoordRoot();
       if (!coordRoot) {
@@ -632,53 +632,53 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
         });
         process.exit(1);
       }
-      if (!opts.yes) {
-        emit.error({
-          code: "reclaim_confirmation_required",
-          message: opts.discard
-            ? "reclaim --discard permanently destroys uncommitted work; pass --yes to confirm"
-            : "workspace reclaim commits uncommitted work to its branch and then releases the worktree; pass --yes to confirm",
-        });
-        process.exit(1);
-      }
       try {
-        const { inspectWorkflowWorkspace, prepareReclaim, cleanupWorkspace } = await import(
+        const { createLocalGitWorktreeProvider, readWorkflowRunManifest } = await import(
           "../core/workflow/index.ts"
         );
-        const inspection = inspectWorkflowWorkspace(coordRoot, runId);
-        if (!inspection.ok) {
-          emit.error({ code: "workflow_reclaim_failed", message: inspection.error });
-          process.exit(1);
-        }
-        const allocation = inspection.value.allocation;
-        if (!allocation) {
+        const binding = readWorkflowRunManifest(coordRoot, runId).execution.workspace_binding;
+        if (binding?.provider.id !== "local-git-worktree") {
           emit.error({
             code: "workflow_reclaim_unavailable",
             message: `run ${runId} has no provider-owned Git workspace to reclaim`,
           });
           process.exit(1);
         }
-        const preparation = prepareReclaim({
-          worktreePath: allocation.active_root,
+        const provider = createLocalGitWorktreeProvider({ coordRoot });
+        const result = await provider.reclaim(binding, {
           mode: opts.discard ? "discard" : "salvage",
-          runId,
+          yes: opts.yes,
         });
-        // Cleanup still owns removal. Reclaim only changes whether the tree it
-        // finds is dirty, so there is one audited release path, not two.
-        const provider = await builtInProviderForRun(coordRoot, runId);
-        const cleanup = await cleanupWorkspace({ coordRoot, runId, provider });
         if (opts.json) {
           emit.config({ format: "json" });
-          emit.data({ preparation, cleanup });
+          emit.data(result);
+          return;
+        }
+        if (result.action === "preview") {
+          const holders = result.lease_holder.map(
+            (holder) =>
+              `${holder.scope}: ${holder.owner_id ?? "unknown"}${holder.pid ? ` (pid ${holder.pid})` : ""}${holder.detail ? `; ${holder.detail}` : ""}`,
+          );
+          emit.text(
+            `reclaim preview: ${result.run_id}\n` +
+              `mode: ${result.mode}\nliveness: ${result.liveness}\nownership: ${result.ownership}\n` +
+              `lease holder: ${holders.length > 0 ? holders.join(", ") : "none observed"}\n` +
+              `dirty paths: ${result.dirty_paths === null ? "unknown" : result.dirty_paths.length > 0 ? result.dirty_paths.join(", ") : "none"}\n` +
+              (result.ownership_detail ? `ownership detail: ${result.ownership_detail}\n` : "") +
+              `Pass --yes to confirm ${result.mode} and release after all checks pass.\n`,
+          );
           return;
         }
         emit.text(
-          `reclaim ${preparation.action}: ${preparation.detail}\n` +
-            `workspace cleanup ${cleanup.status}: ${cleanup.binding_id}\n`,
+          `reclaim ${result.preparation.action}: ${result.preparation.detail}\n` +
+            `workspace cleanup ${result.cleanup.status}: ${result.cleanup.binding_id}\n`,
         );
       } catch (error) {
         emit.error({
-          code: "workflow_reclaim_failed",
+          code:
+            error instanceof Error && "code" in error && typeof error.code === "string"
+              ? error.code
+              : "workflow_reclaim_failed",
           message: error instanceof Error ? error.message : String(error),
         });
         process.exit(1);

package/src/core/agents/live-authority-v3.ts

@@ -88,6 +88,7 @@ interface LiveAuthorityBaseV3 {
   nativeSessionId: string;
   adapter: Adapter;
   observationId?: string;
+  expectedGenerationId?: `gen_${string}`;
 }
 
 /**
@@ -648,6 +649,13 @@ function recordLiveAuthority<S extends CoordinationAuthoritySignalV3>(
     platform: livePlatformV3(),
     expected_prior_state_digest: coordinationAuthorityStateDigestV3(expected),
     desired_state_digest: coordinationAuthorityStateDigestV3(desired),
+    expected_generation_id:
+      input.expectedGenerationId ??
+      ((subject === input.owner
+        ? expected.v3_generation_id
+        : readLiveCoordinationRow(input.coordRoot, input.owner)?.v3_generation_id) as
+        | `gen_${string}`
+        | undefined),
     reconciler: {
       readStateDigest: () => {
         const heartbeat = readHeartbeat(input.coordRoot, subject);
@@ -681,6 +689,12 @@ export function liveCoordinationWriteModeV3(coordRoot: string): EventV3WriteMode
 }
 
 function requireHeartbeat(input: LiveAuthorityBaseV3, owner: string): Heartbeat {
+  if (
+    input.expectedGenerationId &&
+    readLiveCoordinationRow(input.coordRoot, owner)?.v3_generation_id !== input.expectedGenerationId
+  ) {
+    throw new LiveCoordinationAuthorityV3Error("expected_generation_changed");
+  }
   const heartbeat = ensureLiveCoordinationHeartbeat(
     input.coordRoot,
     owner,
@@ -688,6 +702,9 @@ function requireHeartbeat(input: LiveAuthorityBaseV3, owner: string): Heartbeat
     input.adapter,
   );
   if (!heartbeat) throw new LiveCoordinationAuthorityV3Error(`heartbeat_missing:${owner}`);
+  if (input.expectedGenerationId && heartbeat.v3_generation_id !== input.expectedGenerationId) {
+    throw new LiveCoordinationAuthorityV3Error("expected_generation_changed");
+  }
   return heartbeat;
 }
 

package/src/core/agents/live-lifecycle-v3.ts

@@ -5,6 +5,7 @@ import { normalizeNativeIdV3 } from "../events/v3/canonical.ts";
 import type { EventV3 } from "../events/v3/contract.ts";
 import { readEventV3ControlState } from "../events/v3/control.ts";
 import { fingerprintContextV3 } from "../events/v3/fingerprint-keys.ts";
+import { withGenerationCustodyV3 } from "../events/v3/generation-custody.ts";
 import {
   liveInstanceIdV3,
   livePlatformV3,
@@ -25,17 +26,34 @@ interface LiveLifecycleObservationBaseV3 {
   observedAt?: string;
 }
 
+interface LiveSweepObservationV3Input extends LiveLifecycleObservationBaseV3 {
+  expectedGenerationId: `gen_${string}` | null;
+  observation: "stale_heartbeat" | "killed" | "unparseable_heartbeat" | "missing_timestamp";
+  ageMs: number;
+}
+
 export function recordLiveSweepObservationV3(
-  input: LiveLifecycleObservationBaseV3 & {
-    observation: "stale_heartbeat" | "killed" | "unparseable_heartbeat" | "missing_timestamp";
-    ageMs: number;
-  },
+  input: LiveSweepObservationV3Input,
 ): LiveLifecycleObservationV3Result {
-  return recordObservation(input, "lifecycle.sweep_observed", {
-    subject_instance_id: liveInstanceIdV3(input.owner),
-    observation: input.observation,
-    provisional: true,
-    age_ms: Math.max(0, Math.floor(input.ageMs)),
+  input = { ...input };
+  // Reject stale observations before preparing durable custody state. The
+  // in-custody checks cover replacement while acquiring custody and reentry.
+  requireSweepHookState(input);
+  return withGenerationCustodyV3(input.coordRoot, [liveInstanceIdV3(input.owner)], () => {
+    requireSweepHookState(input);
+    return recordObservation(
+      input,
+      "lifecycle.sweep_observed",
+      {
+        subject_instance_id: liveInstanceIdV3(input.owner),
+        observation: input.observation,
+        provisional: true,
+        age_ms: Math.max(0, Math.floor(input.ageMs)),
+      },
+      () => {
+        requireSweepHookState(input);
+      },
+    );
   });
 }
 
@@ -44,11 +62,16 @@ export function recordLiveResumeObservationV3(
 ): LiveLifecycleObservationV3Result {
   const normalized = withAttestedAdapter(input);
   const hook = requireHookState(normalized);
-  return recordObservation(normalized, "session.resumed", {
-    prior_generation_id: hook.generation_id,
-    continuity: "native",
-    evidence_reference: "heartbeat_recreated",
-  });
+  return recordObservation(
+    normalized,
+    "session.resumed",
+    {
+      prior_generation_id: hook.generation_id,
+      continuity: "native",
+      evidence_reference: "heartbeat_recreated",
+    },
+    () => {},
+  );
 }
 
 function recordObservation<T extends "lifecycle.sweep_observed" | "session.resumed">(
@@ -66,6 +89,7 @@ function recordObservation<T extends "lifecycle.sweep_observed" | "session.resum
         continuity: "native";
         evidence_reference: string;
       },
+  beforeWrite: () => void,
 ): LiveLifecycleObservationV3Result {
   const route = resolveLiveEventLedgerRouteV3(input.coordRoot);
   if (route.state === "blocked") throw new LiveCoordinationAuthorityV3Error(route.reason);
@@ -121,6 +145,7 @@ function recordObservation<T extends "lifecycle.sweep_observed" | "session.resum
     monotonic_ns: process.hrtime.bigint().toString(),
   };
   const event = buildEventV3(eventType, { ...common, payload } as never) as EventV3;
+  beforeWrite();
   const durability = writeEventV3(input.coordRoot, event, {
     expectedGenesisId: control.genesis.event.payload.genesis_id as `gex_${string}`,
   });
@@ -130,6 +155,19 @@ function recordObservation<T extends "lifecycle.sweep_observed" | "session.resum
   return { state: "recorded", event };
 }
 
+function requireSweepHookState(input: LiveSweepObservationV3Input): void {
+  if (
+    typeof input.expectedGenerationId !== "string" ||
+    !/^gen_[a-zA-Z0-9._-]+$/.test(input.expectedGenerationId)
+  ) {
+    throw new LiveCoordinationAuthorityV3Error("hook_generation_not_joinable");
+  }
+  const hook = requireHookState(withAttestedAdapter(input));
+  if (hook.generation_id !== input.expectedGenerationId) {
+    throw new LiveCoordinationAuthorityV3Error("expected_generation_changed");
+  }
+}
+
 function withAttestedAdapter<T extends LiveLifecycleObservationBaseV3>(input: T): T {
   const adapter = liveCoordinationAdapterV3(input.coordRoot, input.owner);
   if (!adapter) return input;

package/src/core/agents/mailbox.ts

@@ -9,13 +9,14 @@
  * shown to them, because nothing surfaces another session's journal.
  *
  * This module addresses the durable persona name instead of the instance, so a
- * message can be queued before its recipient exists. Delivery happens on the
- * recipient's side: their next SessionStart or prompt drains the queue, shows
- * the messages, and records them in their journal.
+ * message can be queued before its recipient exists. The recipient's next
+ * SessionStart or prompt can drain the queue for injection. A drain does not
+ * confirm that the adapter emitted the context or that anyone read it.
  *
  * Storage: `.harnery/mailbox/<slug>.jsonl`, one JSON record per line, appended
- * by senders and removed by an atomic claim on the recipient's side. Delivered
- * records are appended to `.harnery/mailbox/delivered/<slug>.jsonl` for audit.
+ * by senders and removed by an atomic claim on the recipient's side. Drained
+ * records are appended to `.harnery/mailbox/delivered/<slug>.jsonl` for audit,
+ * with injection explicitly unconfirmed.
  *
  * Related but distinct: `core/inbox` is an instance-keyed transport with a
  * storage-framework service behind it. This mailbox is name-keyed, file-only,
@@ -48,8 +49,8 @@ export const MAILBOX_MESSAGE_SCHEMA = "harnery.mailbox-message/v1" as const;
 export const MAX_BODY_BYTES = 4000;
 /** Pending messages held for one name before senders are refused. */
 export const MAX_PENDING = 25;
-/** Delivered-archive ceiling; the file is truncated from the head past this. */
-const MAX_DELIVERED_BYTES = 256 * 1024;
+/** Drain-archive ceiling; the file is truncated from the head past this. */
+const MAX_ARCHIVE_BYTES = 256 * 1024;
 
 export interface MailboxMessageV1 {
   schema: typeof MAILBOX_MESSAGE_SCHEMA;
@@ -104,7 +105,7 @@ export function mailboxPath(coordRoot: string, name: string): string {
   return join(mailboxDir(coordRoot), `${slugFor(name)}.jsonl`);
 }
 
-function deliveredPath(coordRoot: string, name: string): string {
+function archivePath(coordRoot: string, name: string): string {
   return join(mailboxDir(coordRoot), "delivered", `${slugFor(name)}.jsonl`);
 }
 
@@ -243,10 +244,10 @@ export function peekMailbox(coordRoot: string, name: string): MailboxMessageV1[]
 /**
  * Claim and return every pending message for a name.
  *
- * The claim is an atomic rename, so two sessions sharing a name cannot deliver
+ * The claim is an atomic rename, so two sessions sharing a name cannot claim
  * the same message twice: whichever rename wins owns the batch. Claimed records
- * are appended to the delivered archive before the claim file is removed, so a
- * crash between the two leaves an auditable copy rather than a silent loss.
+ * are archived before the claim file is removed. The archive records only the
+ * drain; output, recipient read, and turn completion remain unconfirmed.
  */
 export function drainMailbox(coordRoot: string, name: string): MailboxMessageV1[] {
   let path: string;
@@ -279,12 +280,20 @@ export function drainMailbox(coordRoot: string, name: string): MailboxMessageV1[
 
   if (messages.length > 0) {
     try {
-      const archive = deliveredPath(coordRoot, name);
+      const archive = archivePath(coordRoot, name);
       mkdirSync(join(mailboxDir(coordRoot), "delivered"), { recursive: true });
-      const deliveredAt = new Date().toISOString();
+      const drainedAt = new Date().toISOString();
       appendFileSync(
         archive,
-        `${messages.map((m) => JSON.stringify({ ...m, delivered_at: deliveredAt })).join("\n")}\n`,
+        `${messages
+          .map((m) =>
+            JSON.stringify({
+              ...m,
+              drained_at: drainedAt,
+              delivery_status: "injection-unconfirmed",
+            }),
+          )
+          .join("\n")}\n`,
         "utf8",
       );
       trimArchive(archive);
@@ -336,7 +345,7 @@ function sweepStaleClaims(coordRoot: string): void {
 
 function trimArchive(path: string): void {
   try {
-    if (statSync(path).size <= MAX_DELIVERED_BYTES) return;
+    if (statSync(path).size <= MAX_ARCHIVE_BYTES) return;
     const lines = readFileSync(path, "utf8").split("\n").filter(Boolean);
     const keep = lines.slice(Math.floor(lines.length / 2));
     writeFileSync(path, `${keep.join("\n")}\n`, "utf8");
@@ -354,8 +363,8 @@ export function formatMailboxDelivery(
   const bin = resolveBinName(coordRoot);
   const header =
     messages.length === 1
-      ? `Message from a peer agent (delivered now, recorded in your journal):`
-      : `${messages.length} messages from peer agents (delivered now, recorded in your journal):`;
+      ? `Message from a peer agent (prepared for injection, recorded in your journal):`
+      : `${messages.length} messages from peer agents (prepared for injection, recorded in your journal):`;
   const body = messages
     .map((m) => {
       const when = m.created_at.replace("T", " ").replace(/\.\d+Z$/, "Z");

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

@@ -48,17 +48,18 @@ import { join } from "node:path";
 import { coordEnv } from "../../../lib/env.ts";
 import { endOfTurnStatusCommand, hostPromptReminder, resolveBinName } from "../../config.ts";
 import type { PressureWorkloadClass } from "../../diagnostics/contract.ts";
+import { formatPeerInbox, peerInbox } from "../../inbox/peer-messages.ts";
 import { type RemoteMachine, readRemoteMachines } from "../../presence/index.ts";
 import { readResourceStatus } from "../../resources/status.ts";
-import { drainMailbox, formatMailboxDelivery } from "../mailbox.ts";
 import { sessionNameDisplayBlock, sessionNameDisplayPending } from "../session-name-display.ts";
 import { heartbeatPath } from "../state/heartbeat-reader.ts";
 import {
   readLiveCoordinationRow,
   readLiveCoordinationRows,
 } from "../state/live-coordination-view.ts";
+import { forkRelationLabels } from "../state/names.ts";
 import type { AgentActivity, TaskState } from "../state/session-state.ts";
-import { formatPendingCouncils, recordDeliveredMessages } from "./session-context.ts";
+import { formatPendingCouncils } from "./session-context.ts";
 
 interface HeartbeatRow {
   instance_id?: string;
@@ -102,6 +103,8 @@ export interface PromptContextOpts {
    * being bounced into a retry. Not hash-deduped, same rationale as the
    * status footer. */
   turnRitualNudge?: string;
+  /** The emitter acknowledges exactly these IDs only after output succeeds. */
+  onInboxPrepared?: (messageIds: readonly string[]) => void;
 }
 
 /**
@@ -131,16 +134,12 @@ export function renderPromptContext(opts: PromptContextOpts): string {
   // skipped without it.
   const resolvedName = agentName ?? readLiveCoordinationRow(coordRoot, instanceId)?.name;
 
-  // 1. Peer messages. Drained first and never deduped: a message is delivered
-  // exactly once, and it is the one section here that carries new information
-  // from another agent rather than a reminder.
-  //
-  if (resolvedName) {
-    const delivered = drainMailbox(coordRoot, resolvedName);
-    if (delivered.length > 0) {
-      recordDeliveredMessages(instanceId, delivered);
-      sections.push(formatMailboxDelivery(coordRoot, delivered));
-    }
+  // 1. Instance-bound messages. Rendering is read-only; failed output leaves
+  // this same batch pending rather than losing it before a prompt sees it.
+  const delivered = peerInbox(coordRoot).prepareSurface(instanceId);
+  if (delivered.length > 0) {
+    opts.onInboxPrepared?.(delivered.map(({ message_id }) => message_id));
+    sections.push(formatPeerInbox(coordRoot, delivered));
   }
 
   // 2. Peer table with hash dedup.
@@ -441,7 +440,11 @@ function computePeerTableIfChanged(
   if (oldHash && oldHash === newHash) return "";
 
   // Render peer table via the same formatter used at SessionStart.
-  const local = formatPeerTable(peers, mySessionId);
+  const local = formatPeerTable(
+    peers,
+    mySessionId,
+    forkRelationLabels(coordRoot, selfInstanceId, new Set(peers.map((p) => p.instance_id ?? ""))),
+  );
   const remoteTable = formatRemoteTable(remote);
   const table = [local, remoteTable].filter(Boolean).join("\n\n");
   if (!table) return "";
@@ -580,7 +583,11 @@ function writeHashFile(path: string, value: string): void {
  * (no cross-file imports of formatting internals). If both renderers diverge,
  * pull the shared bits into a small util module. */
 
-function formatPeerTable(peers: HeartbeatRow[], mySessionId: string): string {
+function formatPeerTable(
+  peers: HeartbeatRow[],
+  mySessionId: string,
+  relations: Map<string, string> = new Map(),
+): string {
   if (peers.length === 0) return "";
   const nowSec = Math.floor(Date.now() / 1000);
 
@@ -592,16 +599,20 @@ function formatPeerTable(peers: HeartbeatRow[], mySessionId: string): string {
     }
   }
 
-  type RowExt = HeartbeatRow & { display_files: string[] };
+  type RowExt = HeartbeatRow & { display_files: string[]; relation?: string };
   const rows: RowExt[] = peers
     .filter((p) => (p.kind ?? "unknown") !== "transient")
     .map((p) => {
       const folded = fold[p.instance_id ?? ""] ?? [];
       const display = Array.from(new Set([...(p.files_touched ?? []), ...folded])).sort();
-      return { ...p, display_files: display };
+      const relation = relations.get(p.instance_id ?? "");
+      return { ...p, display_files: display, ...(relation ? { relation } : {}) };
     });
 
-  const blocking = rows.filter((p) => p.session_id !== mySessionId).sort(byStartedAt);
+  // Related sessions sort first so a fork parent never hides in "+N more".
+  const blocking = rows
+    .filter((p) => p.session_id !== mySessionId)
+    .sort((a, b) => Number(!!b.relation) - Number(!!a.relation) || byStartedAt(a, b));
   const group = rows.filter((p) => p.session_id === mySessionId).sort(byStartedAt);
 
   const out: string[] = [];
@@ -625,7 +636,7 @@ function byStartedAt(a: HeartbeatRow, b: HeartbeatRow): number {
 }
 
 function renderSubtable(
-  rows: Array<HeartbeatRow & { display_files: string[] }>,
+  rows: Array<HeartbeatRow & { display_files: string[]; relation?: string }>,
   header: string,
   nowSec: number,
 ): string {
@@ -635,7 +646,10 @@ function renderSubtable(
   return `${header}\n${first.join("\n")}${overflow}`;
 }
 
-function formatRow(r: HeartbeatRow & { display_files: string[] }, nowSec: number): string {
+function formatRow(
+  r: HeartbeatRow & { display_files: string[]; relation?: string },
+  nowSec: number,
+): string {
   const taskPart = r.task ? ` "${r.task.slice(0, 60)}"` : "";
   const statePart = formatState(r);
   // Fall back started_at → last_heartbeat; if neither is a valid timestamp,
@@ -646,7 +660,8 @@ function formatRow(r: HeartbeatRow & { display_files: string[] }, nowSec: number
   // Prefer a short instance_id over a bare "unknown" so an incomplete row is
   // still identifiable.
   const label = r.name ?? (r.instance_id ? r.instance_id.slice(0, 8) : "unknown");
-  return `  - agent-${label}${taskPart}   (${statePart}, ${ageFrom}, ${filesPart})`;
+  const relation = r.relation ? ` [${r.relation}]` : "";
+  return `  - agent-${label}${relation}${taskPart}   (${statePart}, ${ageFrom}, ${filesPart})`;
 }
 
 function formatState(r: HeartbeatRow): string {