trantor 0.18.82 → 0.18.86

package/lib/identity.mjs

@@ -1,7 +1,8 @@
 // trantor — cryptographic identity, THE INTERFACE CONTRACT for Phase 0 (docs/TDD-trantor-platform.md §7).
 // An identity is an Ed25519 keypair and the label is cosmetic; every primitive lives behind this module.
 import { generateKeyPairSync, createPublicKey, createPrivateKey, sign as cryptoSign, verify as cryptoVerify, createHash, randomBytes } from "node:crypto";
-import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, chmodSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, chmodSync, readdirSync, unlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { asFunction, asString } from "./decode.mjs";
@@ -64,23 +65,120 @@ function privKeyObject(identity) {
   });
 }
 
+// --- the keychain layer (#11370) -----------------------------------------------------------------
+// The private half moves OFF disk into the macOS Keychain (service below, account = the raw
+// identity name); `trantor keys migrate` rewrites the file as a pubkey-only stub. Reads go
+// Keychain-first through a per-process cache, with a one-line file fallback when locked/absent.
+export const IDENTITY_SERVICE = "trantor-identity";
+const SECURITY = "/usr/bin/security";
+// A drill points this at a throwaway keychain so the operator's real one is never touched.
+const kcArgs = () => process.env.TRANTOR_IDENTITY_KEYCHAIN ? [process.env.TRANTOR_IDENTITY_KEYCHAIN] : [];
+
+// Test seam: drills inject a fake ({ get, set, remove } — get returns the stored string | null and
+// may THROW to simulate a locked keychain) so no test needs the real thing.
+let injectedKeychain = null;
+export function injectIdentityKeychain(fake) {
+  injectedKeychain = fake || null;
+  processCache.clear();
+  warned = false;
+}
+
+const keychainUsable = () =>
+  !!injectedKeychain ||
+  (process.platform === "darwin" && process.env.TRANTOR_NO_KEYCHAIN !== "1" && existsSync(SECURITY));
+
+let warned = false;
+function warnOnce(msg) {
+  if (warned) return;
+  warned = true;
+  console.error(`trantor identity: ${msg}`);
+}
+
+// Three outcomes matter: a hit, a MISS (never stored — normal before migrate), and UNAVAILABLE
+// (locked, headless, pre-wake). Only the last one ever warns.
+function keychainGet(account) {
+  if (injectedKeychain) {
+    try { return { value: injectedKeychain.get(account) || null }; }
+    catch { return { error: true }; }
+  }
+  const r = spawnSync(SECURITY, ["find-generic-password", "-a", account, "-s", IDENTITY_SERVICE, "-w", ...kcArgs()], { encoding: "utf8", timeout: 8000 });
+  if (r.status === 0) return { value: String(r.stdout).replace(/\n$/, "") };
+  return r.status === 44 ? {} : { error: true };   // 44 = errSecItemNotFound
+}
+
+function keychainSet(account, value) {
+  if (injectedKeychain) { injectedKeychain.set(account, value); return; }
+  // The value travels on stdin in `security -i` syntax, so it never shows in the process table;
+  // only the exit code comes back (security echoes the failing line, so stderr is not relayed).
+  const quote = (s) => `"${String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  const kc = kcArgs();
+  const line = `add-generic-password -a ${quote(account)} -s ${quote(IDENTITY_SERVICE)} -U -w ${quote(value)}${kc.length ? ` ${quote(kc[0])}` : ""}\n`;
+  const r = spawnSync(SECURITY, ["-i"], { encoding: "utf8", input: line, timeout: 8000 });
+  if (r.status !== 0) throw new Error(`keychain write failed for ${account} (security exited ${r.status ?? "signal"})`);
+}
+
+// A keychain entry is the whole identity as JSON, so it stays self-sufficient even if the stub
+// file is lost. Anything that does not parse to a well-formed Ed25519 pair is not a key.
+const HEX64 = /^[0-9a-f]{64}$/i;
+function parseStored(raw) {
+  try {
+    const id = JSON.parse(raw);
+    return HEX64.test(id?.pubkey || "") && HEX64.test(id?.privkey || "") ? id : null;
+  } catch { return null; }
+}
+
 // --- key file ----------------------------------------------------------------------------------
+// One read per process: hooks sign often, and the Keychain read is the expensive half.
+const processCache = new Map();
+const cacheKey = (name) => `${keysDir()}\x00${name}`;
 export function load(name) {
+  const ck = cacheKey(String(name));
+  if (processCache.has(ck)) return processCache.get(ck);
+  const id = resolveIdentity(String(name));
+  processCache.set(ck, id);
+  return id;
+}
+
+function resolveIdentity(name) {
   const f = keyPath(name);
-  if (!existsSync(f)) return null;
-  try {
-    const id = JSON.parse(readFileSync(f, "utf8"));
-    if (!id?.pubkey || !id?.privkey) return null;
-    return id;
-  } catch { return null; }
+  let fileId = null;
+  if (existsSync(f)) {
+    try {
+      const parsed = JSON.parse(readFileSync(f, "utf8"));
+      if (parsed?.pubkey) fileId = parsed;
+    } catch { fileId = null; }
+  }
+  // A file still carrying its privkey is the live record: a rotate or a fresh mint lands in the
+  // file first, so it must win over any older keychain copy under the same name.
+  if (fileId?.privkey) return fileId;
+  if (keychainUsable()) {
+    const kc = keychainGet(String(name));
+    const stored = kc.value ? parseStored(kc.value) : null;
+    // The keychain holds a self-consistent pair; the stub contributes display fields only. Taking
+    // the stub's pubkey with the keychain's privkey would mint an identity whose signatures never
+    // verify — so the crypto pair always comes from the same store.
+    if (stored) return fileId ? { ...stored, ...fileId, privkey: stored.privkey, pubkey: stored.pubkey } : stored;
+    if (fileId) {
+      warnOnce(kc.error
+        ? `the Keychain is unavailable (locked?) and "${name}" has no key file to fall back on — signing fails until it unlocks`
+        : `"${name}": the key file is a pubkey-only stub but the Keychain has no entry — re-run \`trantor keys migrate\` or restore the key`);
+    }
+  } else if (fileId) {
+    warnOnce(`the Keychain is disabled on this platform and "${name}" has no key file to fall back on — signing fails`);
+  }
+  return null;
 }
 
 // Create-if-missing, safe against two hooks racing at session start: write to a unique temp file,
 // rename into place (atomic on the same filesystem), and if we lost the race, use the winner's key.
 // Two identities for one name would silently split a session's history in half.
+// New keys are born as FILES even when the Keychain is up — `trantor keys migrate` moves them.
 export function loadOrCreate(name, kind = "agent") {
   const existing = load(name);
   if (existing) return existing;
+  // A record exists (a pubkey-only stub, or a keychain entry the read above could not use) but its
+  // private half is unreachable right now: minting a new key would split the history, so refuse.
+  if (existsSync(keyPath(name))) return null;
   mkdirSync(keysDir(), { recursive: true, mode: 0o700 });
   try { chmodSync(keysDir(), 0o700); } catch {}
   const { pubkey, privkey } = generate();
@@ -89,11 +187,16 @@ export function loadOrCreate(name, kind = "agent") {
   const tmp = `${f}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
   try {
     writeFileSync(tmp, JSON.stringify(id), { mode: 0o600 });
-    if (existsSync(f)) { return load(f && name) || id; }     // someone beat us between check and write
+    if (existsSync(f)) {                                     // someone beat us between check and write
+      try { unlinkSync(tmp); } catch {}                      // the loser's tmp still holds a private key
+      return load(name) || id;
+    }
     renameSync(tmp, f);
     chmodSync(f, 0o600);
+    processCache.set(cacheKey(String(name)), id);
     return id;
   } catch {
+    try { unlinkSync(tmp); } catch {}
     return load(name) || id;                                  // lost the race, or unwritable — never throw
   }
 }
@@ -103,6 +206,76 @@ export function publicView(identity) {
   return { name: identity.name, kind: identity.kind, pubkey: identity.pubkey, createdAt: identity.createdAt };
 }
 
+// --- migrate + status (`trantor keys …`) ---------------------------------------------------------
+// One <safe-name>.json per durable identity; the instances/ subdir holds per-session subkeys that
+// die with the session and stay files by design.
+export function listKeyNames() {
+  let files = [];
+  try { files = readdirSync(keysDir()); } catch { return []; }
+  return files.filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -".json".length)).sort();
+}
+
+// The stub keeps everything a peer may see plus a pointer at where the private half now lives.
+function writeKeyStub(f, id) {
+  const stub = { name: id.name, kind: id.kind, pubkey: id.pubkey, createdAt: id.createdAt, keychain: IDENTITY_SERVICE };
+  const tmp = `${f}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  writeFileSync(tmp, JSON.stringify(stub), { mode: 0o600 });
+  renameSync(tmp, f);
+  try { chmodSync(f, 0o600); } catch {}
+}
+
+// Copy each file-held private key into the Keychain, prove the stored copy SIGNS (a round-trip
+// against the file's pubkey), and only then rewrite the file as a pubkey-only stub. A key that
+// fails to store or to verify keeps its file untouched.
+export function migrateKeysToKeychain({ dryRun = false } = {}) {
+  const result = { service: IDENTITY_SERVICE, usable: keychainUsable(), moved: [], already: [], failed: [], dryRun };
+  if (!result.usable) return result;
+  for (const fileBase of listKeyNames()) {
+    let id = null;
+    try { id = JSON.parse(readFileSync(keyPath(fileBase), "utf8")); } catch {}
+    // The keychain account is the IDENTITY's name (card #11370), i.e. the raw name the JSON
+    // carries — the file's name is only the sanitised lookup key and load() reads back by the
+    // raw name, so storing under "name_proj" while hooks look for "name:proj" would orphan
+    // every migrated key on its first read.
+    const name = id?.name ?? fileBase;
+    if (!id?.pubkey) { result.failed.push({ name, reason: "unreadable key file" }); continue; }
+    if (!id.privkey) { result.already.push(name); continue; }
+    if (dryRun) { result.moved.push(name); continue; }
+    try {
+      keychainSet(name, JSON.stringify(id));
+      const stored = parseStored(keychainGet(name).value || "");
+      if (!stored || stored.privkey !== id.privkey || stored.pubkey !== id.pubkey) throw new Error("read-back mismatch");
+      const probe = Buffer.from(`trantor-keychain-migrate\n${id.pubkey}`, "utf8");
+      const sig = cryptoSign(null, probe, privKeyObject(stored));
+      if (!cryptoVerify(null, probe, pubFromHex(id.pubkey), sig)) throw new Error("signature round-trip failed");
+      writeKeyStub(keyPath(name), id);
+      processCache.clear();                    // this process now reads stub + keychain
+      result.moved.push(name);
+    } catch (e) {
+      result.failed.push({ name, reason: String(e?.message || e) });
+    }
+  }
+  return result;
+}
+
+// Where does each identity's PRIVATE half live? Presence booleans only — key material is never
+// read into the report.
+export function keyLocationReport() {
+  const usable = keychainUsable();
+  return listKeyNames().map((fileBase) => {
+    let fileKey = false, pubkey = null, name = fileBase;
+    try {
+      const id = JSON.parse(readFileSync(keyPath(fileBase), "utf8"));
+      fileKey = !!id?.privkey;
+      pubkey = id?.pubkey || null;
+      name = id?.name ?? fileBase;               // the identity's real name is what the keychain is keyed on
+    } catch {}
+    const inKeychain = usable ? !!parseStored(keychainGet(name).value || "") : false;
+    const where = fileKey && inKeychain ? "file + keychain" : fileKey ? "file (plaintext)" : inKeychain ? "keychain" : "NO USABLE PRIVATE KEY";
+    return { name, pubkey, where, keychain: inKeychain, fileKey };
+  });
+}
+
 // --- canonical request -------------------------------------------------------------------------
 export function bodyHash(body) {
   if (body === undefined || body === null || body === "") return "";

package/lib/nudge-ledger.mjs

@@ -0,0 +1,95 @@
+// #11355: ONE shared nudged-id ledger for BOTH orchestrator-wake nudgers — the mechanical
+// com.trantor.wake-nudge daemon and the duty seat's runner-side nudge plan. Each path checks and
+// stamps BEFORE sending; of two nudgers offered the same unread id exactly one send lands, the
+// other logs "already nudged #N". Per-recipient file, atomic check-and-stamp under a lock.
+import { closeSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { busDir } from "./project.mjs";
+
+// While an id is nudged under this window it is suppressed; past it the stamp is pruned and a
+// still-unread id is nudgeable again.
+export const NUDGE_LEDGER_TTL_MS = 10 * 60 * 1000;
+
+export function nudgeLedgerPath(recipient, { bus = busDir() } = {}) {
+  const safe = String(recipient || "").replace(/[^A-Za-z0-9_.-]/g, "_");
+  return join(bus, `nudged-${safe}.json`);
+}
+
+function readLedger(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!(parsed?.nudged instanceof Object) || Array.isArray(parsed.nudged)) throw new Error("bad shape");
+    return parsed;
+  } catch {
+    return { version: 1, nudged: {} };
+  }
+}
+
+function writeLedger(path, state) {
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+async function withLedgerLock(path, update) {
+  const lockPath = `${path}.lock`;
+  let lock = null;
+  for (let attempt = 0; attempt < 100 && lock === null; attempt++) {
+    try { lock = openSync(lockPath, "wx", 0o600); }
+    catch { await new Promise(resolve => setTimeout(resolve, 10)); }
+  }
+  if (lock === null) throw new Error(`could not lock ${path}`);
+  try {
+    const state = readLedger(path);
+    await update(state);
+    writeLedger(path, state);
+  } finally {
+    closeSync(lock);
+    try { unlinkSync(lockPath); } catch {}
+  }
+}
+
+// Check-and-stamp BEFORE sending: ids stamped under the TTL come back skipped (the caller logs
+// "already nudged #N"), the rest are stamped for `owner`. One locked step, so of two concurrent
+// nudgers exactly one wins.
+export async function reserveNudgeIds({
+  recipient, ids, owner, now = Date.now(), ttlMs = NUDGE_LEDGER_TTL_MS, bus, ledgerPath, log = (m) => console.error(m),
+} = {}) {
+  const wanted = [...new Set((ids || []).map(id => String(id ?? "").trim()).filter(Boolean))];
+  if (!recipient || !wanted.length) return { allowed: [], skipped: [] };
+  // ledgerPath is resolved LAZILY from `bus`: a default parameter would bind busDir() at call
+  // time and silently ignore the caller's bus override.
+  const path = ledgerPath || nudgeLedgerPath(recipient, { bus });
+  const allowed = [], skipped = [];
+  await withLedgerLock(path, state => {
+    for (const id of wanted) {
+      const at = Number(state.nudged[id]?.at || 0);
+      if (at > 0 && now - at < ttlMs) skipped.push({ id, reason: `already nudged #${id}` });
+      else {
+        state.nudged[id] = { at: now, by: String(owner || "") };
+        allowed.push(id);
+      }
+    }
+    for (const [id, v] of Object.entries(state.nudged)) {
+      if (now - Number(v?.at || 0) >= ttlMs) delete state.nudged[id];
+    }
+  });
+  for (const s of skipped) log(s.reason);
+  return { allowed, skipped };
+}
+
+// Drop stamps for ids whose send ended UNVERIFIED — the ledger mirrors the duty-claim lifecycle
+// (auditDutyNudges releases unverified claims), so a failed or unconfirmed send never suppresses
+// the other nudger. With `owner`, only that path's own stamps are dropped.
+export async function releaseNudgeIds({ recipient, ids, owner, bus, ledgerPath, now = Date.now(), ttlMs = NUDGE_LEDGER_TTL_MS } = {}) {
+  const wanted = [...new Set((ids || []).map(id => String(id ?? "").trim()).filter(Boolean))];
+  if (!recipient || !wanted.length) return;
+  const path = ledgerPath || nudgeLedgerPath(recipient, { bus });
+  await withLedgerLock(path, state => {
+    for (const id of wanted) {
+      const at = Number(state.nudged[id]?.at || 0);
+      const own = !owner || state.nudged[id]?.by === String(owner);
+      if (at > 0 && now - at < ttlMs && own) delete state.nudged[id];
+    }
+  });
+}

package/lib/overseer.mjs

@@ -3,7 +3,7 @@
 // so the episode-recurrence path was untestable and therefore unproven.
 const PEER_LIVE_MS = Number(process.env.RELAY_OVERSEER_PEER_LIVE_MS || 5 * 60 * 1000);
 const CLAIM_LIVE_MS = Number(process.env.RELAY_OVERSEER_CLAIM_LIVE_MS || 10 * 60 * 1000);
-const KINDS = new Set(["same-project-sessions", "file-conflict", "linked-activity"]);
+const KINDS = new Set(["same-project-sessions", "file-conflict", "linked-activity", "remote-overlap"]);
 // A card in `todo` is queued, not held; `done`/`failed`/`blocked` are nobody's hands. Only these
 // two mean a session has it open right now.
 const HELD_STATUSES = new Set(["doing", "testing"]);
@@ -21,7 +21,19 @@ export function levelFor(project, autonomy = {}) {
   const direct = autonomy?.[key];
   if (isLevel(direct)) return direct;
   const fallback = autonomy?.["*"];
-  return isLevel(fallback) ? fallback : 1;
+  return isLevel(fallback) ? fallback : 2;
+}
+
+export function checkoutKey({ project, gitRoot }) {
+  return JSON.stringify(gitRoot ? ["checkout", gitRoot] : ["project", project]);
+}
+
+export function collisionIdentity(collision) {
+  // #11311: remote episodes are PROJECT/repo/PR/file per the orchestrator's spec — project, not
+  // checkoutKey, so one gitRoot shared across projects never merges two projects' remote episodes.
+  const base = collision.kind === "remote-overlap" ? clean(collision.project) : checkoutKey(collision);
+  const remote = collision.kind === "remote-overlap" ? ` ${clean(collision.repo)}#${finiteNumber(collision.pr) ?? ""}` : "";
+  return `${base} ${collision.kind} ${(collision.files || []).join(",")}${remote}`;
 }
 
 function isFresh(ts, now, ttl) {
@@ -35,13 +47,17 @@ function sortedStrings(items) {
 
 function pushCollision(out, collision) {
   if (!collision.project || !KINDS.has(collision.kind) || collision.sessions.length === 0) return;
-  out.push({
+  const row = {
     project: collision.project,
     kind: collision.kind,
     sessions: sortedStrings(collision.sessions),
     files: sortedStrings(collision.files ?? []),
     detail: collision.detail,
-  });
+  };
+  if (collision.gitRoot) { row.gitRoot = collision.gitRoot; row.projects = collision.projects; }
+  // (repo, PR number, file) is the remote-overlap episode identity — collisionIdentity appends it.
+  if (collision.repo) { row.repo = clean(collision.repo); row.pr = finiteNumber(collision.pr); }
+  out.push(row);
 }
 
 function collisionKey(c) {
@@ -80,22 +96,22 @@ export function detectCollisions({ peers = [], claims = [], links = [], cards =
     livePeers.push({ ...peer, session, project });
   }
 
-  const sessionsByProject = new Map();
+  const sessionsByCheckout = new Map();
   for (const peer of livePeers) {
-    const sessions = sessionsByProject.get(peer.project) ?? [];
-    sessions.push(peer.session);
-    sessionsByProject.set(peer.project, sessions);
+    const key = checkoutKey(peer);
+    const group = sessionsByCheckout.get(key) ?? [];
+    group.push(peer);
+    sessionsByCheckout.set(key, group);
   }
-
-  for (const project of sortedStrings(sessionsByProject.keys())) {
-    const sessions = sortedStrings(sessionsByProject.get(project));
+  for (const group of sessionsByCheckout.values()) {
+    const sessions = sortedStrings(group.map(p => p.session));
     if (sessions.length < 2) continue;
+    const projects = sortedStrings(group.map(p => p.project));
+    const gitRoot = clean(group[0].gitRoot);
     pushCollision(out, {
-      project,
-      kind: "same-project-sessions",
-      sessions,
-      files: [],
-      detail: `${sessions.join(", ")} are live on project ${project}.`,
+      project: projects[0], projects, gitRoot,
+      kind: "same-project-sessions", sessions, files: [],
+      detail: `${sessions.join(", ")} are live on ${gitRoot ? `checkout ${gitRoot}` : `project ${projects[0]}`}.`,
     });
   }
 
@@ -105,30 +121,36 @@ export function detectCollisions({ peers = [], claims = [], links = [], cards =
   // file — the cross-project overlap that claimSessionsByFile, keyed on project+file, structurally
   // cannot see. linked-activity reads this one.
   const claimProjectsByPath = new Map();
+  const liveClaims = [];
   for (const claim of asArray(claims)) {
     const project = clean(claim?.project);
     const file = clean(claim?.file);
     const session = clean(claim?.session);
     if (!project || !file || !session || !isFresh(claim?.ts, at, CLAIM_LIVE_MS)) continue;
-    const key = `${project}\u0000${file}`;
-    const sessions = claimSessionsByFile.get(key) ?? new Set();
-    sessions.add(session);
-    claimSessionsByFile.set(key, sessions);
+    const gitRoot = clean(claim.gitRoot || livePeers.find(p => p.session === session)?.gitRoot);
+    const key = JSON.stringify([checkoutKey({ project, gitRoot }), file]);
+    liveClaims.push({ project, file, session, gitRoot, key, remote: claim.remote });
+    const group = claimSessionsByFile.get(key) ?? { gitRoot, file, sessions: new Set(), projects: new Set() };
+    group.sessions.add(session);
+    group.projects.add(project);
+    claimSessionsByFile.set(key, group);
     const byProject = claimProjectsByPath.get(file) ?? new Map();
     byProject.set(project, (byProject.get(project) ?? new Set()).add(session));
     claimProjectsByPath.set(file, byProject);
   }
 
   for (const key of [...claimSessionsByFile.keys()].sort()) {
-    const [project, file] = key.split("\u0000");
-    const sessions = sortedStrings(claimSessionsByFile.get(key));
+    const group = claimSessionsByFile.get(key);
+    const projects = sortedStrings(group.projects);
+    const project = projects[0], file = group.file;
+    const sessions = sortedStrings(group.sessions);
     if (sessions.length < 2) continue;
     pushCollision(out, {
       project,
-      kind: "file-conflict",
+      kind: "file-conflict", gitRoot: group.gitRoot, projects,
       sessions,
       files: [file],
-      detail: `${sessions.join(", ")} have live claims on ${project}/${file}.`,
+      detail: `${sessions.join(", ")} have live claims on ${group.gitRoot || project}/${file}.`,
     });
   }
 
@@ -191,6 +213,42 @@ export function detectCollisions({ peers = [], claims = [], links = [], cards =
     });
   }
 
+  // #11311: open-PR evidence is computed CLIENT-SIDE (hooks/file-claim.mjs polls the claimant's
+  // own checkout via lib/remote-overlap.mjs) and rides the claim as its `remote` field — repo- and
+  // checkout-scoped by construction, one collision per (repo, PR, file) triple, warn-level, gone
+  // when the PR closes. That triple IS the episode identity (collisionIdentity appends repo#pr).
+  for (const claim of liveClaims) {
+    for (const r of asArray(claim.remote)) {
+      const pr = finiteNumber(r?.number);
+      const repo = clean(r?.repo);
+      if (pr == null || !repo || !repo.includes("/")) continue;
+      const author = clean(r?.author) || "unknown";
+      const url = clean(r?.url);
+      for (const file of sortedStrings(r.files)) {
+        if (file !== claim.file) continue;
+        // Recipients are EVIDENCE-MATCHED (codex hub case): within the same project+file, only
+        // claimants whose OWN remote carries this same repo+PR get warned — a checkout without
+        // that evidence is not a participant in a PR its repo does not have.
+        const sessions = sortedStrings(
+          liveClaims
+            .filter((c) => c.project === claim.project && c.file === claim.file
+              && asArray(c.remote).some((x) => clean(x?.repo) === repo && finiteNumber(x?.number) === pr))
+            .map((c) => c.session)
+        );
+        pushCollision(out, {
+          project: claim.project,
+          kind: "remote-overlap",
+          gitRoot: claim.gitRoot,
+          sessions,
+          files: [file],
+          repo,
+          pr,
+          detail: `open PR #${pr} by ${author} in ${repo} also changes ${file}${url ? ` (${url})` : ""}.`,
+        });
+      }
+    }
+  }
+
   const deduped = new Map();
   for (const collision of sortCollisions(out)) deduped.set(collisionKey(collision), collision);
   return [...deduped.values()];

package/lib/persona.mjs

@@ -0,0 +1,43 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function personaName(value) {
+  if (!/^[A-Za-z0-9_-]+$/.test(value || "")) throw new Error("persona must contain only letters, digits, underscores or hyphens");
+  return value;
+}
+
+export function runnerPersona(env, agent) {
+  return personaName(env.CREW_PERSONA || agent);
+}
+
+export function allocatePersona({ dir, project, agent, model = "", name, occupied = [], dry = false }) {
+  personaName(agent);
+  const folder = join(dir, "personas", encodeURIComponent(project));
+  if (!dry) mkdirSync(folder, { recursive: true });
+  for (let n = 1; ; n++) {
+    const persona = personaName(name || (n === 1 ? agent : `${agent}-${n}`));
+    if (occupied.includes(persona)) {
+      if (name) throw new Error(`persona ${persona} is already active`);
+      continue;
+    }
+    const file = join(folder, `${persona}.json`);
+    const seat = { persona, agent, model };
+    if (dry) return seat;
+    try {
+      writeFileSync(file, JSON.stringify(seat), { flag: "wx", mode: 0o600 });
+      return seat;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (!name) continue;
+      const prior = JSON.parse(readFileSync(file, "utf8"));
+      if (prior.agent !== agent) throw new Error(`persona ${persona} runs ${prior.agent}; use swap to change its agent`);
+      return { ...prior, model };
+    }
+  }
+}
+
+export function updatePersona({ dir, project, persona, agent, model = "" }) {
+  const folder = join(dir, "personas", encodeURIComponent(project));
+  mkdirSync(folder, { recursive: true });
+  writeFileSync(join(folder, `${personaName(persona)}.json`), JSON.stringify({ persona, agent, model }), { mode: 0o600 });
+}