harnery 0.42.0 → 0.44.0

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

@@ -12,11 +12,10 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { resolveBinName, resolveHooksSetupHint } from "../../config.ts";
 import { harneryVersion, loadAdapterWiring } from "../../hooks/adapter/wiring.ts";
-import { appendEntry } from "../../journal/index.ts";
+import { formatPeerInbox, peerInbox } from "../../inbox/peer-messages.ts";
 import { readRemoteMachines } from "../../presence/index.ts";
-import { drainMailbox, formatMailboxDelivery, type MailboxMessageV1 } from "../mailbox.ts";
 import { readLiveCoordinationRows } from "../state/live-coordination-view.ts";
-import { readForkParent } from "../state/names.ts";
+import { forkRelationLabels, readForkState } from "../state/names.ts";
 import type { AgentActivity, TaskState } from "../state/session-state.ts";
 
 interface HeartbeatRow {
@@ -42,6 +41,8 @@ export interface RenderOpts {
   /** Adapter label rendered in parens after the self-name (e.g. "Cursor", "Codex").
    * Claude Code omits it. */
   platformLabel?: string;
+  /** The emitter acknowledges exactly these IDs only after output succeeds. */
+  onInboxPrepared?: (messageIds: readonly string[]) => void;
 }
 
 /**
@@ -54,7 +55,17 @@ export function renderSessionContext(opts: RenderOpts): string {
 
   // 1. Self-name line + peer table (folded if peers present)
   const peers = readActivePeers(coordRoot, instanceId);
-  const localTable = formatPeerTable(peers, sessionId);
+  const forkState = readForkState(coordRoot, instanceId);
+  const forkParent = forkState?.parent ?? null;
+  const parentRow = forkParent
+    ? peers.find((peer) => peer.instance_id === forkParent.instance_id)
+    : undefined;
+  const relations = forkRelationLabels(
+    coordRoot,
+    instanceId,
+    new Set(peers.map((peer) => peer.instance_id ?? "")),
+  );
+  const localTable = formatPeerTable(peers, sessionId, relations);
   // Cross-machine presence (ADR 0016): sessions on other machines (advisory).
   const peerTable = [localTable, formatRemoteMachines(coordRoot)].filter(Boolean).join("\n\n");
   if (agentName) {
@@ -64,13 +75,11 @@ export function renderSessionContext(opts: RenderOpts): string {
     // asserts the parent's name, claims, and task. When recorded fork lineage
     // (.name-history forked_from) names the parent, say so specifically — the
     // fork is about to read a transcript full of that exact name. Otherwise
-    // fall back to the generic clause, which needs no fork detection.
-    const forkParent = readForkParent(coordRoot, instanceId);
-    const authority = forkParent?.name
-      ? `This conversation was branched from agent-${forkParent.name}'s session: earlier context showing agent-${forkParent.name}'s name, task, or file claims belongs to the pre-fork session, not to you.`
-      : forkParent
-        ? `This conversation was branched from another session (${forkParent.instance_id}); any agent name in earlier context belongs to that session, not to you.`
-        : "Any different agent name in earlier context was inherited from another session; this one is authoritative.";
+    // fall back to the generic clause, which needs no fork detection. A live
+    // parent is the dangerous case (2026-10-07: a fork read its running
+    // parent as its own earlier self and offered to close it), so the notice
+    // names what the parent is doing and forbids ending it.
+    const authority = forkAuthorityClause(forkParent, forkState?.fork === true, parentRow);
     const selfLine = `You are agent-${agentName}${suffix}. ${authority}`;
     messages.push(peerTable ? `${selfLine}\n\n${peerTable}` : selfLine);
   } else if (peerTable) {
@@ -84,15 +93,12 @@ export function renderSessionContext(opts: RenderOpts): string {
     );
   }
 
-  // 3. Peer messages queued for this name while no session held it. Draining
-  // here is what makes `agents ping` safe to use on a dormant agent: the sender
-  // never has to know whether the recipient is running.
-  if (agentName) {
-    const delivered = drainMailbox(coordRoot, agentName);
-    if (delivered.length > 0) {
-      recordDeliveredMessages(instanceId, delivered);
-      messages.push(formatMailboxDelivery(coordRoot, delivered));
-    }
+  // 3. Rendering never consumes a message. The native emitter acknowledges the
+  // prepared instance-bound batch only after it has flushed the output.
+  const delivered = peerInbox(coordRoot).prepareSurface(instanceId);
+  if (delivered.length > 0) {
+    opts.onInboxPrepared?.(delivered.map(({ message_id }) => message_id));
+    messages.push(formatPeerInbox(coordRoot, delivered));
   }
 
   // 4. Council invites
@@ -139,27 +145,6 @@ export function renderSessionContext(opts: RenderOpts): string {
   return messages.join("\n\n");
 }
 
-/**
- * Write delivered peer messages into the recipient's own journal, so they
- * survive context compaction the way any other coordination breadcrumb does.
- * A message the sender already journaled (the recipient was live when it was
- * sent) is skipped to avoid a duplicate entry.
- */
-export function recordDeliveredMessages(
-  instanceId: string,
-  messages: readonly MailboxMessageV1[],
-): void {
-  for (const m of messages) {
-    if (m.journaled) continue;
-    try {
-      appendEntry(instanceId, "handoff", `from agent-${m.from_name}: ${m.body}`);
-    } catch {
-      // A journal write failure must never cost the delivery itself; the
-      // message is already in the rendered context the model reads.
-    }
-  }
-}
-
 /** One-line-per-agent view of sessions on other machines (presence refs). */
 function formatRemoteMachines(coordRoot: string): string {
   try {
@@ -194,13 +179,64 @@ function readActivePeers(coordRoot: string, selfInstanceId: string): HeartbeatRo
   );
 }
 
+const DO_NOT_END =
+  "Do not end, release, or finalize that session unless the operator explicitly tells you to.";
+
+function forkAuthorityClause(
+  parent: { instance_id: string; name: string | null } | null,
+  fork: boolean,
+  parentRow: HeartbeatRow | undefined,
+): string {
+  if (parent?.name && parentRow) {
+    const files = parentRow.files_touched ?? [];
+    const task = parentRow.task ? ` on "${parentRow.task.slice(0, 80)}"` : "";
+    const holds =
+      files.length > 0
+        ? ` and holds ${files.length} file${files.length === 1 ? "" : "s"} (${fmtFileList(files)})`
+        : "";
+    const owned =
+      files.length > 0
+        ? parentRow.task
+          ? "That name, task, and those files"
+          : "That name and those files"
+        : parentRow.task
+          ? "That name and task"
+          : "That name";
+    return (
+      `This conversation was forked from agent-${parent.name}, which is still running as a separate session${task}${holds}. ` +
+      `${owned} belong${owned === "That name" ? "s" : ""} to agent-${parent.name}, not to you. ${DO_NOT_END}`
+    );
+  }
+  if (parent?.name) {
+    return `This conversation was branched from agent-${parent.name}'s session: earlier context showing agent-${parent.name}'s name, task, or file claims belongs to the pre-fork session, not to you.`;
+  }
+  if (parent) {
+    return `This conversation was branched from another session (${parent.instance_id}); any agent name in earlier context belongs to that session, not to you.`;
+  }
+  if (fork) {
+    return `This conversation was forked from another session, which may still be running. Any agent name, task, or file claim in earlier context belongs to that session, not to you. ${DO_NOT_END}`;
+  }
+  return "Any different agent name in earlier context was inherited from another session; this one is authoritative.";
+}
+
+function fmtFileList(files: string[]): string {
+  const sorted = [...files].sort();
+  return sorted.length <= 3
+    ? sorted.join(", ")
+    : `${sorted.slice(0, 3).join(", ")}, +${sorted.length - 3} more`;
+}
+
 /**
  * Renders the peer table as
  * two subsections: "Other agent groups active" (blocking) and "Your group"
  * (subagents/siblings, no mutual block). Folds transient subagents' files
  * into their parent session.
  */
-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);
 
@@ -214,16 +250,20 @@ function formatPeerTable(peers: HeartbeatRow[], mySessionId: string): string {
   }
 
   // Build rows with display_files (own files + folded transient files).
-  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 the 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 sections: string[] = [];
@@ -248,7 +288,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 {
@@ -258,7 +298,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 activity = r.activity ?? "unknown";
   const lifecycle = r.task_state ?? "active";
@@ -266,7 +309,8 @@ function formatRow(r: HeartbeatRow & { display_files: string[] }, nowSec: number
     lifecycle === "blocked" && r.task_state_reason ? `: ${r.task_state_reason.slice(0, 80)}` : "";
   const ageFrom = fmtAge(nowSec - parseIsoSec(r.started_at));
   const filesPart = fmtFiles(r.display_files);
-  return `  - agent-${r.name ?? "unknown"}${taskPart}   (activity=${activity}, lifecycle=${lifecycle}${reason}, ${ageFrom}, ${filesPart})`;
+  const relation = r.relation ? ` [${r.relation}]` : "";
+  return `  - agent-${r.name ?? "unknown"}${relation}${taskPart}   (activity=${activity}, lifecycle=${lifecycle}${reason}, ${ageFrom}, ${filesPart})`;
 }
 
 function fmtFiles(files: string[]): string {

package/src/core/agents/rules/stop-hook.ts

@@ -424,9 +424,9 @@ function sessionNameBlock(coordRoot: string, instanceId: string): VerdictResult
   } catch {
     // The ledger evidence still authorizes the block; the cache is UX only.
   }
-  const instruction = name
-    ? `Reproduce it by itself in a fenced code block: ${name}`
-    : `Run \`${resolveBinName(coordRoot)} agents suggest-name\`, then reproduce its output by itself in a fenced code block.`;
+  // The first post-mint reply was already rejected. Repeating its title later
+  // cannot change that evidence; the JSON retry result opens a new window.
+  const instruction = `Run \`${resolveBinName(coordRoot)} agents suggest-name --json\` as your only tool call to create a fresh verification boundary, then display its suggested_session_name verbatim by itself in a fenced code block${name ? `: ${name}` : "."}`;
   return {
     allow: false,
     exit_code: 2,

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

@@ -24,6 +24,11 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
+import {
+  assertCurrentGenerationV3,
+  withGenerationCustodyV3,
+} from "../../events/v3/generation-custody.ts";
+import { liveInstanceIdV3 } from "../../events/v3/live-routing.ts";
 import { canonicalClaimPath } from "../claim-path.ts";
 import { type Heartbeat, heartbeatPath, readHeartbeat } from "./heartbeat-reader.ts";
 import type { TaskState } from "./session-state.ts";
@@ -63,12 +68,15 @@ function mutate(
   instanceId: string,
   fn: (hb: Heartbeat) => Heartbeat,
 ): Heartbeat | null {
-  const hb = readHeartbeat(coordRoot, instanceId);
-  if (!hb) return null;
-  const next = fn(hb);
-  next.last_heartbeat = nowIsoSeconds();
-  atomicWrite(heartbeatPath(coordRoot, instanceId), JSON.stringify(next, null, 2));
-  return next;
+  return withGenerationCustodyV3(coordRoot, [liveInstanceIdV3(instanceId)], () => {
+    const hb = readHeartbeat(coordRoot, instanceId);
+    if (!hb) return null;
+    const next = fn(hb);
+    next.last_heartbeat = nowIsoSeconds();
+    assertCurrentGenerationV3(coordRoot, liveInstanceIdV3(instanceId), hb.v3_generation_id);
+    atomicWrite(heartbeatPath(coordRoot, instanceId), JSON.stringify(next, null, 2));
+    return next;
+  });
 }
 
 export function setTask(coordRoot: string, instanceId: string, task: string): Heartbeat | null {
@@ -100,12 +108,15 @@ export function setIdentityCache(
   name: string,
   agentId: string,
 ): Heartbeat | null {
-  const heartbeat = readHeartbeat(coordRoot, instanceId);
-  if (!heartbeat) return null;
-  heartbeat.name = name;
-  heartbeat.agent_id = agentId;
-  atomicWrite(heartbeatPath(coordRoot, instanceId), JSON.stringify(heartbeat, null, 2));
-  return heartbeat;
+  return withGenerationCustodyV3(coordRoot, [liveInstanceIdV3(instanceId)], () => {
+    const heartbeat = readHeartbeat(coordRoot, instanceId);
+    if (!heartbeat) return null;
+    heartbeat.name = name;
+    heartbeat.agent_id = agentId;
+    assertCurrentGenerationV3(coordRoot, liveInstanceIdV3(instanceId), heartbeat.v3_generation_id);
+    atomicWrite(heartbeatPath(coordRoot, instanceId), JSON.stringify(heartbeat, null, 2));
+    return heartbeat;
+  });
 }
 
 /** Restore the pool-assigned display name on a generation that was
@@ -328,6 +339,12 @@ export function clearCoordinationCache(coordRoot: string, instanceId: string): b
 }
 
 export function healPidmap(coordRoot: string, instanceId: string, pid: number): void {
+  withGenerationCustodyV3(coordRoot, [liveInstanceIdV3(instanceId)], () =>
+    healPidmapUnderCustody(coordRoot, instanceId, pid),
+  );
+}
+
+function healPidmapUnderCustody(coordRoot: string, instanceId: string, pid: number): void {
   const dir = join(coordRoot, ".harnery", "pid-map");
   mkdirSync(dir, { recursive: true });
   const hb = readHeartbeat(coordRoot, instanceId);

package/src/core/agents/state/live-coordination-writer.ts

@@ -5,6 +5,10 @@ import {
   readCoordinationViewV3,
   requireAuthoritySafeCoordinationViewV3,
 } from "../../events/v3/coordination-view.ts";
+import {
+  assertCurrentGenerationV3,
+  withGenerationCustodyV3,
+} from "../../events/v3/generation-custody.ts";
 import { liveInstanceIdV3, resolveLiveEventLedgerRouteV3 } from "../../events/v3/live-routing.ts";
 import { type Heartbeat, readHeartbeat } from "./heartbeat-reader.ts";
 import {
@@ -64,6 +68,26 @@ function materializeLiveCoordinationHeartbeat(
   _adapter: Adapter,
   model: string | undefined,
   force: boolean,
+): Heartbeat | null {
+  return withGenerationCustodyV3(coordRoot, [liveInstanceIdV3(nativeInstanceId)], () =>
+    materializeHeartbeatUnderCustody(
+      coordRoot,
+      nativeInstanceId,
+      nativeSessionId,
+      _adapter,
+      model,
+      force,
+    ),
+  );
+}
+
+function materializeHeartbeatUnderCustody(
+  coordRoot: string,
+  nativeInstanceId: string,
+  nativeSessionId: string,
+  _adapter: Adapter,
+  model: string | undefined,
+  force: boolean,
 ): Heartbeat | null {
   const route = resolveLiveEventLedgerRouteV3(coordRoot);
   if (route.state === "blocked") throw new Error(`event_v3_coordination_view:${route.reason}`);
@@ -133,6 +157,11 @@ function materializeLiveCoordinationHeartbeat(
     v3_projection_event_id: generation.last_event_id,
     v3_task_state: generation.task_state === "set" ? "set" : "cleared",
   };
+  assertCurrentGenerationV3(
+    coordRoot,
+    liveInstanceIdV3(nativeInstanceId),
+    generation.generation_id,
+  );
   writeHeartbeatCache(coordRoot, nativeInstanceId, materialized);
   return materialized;
 }

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

@@ -331,13 +331,20 @@ export interface NameHistoryRow {
   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";
+  /** Audit marker distinguishing an explicit role adoption from pool assignment,
+   * and a lineage row appended after the name was already assigned. */
+  source?: "pool" | "identity.assume" | "fork.detected";
   previous_name?: string;
   /** Instance this session was forked/branched from (recorded fork lineage).
    * Stamped only on the row that first assigns this instance, when the adapter
    * layer detected or supplied a parent conversation. */
   forked_from?: string;
+  /** The adapter declared or inherited-history proved this instance is a fork,
+   * even when its parent could not be resolved yet. */
+  fork?: true;
+  /** Fork detection has run against this instance's transcript; the tool-path
+   * heal skips instances carrying it so the scan runs once per instance. */
+  fork_checked?: true;
 }
 
 function atomicWrite(path: string, content: string): void {
@@ -516,7 +523,13 @@ export function assignName(
   coordRoot: string,
   instanceId: string,
   kind: NameKind,
-  opts: { freshnessSecs: number; forkedFrom?: string; nowMs?: number },
+  opts: {
+    freshnessSecs: number;
+    forkedFrom?: string;
+    fork?: boolean;
+    forkChecked?: boolean;
+    nowMs?: number;
+  },
 ): string {
   // Check 1: existing history row → original name. A resume re-enters here,
   // which also makes fork stamping naturally idempotent: lineage lands only on
@@ -558,13 +571,111 @@ export function assignName(
     kind,
     source: "pool",
     ...(forkedFrom && forkedFrom !== instanceId ? { forked_from: forkedFrom } : {}),
+    ...(opts.fork || (forkedFrom && forkedFrom !== instanceId) ? { fork: true as const } : {}),
+    ...(opts.forkChecked ? { fork_checked: true as const } : {}),
     ts: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
   });
   return name;
 }
 
+export interface ForkState {
+  /** True when the instance is a recorded fork, parent known or not. */
+  fork: boolean;
+  /** Detection already ran for this instance. */
+  checked: boolean;
+  parent: { instance_id: string; name: string | null } | null;
+}
+
+/** Recorded fork state for <instanceId>, or null when it has no history row. */
+export function readForkState(coordRoot: string, instanceId: string): ForkState | null {
+  const history = readHistory(coordRoot);
+  let seen = false;
+  let fork = false;
+  let checked = false;
+  let parentId: string | undefined;
+  for (const row of history) {
+    if (row.instance_id !== instanceId) continue;
+    seen = true;
+    if (row.fork || row.forked_from) fork = true;
+    if (row.fork_checked) checked = true;
+    if (row.forked_from && row.forked_from !== instanceId) parentId = row.forked_from;
+  }
+  if (!seen) return null;
+  const parent = parentId
+    ? { instance_id: parentId, name: resolveName(coordRoot, parentId)?.name ?? null }
+    : null;
+  return { fork, checked, parent };
+}
+
+/**
+ * Record fork detection that ran after the instance was already named (the
+ * tool-path heal). Appends a copy of the latest identity row, so the name,
+ * kind, and persona are unchanged, plus `fork_checked` and any lineage found.
+ * A no-op for an instance with no history row or one already checked.
+ */
+export function recordForkDetection(
+  coordRoot: string,
+  instanceId: string,
+  detection: { fork: boolean; forkedFrom?: string },
+): boolean {
+  const history = readHistory(coordRoot);
+  let latest: NameHistoryRow | undefined;
+  for (const row of history) {
+    if (row.instance_id !== instanceId) continue;
+    if (row.fork_checked) return false;
+    latest = row;
+  }
+  if (!latest) return false;
+  const forkedFrom =
+    detection.forkedFrom && detection.forkedFrom !== instanceId ? detection.forkedFrom : undefined;
+  appendHistory(coordRoot, {
+    instance_id: instanceId,
+    name: latest.name,
+    kind: latest.kind,
+    ...(latest.agent_id ? { agent_id: latest.agent_id } : {}),
+    source: "fork.detected",
+    ...(forkedFrom ? { forked_from: forkedFrom } : {}),
+    ...(detection.fork || forkedFrom || latest.fork ? { fork: true as const } : {}),
+    fork_checked: true,
+    ts: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+  });
+  return true;
+}
+
+/**
+ * Peer labels for recorded fork relations, keyed by instance id: this
+ * session's fork parent and its direct forks. `liveIds` marks which of them
+ * are running, so a fork can tell its live parent from its own earlier self.
+ */
+export function forkRelationLabels(
+  coordRoot: string,
+  instanceId: string,
+  liveIds: Set<string>,
+): Map<string, string> {
+  const out = new Map<string, string>();
+  const parent = readForkParent(coordRoot, instanceId);
+  if (parent) {
+    out.set(
+      parent.instance_id,
+      liveIds.has(parent.instance_id) ? "your fork parent, live" : "your fork parent",
+    );
+  }
+  for (const child of readForkChildren(coordRoot, instanceId)) out.set(child, "your fork");
+  return out;
+}
+
+/** Instance ids recorded as direct forks of <instanceId>. */
+export function readForkChildren(coordRoot: string, instanceId: string): Set<string> {
+  const out = new Set<string>();
+  for (const row of readHistory(coordRoot)) {
+    if (row.forked_from === instanceId && row.instance_id !== instanceId) out.add(row.instance_id);
+  }
+  return out;
+}
+
 /** One step of recorded fork lineage: the latest row for <instanceId> that
- * carries `forked_from` (latest-row-wins, matching resolveName). */
+ * carries `forked_from`. Later rows without lineage (an identity assumption)
+ * do not erase it: a session never stops being a fork. */
 export function readForkParent(
   coordRoot: string,
   instanceId: string,
@@ -572,8 +683,8 @@ export function readForkParent(
   const history = readHistory(coordRoot);
   for (let i = history.length - 1; i >= 0; i--) {
     const row = history[i]!;
-    if (row.instance_id !== instanceId) continue;
-    if (!row.forked_from) return null;
+    if (row.instance_id !== instanceId || !row.forked_from) continue;
+    if (row.forked_from === instanceId) return null;
     const parent = resolveName(coordRoot, row.forked_from);
     return { instance_id: row.forked_from, name: parent?.name ?? null };
   }

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

@@ -24,6 +24,8 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
+import { withGenerationCustodyV3 } from "../../events/v3/generation-custody.ts";
+import { liveInstanceIdV3 } from "../../events/v3/live-routing.ts";
 import { checkPidToken, processStartToken } from "./proc-start.ts";
 
 /**
@@ -126,6 +128,17 @@ export function writePidmapRow(
   pid: number,
   instanceId: string,
   platform: string,
+): void {
+  withGenerationCustodyV3(coordRoot, [liveInstanceIdV3(instanceId)], () =>
+    writePidmapRowUnderCustody(coordRoot, pid, instanceId, platform),
+  );
+}
+
+function writePidmapRowUnderCustody(
+  coordRoot: string,
+  pid: number,
+  instanceId: string,
+  platform: string,
 ): void {
   const dir = join(coordRoot, ".harnery", "pid-map");
   const path = join(dir, String(pid));

package/src/core/agents/state/proc-start.ts

@@ -160,6 +160,63 @@ export function processStartToken(pid: number): string | null {
   return startTokenProbe() === "procfs" ? procfsStartToken(pid) : psStartToken(pid);
 }
 
+export type ProcessGenerationVerdict = "same" | "different" | "unknown";
+
+type ReadProcessStartToken = (pid: number) => string | null;
+
+/** A missing or unreadable token never establishes process identity. */
+export function verifyProcessGeneration(
+  pid: number,
+  recordedToken: string | null | undefined,
+  readToken: ReadProcessStartToken = processStartToken,
+): ProcessGenerationVerdict {
+  if (
+    !Number.isInteger(pid) ||
+    pid <= 0 ||
+    typeof recordedToken !== "string" ||
+    !recordedToken.trim()
+  )
+    return "unknown";
+  // A bootless Linux token cannot identify a process across machine boots.
+  if (/^l\d+$/.test(recordedToken)) return "unknown";
+  try {
+    const currentToken = readToken(pid);
+    if (typeof currentToken !== "string" || !currentToken.trim()) return "unknown";
+    if (/^l\d+$/.test(currentToken)) return "unknown";
+    return currentToken === recordedToken ? "same" : "different";
+  } catch {
+    return "unknown";
+  }
+}
+
+export interface ProcessGenerationSignalDependencies {
+  readToken?: ReadProcessStartToken;
+  kill?: (pid: number, signal: NodeJS.Signals | number) => unknown;
+}
+
+/**
+ * Recheck the process generation immediately before sending the signal.
+ *
+ * The process can still exit and its PID can be reused between the token read
+ * and the signal. Eliminating that race requires a generation-bound OS handle.
+ */
+export function signalIfSameGeneration(
+  pid: number,
+  recordedToken: string | null | undefined,
+  signal: NodeJS.Signals | number,
+  dependencies: ProcessGenerationSignalDependencies = {},
+): { sent: boolean; verdict: ProcessGenerationVerdict } {
+  const kill = dependencies.kill ?? process.kill;
+  const verdict = verifyProcessGeneration(pid, recordedToken, dependencies.readToken);
+  if (verdict !== "same") return { sent: false, verdict };
+  try {
+    kill(pid, signal);
+    return { sent: true, verdict };
+  } catch {
+    return { sent: false, verdict };
+  }
+}
+
 /**
  * Do two tokens describe the same run?
  *