trantor 0.18.82 → 0.18.85

package/hub/routes/admin.mjs

@@ -1,3 +1,4 @@
+import { checkoutKey, collisionIdentity, levelFor } from "../../lib/overseer.mjs";
 /* oxlint-disable anti-slop/no-runtime-typeof -- SAFETY: These checks preserve the established request and provider-response compatibility boundary during a route-only extraction. */
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -7,6 +8,19 @@ import { join } from "node:path";
 // consume a claim's first-touch (or vice versa), and /claims must never list reads. #7972.
 const fileReads = new Map();
 
+function remoteEvidence(value, file) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, 25).filter(row =>
+    row && typeof row.repo === "string" && /^[\w.-]+\/[\w.-]+$/.test(row.repo) && row.repo.length <= 200 &&
+    Number.isSafeInteger(row.number) && row.number > 0 &&
+    typeof row.author === "string" && row.author.length > 0 && row.author.length <= 120 &&
+    typeof row.url === "string" && row.url.length <= 2000 &&
+    (row.url === "" || /^https:\/\/[^\s]+$/.test(row.url)) &&
+    Array.isArray(row.files) && row.files.includes(file)
+  ).map(row => ({ repo: row.repo.toLowerCase(), number: row.number, author: row.author,
+    url: row.url, files: [file] }));
+}
+
 export async function routeAdmin({ req, res, q, P, auth, ctx }) {
   const {
     state, body, json, crossProjectGuard, touch, canon, filterReadable,
@@ -23,6 +37,13 @@ export async function routeAdmin({ req, res, q, P, auth, ctx }) {
       // WHO is this, really: the LLM brand + the exact model currently loaded. In-memory like the
       // rest of presence — the next heartbeat re-supplies it after a restart.
       const pr = state.peers[b.session];
+      if (pr && b.gitRoot) {
+        pr.gitRoot = String(b.gitRoot).slice(0, 2000);
+        state.overseerState ??= {};
+        state.overseerState.roots ??= {};
+        state.overseerState.roots[b.session] = pr.gitRoot;
+        markDirty();
+      }
       // #6148: WHAT a session is rides its peer row (kind "genesis" = the CLI's brief-poster,
       // "agent" = a crew seat) — /peers hands it to the app so the seat strip can tell them apart.
       if (pr) { if (b.model) pr.model = String(b.model).slice(0, 80); if (b.llm) pr.llm = String(b.llm).slice(0, 40); if (b.kind) pr.kind = String(b.kind).slice(0, 40); }
@@ -194,7 +215,7 @@ export async function routeAdmin({ req, res, q, P, auth, ctx }) {
       const proj = canon(String(q.project || "").slice(0, 80));
       if (!proj) return json(res, 400, { error: "project required" });
       const pol = overseerPolicy();
-      const level = overseer.engine?.levelFor ? overseer.engine.levelFor(proj, pol.autonomy) : (pol.autonomy[proj] ?? pol.autonomy["*"] ?? 1);
+      const level = overseer.engine?.levelFor ? overseer.engine.levelFor(proj, pol.autonomy) : (pol.autonomy[proj] ?? pol.autonomy["*"] ?? 2);
       const links = pol.links.filter(l => (l.projects || []).includes(proj));
       const linked = new Set(links.flatMap(l => l.projects).filter(x => x !== proj));
       const cutoff = now() - ONLINE_MS;
@@ -207,7 +228,7 @@ export async function routeAdmin({ req, res, q, P, auth, ctx }) {
       let warnings = [];
       try {
         warnings = (overseer.engine?.detectCollisions ? overseer.engine.detectCollisions(overseerInputs()) : [])
-          .filter(c => c.project === proj || linked.has(c.project));
+          .filter(c => c.project === proj || c.projects?.includes(proj) || linked.has(c.project));
         // #5760: a declared crew is the NORMAL state of a project, not a collision — the tick
         // loop drops crew-only sets before they ever become episodes, and this live view must
         // agree with it: the SessionStart hook narrates exactly these lines, so a crew-only leak
@@ -215,14 +236,14 @@ export async function routeAdmin({ req, res, q, P, auth, ctx }) {
         warnings = warnings.filter(c => !(c.kind === "same-project-sessions" && overseer.sameProject?.sameProjectDecision &&
           overseer.sameProject.sameProjectDecision({
             current: c.sessions,
-            declaredCrew: declaredCrewFor(c.project),
+            declaredCrew: declaredCrewFor(c.project, c.gitRoot),
             now: now(),
           }).reason === "crew-only"));
         // The record line reports DURATION ("standing for 6h"), never a count of warnings. Episode
         // identity is project+kind+files, exactly as the tick loop keys it, so this view says the
         // same thing the warning did  for every kind, not just same-project (#7029).
         for (const c of warnings) {
-          const ep = overseer.active.get(`${c.project} ${c.kind}${c.kind === "same-project-sessions" ? "" : ` ${(c.files || []).join(",")}`}`);
+          const ep = overseer.active.get(c.kind === "same-project-sessions" ? `${checkoutKey(c)} ${c.kind}` : collisionIdentity(c));
           if (!ep) continue;
           c.since = ep.since;
           const label = c.kind === "same-project-sessions" ? "same-project" : "standing";
@@ -269,25 +290,50 @@ export async function routeAdmin({ req, res, q, P, auth, ctx }) {
       markDirty();
       return json(res, 200, { ok: true });
     }
-    if (req.method === "POST" && P === "/claim") {
+    if (req.method === "GET" && P === "/holds") {
+      const rows = overseer.listHolds().filter(h => (!q.project || h.project === canon(q.project)) && (!q.status || h.status === q.status));
+      return json(res, 200, { holds: filterReadable(auth, rows, h => h.project) });
+    }
+    if (req.method === "POST" && P === "/hold/decide") {
+      const b = await body(req);
+      const hold = overseer.listHolds().find(h => h.id === Number(b.id));
+      if (!hold) return json(res, 404, { error: "hold expired or not found" });
+      if (AUTH_MODE !== "off" && !scopeAllows(auth?.identity, hold.project, "owner")) return json(res, 403, { error: "operator permission required" });
+      if (b.status !== "go" && b.status !== "nogo") return json(res, 400, { error: "status must be go or nogo" });
+      const decided = overseer.decideHold(hold.id, b.status, auth?.identity?.name || "operator");
+      return decided ? json(res, 200, { ok: true, hold: decided }) : json(res, 409, { error: "hold already decided" });
+    }
+    if (req.method === "POST" && (P === "/claim" || P === "/hold/check")) {
       const b = await body(req);
       const proj = canon(String(b.project || "").slice(0, 80));
       const file = String(b.file || "").slice(0, 400);
       const session = String(b.session || "").slice(0, 120);
       if (!proj || !file || !session) return json(res, 400, { error: "project, file and session required" });
+      if (auth?.identity && session !== auth.identity.name) return json(res, 403, { error: "session must match signer" });
+      const gitRoot = String(b.gitRoot || state.peers[session]?.gitRoot || state.overseerState?.roots?.[session] || "").slice(0, 2000);
       pruneClaims();
-      const key = `${proj}${file}${session}`;
+      const key = `${checkoutKey({ project: proj, gitRoot })}\u0000${file}\u0000${session}`;
       const mine = fileClaims.get(key);
       const conflicts = [...fileClaims.values()]
-        .filter(c => c.project === proj && c.file === file && c.session !== session)
+        .filter(c => checkoutKey(c) === checkoutKey({ project: proj, gitRoot }) && c.file === file && c.session !== session)
         .map(c => ({ session: c.session, ts: c.ts, agoSec: Math.round((now() - c.ts) / 1000) }));
-      fileClaims.set(key, { project: proj, file, session, ts: now() });
+      const remote = P === "/hold/check" && b.remote === undefined
+        ? (mine?.remote || []) : remoteEvidence(b.remote, file);
+      fileClaims.set(key, { project: proj, file, session, gitRoot, ts: now(), remote });
       touch(session, undefined, undefined, undefined, auth);
-      // Feed events, throttled by design: the FIRST touch inside a TTL window says "claimed";
-      // a collision says so every time — that is the one worth seeing on the FEED.
+      if (gitRoot) {
+        state.peers[session].gitRoot = gitRoot;
+        state.overseerState ??= {};
+        state.overseerState.roots ??= {};
+        state.overseerState.roots[session] = gitRoot;
+      }
+      // Repeated checks refresh the claim without repeating its conflict event.
       if (!mine) appendEvent("file.claim", proj, session, { file });
-      if (conflicts.length) appendEvent("file.conflict", proj, session, { file, with: conflicts.map(c => c.session) });
-      return json(res, 200, { ok: true, conflicts, ttlMs: CLAIM_TTL_MS });
+      if (!mine && conflicts.length) appendEvent("file.conflict", proj, session, { file, with: conflicts.map(c => c.session) });
+      overseer.overseerTick();
+      const hold = overseer.holdFor(proj, file, session, gitRoot);
+      const level = levelFor(proj, overseer.overseerPolicy().autonomy);
+      return json(res, 200, { ok: true, conflicts: level >= 2 ? conflicts : [], level, hold, ttlMs: CLAIM_TTL_MS });
     }
     if (req.method === "GET" && P === "/claims") {
       pruneClaims();

package/hub/store.mjs

@@ -6,7 +6,7 @@ import { DEFAULT_ORG } from "../lib/store-contract.mjs";
 
 export async function createStoreRuntime({ STORE_KIND, PG_URL, ORG_ID, DATA }) {
 function emptyState() {
-  return { messages: [], peers: {}, seq: 0, tasks: [], taskSeq: 0, projectMeta: {}, lessons: [], events: [], cardEventsBackfilled: false, aliases: {}, phaseMeta: {}, verifyGates: [], verifyGateSeq: 0, proposals: [], proposalSeq: 0, balances: { ts: 0, by: "", entries: [] }, subagentCostReset: false, handoffLog: [], identities: {}, inviteTokens: {}, focus: {}, orgPolicy: {}, instances: {}, dutySession: "", contractReap: {}, eventSeq: 0 };
+  return { messages: [], peers: {}, seq: 0, tasks: [], taskSeq: 0, projectMeta: {}, lessons: [], events: [], cardEventsBackfilled: false, aliases: {}, phaseMeta: {}, verifyGates: [], verifyGateSeq: 0, proposals: [], proposalSeq: 0, balances: { ts: 0, by: "", entries: [] }, subagentCostReset: false, handoffLog: [], identities: {}, inviteTokens: {}, focus: {}, orgPolicy: {}, overseerState: {}, instances: {}, dutySession: "", contractReap: {}, eventSeq: 0 };
 }
 
 const CARD_LOG_MAX = 40;
@@ -110,6 +110,7 @@ function normalizeState(loaded = {}) {
   s.instances = loaded.instances && typeof loaded.instances === "object" ? loaded.instances : {};
   s.focus = loaded.focus && typeof loaded.focus === "object" ? loaded.focus : {};
   s.orgPolicy = loaded.orgPolicy && typeof loaded.orgPolicy === "object" ? loaded.orgPolicy : {};
+  s.overseerState = loaded.overseerState || {};
   s.dutySession = String(loaded.dutySession || "");
   s.contractReap = loaded.contractReap && typeof loaded.contractReap === "object" ? loaded.contractReap : {};
   // The event id high-water mark. Seeded from the store's own MAX(id) where it supplied one, and
@@ -127,7 +128,7 @@ function normalizeState(loaded = {}) {
       // #6170: `kind` rides the load. This normalizer rebuilds every peer from an explicit field
       // list, so a field missing here is dropped however faithfully the store returned it (the kinds
       // came back empty on the first live restart). llm/model stay out: they are in-memory presence.
-      : { lastSeen: v.lastSeen || 0, status: v.status || "", project: v.project || "", pubkey: v.pubkey || "", identity: v.identity || null, authWarning: v.authWarning || "", hookVersion: v.hookVersion || "", kind: v.kind || "", deliveredUpTo: v.deliveredUpTo || v.delivered_up_to || 0, _on: v._on === true || v.online === true };
+      : { lastSeen: v.lastSeen || 0, status: v.status || "", project: v.project || "", pubkey: v.pubkey || "", identity: v.identity || null, authWarning: v.authWarning || "", hookVersion: v.hookVersion || "", kind: v.kind || "", gitRoot: v.gitRoot || loaded.overseerState?.roots?.[session] || "", deliveredUpTo: v.deliveredUpTo || v.delivered_up_to || 0, _on: v._on === true || v.online === true };
   }
   return s;
 }

package/lib/duty-nudges.mjs

@@ -283,6 +283,18 @@ export async function recordDutyNudges({ plan, observedIds, statePath, now = Dat
   return nudged;
 }
 
+// #11355: an id the shared pre-send ledger awarded to the OTHER nudger must not keep this path's
+// planned claim — it would block the winner's own re-claim machinery for up to 30 minutes.
+export async function releaseDutyNudgeClaims({ ids, statePath, owner }) {
+  const wanted = [...new Set((ids || []).map(String).filter(Boolean))];
+  if (!wanted.length) return;
+  await withStateLock(statePath, state => {
+    for (const id of wanted) {
+      if (state.planned[id]?.owner === owner) delete state.planned[id];
+    }
+  });
+}
+
 export async function auditDutyNudges({ plan, observedIds, statePath, reportFailure, now = Date.now() }) {
   const nudged = await recordDutyNudges({ plan, observedIds, statePath, now });
   // #7429: the audit reads the ledger — an id the mechanical wake already verified (or a terminal

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/remote-overlap.mjs

@@ -0,0 +1,193 @@
+// #11311: client-side open-PR overlap evidence. The session's OWN hook polls the repo it is
+// actually editing (`git -C <gitRoot> remote get-url origin`) — never the hub, whose checkout and
+// unauthenticated gh would match trantor's PRs to every project. Cached 5 min per repo in
+// ~/.agent-bus/remote-overlap-<owner>-<name>.json; gh missing/unauthenticated = off, one log line.
+import { execFile, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const POLL_TTL_MS = 5 * 60 * 1000;
+const RATE_LIMIT_BACKOFF_MS = 10 * 60 * 1000;
+const BLIP_BACKOFF_MS = 30 * 1000;
+const GH_TIMEOUT_MS = Number(process.env.RELAY_REMOTE_OVERLAP_TIMEOUT_MS || 5000);
+// Cap PRs per poll: each costs a /files call, and a busy repo must not eat the rate limit.
+const PR_CAP = 25;
+
+const GH_OFF = /gh auth login|not logged into|gh: auth|authentication/i;
+const RATE_LIMIT = /rate limit/i;
+
+// "owner/name" from every remote form in the wild — https, ssh, git://, with credentials or a
+// .git suffix — or a bare owner/name that is already parsed. Anything else is not pollable.
+export function parseRepoUrl(url) {
+  const raw = String(url ?? "").trim();
+  if (!raw) return null;
+  if (/^[\w.-]+\/[\w.-]+$/.test(raw)) return raw;
+  const m = raw.match(/^(?:(?:https?:\/\/|ssh:\/\/|git:\/\/)(?:[^@/]+@)?|git@)?[^/:@]+[:/](.+?)(?:\.git)?\/?$/i);
+  const parts = m ? m[1].replace(/\.git$/i, "").split("/").filter(Boolean) : [];
+  const owner = parts[parts.length - 2];
+  const name = parts[parts.length - 1];
+  return owner && name && /^[\w.-]+$/.test(owner) && /^[\w.-]+$/.test(name) ? `${owner}/${name}` : null;
+}
+
+function defaultGitRun(args, { cwd } = {}) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 5000 });
+  return { status: r.status, stdout: r.stdout || "", stderr: r.stderr || "" };
+}
+
+function defaultGhRun(args) {
+  const r = spawnSync("gh", args, { encoding: "utf8", timeout: GH_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 });
+  if (r.error && !r.error.message?.includes("exited with")) {
+    return { code: r.error.code ?? 1, stdout: "", stderr: String(r.stderr || r.error.message || "") };
+  }
+  return { code: r.status ?? 1, stdout: r.stdout || "", stderr: r.stderr || "" };
+}
+
+// Repo detection: `git remote get-url origin` from the session's git root. Null when there is
+// no origin or it is not a GitHub-ish remote — the poller stays quietly off.
+export function detectRepo({ dir = process.cwd(), run = defaultGitRun } = {}) {
+  try {
+    const r = run(["remote", "get-url", "origin"], { cwd: dir });
+    return r.status === 0 ? parseRepoUrl(r.stdout) : null;
+  } catch {
+    return null;
+  }
+}
+
+const cleanPaths = (files) =>
+  [...new Set(Array.from(files ?? []).map((f) => String(f ?? "").trim()).filter(Boolean))].sort((a, b) => a.localeCompare(b));
+
+// The poller. overlapsFor({repo, gitRoot, files}) is SYNC: cache file read first (the norm), a
+// stale or cold repo triggers one gh poll (list + per-PR files) whose result rewrites the cache,
+// so sibling processes (other claims, other seats) hit the warm file. rate-limit and gh-off state
+// persist in the cache file too, so backoff survives the hook's short-lived processes.
+export function createRemoteOverlap({
+  run = defaultGhRun,
+  gitRun = defaultGitRun,
+  log = (m) => console.error(`[remote-overlap] ${m}`),
+  now = Date.now,
+  ttlMs = POLL_TTL_MS,
+  backoffMs = RATE_LIMIT_BACKOFF_MS,
+  cacheDir,
+} = {}) {
+  const dir = cacheDir || process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus");
+  let enabled = true;
+  let logged = "";
+
+  const say = (m) => {
+    if (!logged) {
+      logged = m;
+      log(m);
+    }
+  };
+
+  const cachePath = (repo) => join(dir, `remote-overlap-${String(repo).replace(/\//g, "-")}.json`);
+  const readCache = (repo) => {
+    try {
+      return JSON.parse(readFileSync(cachePath(repo), "utf8"));
+    } catch {
+      return null;
+    }
+  };
+  const writeCache = (repo, data) => {
+    try {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(cachePath(repo), JSON.stringify({ repo, at: now(), prs: [], off: "", blockedUntil: 0, ...data }));
+    } catch {}
+  };
+
+  function fail(repo, res) {
+    const stderr = String(res?.stderr || "");
+    if (res?.code === "ENOENT" || GH_OFF.test(stderr)) {
+      enabled = false;
+      say(`gh unusable (${res?.code === "ENOENT" ? "gh not found" : "not authenticated"}) — remote-overlap off.`);
+      writeCache(repo, { off: "gh missing or unauthenticated", prs: [] });
+      return null;
+    }
+    const prior = readCache(repo);
+    const blockedUntil = RATE_LIMIT.test(stderr) ? (say(`GitHub rate limit hit — polling paused ${Math.round(backoffMs / 60000)}m.`), now() + backoffMs) : now() + BLIP_BACKOFF_MS;
+    writeCache(repo, { at: prior?.at ?? 0, prs: prior?.prs ?? [], blockedUntil, off: "" });
+    return null;
+  }
+
+  function poll(repo) {
+    const list = run(["api", `repos/${repo}/pulls?state=open`]);
+    if (list.code !== 0) return fail(repo, list);
+    let pulls;
+    try {
+      pulls = JSON.parse(list.stdout || "[]");
+    } catch {
+      return fail(repo, { code: list.code, stderr: "unparsable PR list" });
+    }
+    if (!Array.isArray(pulls)) return fail(repo, { code: list.code, stderr: "unexpected PR list shape" });
+    const prs = [];
+    for (const p of pulls.slice(0, PR_CAP)) {
+      const number = Number(p?.number);
+      if (!Number.isFinite(number)) continue;
+      const res = run(["api", `repos/${repo}/pulls/${number}/files`]);
+      let files = [];
+      if (res.code === 0) {
+        try {
+          files = cleanPaths(JSON.parse(res.stdout || "[]").map((f) => f?.filename));
+        } catch {
+          files = [];
+        }
+      }
+      prs.push({ number, author: String(p?.user?.login || ""), url: String(p?.html_url || ""), files });
+    }
+    const data = { repo, at: now(), prs, off: "", blockedUntil: 0 };
+    writeCache(repo, data);
+    return data;
+  }
+
+  function overlapsFor(input = {}) {
+    if (!enabled) return [];
+    const want = cleanPaths(input.files);
+    if (!want.length) return [];
+    const repo = String(input.repo || "").trim() || (input.gitRoot ? detectRepo({ dir: input.gitRoot, run: gitRun }) : null);
+    if (!repo) return [];
+    const t = now();
+    let data = readCache(repo);
+    if (!data || data.off) {
+      // a fresh off marker stays off without spawning gh; past the TTL the poll retries once
+      if (data?.off && t - (data.at ?? 0) <= ttlMs) return [];
+      poll(repo);
+      data = readCache(repo);
+      if (!data || data.off) return [];
+    } else if (t - (data.at ?? 0) > ttlMs && t >= (data.blockedUntil ?? 0)) {
+      poll(repo);
+      data = readCache(repo) ?? data;
+    }
+    const wantSet = new Set(want);
+    const out = [];
+    for (const p of data.prs ?? []) {
+      const hit = (p.files || []).filter((f) => wantSet.has(f));
+      if (hit.length) out.push({ repo, number: p.number, author: p.author, url: p.url, files: cleanPaths(hit) });
+    }
+    return out.sort((a, b) => a.number - b.number);
+  }
+
+  // Force a poll, cache result, return it (or null on failure) — the test seam and warm-up path.
+  function refresh(repo) {
+    return poll(repo);
+  }
+
+  return {
+    overlapsFor,
+    refresh,
+    get enabled() {
+      return enabled;
+    },
+  };
+}
+
+const defaultApi = createRemoteOverlap({});
+
+// The hook-facing seam: never raises, whatever the input.
+export function overlapsFor(input) {
+  try {
+    return defaultApi.overlapsFor(input);
+  } catch {
+    return [];
+  }
+}

package/lib/seat-why.mjs

@@ -134,6 +134,7 @@ export function seatWhy(project, agent, opts = {}) {
   const pids = opts.pidCheck ? opts.pidCheck(project, agent) : scanPids(project, agent);
   const last = [...telemetry].reverse().find(r => asNumber(r.turn) !== null) || null;
   const boots = telemetry.filter(r => r.boot).length;
+  const lifecycle = [...telemetry].reverse().find(r => r.boot || r.stopped);
   const errTail = errText.trim().split("\n").filter(Boolean).slice(-2).join(" | ").slice(0, 240);
 
   let state, why, advice;
@@ -184,7 +185,11 @@ export function seatWhy(project, agent, opts = {}) {
     else if (boots) bits.push(`${boots} boot record(s), no completed turn`);
     if (pane) bits.push(`pane ${pane.source}/${pane.pane} registered but no runner process`);
 
-    if (last?.authFailed || AUTH_RE.test(errText)) {
+    if (lifecycle?.stopped) {
+      state = "stopped";
+      why = `no runner process; operator stopped ${agent}:${project} ${rel(lifecycle.ts)}.`;
+      advice = "seat was deliberately stopped — `trantor up <agent>` to start it again.";
+    } else if (last?.authFailed || AUTH_RE.test(errText)) {
       state = "dead-auth";
       why = `no runner process; ${bits.join("; ") || "auth markers in evidence"}.`;
       advice = "provider credentials are rejected — fix the key (~/.agent-bus/.env or the seat's token-scrooge .env), then `trantor up <agent>`.";