harnery 0.30.0 → 0.31.0

package/dist/core/agents/state/heartbeat-projector.js

@@ -67,7 +67,7 @@ function seed(ev, coordRoot) {
     const hb = {
         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,
@@ -112,12 +112,12 @@ function apply(hb, ev, coordRoot) {
     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)
@@ -141,6 +141,9 @@ function apply(hb, ev, coordRoot) {
                 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 = [];
             }
@@ -164,7 +167,7 @@ function apply(hb, ev, coordRoot) {
             hb.started_at = ev.ts;
             if (!hb.files_touched)
                 hb.files_touched = [];
-            hb.platform = harnessToPlatform(ev.harness);
+            hb.platform = adapterToPlatform(ev.adapter);
             break;
         }
         case "subagent.stop":
@@ -183,7 +186,7 @@ function apply(hb, ev, coordRoot) {
                     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");
@@ -270,14 +273,14 @@ function apply(hb, ev, coordRoot) {
         }
     }
 }
-function harnessToPlatform(harness) {
-    if (harness === "claude-code")
+function adapterToPlatform(adapter) {
+    if (adapter === "claude-code")
         return "claude_code";
-    if (harness === "cursor")
+    if (adapter === "cursor")
         return "cursor";
-    if (harness === "codex")
+    if (adapter === "codex")
         return "codex";
-    return harness;
+    return adapter;
 }
 function extractFilePath(data) {
     const raw = data.tool_input;
@@ -411,6 +414,7 @@ function writeHeartbeat(coordRoot, instanceId, hb) {
         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/dist/core/agents/state/heartbeat-writer.d.ts

@@ -69,7 +69,7 @@ export interface GroupUnclaimHit {
 export declare function groupUnclaim(coordRoot: string, groupId: string, path: string): GroupUnclaimHit[];
 export declare function killHeartbeat(coordRoot: string, instanceId: string): boolean;
 export declare function healPidmap(coordRoot: string, instanceId: string, pid: number): void;
-export declare function healHeartbeat(coordRoot: string, instanceId: string, sessionId?: string, model?: string, harness?: string): Heartbeat | null;
+export declare function healHeartbeat(coordRoot: string, instanceId: string, sessionId?: string, model?: string, adapter?: string): Heartbeat | null;
 /**
  * Stamp the heartbeat with the most-recent tool name + target. Written from
  * the post-tool-use hook.

package/dist/core/agents/state/heartbeat-writer.js

@@ -15,23 +15,23 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { emit } from "../events/emit.js";
-/** 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) {
+function adapterOf(platform) {
     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) {
-    if (harness === "cursor")
+function adapterToPlatform(adapter) {
+    if (adapter === "cursor")
         return "cursor";
-    if (harness === "codex")
+    if (adapter === "codex")
         return "codex";
     return "claude_code";
 }
@@ -49,7 +49,7 @@ function emitHealthHeal(coordRoot, type, instanceId, hb, data) {
             event_type: type,
             instance_id: instanceId,
             session_id: hb?.session_id ?? instanceId,
-            harness: harnessOf(hb?.platform),
+            adapter: adapterOf(hb?.platform),
             source: "agent-coord",
             data,
         });
@@ -226,7 +226,7 @@ export function healPidmap(coordRoot, instanceId, pid) {
         ...(existingOwner ? { prior: existingOwner.slice(0, 8) } : {}),
     });
 }
-export function healHeartbeat(coordRoot, instanceId, sessionId, model, harness) {
+export function healHeartbeat(coordRoot, instanceId, sessionId, model, adapter) {
     const path = heartbeatPath(coordRoot, instanceId);
     if (existsSync(path)) {
         // Already alive, return it.
@@ -264,11 +264,11 @@ export function healHeartbeat(coordRoot, instanceId, sessionId, model, harness)
         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/dist/core/agents/state/{scratch.d.ts → journal.d.ts}

@@ -1,27 +1,27 @@
 /**
- * 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.
  */
 /**
- * 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 declare function appendScratch(coordRoot: string, instanceId: string, category: string, body: string): {
+export declare function appendJournal(coordRoot: string, instanceId: string, category: string, body: string): {
     ok: boolean;
     reason?: string;
     path?: string;
 };
 /**
- * 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 declare function editScratchpad(coordRoot: string, instanceId: string, newBody: string, summary: string): {
+export declare function editJournal(coordRoot: string, instanceId: string, newBody: string, summary: string): {
     ok: boolean;
     reason?: string;
     archivePath?: string;
     path?: string;
 };
-//# sourceMappingURL=scratch.d.ts.map
+//# sourceMappingURL=journal.d.ts.map

package/dist/core/agents/state/{scratch.d.ts.map → journal.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"scratch.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/scratch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2CH;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAqBjD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CA8BvE"}
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/journal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2CH;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAqBjD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CA8BvE"}

package/dist/core/agents/state/{scratch.js → journal.js}

@@ -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.
@@ -20,11 +20,11 @@ const APPEND_BODY_CAP = 4096;
 function nowIsoSeconds() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
-function scratchPath(coordRoot, instanceId) {
-    return join(coordRoot, ".harnery", "scratch", `${instanceId}.md`);
+function journalPath(coordRoot, instanceId) {
+    return join(coordRoot, ".harnery", "journal", `${instanceId}.md`);
 }
 function archivePath(coordRoot, instanceId, suffix) {
-    return join(coordRoot, ".harnery", "scratch", "archived", `${instanceId}-${suffix}.md`);
+    return join(coordRoot, ".harnery", "journal", "archived", `${instanceId}-${suffix}.md`);
 }
 function atomicWriteText(path, content) {
     mkdirSync(dirname(path), { recursive: true });
@@ -33,10 +33,10 @@ function atomicWriteText(path, content) {
     renameSync(tmp, path);
 }
 /**
- * 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(coordRoot, instanceId, category, body) {
+export function appendJournal(coordRoot, instanceId, category, body) {
     if (!ALLOWED_CATEGORIES.has(category)) {
         return { ok: false, reason: `invalid category "${category}"` };
     }
@@ -44,7 +44,7 @@ export function appendScratch(coordRoot, instanceId, category, body) {
         return { ok: false, reason: "body required" };
     }
     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 = "";
     if (existsSync(target)) {
@@ -57,14 +57,14 @@ export function appendScratch(coordRoot, instanceId, category, body) {
     return { ok: true, path: target };
 }
 /**
- * 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(coordRoot, instanceId, newBody, summary) {
+export function editJournal(coordRoot, instanceId, newBody, summary) {
     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);
@@ -84,7 +84,7 @@ export function editScratchpad(coordRoot, instanceId, newBody, summary) {
     const summaryText = summary && summary.length > 0 ? summary : "(no summary)";
     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/dist/core/agents/state/pidmap.d.ts

@@ -1,14 +1,38 @@
 /**
  * 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.
  */
+/** Split a row into its fields, tolerating the pre-token two-field shape. */
+export declare function parsePidmapRow(row: string): {
+    instanceId: string;
+    platform: string;
+    startToken: string | undefined;
+};
+/**
+ * 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 declare function prunePidmapDeadRows(coordRoot: string): number;
 export declare function writePidmapRow(coordRoot: string, pid: number, instanceId: string, platform: string): void;
-/** 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 declare function instanceHasLivePid(coordRoot: string, instanceId: string): boolean;
 /** Drop every pid-map row owned by `instanceId`. Returns how many files were removed. */
 export declare function removePidmapRowsForInstance(coordRoot: string, instanceId: string): number;

package/dist/core/agents/state/pidmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pidmap.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/pidmap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,IAAI,CAYN;AAED,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAsBjF;AAED,yFAAyF;AACzF,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAqBzF"}
+{"version":3,"file":"pidmap.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/pidmap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAyBH,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,CAGA;AAwCD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CA8B7D;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,IAAI,CA6BN;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAmBjF;AAED,yFAAyF;AACzF,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAoBzF"}

package/dist/core/agents/state/pidmap.js

@@ -1,23 +1,124 @@
 /**
  * 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.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
+import { checkPidToken, processStartToken } from "./proc-start.js";
+/**
+ * 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) {
+    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, startToken) {
+    if (!pidIsAlive(pid))
+        return false;
+    return checkPidToken(pid, startToken) !== "mismatch";
+}
 function atomicWrite(path, content) {
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.tmp.${process.pid}`;
     writeFileSync(tmp, content, "utf8");
     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) {
+    try {
+        process.kill(pid, 0); // signal 0 = liveness probe
+        return true;
+    }
+    catch (error) {
+        return error.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) {
+    const dir = join(coordRoot, ".harnery", "pid-map");
+    if (!existsSync(dir))
+        return 0;
+    let removed = 0;
+    let names;
+    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;
+        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, pid, instanceId, platform) {
-    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 {
@@ -28,9 +129,27 @@ export function writePidmapRow(coordRoot, pid, instanceId, platform) {
             /* 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, instanceId) {
     const dir = join(coordRoot, ".harnery", "pid-map");
     if (!existsSync(dir))
@@ -43,19 +162,16 @@ export function instanceHasLivePid(coordRoot, instanceId) {
         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
+        // Rows that no longer name their process keep the scan going; one that does
+        // settles it.
+        if (rowStillNamesItsProcess(pid, startToken))
             return true;
-        }
-        catch {
-            // ESRCH (no such process): pid-map entry is stale, keep scanning
-        }
     }
     return false;
 }
@@ -73,8 +189,7 @@ export function removePidmapRowsForInstance(coordRoot, instanceId) {
         catch {
             continue;
         }
-        const owner = row.split("\t")[0]?.trim() ?? "";
-        if (owner !== instanceId)
+        if (parsePidmapRow(row).instanceId !== instanceId)
             continue;
         try {
             unlinkSync(join(dir, f));

package/dist/core/agents/state/proc-start.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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.
+ */
+/** Which probe answers "when did this process start?" on this machine. */
+export type StartTokenProbe = "procfs" | "ps";
+/**
+ * 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 declare function startTokenProbe(): StartTokenProbe;
+/** Forget the cached probe and boot id. Tests only. */
+export declare function resetStartTokenCaches(): void;
+/**
+ * `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 declare function procfsStartToken(pid: number): string | null;
+/**
+ * `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 declare function psStartToken(pid: number, run?: (pid: number) => {
+    status: number | null;
+    stdout: string;
+}): string | null;
+/**
+ * An opaque token identifying *this run* of `pid`, or null when the platform
+ * will not say.
+ */
+export declare function processStartToken(pid: number): string | null;
+/**
+ * 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 declare function tokensAgree(recorded: string, current: string): boolean;
+/**
+ * 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 declare function checkPidToken(pid: number, recorded: string | undefined): "match" | "mismatch" | "unverified";
+//# sourceMappingURL=proc-start.d.ts.map

package/dist/core/agents/state/proc-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proc-start.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/proc-start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,IAAI,CAAC;AAc9C;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAOjD;AAyBD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc3D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAiB,GAC7E,MAAM,GAAG,IAAI,CAUf;AAWD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQtE;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,GAAG,UAAU,GAAG,YAAY,CAKrC"}