@staix/agent-hub 0.12.20 → 0.12.22

package/src/hub/delivery-journal.ts

@@ -3,6 +3,7 @@ import { dirname } from "node:path";
 import { Database } from "bun:sqlite";
 import type { BusSnapshot } from "./bus.ts";
 import type { Envelope } from "./envelope.ts";
+import { processLiveness } from "../pi/process-signature.ts";
 
 export type JournalDeliveryState =
   | "queued"
@@ -331,13 +332,12 @@ export class DeliveryJournal {
         Number.isInteger(status.pid) &&
         Number(status.pid) > 0
       ) {
-        try {
-          process.kill(Number(status.pid), 0);
+        // #226: a signed manifest whose pid was reused is gone; with a signature, an owner that cannot be identified is
+        // refused like a live one. Unsigned, a pid that cannot be probed (EPERM) never refused here, as before.
+        const signature = typeof status.pidSignature === "string" ? status.pidSignature : undefined;
+        const owner = processLiveness(Number(status.pid), signature);
+        if (owner === "live" || (signature && owner === "unknown"))
           throw new Error("delivery journal is owned by a live instance");
-        } catch (e) {
-          if (e instanceof Error && e.message.includes("owned by a live"))
-            throw e;
-        }
       }
     } catch (e) {
       if (e instanceof Error && e.message.includes("owned by a live")) throw e;

package/src/hub/events.ts

@@ -11,6 +11,7 @@ export const EVENTS_SCHEMA = 1;
  * ids, routing and sizes, tasks carry ids and states, so the file can be exported without leaking what agents wrote.
  */
 export type HubEvent =
+  | { type: "permission_mode"; peer: string; from: import("./permission-mode.ts").PermissionMode; to: import("./permission-mode.ts").PermissionMode }
   | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string }
   | { type: "overflow" | "undeliverable"; id: string; from: string; peer: string }
   | { type: "stale"; id: string; from: string; peer: string; task?: string }
@@ -39,7 +40,7 @@ export type HubEvent =
   | { type: "cohort"; id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: string[] }
   | ({ type: "tokens"; peer: string; n: number } & Partial<TaskAttribution>)
   | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript"; id: string; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
-  | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; pii: boolean }
+  | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; pii: boolean; reason?: string }
   | { type: "overlap"; task: number; owner: string; others: { task: number; owner: string; paths: string[]; symbols?: string[] }[] }
   /** A PII screen verdict (issue #198): what was screened and the closed label, source and category, never the text. */
   | ({ type: "pii_screen" } & ScreenRecord)
@@ -65,7 +66,7 @@ function cutShort(file: string): boolean {
 }
 
 /** An appender that never throws: the state dir can vanish under a running hub, and telemetry must not take it down. */
-export function eventLog(file: string): (e: HubEvent) => void {
+export function eventLog(file: string, onFailure?: (e: HubEvent) => void): (e: HubEvent) => void {
   let first = true;
   return (e) => {
     try {
@@ -74,6 +75,7 @@ export function eventLog(file: string): (e: HubEvent) => void {
       first = false;
       appendFileSync(file, `${lead}${JSON.stringify({ v: EVENTS_SCHEMA, at: new Date().toISOString(), ...e })}\n`);
     } catch {
+      try { onFailure?.(e); } catch { /* telemetry failure reporting is optional too */ }
       // the state dir is gone; the watchdog is stopping the hub
     }
   };

package/src/hub/lifecycle.ts

@@ -8,6 +8,7 @@ import { startDaemon } from "./daemon.ts";
 import { Registry, type Project } from "./registry.ts";
 import { CODEX_APP, CODEX_PROXY, CONTROL, SWITCHYARD } from "./ports.ts";
 import { assertLifecycleAvailable, recoveryLock } from "./recovery-store.ts";
+import { processLiveness, processSignature } from "../pi/process-signature.ts";
 
 export type ProjectInspection = {
   state: "running" | "stopped" | "stopping" | "unavailable" | "incompatible" | "missing" | "starting";
@@ -15,19 +16,12 @@ export type ProjectInspection = {
   error?: string;
 };
 
-/** Alive, gone (`false`), or uncertain (`undefined`: no valid pid, or no permission to ask). */
-export function processAlive(pid: unknown): boolean | undefined {
-  if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) return undefined;
-  try { process.kill(pid, 0); return true; }
-  catch (error) { return (error as NodeJS.ErrnoException).code === "ESRCH" ? false : undefined; }
-}
-
 /** A port or PID alone is never evidence that the selected project's hub is alive. */
 export async function inspectProject(project: Project): Promise<ProjectInspection> {
   if (!existsSync(project.root)) return { state: "missing", error: "project directory is missing" };
   const control = readControl(project.stateDir);
   if (control) {
-    if (processAlive(control.pid) === false) return { state: "stopped" };
+    if (processLiveness(control.pid, control.pidSignature) === "gone") return { state: "stopped" };
     if (control.protocol !== undefined && control.protocol !== PROTOCOL) {
       return { state: "incompatible", error: `hub protocol ${control.protocol}; stop with its matching CLI before upgrading` };
     }
@@ -43,7 +37,7 @@ export async function inspectProject(project: Project): Promise<ProjectInspectio
       if (!response.status || response.status.projectId !== project.id || !response.status.instanceId || response.status.cwd !== project.root) {
         return { state: "unavailable", error: "authenticated hub identity does not match registration" };
       }
-      if (project.instanceId && project.instanceId !== response.status.instanceId && processAlive(project.pid) !== false) {
+      if (project.instanceId && project.instanceId !== response.status.instanceId && processLiveness(project.pid, project.pidSignature) !== "gone") {
         return { state: "unavailable", error: "daemon instance differs from the registry claim" };
       }
       return response.status.stopping
@@ -53,10 +47,11 @@ export async function inspectProject(project: Project): Promise<ProjectInspectio
       return { state: (error as { code?: number }).code === 4426 ? "incompatible" : "unavailable", error: (error as Error).message };
     } finally { client?.close(); }
   }
-  if (project.instanceId && processAlive(project.pid) !== false) return { state: "starting", error: "daemon owns a startup or shutdown claim" };
+  if (project.instanceId && processLiveness(project.pid, project.pidSignature) !== "gone") return { state: "starting", error: "daemon owns a startup or shutdown claim" };
   try {
+    // Written only by daemons up to 0.12.20 (#226): an unsigned legacy record, read as those releases read it.
     const pid = Number(readFileSync(join(project.stateDir, "hub.pid"), "utf8").trim());
-    if (processAlive(pid) !== false) return { state: "unavailable", error: "state has a live or uncertain owner but no usable control connection" };
+    if (processLiveness(pid) !== "gone") return { state: "unavailable", error: "state has a live or uncertain owner but no usable control connection" };
   } catch { /* no legacy PID file */ }
   return { state: "stopped" };
 }
@@ -109,7 +104,7 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
     const before = await inspectProject(registry.get(project.id) ?? project);
     if (before.state === "running" || before.state === "starting") return;
     if (before.state !== "stopped") throw new Error(before.error ?? before.state);
-    claimed = registry.claim(project.id, instanceId, process.pid);
+    claimed = registry.claim(project.id, instanceId, process.pid, processSignature(process.pid));
     if (!claimed) return;
     let base = registry.get(project.id)!.basePort;
     for (let attempt = 0; attempt < 100; attempt++) {
@@ -185,7 +180,7 @@ function claimHeld(id: string, instanceId: string): boolean {
   const registry = new Registry();
   try {
     const row = registry.get(id);
-    return row?.instanceId === instanceId && (row.pid === null || processAlive(row.pid) !== false);
+    return row?.instanceId === instanceId && (row.pid === null || processLiveness(row.pid, row.pidSignature) !== "gone");
   } finally { registry.close(); }
 }
 

package/src/hub/manager.ts

@@ -9,6 +9,7 @@ import { hubHome } from "./project.ts";
 import { startDashboard } from "./ui.ts";
 import { projectChain } from "../memory/recall.ts";
 import type { ProjectInspection } from "./lifecycle.ts";
+import { processLiveness, processSignature } from "../pi/process-signature.ts";
 
 export type ProjectRecord = Project;
 export type Lifecycle = {
@@ -18,7 +19,7 @@ export type Lifecycle = {
 };
 export type ManagerOptions = { registry?: Registry; lifecycle?: Lifecycle; home?: string; cli?: string; orphanWatchMs?: number };
 type ManagerHandle = { stop(): Promise<void>; stopped: Promise<void> };
-type Manifest = { port: number; protocol: number; instanceId: string; pid: number };
+type Manifest = { port: number; protocol: number; instanceId: string; pid: number; pidSignature?: string };
 const active = new Map<string, { handle: ManagerHandle; issue(): string }>();
 const CONTROL_TIMEOUT = 3000;
 // A current CLI may authenticate the previous protocol-9 manager while
@@ -41,20 +42,20 @@ async function bounded<T>(promise: Promise<T>, ms: number): Promise<T> {
     timer = setTimeout(() => reject(new Error("completion was not confirmed; refresh before retrying")), ms);
   })]); } finally { clearTimeout(timer); }
 }
-function alive(pid: number): boolean | undefined {
-  if (!Number.isSafeInteger(pid) || pid < 1) return undefined;
-  try { process.kill(pid, 0); return true; }
-  catch (error) { return (error as NodeJS.ErrnoException).code === "ESRCH" ? false : undefined; }
-}
-function claimOwner(path: string, instanceId: string): Database {
+function claimOwner(path: string, instanceId: string, signature: string | undefined): Database {
   const db = new Database(path, { create: true });
   try {
     db.run("PRAGMA busy_timeout = 5000");
-    db.run("CREATE TABLE IF NOT EXISTS owner (slot INTEGER PRIMARY KEY CHECK (slot = 1), instance_id TEXT NOT NULL, pid INTEGER NOT NULL)");
+    db.run("CREATE TABLE IF NOT EXISTS owner (slot INTEGER PRIMARY KEY CHECK (slot = 1), instance_id TEXT NOT NULL, pid INTEGER NOT NULL, signature TEXT)");
+    if (!(db.query("PRAGMA table_info(owner)").all() as { name: string }[]).some((c) => c.name === "signature")) {
+      try { db.run("ALTER TABLE owner ADD COLUMN signature TEXT"); }
+      catch (error) { if (!/duplicate column/i.test((error as Error).message)) throw error; }
+    }
     db.transaction(() => {
-      const row = db.query("SELECT pid FROM owner WHERE slot = 1").get() as { pid: number } | null;
-      if (row && alive(row.pid) !== false) throw new Error("manager has a live or uncertain owner");
-      db.query("INSERT OR REPLACE INTO owner (slot, instance_id, pid) VALUES (1, ?, ?)").run(instanceId, process.pid);
+      // #226: an older manager's INSERT OR REPLACE leaves the signature NULL, so its row is judged by the pid alone.
+      const row = db.query("SELECT pid, signature FROM owner WHERE slot = 1").get() as { pid: number; signature: string | null } | null;
+      if (row && processLiveness(row.pid, row.signature) !== "gone") throw new Error("manager has a live or uncertain owner");
+      db.query("INSERT OR REPLACE INTO owner (slot, instance_id, pid, signature) VALUES (1, ?, ?, ?)").run(instanceId, process.pid, signature ?? null);
     }).immediate();
     return db;
   } catch (error) { db.close(); throw error; }
@@ -83,6 +84,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
   const f = files(home);
   mkdirSync(f.dir, { recursive: true, mode: 0o700 });
   const token = randomBytes(32).toString("hex"), instanceId = randomUUID();
+  const pidSignature = processSignature(process.pid); // #226: the owner row and manifest say which process holds this pid
   let owner: Database | undefined;
   let server: ReturnType<typeof Bun.serve> | undefined;
   let dashboard: ReturnType<typeof startDashboard> | undefined;
@@ -110,7 +112,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
     cleanup(); resolveStopped();
   };
   try {
-    owner = claimOwner(f.owner, instanceId);
+    owner = claimOwner(f.owner, instanceId, pidSignature);
     const aliases = new Map<string, { at: number; names: string[] }>();
     const list = async () => {
       const projects = registry.list();
@@ -172,7 +174,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
     writeFileSync(f.token, token, { mode: 0o600 });
     chmodSync(f.token, 0o600);
     const temp = `${f.status}.${instanceId}.tmp`;
-    writeFileSync(temp, JSON.stringify({ port: server.port, protocol: PROTOCOL, instanceId, pid: process.pid }));
+    writeFileSync(temp, JSON.stringify({ port: server.port, protocol: PROTOCOL, instanceId, pid: process.pid, ...(pidSignature ? { pidSignature } : {}) }));
     renameSync(temp, f.status);
     // The manager outlives whoever opened it; a deleted AGENTHUB_HOME (a test suite's temp
     // home, issue #56) must not leave it serving a registry that no longer exists.
@@ -209,7 +211,7 @@ export async function openManager(options: ManagerOptions = {}): Promise<string>
   try { return (await managerRequest(home, "/open")).body.url; }
   catch (error) {
     const old = readManifest(home);
-    if (old && alive(old.pid) !== false) throw error;
+    if (old && processLiveness(old.pid, old.pidSignature) !== "gone") throw error;
     // A definitely dead manager can be recovered by its ownership claim.
   }
   const f = files(home);

package/src/hub/peers.ts

@@ -18,7 +18,7 @@ export interface PeerAdapter {
   /** Optional: feed envelopes into the turn that is running now. Only called while `state === "busy"`. */
   steer?(envs: Envelope[], deliveryId?: string): Promise<void>;
   start(): Promise<void>;
-  stop(): Promise<void>;
+  stop(reason?: string): Promise<void>;
   /** Set by the bus. The peer said something worth sharing. */
   onMessage?: (body: string, opts?: EnvelopeOpts) => unknown;
   /** Set by the bus. */
@@ -84,5 +84,5 @@ export abstract class BasePeer implements PeerAdapter {
 
   abstract deliver(envs: Envelope[], deliveryId?: string): Promise<void>;
   abstract start(): Promise<void>;
-  abstract stop(): Promise<void>;
+  abstract stop(reason?: string): Promise<void>;
 }

package/src/hub/permission-mode.ts

@@ -0,0 +1,44 @@
+import { lstatSync } from "node:fs";
+import { isAbsolute, relative, sep } from "node:path";
+
+/** Operator-selected approval frequency; agent sandboxes remain separate. */
+export const PERMISSION_MODES = ["ask", "ask-when-needed", "never-ask"] as const;
+export type PermissionMode = typeof PERMISSION_MODES[number];
+export const KIMI_MODE_IDS: Readonly<Record<PermissionMode, string>> = { ask: "default", "ask-when-needed": "yolo", "never-ask": "auto" };
+export const isPermissionMode = (value: unknown): value is PermissionMode => typeof value === "string" && (PERMISSION_MODES as readonly string[]).includes(value);
+export function permissionDefaults(value: unknown): Record<string, PermissionMode> {
+  if (value === undefined) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("permission_modes must be an object with ask, ask-when-needed or never-ask values");
+  const result: Record<string, PermissionMode> = {};
+  for (const [peer, mode] of Object.entries(value)) {
+    if (!["claude", "codex", "kimi", "pi", "local"].includes(peer)) throw new Error(`permission_modes.${peer}: unsupported peer`);
+    if (!isPermissionMode(mode)) throw new Error(`permission_modes.${peer} must be ask, ask-when-needed or never-ask`);
+    result[peer] = mode;
+  }
+  return result;
+}
+export const PI_EDIT_TOOLS = new Set(["edit", "write"]);
+/** Native agent policy files are never included in scoped automatic file grants. */
+export const AGENT_CONFIG_SEGMENTS: ReadonlySet<string> = new Set([".claude", ".codex", ".qwen", ".kimi", ".pi", ".mcp.json"]);
+/**
+ * One spelling per name, as a case-insensitive disk sees it: it opens `.mcp.j\u017Fon` (long s) as `.mcp.json`, and
+ * HFS+ also ignores the default-ignorable code points (a zero-width joiner inside `.codex` is still `.codex`).
+ */
+export const foldSegment = (segment: string): string => segment.normalize("NFKC").replace(/\p{Default_Ignorable_Code_Point}/gu, "").toLowerCase().toUpperCase().toLowerCase();
+/** The hub's and git's own directories: writing them changes what runs outside any agent's control. */
+export const HUB_WRITE_SEGMENTS: ReadonlySet<string> = new Set([".git", ".agenthub"]);
+export const isHubWritePath = (path: string): boolean => path.split(/[\\/]/).some(segment => HUB_WRITE_SEGMENTS.has(foldSegment(segment)));
+export const isAgentConfigPath = (path: string): boolean => path.split(/[\\/]/).some(segment => AGENT_CONFIG_SEGMENTS.has(foldSegment(segment)));
+/** A file with a second name somewhere else: a grant for this name would write that one too. */
+export function hardLinked(path: string): boolean {
+  try { const st = lstatSync(path); return st.isFile() && st.nlink > 1; } catch { return false; } // a file that does not exist yet has no other name
+}
+/**
+ * Whether a scoped automatic write or edit grant may cover `path` (canonical) in the project at `root` (canonical):
+ * inside the project, outside every agent's configuration, judged by the path within the project (a project that
+ * itself lives under `.claude/worktrees/` is still a project), and not a hard link.
+ */
+export function grantablePath(root: string, path: string): boolean {
+  const inside = relative(root, path);
+  return !!inside && inside !== ".." && !inside.startsWith(`..${sep}`) && !isAbsolute(inside) && !isAgentConfigPath(inside) && !isHubWritePath(inside) && !hardLinked(path);
+}

package/src/hub/recovery-store.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { Database } from "bun:sqlite";
 import { hubHome } from "./project.ts";
+import { processLiveness, processSignature } from "../pi/process-signature.ts";
 
 export const operationIdPattern = /^[a-f0-9-]{36}$/;
 export function operationPath(id: string, home = hubHome()): string {
@@ -73,6 +74,12 @@ export function recoveryCommand(op: { id: string; sourceRoot?: string }, action:
   return `${cli} recovery ${action} ${op.id}${flags ? ` ${flags}` : ""}`;
 }
 
+/** #272: the command above as an argv for `bun`, which a screen runs instead of printing; with no coordinator of its own, this release's. */
+export function recoveryArgv(op: { id: string; sourceRoot?: string }, action: "status" | "resume" | "abort" | "dispose", flags: string[] = []): string[] {
+  const entry = op.sourceRoot && coordinatorCurrent(op.sourceRoot) ? join(op.sourceRoot, "src/cli/main.js") : join(import.meta.dir, "../cli/main.js");
+  return [entry, "recovery", action, op.id, ...flags];
+}
+
 /**
  * Whether a coordinator has the #215 recovery commands (dispose, re-preparation, next actions).
  * ponytail: a text sniff of its upgrade.ts; a rename or re-export reads as an older coordinator (the running release is
@@ -90,9 +97,13 @@ export function activeOperation(owner: string, home = hubHome()): string {
   return `recovery operation ${owner} is active; ${recoveryCommand(op, "status")} lists what to do next`;
 }
 
+/** #226: the runner row's signature column, added to a runner.db an older release created; older runners leave it NULL. */
+const signed = (db: Database) => (db.query("PRAGMA table_info(runner)").all() as { name: string }[]).some((c) => c.name === "signature");
+
 /**
  * The pid of the runner that holds the operation now, read without claiming it (#215 status): undefined when none does,
- * "unknown" when the record cannot be read (unreadable, or still locked after the busy timeout), never "none" then.
+ * "unknown" when the record cannot be read (unreadable, or still locked after the busy timeout) or its owner cannot be
+ * identified, never "none" then. A row whose signature belongs to another process now is no runner (#226).
  */
 export function recoveryRunner(id: string, home = hubHome()): number | "unknown" | undefined {
   const path = `${operationPath(id, home)}.runner.db`;
@@ -103,14 +114,46 @@ export function recoveryRunner(id: string, home = hubHome()): number | "unknown"
     db.run("PRAGMA busy_timeout = 3000"); // a claim in progress must not read as no runner
     // A crash between creating the file and its table leaves no runner; claimRunner creates the table and claims.
     if (!db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'runner'").get()) return undefined;
-    const row = db.query("SELECT pid FROM runner WHERE slot = 1").get() as { pid: number } | null;
+    const row = db.query(`SELECT pid${signed(db) ? ", signature" : ""} FROM runner WHERE slot = 1`).get() as { pid: number; signature?: string | null } | null;
     if (!row) return undefined;
     if (!Number.isSafeInteger(row.pid) || row.pid < 1) return "unknown";
-    try { process.kill(row.pid, 0); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ESRCH") return undefined; }
-    return row.pid;
+    const state = processLiveness(row.pid, row.signature);
+    return state === "gone" ? undefined : state === "live" ? row.pid : "unknown";
   } catch { return "unknown"; } finally { db?.close(); }
 }
 
+/**
+ * #272: the pid of the runner that holds `id`, only when its claim carries a process signature that still matches.
+ * `recoveryRunner` answers a claim without one (a coordinator of 0.12.20 or older, or a `ps` that failed at claim
+ * time) from its bare pid, which is enough to wait for it and never enough to signal it.
+ */
+export function signedRunner(id: string, home = hubHome()): number | undefined {
+  const path = `${operationPath(id, home)}.runner.db`;
+  if (!existsSync(path)) return undefined;
+  let db: Database | undefined;
+  try {
+    db = new Database(path, { readonly: true });
+    db.run("PRAGMA busy_timeout = 3000");
+    if (!signed(db)) return undefined;
+    const row = db.query("SELECT pid, signature FROM runner WHERE slot = 1").get() as { pid: number; signature: string | null } | null;
+    if (!row?.signature || !Number.isSafeInteger(row.pid) || row.pid < 1) return undefined;
+    return processSignature(row.pid) === row.signature ? row.pid : undefined;
+  } catch { return undefined; } finally { db?.close(); }
+}
+
+/** #272: stop that verified runner and wait until no runner holds the operation. False when one still does, or cannot be verified. */
+export async function stopSignedRunner(id: string, home = hubHome(), waitMs = 5000): Promise<boolean> {
+  if (recoveryRunner(id, home) === undefined) return true;
+  const pid = signedRunner(id, home);
+  if (pid === undefined) return false;
+  try { process.kill(pid, "SIGTERM"); } catch { /* gone meanwhile */ }
+  for (const deadline = Date.now() + waitMs; Date.now() < deadline;) {
+    if (recoveryRunner(id, home) === undefined) return true;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return false;
+}
+
 /** An exclusive runner claim. Never steal a live or uncertain owner on resume. */
 export function claimRunner(id: string, home = hubHome()): () => void {
   const path = `${operationPath(id, home)}.runner.db`;
@@ -119,15 +162,22 @@ export function claimRunner(id: string, home = hubHome()): () => void {
   const nonce = randomUUID();
   try {
     db.run("PRAGMA busy_timeout = 3000");
-    db.run("CREATE TABLE IF NOT EXISTS runner (slot INTEGER PRIMARY KEY, pid INTEGER NOT NULL, nonce TEXT NOT NULL)");
+    db.run("CREATE TABLE IF NOT EXISTS runner (slot INTEGER PRIMARY KEY, pid INTEGER NOT NULL, nonce TEXT NOT NULL, signature TEXT)");
+    if (!signed(db)) {
+      try { db.run("ALTER TABLE runner ADD COLUMN signature TEXT"); }
+      catch (error) { if (!/duplicate column/i.test((error as Error).message)) throw error; } // a concurrent claim added it
+    }
+    const signature = processSignature(process.pid) ?? null;
     db.transaction(() => {
-      const row = db.query("SELECT pid FROM runner WHERE slot = 1").get() as { pid: number } | null;
+      const row = db.query("SELECT pid, signature FROM runner WHERE slot = 1").get() as { pid: number; signature: string | null } | null;
       if (row) {
         if (!Number.isSafeInteger(row.pid) || row.pid < 1) throw new Error("invalid recovery runner ownership");
-        try { process.kill(row.pid, 0); throw new Error(`recovery runner ${row.pid} is still alive`); }
-        catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+        const state = processLiveness(row.pid, row.signature);
+        if (state === "live") throw new Error(`recovery runner ${row.pid} is still alive`);
+        if (state === "unknown") throw new Error(`recovery runner ${row.pid} cannot be identified (its process exists but cannot be inspected); refusing to replace it`);
       }
-      db.query("INSERT OR REPLACE INTO runner (slot, pid, nonce) VALUES (1, ?, ?)").run(process.pid, nonce);
+      // An older runner rewrites the whole row (INSERT OR REPLACE), so its claim never inherits this signature.
+      db.query("INSERT OR REPLACE INTO runner (slot, pid, nonce, signature) VALUES (1, ?, ?, ?)").run(process.pid, nonce, signature);
     }).immediate();
   } catch (error) { db.close(); throw error; }
   return () => {

package/src/hub/registry.ts

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { canonicalPath, hubHome, projectRoot } from "./project.ts";
+import { processLiveness } from "../pi/process-signature.ts";
 
 const BASE_PORT = 4600;
 const STRIDE = 10;
@@ -19,22 +20,27 @@ export interface Project {
   basePort: number;
   instanceId: string | null;
   pid: number | null;
+  /** #226: the claimant's processSignature; absent for a claim written by 0.12.20 or older (judged by its pid alone). */
+  pidSignature?: string | null;
+}
+
+/**
+ * #226: `pid_signature` holds "<instance id> <signature>". An older daemon's claim rewrites instance_id and pid but not
+ * this column, so a signature counts only for the instance that wrote it: under another instance the claim is unsigned.
+ */
+export const PROJECT_COLUMNS = "id, root, state_dir as stateDir, base_port as basePort, instance_id as instanceId, pid";
+export function projectFromRow(raw: Record<string, unknown>): Project {
+  const { pid_signature: signed, ...row } = raw;
+  const project = { ...row } as unknown as Project;
+  const prefix = `${project.instanceId} `;
+  if (project.instanceId && typeof signed === "string" && signed.startsWith(prefix) && signed.length > prefix.length) project.pidSignature = signed.slice(prefix.length);
+  return project;
 }
 
 const idFor = (root: string) => `p_${createHash("sha256").update(root).digest("hex").slice(0, 24)}`;
 // Preserve the original identifier of missing legacy checkouts as a reservation.
 const legacyRoot = (path: string) => { try { return realpathSync(path); } catch { return resolve(path); } };
 const canonicalState = canonicalPath;
-const alive = (pid: number): boolean | undefined => {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    const code = (error as NodeJS.ErrnoException).code;
-    if (code === "ESRCH") return false;
-    return undefined;
-  }
-};
 
 export class Registry {
   readonly path: string;
@@ -56,6 +62,11 @@ export class Registry {
       base_port INTEGER NOT NULL UNIQUE, instance_id TEXT, pid INTEGER, claimed_at INTEGER
     )`);
     this.db.run("CREATE TABLE IF NOT EXISTS registry_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
+    const columns = this.db.query("PRAGMA table_info(projects)").all() as { name: string }[];
+    if (!columns.some((c) => c.name === "pid_signature")) {
+      try { this.db.run("ALTER TABLE projects ADD COLUMN pid_signature TEXT"); }
+      catch (error) { if (!/duplicate column/i.test((error as Error).message)) throw error; } // a concurrent open added it
+    }
     this.importLegacy();
   }
 
@@ -70,7 +81,7 @@ export class Registry {
       if (existing) {
         if (existing.root !== canonicalRoot) throw new Error(`registry id collision for ${canonicalRoot}`);
         if (explicitState && existing.stateDir !== state) {
-          if (existing.instanceId && (existing.pid === null || alive(existing.pid) !== false)) throw new Error(`cannot relocate live or uncertain project ${id}`);
+          if (existing.instanceId && (existing.pid === null || processLiveness(existing.pid, existing.pidSignature) !== "gone")) throw new Error(`cannot relocate live or uncertain project ${id}`);
           this.db.query("UPDATE projects SET state_dir = ? WHERE id = ?").run(state, id);
         }
         return;
@@ -91,7 +102,7 @@ export class Registry {
   }
 
   list(): Project[] {
-    return this.db.query("SELECT id, root, state_dir as stateDir, base_port as basePort, instance_id as instanceId, pid FROM projects ORDER BY root").all() as Project[];
+    return (this.db.query(`SELECT ${PROJECT_COLUMNS}, pid_signature FROM projects ORDER BY root`).all() as Record<string, unknown>[]).map(projectFromRow);
   }
 
   allocate(root: string): number {
@@ -110,17 +121,18 @@ export class Registry {
     return base;
   }
 
-  claim(id: string, instanceId: string, pid: number): boolean {
+  /** `signature`: the claimant's processSignature (#226); without one the claim is judged by its pid alone. */
+  claim(id: string, instanceId: string, pid: number, signature?: string): boolean {
     let claimed = false;
     const tx = this.db.transaction(() => {
       const project = this.row(id);
       if (!project) return;
       if (project.instanceId && project.instanceId !== instanceId) {
         if (project.pid === null) return;
-        const state = alive(project.pid);
-        if (state !== false) return;
+        if (processLiveness(project.pid, project.pidSignature) !== "gone") return;
       }
-      this.db.query("UPDATE projects SET instance_id = ?, pid = ?, claimed_at = ? WHERE id = ?").run(instanceId, pid, Date.now(), id);
+      this.db.query("UPDATE projects SET instance_id = ?, pid = ?, pid_signature = ?, claimed_at = ? WHERE id = ?")
+        .run(instanceId, pid, signature ? `${instanceId} ${signature}` : null, Date.now(), id);
       claimed = true;
     });
     runTx(tx as Tx);
@@ -128,7 +140,7 @@ export class Registry {
   }
 
   release(id: string, instanceId: string): void {
-    this.db.query("UPDATE projects SET instance_id = NULL, pid = NULL, claimed_at = NULL WHERE id = ? AND instance_id = ?").run(id, instanceId);
+    this.db.query("UPDATE projects SET instance_id = NULL, pid = NULL, pid_signature = NULL, claimed_at = NULL WHERE id = ? AND instance_id = ?").run(id, instanceId);
   }
 
   remove(id: string): void {
@@ -136,16 +148,17 @@ export class Registry {
       const project = this.row(id);
       if (!project) return;
       if (project.instanceId) {
-        if (project.pid === null || alive(project.pid) !== false) throw new Error(`project ${id} has a live or uncertain claim`);
+        if (project.pid === null || processLiveness(project.pid, project.pidSignature) !== "gone") throw new Error(`project ${id} has a live or uncertain claim`);
       } else if (existsSync(join(project.stateDir, "status.json")) || existsSync(join(project.stateDir, "control-token"))) {
-        let pid: number | undefined;
+        let pid: number | undefined, signature: string | undefined;
         try {
-          const status = JSON.parse(readFileSync(join(project.stateDir, "status.json"), "utf8")) as { pid?: number };
+          const status = JSON.parse(readFileSync(join(project.stateDir, "status.json"), "utf8")) as { pid?: number; pidSignature?: unknown };
           pid = typeof status.pid === "number" ? status.pid : undefined;
+          signature = typeof status.pidSignature === "string" ? status.pidSignature : undefined;
         } catch {
           // A state directory without a readable owner marker is uncertain.
         }
-        if (pid === undefined || alive(pid) !== false) throw new Error(`project ${id} has a live or uncertain legacy state`);
+        if (pid === undefined || processLiveness(pid, signature) !== "gone") throw new Error(`project ${id} has a live or uncertain legacy state`);
       }
       this.db.query("DELETE FROM projects WHERE id = ?").run(id);
     });
@@ -157,7 +170,8 @@ export class Registry {
   }
 
   private row(id: string): Project | null {
-    return this.db.query("SELECT id, root, state_dir as stateDir, base_port as basePort, instance_id as instanceId, pid FROM projects WHERE id = ?").get(id) as Project | null;
+    const raw = this.db.query(`SELECT ${PROJECT_COLUMNS}, pid_signature FROM projects WHERE id = ?`).get(id) as Record<string, unknown> | null;
+    return raw ? projectFromRow(raw) : null;
   }
 
   private nextBase(after = BASE_PORT - STRIDE): number {