harnery 0.30.0 → 0.31.0

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

@@ -16,7 +16,7 @@ import type { CanonicalEvent } from "../events/consume.ts";
 export interface V2Heartbeat {
   instance_id: string;
   session_id: string;
-  harness: string;
+  adapter: string;
   agent_id?: string;
   name?: string;
   kind?: "session" | "subagent" | "transient";
@@ -24,8 +24,9 @@ export interface V2Heartbeat {
   platform?: string;
   subagent_call_id?: string;
   parent_session_id?: string;
-  /** Set iff this owner is a `workflow run` child (joins to the run journal). */
+  /** Set iff this owner is a `workflow run` child (joins to the run transcript). */
   workflow_run_id?: string;
+  workflow_agent_id?: string;
   started_at?: string;
   last_heartbeat: string;
   last_tool?: string;
@@ -120,7 +121,7 @@ function seed(ev: CanonicalEvent, coordRoot: string): V2Heartbeat {
   const hb: V2Heartbeat = {
     instance_id: ev.instance_id,
     session_id: ev.session_id,
-    harness: ev.harness,
+    adapter: ev.adapter,
     last_heartbeat: ev.ts,
     last_event_id: ev.event_id,
     events_applied: 0,
@@ -167,11 +168,11 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
   switch (ev.event_type) {
     case "session.start":
       hb.started_at = pickStr(d, "started_at") ?? ev.ts;
-      hb.harness = ev.harness;
+      hb.adapter = ev.adapter;
       {
         const model = pickStr(d, "model");
         if (model) hb.model = model;
-        const platform = pickStr(d, "platform") ?? harnessToPlatform(ev.harness);
+        const platform = pickStr(d, "platform") ?? adapterToPlatform(ev.adapter);
         hb.platform = platform;
         const name = pickStr(d, "name");
         if (name) hb.name = name;
@@ -189,6 +190,8 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
         if (parentSession) hb.parent_session_id = parentSession;
         const workflowRunId = pickStr(d, "workflow_run_id");
         if (workflowRunId) hb.workflow_run_id = workflowRunId;
+        const workflowAgentId = pickStr(d, "workflow_agent_id");
+        if (workflowAgentId) hb.workflow_agent_id = workflowAgentId;
         if (!hb.files_touched) hb.files_touched = [];
       }
       break;
@@ -209,7 +212,7 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
       hb.agent_id = ev.instance_id;
       hb.started_at = ev.ts;
       if (!hb.files_touched) hb.files_touched = [];
-      hb.platform = harnessToPlatform(ev.harness);
+      hb.platform = adapterToPlatform(ev.adapter);
       break;
     }
 
@@ -231,7 +234,7 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
           hb.turn_summary = summary;
           hb.turn_summary_updated_at = ev.ts;
         }
-        // Backfill model for harnesses that omit it at session.start (Claude
+        // Backfill model for adapters that omit it at session.start (Claude
         // Code). The Stop hook resolves it from the transcript by this point;
         // only set when present so we never clobber a known model.
         const model = pickStr(d, "model");
@@ -320,11 +323,11 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
   }
 }
 
-function harnessToPlatform(harness: string): string {
-  if (harness === "claude-code") return "claude_code";
-  if (harness === "cursor") return "cursor";
-  if (harness === "codex") return "codex";
-  return harness;
+function adapterToPlatform(adapter: string): string {
+  if (adapter === "claude-code") return "claude_code";
+  if (adapter === "cursor") return "cursor";
+  if (adapter === "codex") return "codex";
+  return adapter;
 }
 
 function extractFilePath(data: Record<string, unknown>): string | undefined {
@@ -458,6 +461,7 @@ function writeHeartbeat(coordRoot: string, instanceId: string, hb: V2Heartbeat):
     setIfDefined(merged, "agent_id", hb.agent_id);
     setIfDefined(merged, "subagent_call_id", hb.subagent_call_id);
     setIfDefined(merged, "workflow_run_id", hb.workflow_run_id);
+    setIfDefined(merged, "workflow_agent_id", hb.workflow_agent_id);
     setIfDefined(merged, "model", hb.model);
     setIfDefined(merged, "platform", hb.platform);
     setIfDefined(merged, "started_at", hb.started_at);

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

@@ -25,21 +25,21 @@ import {
 import { dirname, join } from "node:path";
 import { emit } from "../events/emit.ts";
 
-/** Inline harness normalizer (mirrors canonical-emit.normalizeHarness), kept
+/** Inline adapter normalizer (mirrors canonical-emit.normalizeAdapter), kept
  * local so the writer's only cross-module dep is the in-process emit(). */
-function harnessOf(platform: string | undefined): "claude-code" | "cursor" | "codex" {
+function adapterOf(platform: string | undefined): "claude-code" | "cursor" | "codex" {
   if (platform === "cursor") return "cursor";
   if (platform === "codex") return "codex";
   return "claude-code";
 }
 
-/** Inverse of harnessOf: maps the canonical harness ("claude-code"/"cursor"/
+/** Inverse of adapterOf: maps the canonical adapter ("claude-code"/"cursor"/
  * "codex") to the legacy underscore platform label stored on the heartbeat.
- * Mirrors heartbeat-projector.harnessToPlatform so a healed heartbeat carries
+ * Mirrors heartbeat-projector.adapterToPlatform so a healed heartbeat carries
  * the same platform value projection would have written. */
-function harnessToPlatform(harness: string | undefined): string {
-  if (harness === "cursor") return "cursor";
-  if (harness === "codex") return "codex";
+function adapterToPlatform(adapter: string | undefined): string {
+  if (adapter === "cursor") return "cursor";
+  if (adapter === "codex") return "codex";
   return "claude_code";
 }
 
@@ -63,7 +63,7 @@ function emitHealthHeal(
       event_type: type,
       instance_id: instanceId,
       session_id: hb?.session_id ?? instanceId,
-      harness: harnessOf(hb?.platform),
+      adapter: adapterOf(hb?.platform),
       source: "agent-coord",
       data,
     });
@@ -290,7 +290,7 @@ export function healHeartbeat(
   instanceId: string,
   sessionId?: string,
   model?: string,
-  harness?: string,
+  adapter?: string,
 ): Heartbeat | null {
   const path = heartbeatPath(coordRoot, instanceId);
   if (existsSync(path)) {
@@ -330,11 +330,11 @@ export function healHeartbeat(
     started_at: now,
     last_heartbeat: now,
     files_touched: [],
-    // Default to claude_code only when the caller can't tell us the harness
+    // Default to claude_code only when the caller can't tell us the adapter
     // (e.g. manual `harn agents heal`). The live tool.pre_use heal threads the
-    // detected harness so a pruned Cursor/Codex heartbeat is recreated with
+    // detected adapter so a pruned Cursor/Codex heartbeat is recreated with
     // the correct platform instead of being mislabeled claude_code.
-    platform: harnessToPlatform(harness),
+    platform: adapterToPlatform(adapter),
   };
   atomicWrite(path, JSON.stringify(hb, null, 2));
   // Write-only telemetry: only the actual-recreate branch reaches here (the

package/src/core/agents/state/{scratch.ts → journal.ts}

@@ -1,6 +1,6 @@
 /**
- * Scratchpad mutations: append-only timestamped journal at
- * `.harnery/scratch/<instance_id>.md`.
+ * Journal mutations: append-only timestamped transcript at
+ * `.harnery/journal/<instance_id>.md`.
  *
  * Used by the agents-coord web UI route handlers for both operator-nudge
  * appends and inline edits.
@@ -32,12 +32,12 @@ function nowIsoSeconds(): string {
   return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
 
-function scratchPath(coordRoot: string, instanceId: string): string {
-  return join(coordRoot, ".harnery", "scratch", `${instanceId}.md`);
+function journalPath(coordRoot: string, instanceId: string): string {
+  return join(coordRoot, ".harnery", "journal", `${instanceId}.md`);
 }
 
 function archivePath(coordRoot: string, instanceId: string, suffix: string): string {
-  return join(coordRoot, ".harnery", "scratch", "archived", `${instanceId}-${suffix}.md`);
+  return join(coordRoot, ".harnery", "journal", "archived", `${instanceId}-${suffix}.md`);
 }
 
 function atomicWriteText(path: string, content: string): void {
@@ -48,10 +48,10 @@ function atomicWriteText(path: string, content: string): void {
 }
 
 /**
- * Append a timestamped entry to the owner's scratchpad.
+ * Append a timestamped entry to the owner's journal.
  * Returns true on success, false if validation failed.
  */
-export function appendScratch(
+export function appendJournal(
   coordRoot: string,
   instanceId: string,
   category: string,
@@ -66,7 +66,7 @@ export function appendScratch(
 
   const trimmedBody =
     body.length > APPEND_BODY_CAP ? `${body.slice(0, APPEND_BODY_CAP - 3)}...` : body;
-  const target = scratchPath(coordRoot, instanceId);
+  const target = journalPath(coordRoot, instanceId);
   const ts = nowIsoSeconds();
 
   let prior = "";
@@ -80,10 +80,10 @@ export function appendScratch(
 }
 
 /**
- * Replace the scratchpad with new body, archiving prior contents and
+ * Replace the journal with new body, archiving prior contents and
  * appending an "(edited via UI by the operator)" audit-marker note.
  */
-export function editScratchpad(
+export function editJournal(
   coordRoot: string,
   instanceId: string,
   newBody: string,
@@ -92,7 +92,7 @@ export function editScratchpad(
   if (typeof newBody !== "string") {
     return { ok: false, reason: "newBody required" };
   }
-  const target = scratchPath(coordRoot, instanceId);
+  const target = journalPath(coordRoot, instanceId);
   const ts = nowIsoSeconds();
   const archiveSuffix = `pre-ui-${ts.replace(/:/g, "-")}`;
   const archive = archivePath(coordRoot, instanceId, archiveSuffix);
@@ -114,7 +114,7 @@ export function editScratchpad(
   const auditMarker =
     `## [${ts}] note (edited via UI by the operator)\n` +
     `${summaryText}\n` +
-    `Pre-edit archived at .harnery/scratch/archived/${instanceId}-${archiveSuffix}.md\n\n`;
+    `Pre-edit archived at .harnery/journal/archived/${instanceId}-${archiveSuffix}.md\n\n`;
 
   atomicWriteText(target, prior + auditMarker + newBody + (newBody.endsWith("\n") ? "" : "\n"));
   return { ok: true, archivePath: archive, path: target };

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

@@ -1,9 +1,15 @@
 /**
  * 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
- * for a matching entry (preferring the harness, falling back to any platform).
+ * Per-adapter pid-map at `.harnery/pid-map/<pid>` containing
+ * `<instance_id>\t<platform>\t<start_token>`. `harn agents whoami` walks ppid up
+ * 20 hops looking for a matching entry (preferring the adapter, falling back to
+ * any platform).
+ *
+ * The start token pins each row to one *run* of that pid, because a pid on its
+ * own is a number the OS re-issues — see `proc-start.ts` for how fast. Rows
+ * written before tokens existed carry two fields and read as unverified, which
+ * behaves exactly as they always did.
  *
  * Atomic temp+rename. Idempotent: re-writing the same row is a no-op.
  */
@@ -18,6 +24,43 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
+import { checkPidToken, processStartToken } from "./proc-start.ts";
+
+/**
+ * Row count that triggers a dead-row sweep on the next write.
+ *
+ * Rows are written per hook shell, and those shells exit immediately, so an
+ * unattended map only grows. One repo was observed holding 512 rows of which 510
+ * were dead. That matters beyond disk: pids get recycled, so a stale row whose
+ * number is later reused makes an identity walk resolve to a long-gone agent,
+ * and `agents whoami` starts reporting somebody else's session.
+ */
+const PRUNE_AT_ROWS = 200;
+
+/** Split a row into its fields, tolerating the pre-token two-field shape. */
+export function parsePidmapRow(row: string): {
+  instanceId: string;
+  platform: string;
+  startToken: string | undefined;
+} {
+  const [instanceId = "", platform = "", startToken = ""] = row.trim().split("\t");
+  return { instanceId, platform, startToken: startToken || undefined };
+}
+
+/**
+ * Is this row still about the process it was written for?
+ *
+ * Two ways to fail. The pid may have exited, which a liveness probe catches.
+ * Or the pid may have been re-issued to an unrelated process, which a liveness
+ * probe cannot catch — that pid is alive — and which the start token does.
+ * Getting the second one wrong resolves an identity walk to a long-gone agent
+ * and keeps a dead agent's heartbeat looking live, so the check belongs
+ * everywhere a row is believed, not only where it is swept.
+ */
+function rowStillNamesItsProcess(pid: number, startToken: string | undefined): boolean {
+  if (!pidIsAlive(pid)) return false;
+  return checkPidToken(pid, startToken) !== "mismatch";
+}
 
 function atomicWrite(path: string, content: string): void {
   mkdirSync(dirname(path), { recursive: true });
@@ -26,14 +69,73 @@ function atomicWrite(path: string, content: string): void {
   renameSync(tmp, path);
 }
 
+/**
+ * Is this pid a running process?
+ *
+ * `EPERM` means the process exists but belongs to another user, which is still
+ * alive. Treating every failure as "dead" would drop a live foreign row and
+ * weaken the checks that depend on knowing a claim is anchored.
+ */
+function pidIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0); // signal 0 = liveness probe
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * Delete every pid-map row that no longer names its process — exited, or its
+ * pid re-issued to something else. Returns the number removed.
+ */
+export function prunePidmapDeadRows(coordRoot: string): number {
+  const dir = join(coordRoot, ".harnery", "pid-map");
+  if (!existsSync(dir)) return 0;
+  let removed = 0;
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return 0;
+  }
+  for (const f of names) {
+    const pid = Number.parseInt(f, 10);
+    // Only touch files whose whole name is a pid, so a stray note or a
+    // half-written `.tmp.<pid>` file is left where it is.
+    if (!Number.isFinite(pid) || String(pid) !== f) continue;
+    let token: string | undefined;
+    try {
+      token = parsePidmapRow(readFileSync(join(dir, f), "utf8")).startToken;
+    } catch {
+      /* unreadable row: fall back to the liveness check alone */
+    }
+    if (rowStillNamesItsProcess(pid, token)) continue;
+    try {
+      unlinkSync(join(dir, f));
+      removed += 1;
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
+  return removed;
+}
+
 export function writePidmapRow(
   coordRoot: string,
   pid: number,
   instanceId: string,
   platform: string,
 ): void {
-  const path = join(coordRoot, ".harnery", "pid-map", String(pid));
-  const row = `${instanceId}\t${platform}`;
+  const dir = join(coordRoot, ".harnery", "pid-map");
+  const path = join(dir, String(pid));
+  // Stamped at write time, when the pid provably belongs to the process we
+  // mean. A platform that will not say gets no third field rather than an empty
+  // one, so an unverifiable row stays byte-identical to what came before.
+  const startToken = processStartToken(pid);
+  const row = startToken
+    ? `${instanceId}\t${platform}\t${startToken}`
+    : `${instanceId}\t${platform}`;
   // Read-then-write idempotency: skip the rename churn when already current.
   if (existsSync(path)) {
     try {
@@ -42,10 +144,27 @@ export function writePidmapRow(
       /* fall through to write */
     }
   }
+  // Sweep on the way past the threshold. Writes are the only event guaranteed
+  // to happen while agents are active, so hanging the sweep here keeps the map
+  // bounded without a scheduled job, and the common write stays a single stat.
+  try {
+    if (existsSync(dir) && readdirSync(dir).length > PRUNE_AT_ROWS) {
+      prunePidmapDeadRows(coordRoot);
+    }
+  } catch {
+    /* pruning is best-effort; never fail a write over it */
+  }
   atomicWrite(path, row);
 }
 
-/** True when any pid-map row for `instanceId` still belongs to a live process. */
+/**
+ * True when any pid-map row for `instanceId` still belongs to a live process.
+ *
+ * Callers spend this answer on consequential things — whether a commit guard
+ * treats a heartbeat as a live peer, whether a name can be reclaimed from an
+ * abandoned session — so a re-issued pid must not read as that agent still
+ * running.
+ */
 export function instanceHasLivePid(coordRoot: string, instanceId: string): boolean {
   const dir = join(coordRoot, ".harnery", "pid-map");
   if (!existsSync(dir)) return false;
@@ -56,16 +175,13 @@ export function instanceHasLivePid(coordRoot: string, instanceId: string): boole
     } catch {
       continue;
     }
-    const owner = row.split("\t")[0]?.trim() ?? "";
+    const { instanceId: owner, startToken } = parsePidmapRow(row);
     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
-    }
+    // Rows that no longer name their process keep the scan going; one that does
+    // settles it.
+    if (rowStillNamesItsProcess(pid, startToken)) return true;
   }
   return false;
 }
@@ -82,8 +198,7 @@ export function removePidmapRowsForInstance(coordRoot: string, instanceId: strin
     } catch {
       continue;
     }
-    const owner = row.split("\t")[0]?.trim() ?? "";
-    if (owner !== instanceId) continue;
+    if (parsePidmapRow(row).instanceId !== instanceId) continue;
     try {
       unlinkSync(join(dir, f));
       removed += 1;

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

@@ -0,0 +1,208 @@
+/**
+ * Process start-token probe: the "is this still the same process?" half of pid
+ * identity.
+ *
+ * A pid alone does not identify a process. Operating systems hand numbers back
+ * out, and faster than intuition suggests: one development machine runs a
+ * `pid_max` of 99999 against roughly 100 new processes a second, turning the
+ * whole space over about every quarter hour. Anything that remembers a pid for
+ * longer than that is remembering a number, not a process.
+ *
+ * A start token pins the pair down. Two processes can share a pid but never a
+ * pid *and* a start instant, so a recorded `(pid, token)` either still names the
+ * process that was recorded or plainly does not.
+ *
+ * The token is opaque on purpose. Callers compare it for equality and nothing
+ * else, which is why no clock arithmetic appears here: Linux reports ticks since
+ * boot and BSD reports a formatted date, and neither needs converting to be
+ * compared with itself. A platform that will not answer returns null, meaning
+ * "unverifiable" — callers fall back to a plain liveness check, which is where
+ * they were before this existed.
+ *
+ * Two rules keep comparison honest, and both exist because getting them wrong
+ * reports a *false* mismatch, which prunes a live row and hands the identity
+ * walk the same wrong answer this module was written to stop:
+ *
+ * 1. One machine uses one probe. The probe is chosen by capability and locked
+ *    in, never fallen back from, so a transient read failure cannot answer in
+ *    the other probe's dialect and read as a recycled pid.
+ * 2. A probe's output must not depend on who asked. The `ps` text is formatted
+ *    through the caller's locale and timezone, so both are pinned; without that,
+ *    two callers reading the same live process disagree.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { coordEnv } from "../../../lib/env.ts";
+
+/** Which probe answers "when did this process start?" on this machine. */
+export type StartTokenProbe = "procfs" | "ps";
+
+/**
+ * The `ps` probe is text formatted by `strftime("%c", localtime(...))`, so its
+ * output moves with `TZ` and `LC_TIME`. A hook running under `LC_ALL=C` (git
+ * sets it routinely) and a shell running under the user's locale would render
+ * the same start instant two different ways and call each other liars. Pinning
+ * both makes the rendering a property of the process, not of its reader.
+ */
+const PS_ENV_PINS = { TZ: "UTC", LC_ALL: "C" } as const;
+
+let cachedProbe: StartTokenProbe | undefined;
+let cachedBootId: string | null | undefined;
+
+/**
+ * Which probe this machine uses, decided once.
+ *
+ * `HARNERY_PID_PROBE` forces the choice. That exists so the `ps` path can be
+ * exercised on a procfs machine — it is the same code on either OS, and running
+ * it only on hardware we happen to own is how a branch rots.
+ */
+export function startTokenProbe(): StartTokenProbe {
+  const override = coordEnv("PID_PROBE");
+  if (override === "procfs" || override === "ps") return override;
+  if (cachedProbe === undefined) {
+    cachedProbe = existsSync("/proc/self/stat") ? "procfs" : "ps";
+  }
+  return cachedProbe;
+}
+
+/**
+ * A short, stable identifier for the current boot, or null where there is none.
+ *
+ * Linux counts a process's start in ticks *since boot*, so the number alone
+ * repeats every time the machine restarts. Pid-map rows live in the working
+ * tree and outlive reboots, which is the whole exposure: a stale row for pid
+ * 1234 at 45.23s after boot matches a fresh process that happens to land on the
+ * same pid at the same moment of the next boot, and that false match is exactly
+ * the bug the token exists to prevent. Scoping the count to its boot removes
+ * the coincidence. BSD needs no equivalent, since its token is an absolute
+ * date.
+ */
+function bootId(): string | null {
+  if (cachedBootId !== undefined) return cachedBootId;
+  try {
+    const raw = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim().replace(/-/g, "");
+    cachedBootId = /^[0-9a-f]{8,}$/.test(raw) ? raw.slice(0, 8) : null;
+  } catch {
+    cachedBootId = null;
+  }
+  return cachedBootId;
+}
+
+/** Forget the cached probe and boot id. Tests only. */
+export function resetStartTokenCaches(): void {
+  cachedProbe = undefined;
+  cachedBootId = undefined;
+}
+
+/**
+ * `l[<boot>.]<ticks since boot>` from `/proc/<pid>/stat`, with no subprocess.
+ *
+ * The tick count is field 22, counted from the end of the comm field rather
+ * than by splitting the whole line, because comm is the executable name in
+ * parentheses and may itself contain spaces and parens. The boot segment is
+ * dropped rather than faked when the kernel will not name its boot, which
+ * yields the pre-boot-id shape that `tokensAgree` still accepts.
+ */
+export function procfsStartToken(pid: number): string | null {
+  let stat: string;
+  try {
+    stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+  } catch {
+    return null; // dead pid, or no procfs — either way, nothing to say
+  }
+  const afterComm = stat.slice(stat.lastIndexOf(") ") + 2);
+  // Fields after comm, 0-based: 0 is state (field 3), so starttime (field 22)
+  // sits at 19.
+  const ticks = afterComm.split(" ")[19];
+  if (!ticks || !/^\d+$/.test(ticks)) return null;
+  const boot = bootId();
+  return boot ? `l${boot}.${ticks}` : `l${ticks}`;
+}
+
+/**
+ * `p<start date>` from one `ps -o lstart=`, for machines without procfs.
+ *
+ * Second resolution is ample: telling two runs of one pid apart would need the
+ * entire pid space to recycle inside a second. The runner is injectable so the
+ * parsing and the env pinning can be tested without a process to look at.
+ */
+export function psStartToken(
+  pid: number,
+  run: (pid: number) => { status: number | null; stdout: string } = defaultPsRun,
+): string | null {
+  let out: { status: number | null; stdout: string };
+  try {
+    out = run(pid);
+  } catch {
+    return null; // no ps on this machine
+  }
+  if (out.status !== 0) return null;
+  const lstart = (out.stdout ?? "").split("\n")[0]?.trim().replace(/\s+/g, " ");
+  return lstart ? `p${lstart}` : null;
+}
+
+function defaultPsRun(pid: number): { status: number | null; stdout: string } {
+  const out = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+    encoding: "utf8",
+    timeout: 2000,
+    env: { ...process.env, ...PS_ENV_PINS },
+  });
+  return { status: out.status, stdout: out.stdout ?? "" };
+}
+
+/**
+ * An opaque token identifying *this run* of `pid`, or null when the platform
+ * will not say.
+ */
+export function processStartToken(pid: number): string | null {
+  if (!Number.isFinite(pid) || pid <= 0) return null;
+  return startTokenProbe() === "procfs" ? procfsStartToken(pid) : psStartToken(pid);
+}
+
+/**
+ * Do two tokens describe the same run?
+ *
+ * Equality, plus one concession: a row written before tokens carried a boot
+ * segment recorded the tick count alone, so it is compared on the part it
+ * actually recorded. Refusing that would call every pre-upgrade row a recycled
+ * pid and prune a working machine's live rows the first time the new code ran.
+ * Such a row loses its reboot protection until the next write rewrites it,
+ * which is a strictly better position than the one it came from.
+ */
+export function tokensAgree(recorded: string, current: string): boolean {
+  if (recorded === current) return true;
+  // Only the Linux form has a boot segment to disagree about, and only when
+  // exactly one side carries one is this a shape difference rather than two
+  // genuinely different start instants.
+  if (recorded[0] !== "l" || current[0] !== "l") return false;
+  if (recorded.includes(".") === current.includes(".")) return false;
+  return ticksOf(recorded) === ticksOf(current);
+}
+
+function ticksOf(token: string): string {
+  const dot = token.indexOf(".");
+  return dot === -1 ? token.slice(1) : token.slice(dot + 1);
+}
+
+/**
+ * Does `pid` still name the process a row recorded?
+ *
+ * Three answers, and the difference between the last two matters:
+ *
+ * - `"match"` — recorded token, current token, same run. The row is trustworthy.
+ * - `"mismatch"` — both present and different. The pid was recycled. This is
+ *   the case a liveness check cannot see, because a recycled pid is alive.
+ * - `"unverified"` — no recorded token (a row written before tokens existed) or
+ *   no current one (an unsupported platform). Callers treat this the way they
+ *   treated every row previously: trust it if the pid is alive.
+ */
+export function checkPidToken(
+  pid: number,
+  recorded: string | undefined,
+): "match" | "mismatch" | "unverified" {
+  if (!recorded) return "unverified";
+  const current = processStartToken(pid);
+  if (!current) return "unverified";
+  return tokensAgree(recorded, current) ? "match" : "mismatch";
+}

package/src/core/agents/state/shell-mutation.ts

@@ -1,7 +1,7 @@
 /**
  * A heuristic parser that extracts file paths likely to be mutated by a
  * shell command. Used by
- * the cursor + codex harness adapters to emit SHELL_CLAIM_CANDIDATE log lines
+ * the cursor + codex adapter adapters to emit SHELL_CLAIM_CANDIDATE log lines
  * (warn-only, never blocks).
  *
  * Two cases: