@staix/agent-hub 0.24.0 → 0.26.0

package/src/hub/project-runtime-state.ts

@@ -0,0 +1,139 @@
+import { closeSync, constants, existsSync, fstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
+import type { Project } from "./registry.ts";
+import { configRepositoryPresent } from "./config-trust.ts";
+import { childEnv } from "./child-process.ts";
+import { hubGitSync } from "./git.ts";
+
+export type RuntimeProject = Pick<Project, "id" | "root" | "stateDir">;
+export interface ProjectRuntimeSelection { version: string; root: string; digest: string; kind: "restart" | "upgrade" }
+export interface ProjectRuntimeIdentity extends ProjectRuntimeSelection {
+  schema: 1; projectId: string; projectRoot: string; stateDir: string; instanceId: string | null;
+}
+export const PROJECT_RUNTIME_FILE = "runtime.json";
+const LIMIT = 16 * 1024;
+const version = (v: unknown): v is string => typeof v === "string" && v.length <= 64 && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.exec(v)?.[0] === v;
+const pathText = (v: unknown): v is string => typeof v === "string" && v.length <= 4096 && isAbsolute(v) && normalize(v) === v && !/[\x00-\x1f\x7f]/.test(v);
+export const projectRuntimeFile = (project: RuntimeProject): string => join(project.stateDir, PROJECT_RUNTIME_FILE);
+const invalid = (): Error => new Error("project runtime record is invalid; inspect runtime.json before starting");
+
+export function parseProjectRuntime(project: RuntimeProject, input: unknown): ProjectRuntimeIdentity {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw invalid();
+  const row = input as Record<string, unknown>;
+  if (Object.keys(row).sort().join(",") !== "digest,instanceId,kind,projectId,projectRoot,root,schema,stateDir,version"
+    || row.schema !== 1 || row.projectId !== project.id || row.projectRoot !== project.root || row.stateDir !== project.stateDir
+    || !version(row.version) || !pathText(row.root) || typeof row.digest !== "string" || row.digest.length !== 64 || !/^[a-f0-9]{64}$/.test(row.digest)
+    || row.kind !== "restart" && row.kind !== "upgrade"
+    || row.instanceId !== null && (typeof row.instanceId !== "string" || /^[a-zA-Z0-9-]{1,128}$/.exec(row.instanceId)?.[0] !== row.instanceId)) throw invalid();
+  return { schema: 1, projectId: project.id, projectRoot: project.root, stateDir: project.stateDir,
+    version: row.version, root: row.root, digest: row.digest, kind: row.kind, instanceId: row.instanceId as string | null };
+}
+
+const ACCESS = Symbol("project runtime access");
+export interface ProjectRuntimeAccess {
+  readonly [ACCESS]: true;
+  readonly projectId: string; readonly projectRoot: string; readonly stateDir: string;
+  read(): ProjectRuntimeIdentity | undefined;
+  write(runtime: ProjectRuntimeSelection, instanceId: string | null): ProjectRuntimeIdentity;
+}
+const TRUST_GIT_MS = 2000;
+const exactGlob = (value: string) => value.replace(/([*?[\]\\])/g, "\\$1");
+const trustRefusal = (why: string): never => { throw new Error(`project runtime selection is machine-local: ${why}`); };
+
+/** Plain folders remain supported. A repository must affirm this file is untracked using only its parent/ancestor paths. */
+function requireRuntimeTrust(project: RuntimeProject): void {
+  const file = projectRuntimeFile(project), checked = new Set<string>(), deadline = performance.now() + TRUST_GIT_MS;
+  const git = (args: string[]) => {
+    const remaining = deadline - performance.now();
+    if (remaining <= 0) trustRefusal("git could not confirm runtime.json is untracked");
+    return hubGitSync(args, { encoding: "utf8", env: childEnv(process.env), timeout: Math.max(1, Math.ceil(remaining)), maxBuffer: 256 * 1024 });
+  };
+  for (const cwd of new Set([project.root, dirname(file)])) {
+    if (!configRepositoryPresent(cwd)) continue;
+    let at = cwd;
+    while (!existsSync(at) && dirname(at) !== at) at = dirname(at);
+    const top = git(["-C", at, "rev-parse", "--show-toplevel"]);
+    if (top.status !== 0 || !isAbsolute(top.stdout.trim())) trustRefusal("git could not confirm runtime.json is untracked");
+    const root = top.stdout.trim(), selected = relative(root, file).split(sep).join("/");
+    if (checked.has(root) || selected === ".." || selected.startsWith("../") || isAbsolute(selected)) continue;
+    checked.add(root);
+    const parts = selected.split("/"), parent = parts.slice(0, -1).join("/");
+    // ponytail: explicit custom stateDir ancestor listings can exceed 256 KiB (default unaffected); use an untracked dedicated state directory, then upgrade to exact ancestor index lookup.
+    const specs = [`:(icase,literal)${parent || selected}`];
+    for (let i = 1; i < parts.length - 1; i++) specs.push(`:(icase,glob)${exactGlob(parts.slice(0, i).join("/"))}`);
+    const tracked = git(["-C", root, "ls-files", "-s", "-z", "--", ...specs]);
+    if (tracked.status !== 0) trustRefusal("git could not confirm runtime.json is untracked");
+    let opened: { dev: number; ino: number } | undefined;
+    try { opened = statSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") trustRefusal("runtime.json identity is unavailable"); }
+    for (const row of tracked.stdout.split("\0").filter(Boolean)) {
+      const name = row.slice(row.indexOf("\t") + 1);
+      if (name === selected || selected.startsWith(`${name}/`)) trustRefusal("runtime.json or its parent is committed to git");
+      if (opened) {
+        let info; try { info = statSync(join(root, name)); } catch { continue; }
+        if (info.dev === opened.dev && info.ino === opened.ino) trustRefusal("runtime.json is committed to git");
+      }
+    }
+  }
+}
+
+/** This reserved sibling namespace is exclusively for captures withdrawn for pruning. */
+export function assertExecutableRuntimeRoot(root: string): void {
+  for (let at = root; ; at = dirname(at)) {
+    if (basename(at).startsWith(".runtime-prune-")) throw new Error("runtime root is quarantined for pruning");
+    if (dirname(at) === at) return;
+  }
+}
+
+/** Host-only, project-bound admission for one call; callers create it before acquiring the registry lock. */
+export function createProjectRuntimeAccess(project: RuntimeProject): ProjectRuntimeAccess {
+  requireRuntimeTrust(project);
+  const bound = { id: project.id, root: project.root, stateDir: project.stateDir };
+  return Object.freeze({ [ACCESS]: true as const, projectId: bound.id, projectRoot: bound.root, stateDir: bound.stateDir,
+    read: () => readProjectRuntimeReference(bound), write: (runtime: ProjectRuntimeSelection, instanceId: string | null) => writeRuntimeState(bound, runtime, instanceId) });
+}
+function accessFor(project: RuntimeProject, access?: ProjectRuntimeAccess): ProjectRuntimeAccess {
+  if (!access) return createProjectRuntimeAccess(project);
+  if (access[ACCESS] !== true || access.projectId !== project.id || access.projectRoot !== project.root || access.stateDir !== project.stateDir)
+    throw new Error("project runtime access belongs to another project");
+  return access;
+}
+
+export function readProjectRuntime(project: RuntimeProject, access?: ProjectRuntimeAccess): ProjectRuntimeIdentity | undefined {
+  return accessFor(project, access).read();
+}
+
+/** Metadata-only retention reference: bounded binding/JSON checks confer no Git trust or execution authority. */
+export function readProjectRuntimeReference(project: RuntimeProject): ProjectRuntimeIdentity | undefined {
+  let fd: number;
+  try { fd = openSync(projectRuntimeFile(project), constants.O_RDONLY | constants.O_NOFOLLOW); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw invalid(); }
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1 || before.size > LIMIT) throw invalid();
+    const bytes = Buffer.alloc(LIMIT + 1);
+    const count = readSync(fd, bytes, 0, bytes.length, 0), after = fstatSync(fd);
+    if (count > LIMIT || count !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) throw invalid();
+    return parseProjectRuntime(project, JSON.parse(bytes.subarray(0, count).toString("utf8")));
+  } catch { throw invalid(); }
+  finally { closeSync(fd); }
+}
+
+/** Caller holds the shared runtime-capture lock until publication and its launch/reference effects finish. */
+function writeRuntimeState(project: RuntimeProject, runtime: ProjectRuntimeSelection, instanceId: string | null): ProjectRuntimeIdentity {
+  const record = parseProjectRuntime(project, { schema: 1, projectId: project.id, projectRoot: project.root, stateDir: project.stateDir,
+    version: runtime.version, root: runtime.root, digest: runtime.digest, kind: runtime.kind, instanceId });
+  assertExecutableRuntimeRoot(record.root);
+  readProjectRuntimeReference(project); // refuse to overwrite an unknown binding or an unsafe file
+  const body = JSON.stringify(record);
+  if (Buffer.byteLength(body) > LIMIT) throw invalid();
+  mkdirSync(project.stateDir, { recursive: true });
+  const file = projectRuntimeFile(project), temporary = `${file}.${randomUUID()}.tmp`;
+  try { writeFileSync(temporary, body, { mode: 0o600, flag: "wx" }); renameSync(temporary, file); }
+  finally { rmSync(temporary, { force: true }); }
+  return record;
+}
+
+export function writeProjectRuntimeState(project: RuntimeProject, runtime: ProjectRuntimeSelection, instanceId: string | null, access?: ProjectRuntimeAccess): ProjectRuntimeIdentity {
+  return accessFor(project, access).write(runtime, instanceId);
+}

package/src/hub/project-runtime.ts

@@ -0,0 +1,62 @@
+import { resolve } from "node:path";
+import { stageCurrentRuntime, verifyRecoveryTarget, newerVersion, exactVersion } from "../cli/recovery-package.ts";
+import { hubHome, realPath } from "./project.ts";
+import { Registry, type Project } from "./registry.ts";
+import { processLiveness } from "../pi/process-signature.ts";
+import { assertExecutableRuntimeRoot, createProjectRuntimeAccess, readProjectRuntime, writeProjectRuntimeState, type ProjectRuntimeAccess, type ProjectRuntimeIdentity, type ProjectRuntimeSelection } from "./project-runtime-state.ts";
+export { readProjectRuntime } from "./project-runtime-state.ts";
+export type { ProjectRuntimeIdentity, ProjectRuntimeSelection } from "./project-runtime-state.ts";
+
+export const projectRuntimeRefusal = (version: string, detail?: string): Error => new Error(`this project runs ${version}; use ${version} or later / ahub upgrade${detail ? ` (${detail})` : ""}`);
+
+export function verifyProjectRuntime(runtime: ProjectRuntimeSelection): ProjectRuntimeSelection {
+  assertExecutableRuntimeRoot(runtime.root);
+  try {
+    if (realPath(runtime.root) !== runtime.root || verifyRecoveryTarget(runtime.kind, runtime.root, runtime.version) !== runtime.digest)
+      throw new Error("runtime changed");
+    return runtime;
+  } catch { throw projectRuntimeRefusal(runtime.version, "recorded runtime is missing or changed"); }
+}
+
+/** Read-only caller admission also covers an already-running daemon; no capture is staged or hashed here. */
+export function readProjectRuntimeForCaller(project: Project, invokingVersion: string, access?: ProjectRuntimeAccess): ProjectRuntimeIdentity | undefined {
+  exactVersion(invokingVersion);
+  const retained = readProjectRuntime(project, access);
+  // ponytail: only updated resolver code honors runtime.json; bootstrap shared CLI to 0.26.0+ before relying on this floor.
+  if (retained && newerVersion(retained.version, invokingVersion)) throw projectRuntimeRefusal(retained.version);
+  return retained;
+}
+
+/** Selectors first ship in 0.26.0; unmodified earlier published CLIs cannot honor this record. */
+export function resolveProjectRuntime(project: Project, invokingVersion: string, sourceRoot = resolve(import.meta.dir, "../.."), registry?: Registry, access?: ProjectRuntimeAccess): ProjectRuntimeSelection {
+  const retained = readProjectRuntimeForCaller(project, invokingVersion, access);
+  if (retained) return verifyProjectRuntime(retained);
+  const staged = stageCurrentRuntime(sourceRoot, invokingVersion, hubHome(), registry);
+  return { ...staged, kind: "restart" };
+}
+
+export function recordProjectRuntime(project: Project, runtime: ProjectRuntimeSelection, instanceId: string | null, registry: Registry, access?: ProjectRuntimeAccess): void {
+  const admitted = access ?? createProjectRuntimeAccess(project);
+  registry.runtimeCaptureLocked(() => {
+    const current = registry.get(project.id);
+    if (!current || current.root !== project.root || current.stateDir !== project.stateDir
+      || instanceId !== null && current.instanceId !== instanceId
+      || instanceId === null && current.instanceId && processLiveness(current.pid, current.pidSignature) !== "gone")
+      throw new Error("project runtime owner changed; refresh before starting");
+    verifyProjectRuntime(runtime);
+    writeProjectRuntimeState(project, runtime, instanceId, admitted);
+  });
+}
+
+/** A null instance is a pending selection, never consent to replace a later capture choice. */
+export function confirmProjectRuntime(project: Project, runtime: ProjectRuntimeSelection, observed: { version?: unknown; instanceId?: unknown }, registry: Registry, access?: ProjectRuntimeAccess): void {
+  const admitted = access ?? createProjectRuntimeAccess(project);
+  registry.runtimeCaptureLocked(() => {
+    const saved = readProjectRuntime(project, admitted);
+    if (!saved || saved.version !== runtime.version || saved.root !== runtime.root || saved.digest !== runtime.digest || saved.kind !== runtime.kind
+      || observed.version !== runtime.version || typeof observed.instanceId !== "string" || !observed.instanceId
+      || saved.instanceId !== null && saved.instanceId !== observed.instanceId)
+      throw projectRuntimeRefusal(saved?.version ?? runtime.version, "runtime selection changed before readiness");
+    recordProjectRuntime(project, runtime, observed.instanceId, registry, admitted);
+  });
+}

package/src/hub/project.ts

@@ -66,15 +66,24 @@ export function projectContext(cwd: string, env: NodeJS.ProcessEnv = process.env
   const root = projectRoot(cwd);
   const override = env.AGENTHUB_STATE_DIR?.trim();
   if (!override) return { root, stateDir: canonical(join(root, ".agenthub", "state")) };
+  const inherited = inheritedStateDir(root, env);
+  return { root, stateDir: inherited ?? canonical(join(root, ".agenthub", "state")) };
+}
 
+/**
+ * The ownership proof for an inherited state directory, on its own so the channel plugin applies the same rule as the CLI (#604 PR B, item 10). The directory is accepted only when the root
+ * recorded in it equals `root`, or when it records none (a freshly initialized state) and the inherited `AGENTHUB_PROJECT_DIR` names `root`. A marker for another project is authoritative:
+ * an inherited pair from the main checkout must not pull a process started in a linked worktree into the main repository's hub.
+ */
+export function inheritedStateDir(root: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const override = env.AGENTHUB_STATE_DIR?.trim();
+  if (!override) return undefined;
   const declared = env.AGENTHUB_PROJECT_DIR?.trim();
   const stateDir = canonical(override);
   const recorded = stateMarker(stateDir);
-  if (recorded === root) return { root, stateDir };
-  // A marker for another project is authoritative; an inherited mismatch must not
-  // redirect this cwd. The explicit pair is only for a freshly initialized state.
-  if (!recorded && declared && canonical(declared) === root) return { root, stateDir };
-  return { root, stateDir: canonical(join(root, ".agenthub", "state")) };
+  if (recorded === root) return stateDir;
+  if (!recorded && declared && canonical(declared) === root) return stateDir;
+  return undefined;
 }
 
 export function hubHome(env: NodeJS.ProcessEnv = process.env): string {

package/src/hub/protocol-window.ts

@@ -0,0 +1,19 @@
+/** Inclusive supported control-wire interval; v is its highest version. */
+export interface ProtocolWindow { v: number; vMin: number }
+
+/** Older peers without a minimum advertise only their one explicit version. */
+export function protocolWindow(v: unknown, vMin?: unknown): ProtocolWindow | undefined {
+  if (typeof v !== "number" || !Number.isSafeInteger(v) || v <= 0) return undefined;
+  const minimum = vMin === undefined ? v : vMin;
+  if (typeof minimum !== "number" || !Number.isSafeInteger(minimum) || minimum <= 0 || minimum > v) return undefined;
+  return { v, vMin: minimum };
+}
+
+/** Choose the highest common version. Invalid intervals and disjoint ranges negotiate nothing. */
+export function negotiateProtocol(local: ProtocolWindow, remote: ProtocolWindow): number | undefined {
+  if (!local || typeof local !== "object" || Array.isArray(local) || !remote || typeof remote !== "object" || Array.isArray(remote)) return undefined;
+  const a = protocolWindow(local.v, local.vMin), b = protocolWindow(remote.v, remote.vMin);
+  if (!a || !b) return undefined;
+  const highest = Math.min(a.v, b.v);
+  return highest >= Math.max(a.vMin, b.vMin) ? highest : undefined;
+}

package/src/hub/provenance.ts

@@ -0,0 +1,30 @@
+// Sender provenance (#604 PR B, agent-hub#1030 item 11). Pure: a connection's identity fields in, a bounded record out. The record names the sending connection by role, bound peer
+// and launch or instance id, and nothing else: never a path, a cwd, a project root, a message body or a token. Two sessions that both claim `claude` stay distinguishable in
+// events.jsonl because their launch ids differ, and an envelope can be traced to the connection that sent it.
+/** `instanceId` is a declared extra instance's id when the connection is one. It is never the hub run's own id, which is the same for every connection and so distinguishes none. */
+export interface ConnectionIdentity { role?: "peer" | "console" | "tools"; peer?: string; launchId?: string; instanceId?: string; session?: boolean }
+/** `session: true` marks a distinct session: its `peer` is the daemon-minted `<peer>~<origin>` id (agent-hub#1036). */
+export type Origin = { role: "peer" | "console" | "tools" | "hub"; peer?: string; launch?: string; instance?: string; session?: true };
+
+/** An id the hub itself minted (a UUID or a short token). Anything else, or anything long, is dropped rather than copied: the field is evidence, not a channel for caller text. */
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const idOf = (value: unknown): string | undefined => typeof value === "string" && ID.test(value) ? value : undefined;
+const PEER = /^[a-z][a-z0-9_~-]{0,63}$/;
+
+/** `undefined` identity is the hub's own writer (a task flow, a notice): it is `hub`, not a connection. */
+export function originOf(identity: ConnectionIdentity | undefined): Origin {
+  if (!identity?.role) return { role: "hub" };
+  const peer = typeof identity.peer === "string" && PEER.test(identity.peer) ? identity.peer : undefined;
+  const launch = idOf(identity.launchId), instance = idOf(identity.instanceId);
+  return { role: identity.role, ...(peer ? { peer } : {}), ...(launch ? { launch } : {}), ...(instance ? { instance } : {}), ...(identity.session === true && peer ? { session: true as const } : {}) };
+}
+
+/** The one `attach` event a peer or tools hello writes, and the shape an envelope event embeds as `origin`. */
+export function attachEvent(identity: ConnectionIdentity): { type: "attach" } & Origin {
+  return { type: "attach", ...originOf(identity) };
+}
+
+/** Whether two origins name the same connection identity: the same role, peer and launch. A connection with no launch id never equals one that has it. */
+export function sameOrigin(a: Origin, b: Origin): boolean {
+  return a.role === b.role && a.peer === b.peer && a.launch === b.launch && a.instance === b.instance && a.session === b.session;
+}

package/src/hub/recovery-store.ts

@@ -1,14 +1,15 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { Database } from "bun:sqlite";
-import { hubHome } from "./project.ts";
+import { canonicalPath, hubHome } from "./project.ts";
+import { isDatabaseBusy } from "./recovery-error.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 
 const RUNNER_DB_BUSY_TIMEOUT_MS = 3000;
 export const operationIdPattern = /^[a-f0-9-]{36}$/;
 export function operationPath(id: string, home = hubHome()): string {
-  if (!operationIdPattern.test(id)) throw new Error("invalid recovery operation ID");
+  if (typeof id !== "string" || id.length !== 36 || !operationIdPattern.test(id)) throw new Error("invalid recovery operation ID");
   return join(home, "recovery", `${id}.json`);
 }
 
@@ -31,11 +32,11 @@ export function writeOperation(id: string, value: unknown, home = hubHome()): vo
   atomicPrivateJSON(operationPath(id, home), value);
 }
 
-export function recoveryLock(home = hubHome()): string | undefined {
+function legacyRecoveryLock(home: string): string | undefined {
   const file = join(home, "recovery.lock");
   try {
     const data = JSON.parse(readFileSync(file, "utf8"));
-    if (!operationIdPattern.test(data.operationId)) throw new Error("invalid recovery lock");
+    if (typeof data.operationId !== "string" || data.operationId.length !== 36 || !operationIdPattern.test(data.operationId)) throw new Error("invalid recovery lock");
     return data.operationId;
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
@@ -43,23 +44,112 @@ export function recoveryLock(home = hubHome()): string | undefined {
   }
 }
 
-export function acquireRecoveryLock(id: string, home = hubHome()): void {
+const projectLocksPath = (home: string) => join(home, "recovery", "project-locks.db");
+const projectLockError = () => new Error("project recovery coordination state is unreadable; inspect it before changing runtimes");
+function recoveryProjectKey(root: string): string {
+  if (typeof root !== "string" || !isAbsolute(root) || root.includes(String.fromCharCode(0))) throw new Error("recovery scope needs a canonical project root");
+  try { return canonicalPath(root); }
+  catch (error) {
+    // Receipts retain the already-canonical registration spelling so a removed project can still be disposed.
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return resolve(root);
+    throw error;
+  }
+}
+function projectLocksExist(file: string): boolean {
+  try {
+    const info = lstatSync(file);
+    if (!info.isFile() || info.isSymbolicLink()) throw projectLockError();
+    return true;
+  } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; }
+}
+function projectLocks(home: string, create = false): Database | undefined {
+  const file = projectLocksPath(home);
+  if (!projectLocksExist(file)) {
+    if (!create) return undefined;
+    mkdirSync(join(home, "recovery"), { recursive: true, mode: 0o700 });
+    // Publish a complete DELETE-journal database, never an empty coordination file another process could misread.
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+      const db = new Database(temporary, { create: true });
+      try {
+        db.run(`PRAGMA busy_timeout = ${RUNNER_DB_BUSY_TIMEOUT_MS}`);
+        db.run("CREATE TABLE project_locks (project_root TEXT PRIMARY KEY, operation_id TEXT NOT NULL)");
+      } finally { db.close(); }
+      chmodSync(temporary, 0o600);
+      try { linkSync(temporary, file); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+    } finally { rmSync(temporary, { force: true }); }
+  }
+  if (!projectLocksExist(file)) throw projectLockError();
+  let db: Database | undefined;
+  try {
+    db = new Database(file, create ? { readwrite: true, create: false } : { readonly: true, create: false });
+    db.run(`PRAGMA busy_timeout = ${RUNNER_DB_BUSY_TIMEOUT_MS}`);
+    if (!db.query("SELECT 1 FROM sqlite_master WHERE type='table' AND name='project_locks'").get()) throw projectLockError();
+    return db;
+  } catch (error) { db?.close(); if (isDatabaseBusy(error)) throw error; throw projectLockError(); }
+}
+function projectLockOn(db: Database, key: string): string | undefined {
+  const rows = db.query("SELECT CASE WHEN typeof(operation_id)='text' AND length(operation_id)=36 THEN operation_id END AS id FROM project_locks WHERE project_root=? LIMIT 2").all(key) as { id: string | null }[];
+  if (!rows.length) return undefined;
+  if (rows.length !== 1 || typeof rows[0]!.id !== "string" || !operationIdPattern.test(rows[0]!.id)) throw projectLockError();
+  return rows[0]!.id;
+}
+
+/** Legacy machine holds remain authoritative; new project holds affect only their canonical project. */
+export function recoveryLock(home = hubHome(), projectRoot?: string): string | undefined {
+  const legacy = legacyRecoveryLock(home);
+  if (legacy || projectRoot === undefined) return legacy;
+  const key = recoveryProjectKey(projectRoot), db = projectLocks(home);
+  if (!db) return undefined;
+  try { return projectLockOn(db, key); }
+  finally { db.close(); }
+}
+
+export function acquireRecoveryLock(id: string, home = hubHome(), projectRoot?: string): void {
   operationPath(id, home);
+  if (projectRoot !== undefined) {
+    const key = recoveryProjectKey(projectRoot), legacy = legacyRecoveryLock(home);
+    if (legacy && legacy !== id) throw new Error(`another recovery operation owns this machine: ${legacy}`);
+    const db = projectLocks(home, true)!;
+    try {
+      db.transaction(() => {
+        const existing = projectLockOn(db, key);
+        if (existing && existing !== id) throw new Error(`another recovery operation owns this project: ${existing}`);
+        if (!existing) db.query("INSERT INTO project_locks(project_root,operation_id) VALUES(?,?)").run(key, id);
+      }).immediate();
+    } finally { db.close(); }
+    return;
+  }
   mkdirSync(home, { recursive: true, mode: 0o700 });
   const existing = recoveryLock(home);
   if (existing === id) return;
-  try { writeFileSync(join(home, "recovery.lock"), JSON.stringify({ operationId: id }), { mode: 0o600, flag: "wx" }); }
-  catch { throw new Error(`another recovery operation owns this machine: ${recoveryLock(home) ?? "unknown"}`); }
+  const temporary = join(home, `.recovery-lock-${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, JSON.stringify({ operationId: id }), { mode: 0o600, flag: "wx" });
+    try { linkSync(temporary, join(home, "recovery.lock")); }
+    catch { throw new Error(`another recovery operation owns this machine: ${recoveryLock(home) ?? "unknown"}`); }
+  } finally { rmSync(temporary, { force: true }); }
 }
 
-export function releaseRecoveryLock(id: string, home = hubHome()): void {
+export function releaseRecoveryLock(id: string, home = hubHome(), projectRoot?: string): void {
+  operationPath(id, home);
+  if (projectRoot !== undefined) {
+    const key = recoveryProjectKey(projectRoot), db = projectLocks(home, true)!;
+    try {
+      if (db.query("DELETE FROM project_locks WHERE project_root=? AND operation_id=?").run(key, id).changes !== 1)
+        throw new Error("recovery lock ownership changed");
+    } finally { db.close(); }
+    return;
+  }
+  // Legacy release is called under the operation's exclusive runner claim. Project releases compare/delete atomically.
   if (recoveryLock(home) !== id) throw new Error("recovery lock ownership changed");
   rmSync(join(home, "recovery.lock"));
 }
 
 /** Used by CLI and manager lifecycle paths. A detached operation carries its own ID. */
-export function assertLifecycleAvailable(): void {
-  const owner = recoveryLock();
+export function assertLifecycleAvailable(projectRoot?: string): void {
+  const owner = recoveryLock(undefined, projectRoot);
   if (owner && process.env.AGENTHUB_RECOVERY_OPERATION !== owner) throw new Error(activeOperation(owner));
 }
 

package/src/hub/registry.ts

@@ -106,6 +106,11 @@ export class Registry {
     return (this.db.query(`SELECT ${PROJECT_COLUMNS}, pid_signature FROM projects ORDER BY root`).all() as Record<string, unknown>[]).map(projectFromRow);
   }
 
+  /** Serialize capture publication, durable project references and pruning with registry writers. */
+  runtimeCaptureLocked<T>(fn: () => T): T {
+    return this.db.inTransaction ? fn() : this.db.transaction(fn).immediate();
+  }
+
   allocate(root: string): number {
     return this.register(root).basePort;
   }