dev-loops 0.7.2 → 0.8.0

package/scripts/github/verify-briefing-prefixes.mjs

@@ -1,15 +1,20 @@
 #!/usr/bin/env node
 import { readdir, readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { GATE_NAMES } from "./_gate-names.mjs";
 
 const USAGE = `Usage: verify-briefing-prefixes.mjs --head-sha <sha> [--help]
 Fan-in enforcement for GATE-EXEC-BRIEFING-PREFIX (docs/gate-review-sub-loop-contract.md):
-fails closed when this gate-review round's per-scope reviewer sentinels (written by
-verify-fresh-review-context.mjs --prefix-hash/--prefix-file) do not all record the SAME
-invariant-briefing prefix hash. Deterministic and offline: reads only the sentinel files
-already on disk under tmp/, keyed by the given head SHA.
+fails closed when a reviewer sentinel's (written by verify-fresh-review-context.mjs
+--prefix-hash/--prefix-file) recorded prefix hash matches no on-disk per-gate
+briefing-prefix record for this head, matches a DIFFERENT gate than the sentinel's
+scope declares, or is missing outright. When no per-gate records exist it falls
+back to requiring all of this round's sentinels to share ONE hash. Deterministic
+and offline: reads only the sentinel and record files already on disk under tmp/,
+keyed by the given head SHA.
 
 Required:
   --head-sha <sha>  The FULL 40-char reviewed head SHA (git rev-parse HEAD); sentinels are read from
@@ -17,25 +22,43 @@ Required:
 
 Output (stdout, JSON):
   { "ok": true, "verified": true, "headSha": "...", "reviewerCount": <n>, "prefixHash": "..." }
+  { "ok": true, "verified": true, "headSha": "...", "reviewerCount": <n>, "prefixHash": "...", "gates": [{ "gate": "draft_gate", "prefixHash": "...", "reviewerCount": <n> }] }
+  { "ok": true, "verified": true, "headSha": "...", "reviewerCount": <n>, "gates": [{ "gate": "draft_gate", "prefixHash": "...", "reviewerCount": <n> }, { "gate": "pre_approval_gate", "prefixHash": "...", "reviewerCount": <n> }] }
   { "ok": true, "verified": true, "headSha": "...", "reviewerCount": 0, "reason": "no sentinels found for this round" }
   { "ok": true, "verified": false, "headSha": "...", "reviewerCount": <n>, "reason": "...", "missing": [...], "mismatched": [...] }
   On error (stderr, JSON):
   { "ok": false, "error": "...", "usage": "..." }
 ${JQ_OUTPUT_USAGE}
 Exit codes:
-  0  Verified: no sentinels found for this round (nothing to check), or every
-     sentinel records a hash and all hashes are identical (a single hashed
-     sentinel verifies — nothing to mismatch)
-  1  Fail closed: two or more sentinels record DIFFERENT prefix hashes, or ANY
-     sentinel for the round (even a lone one) records no prefix hash — a missing
-     hash is treated as a mismatch, never grandfathered
+  0  Verified: no sentinels found for this round (nothing to check); OR, with
+     on-disk per-gate briefing records present, every sentinel's hash matches a
+     record AND matches the gate its scope declares (two gates reviewed at one
+     head each match their own record, so a verified round can involve
+     different per-gate hashes); OR, with no records, all sentinels share one
+     identical hash
+  1  Fail closed: a sentinel hash matches no on-disk gate record, or matches a
+     DIFFERENT gate than its scope declares (wrong-gate briefing), or any
+     sentinel records no prefix hash — never grandfathered; or two or more
+     sentinels attributed to the SAME gate recorded DIFFERENT prefix hashes
+     (within-gate briefings were not byte-identical); or, with no records,
+     two or more sentinels record different hashes
   2  Usage or internal error, or invalid --jq filter
 
-Caveat: rounds are keyed by head SHA only. Two different gates reviewed at the
-SAME head share one sentinel namespace, so run this check per gate pass (the head
-advances between gate passes per GATE-EXEC-REGATE-MANDATORY; never manually clear sentinels); legitimately different per-gate prefixes at an identical
-head would otherwise flag as a mismatch (conservative fail-closed, never
-fail-open).`.trim();
+Gate scoping: each reviewer sentinel's recorded prefix hash is verified against
+the on-disk per-gate briefing-prefix records (<gate>-<headSha>.briefing-prefix.txt
+under tmp/gate-context/, written by write-gate-context.mjs). Two gates reviewed
+at the SAME head (e.g. a small change clearing draft_gate and pre_approval_gate
+without an intervening push) each verify against their own record instead of
+colliding into a spurious mismatch, and a hash matching no record fails closed.
+A sentinel whose scope self-declares a gate (e.g. "draft-gate-coverage") must
+also match THAT gate's record — a hash that matches a DIFFERENT gate's record
+is a wrong-gate briefing and fails closed even though the hash itself is known.
+Beyond per-sentinel matching, all reviewers attributed to ONE gate must share
+ONE identical prefix hash — two DIFFERENT hashes for the same gate fails closed
+as a within-gate byte-identity violation, even when each hash individually
+matches a known record. When no records are present the check falls back to
+the conservative flat rule (all sentinels must share one hash).
+Never manually clear sentinels.`.trim();
 
 // Full 40-char SHA required: sentinel filenames embed the full `git rev-parse
 // HEAD` value, so a short prefix would glob zero sentinels and read as a
@@ -106,21 +129,117 @@ async function readRoundSentinels(tmpRoot, headSha) {
   return results;
 }
 
+const BRIEFING_PREFIX_SUFFIX = ".briefing-prefix.txt";
+
+/**
+ * Read the per-gate invariant-briefing records for this head from
+ * `<tmpRoot>/gate-context/**` (written by write-gate-context.mjs as
+ * `<gate>-<headSha>.briefing-prefix.txt`). Returns a Map from the record's
+ * sha256 (the exact bytes reviewers hash via `--prefix-file`) to the set of
+ * gate names whose record has that exact hash (normally one gate; a shared
+ * hash across gates is possible in principle and must not false-fail the
+ * wrong-gate check). These records are the authoritative per-(gate, headSha)
+ * proof each reviewer sentinel is verified against — a sentinel hash that
+ * matches no record is a contaminated/stale briefing. Empty Map when none
+ * exist (offline/legacy), which routes evaluation to the conservative flat
+ * fallback.
+ * @param {string} tmpRoot
+ * @param {string} headSha — lowercase hex, already validated
+ * @returns {Promise<Map<string, Set<string>>>} sha256 -> set of gates
+ */
+async function readGateBriefingRecords(tmpRoot, headSha) {
+  const root = path.join(tmpRoot, "gate-context");
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true, recursive: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return new Map();
+    throw err;
+  }
+  const suffix = `-${headSha}${BRIEFING_PREFIX_SUFFIX}`;
+  const records = new Map();
+  const matches = entries
+    .filter((e) => e.isFile() && e.name.endsWith(suffix) && e.name.length > suffix.length)
+    // readdir order is filesystem-dependent; sort by name so the hash->Set<gate>
+    // index is built in a deterministic order across runs.
+    .sort((a, b) => a.name.localeCompare(b.name));
+  for (const e of matches) {
+    const gate = e.name.slice(0, -suffix.length);
+    // Only canonical gate records are trusted: a stray/leftover file whose
+    // prefix isn't a real gate name must not be able to satisfy record-matching.
+    if (!GATE_NAMES.includes(gate)) continue;
+    const dir = e.parentPath ?? root;
+    let bytes;
+    try {
+      bytes = await readFile(path.join(dir, e.name));
+    } catch {
+      continue; // unreadable record: skip; a sentinel relying on it fails closed as unknown
+    }
+    const hash = createHash("sha256").update(bytes).digest("hex");
+    if (!records.has(hash)) records.set(hash, new Set());
+    records.get(hash).add(gate);
+  }
+  return records;
+}
+
+/**
+ * Gate a reviewer scope self-declares, matched against the canonical gate
+ * vocabulary (hyphenated to the `--scope` form, since scopes forbid
+ * underscores). Matching is case-insensitive (`--scope` permits mixed case;
+ * a mis-cased scope must still be attributed to its gate rather than falling
+ * through to the bare-scope path and bypassing the wrong-gate check). Uses
+ * the LONGEST matching prefix so a future gate whose name string-extends
+ * another is attributed correctly. Returns null for a bare/legacy scope with
+ * no recognized gate prefix — those are matched by hash alone.
+ * Exported for direct testing.
+ * @param {string} scope
+ * @param {string[]} [gateNames]
+ * @returns {string|null}
+ */
+export function declaredGateOf(scope, gateNames = GATE_NAMES) {
+  const s = scope.toLowerCase();
+  let best = null;
+  let bestLen = -1;
+  for (const gate of gateNames) {
+    const prefix = gate.replace(/_/g, "-");
+    if ((s === prefix || s.startsWith(`${prefix}-`)) && prefix.length > bestLen) {
+      best = gate;
+      bestLen = prefix.length;
+    }
+  }
+  return best;
+}
+
 /**
- * Pure comparison: given the round's sentinels, decide verified/reason/missing/mismatched.
+ * Pure comparison: decide verified/reason/missing/mismatched for the round.
  * Exported for direct unit testing without touching the filesystem.
+ *
+ * When `gateRecords` (sha256 -> Set<gate>, from the on-disk `<gate>-<headSha>`
+ * briefing-prefix records) is non-empty, EVERY sentinel's recorded prefix hash
+ * must match one of those authoritative records; a hash matching none is a
+ * contaminated/stale briefing and fails closed. This is what lets two gates
+ * legitimately reviewed at ONE head both pass — each verifies against its own
+ * gate's record — without a spurious cross-gate mismatch. When a sentinel's
+ * scope self-declares a gate (against the canonical GATE_NAMES vocabulary),
+ * its matched record's gate set must contain that SAME gate: a known hash that
+ * instead belongs only to a different gate's record fails closed as a
+ * wrong-gate briefing (the fix for the false fail-closed AND the fail-open the
+ * scope-prefix approach would have introduced). Beyond per-sentinel matching,
+ * every reviewer attributed to the SAME gate must share ONE identical prefix
+ * hash — two distinct hashes for one gate fails closed as a within-gate
+ * byte-identity violation (AC2), even though each hash individually matches a
+ * known record for that gate. When no records exist (offline/legacy) it falls
+ * back to the conservative flat check: all sentinels must share one hash.
+ * A missing/hashless sentinel always fails closed (never grandfathered).
+ *
  * @param {Array<{ scope: string, prefixHash: string|null }>} sentinels
- * @returns {{ verified: boolean, reason?: string, missing?: string[], mismatched?: Array<{scope:string, prefixHash:string}> }}
+ * @param {Map<string, Set<string>>|null} [gateRecords] — sha256 -> set of gates
+ * @returns {{ verified: boolean, reason?: string, missing?: string[], mismatched?: Array<{scope:string, prefixHash:string}>, prefixHash?: string, gates?: Array<{gate:string, prefixHash:string, reviewerCount:number}> }}
  */
-export function evaluateBriefingPrefixes(sentinels) {
+export function evaluateBriefingPrefixes(sentinels, gateRecords = null) {
   if (sentinels.length === 0) {
     return { verified: true, reason: "no sentinels found for this round" };
   }
-  // A hashless sentinel fails closed even when it is the ONLY sentinel (a
-  // one-angle Phase-5 retry round is a real case): "never grandfathered" means
-  // the invariant-prefix proof must exist for every reviewer, not just when a
-  // sibling exists to compare against. A single HASHED sentinel stays verified —
-  // with one recorded hash there is nothing to mismatch.
   const missing = sentinels.filter((s) => s.prefixHash === null).map((s) => s.scope);
   if (missing.length > 0) {
     return {
@@ -129,20 +248,90 @@ export function evaluateBriefingPrefixes(sentinels) {
       missing,
     };
   }
-  const distinct = new Map();
-  for (const { scope, prefixHash } of sentinels) {
-    if (!distinct.has(prefixHash)) distinct.set(prefixHash, []);
-    distinct.get(prefixHash).push(scope);
+  const records = gateRecords instanceof Map ? gateRecords : new Map();
+  if (records.size === 0) {
+    // Flat fallback (pre-record behavior, conservative fail-closed): with no
+    // authoritative records to attribute sentinels to gates, all sentinels must
+    // record ONE identical hash. Two distinct hashes fail closed.
+    const distinct = new Map();
+    for (const { scope, prefixHash } of sentinels) {
+      if (!distinct.has(prefixHash)) distinct.set(prefixHash, []);
+      distinct.get(prefixHash).push(scope);
+    }
+    if (distinct.size > 1) {
+      return {
+        verified: false,
+        reason: `Reviewer sentinels for this round recorded ${distinct.size} DIFFERENT invariant-briefing prefix hashes and no on-disk gate briefing-prefix records were found to attribute them per gate — the seeded briefings were not byte-identical (GATE-EXEC-BRIEFING-PREFIX).`,
+        mismatched: sentinels.map(({ scope, prefixHash }) => ({ scope, prefixHash })),
+      };
+    }
+    return { verified: true, prefixHash: sentinels[0].prefixHash };
   }
-  if (distinct.size > 1) {
-    const mismatched = sentinels.map(({ scope, prefixHash }) => ({ scope, prefixHash }));
+  // Record-matching: every sentinel hash must match an on-disk record; a scope
+  // that declares a gate must match a record for THAT gate; and all reviewers
+  // attributed to one gate must share ONE hash (within-gate byte-identity, AC2).
+  const unknown = sentinels.filter((s) => !records.has(s.prefixHash));
+  if (unknown.length > 0) {
     return {
       verified: false,
-      reason: `Reviewer sentinels for this round recorded ${distinct.size} DIFFERENT invariant-briefing prefix hashes — the seeded briefings were not byte-identical (GATE-EXEC-BRIEFING-PREFIX).`,
-      mismatched,
+      reason: `${unknown.length} of ${sentinels.length} reviewer sentinel(s) recorded an invariant-briefing prefix hash that matches no gate briefing-prefix record for this head — a contaminated, stale, or hand-edited briefing (GATE-EXEC-BRIEFING-PREFIX). Never grandfathered.`,
+      mismatched: unknown.map(({ scope, prefixHash }) => ({ scope, prefixHash })),
     };
   }
-  return { verified: true, prefixHash: sentinels[0].prefixHash };
+  // Attribute each sentinel to a gate and detect wrong-gate briefings.
+  const wrongGate = [];
+  const attributed = []; // { scope, prefixHash, gate }
+  for (const s of sentinels) {
+    const gatesForHash = records.get(s.prefixHash); // Set<gate>, non-empty
+    const declared = declaredGateOf(s.scope);
+    if (declared !== null) {
+      if (!gatesForHash.has(declared)) {
+        wrongGate.push({ scope: s.scope, prefixHash: s.prefixHash });
+        continue;
+      }
+      attributed.push({ scope: s.scope, prefixHash: s.prefixHash, gate: declared });
+    } else {
+      // Bare/legacy scope: attribute by the record's gate. A hash mapping to
+      // multiple gates (byte-identical briefings across gates — practically
+      // impossible since the gate is embedded in the hashed bytes) is resolved
+      // deterministically to the alphabetically-first gate for a stable summary.
+      const gate = gatesForHash.size === 1 ? [...gatesForHash][0] : [...gatesForHash].sort()[0];
+      attributed.push({ scope: s.scope, prefixHash: s.prefixHash, gate });
+    }
+  }
+  if (wrongGate.length > 0) {
+    return {
+      verified: false,
+      reason: `${wrongGate.length} of ${sentinels.length} reviewer sentinel(s) recorded a prefix hash belonging to a DIFFERENT gate than their scope declares — a wrong-gate briefing (GATE-EXEC-BRIEFING-PREFIX).`,
+      mismatched: wrongGate,
+    };
+  }
+  // Within-gate byte-identity: every reviewer attributed to one gate must share
+  // one hash. Two distinct hashes for the same gate (e.g. multiple same-gate
+  // records at this head) fails closed — the byte-identity invariant (AC2).
+  const gateHashes = new Map(); // gate -> Set<hash>
+  const gateCounts = new Map(); // gate -> count
+  for (const a of attributed) {
+    if (!gateHashes.has(a.gate)) gateHashes.set(a.gate, new Set());
+    gateHashes.get(a.gate).add(a.prefixHash);
+    gateCounts.set(a.gate, (gateCounts.get(a.gate) ?? 0) + 1);
+  }
+  const split = [...gateHashes.entries()].find(([, hs]) => hs.size > 1);
+  if (split) {
+    const [g] = split;
+    return {
+      verified: false,
+      reason: `Reviewer sentinels for gate ${g} recorded ${split[1].size} DIFFERENT invariant-briefing prefix hashes — within-gate briefings were not byte-identical (GATE-EXEC-BRIEFING-PREFIX).`,
+      mismatched: attributed.filter((a) => a.gate === g).map(({ scope, prefixHash }) => ({ scope, prefixHash })),
+    };
+  }
+  const gates = [...gateHashes.entries()]
+    .map(([gate, hs]) => ({ gate, prefixHash: [...hs][0], reviewerCount: gateCounts.get(gate) }))
+    .sort((a, b) => a.gate.localeCompare(b.gate));
+  if (gates.length === 1) {
+    return { verified: true, prefixHash: gates[0].prefixHash, gates };
+  }
+  return { verified: true, gates };
 }
 
 export async function main(argv = process.argv.slice(2), { tmpRoot = path.join(process.cwd(), "tmp") } = {}) {
@@ -167,7 +356,8 @@ export async function main(argv = process.argv.slice(2), { tmpRoot = path.join(p
   const silent = argv.includes("--silent") || argv.includes("-s");
 
   const sentinels = await readRoundSentinels(tmpRoot, headSha);
-  const verdict = evaluateBriefingPrefixes(sentinels);
+  const gateRecords = await readGateBriefingRecords(tmpRoot, headSha);
+  const verdict = evaluateBriefingPrefixes(sentinels, gateRecords);
   const payload = {
     ok: true,
     verified: verdict.verified,
@@ -177,6 +367,7 @@ export async function main(argv = process.argv.slice(2), { tmpRoot = path.join(p
     ...(verdict.missing ? { missing: verdict.missing } : {}),
     ...(verdict.mismatched ? { mismatched: verdict.mismatched } : {}),
     ...(verdict.prefixHash ? { prefixHash: verdict.prefixHash } : {}),
+    ...(verdict.gates ? { gates: verdict.gates } : {}),
   };
   return emitResult(payload, { jq, silent, ok: verdict.verified });
 }

package/scripts/github/write-gate-context.mjs

@@ -39,6 +39,7 @@ import { resolveGateAnglesDynamic } from "@dev-loops/core/config";
 import { parsePrNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { buildAdjacentBundle, DEFAULT_MAX_FILE_BYTES } from "./build-adjacent-bundle.mjs";
+import { GATE_NAMES } from "./_gate-names.mjs";
 import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 /**
@@ -132,7 +133,7 @@ function parseError(message) {
 }
 
 function normalizeGate(value) {
-  const gates = new Set(["draft_gate", "pre_approval_gate"]);
+  const gates = new Set(GATE_NAMES);
   const normalized = String(value).trim().toLowerCase();
   return gates.has(normalized) ? normalized : null;
 }
@@ -152,6 +153,9 @@ function normalizeHeadSha(value) {
 // with our own "<base>...HEAD" triple-dot construction). Everything else —
 // including HEAD@{upstream}, main@{1}, tag-peel v1.0.0^{commit}, HEAD~3 — is
 // accepted.
+// Revisit toward an explicit allowlist if `base` ever reaches a shell (or any
+// call without execFileSync's no-shell argv guarantee), or if a malformed ref
+// shape is found slipping past these checks into `git diff`.
 function normalizeBaseRef(value) {
   const trimmed = String(value).trim();
   if (trimmed.length === 0 || trimmed.startsWith("-") || trimmed.includes("..")) return null;
@@ -375,8 +379,8 @@ export function buildGateContextPath({ repo, pr, gate, headSha, tmpRoot = "tmp"
  * @returns {{ pr: number, gate: string, headSha: string }}
  */
 function validatePathSegments({ pr, gate, headSha }) {
-  if (gate !== "draft_gate" && gate !== "pre_approval_gate") {
-    throw new Error(`--gate segment ${JSON.stringify(gate)} is unsafe (expected draft_gate or pre_approval_gate)`);
+  if (!GATE_NAMES.includes(gate)) {
+    throw new Error(`--gate segment ${JSON.stringify(gate)} is unsafe (expected ${GATE_NAMES.join(" or ")})`);
   }
   // Require a CANONICAL positive integer: the trimmed string must be all digits
   // (`/^\d+$/`) and > 0. This mirrors the CLI's parsePrNumber rule so the path
@@ -522,7 +526,7 @@ export function renderBriefingPrefix({
   lines.push(`prefixMode: ${prefixMode}`);
   lines.push("");
   lines.push(
-    `Mandatory: before doing any angle-specific work, run \`node scripts/github/verify-fresh-review-context.mjs --scope <your-angle> --context-path ${contextPath} --prefix-file ${briefingPrefixPath}\`. Refuse to proceed on contamination or a missing artifact.`,
+    `Mandatory: before doing any angle-specific work, run \`node scripts/github/verify-fresh-review-context.mjs --scope ${gate.replace(/_/g, "-")}-<your-angle> --context-path ${contextPath} --prefix-file ${briefingPrefixPath}\`. Refuse to proceed on contamination or a missing artifact.`,
   );
   lines.push("");
   lines.push("## PR body");

package/scripts/loop/_post-convergence-change.mjs

@@ -8,7 +8,7 @@
 // It lives in scripts/loop/ (not packages/core) because significance is derived
 // from a `gh api .../compare` diff — gh I/O that does not belong in core.
 import { extractReviewCommitSha, isCopilotLogin, parseJsonText } from "../_core-helpers.mjs";
-import { runChild } from "../_cli-primitives.mjs";
+import { runChild as defaultRunChild } from "../_cli-primitives.mjs";
 
 export function getLatestSubmittedCopilotReviewHeadSha(reviews) {
   const copilotSubmitted = (Array.isArray(reviews) ? reviews : [])
@@ -149,7 +149,7 @@ export function isCommentOnlyFileChange(file) {
 
 export async function detectPostConvergenceSignificantChange(
   { repo, pr, currentHeadSha, reviews, changedFiles, roundCapReached, regularCopilotRounds },
-  { env = process.env, ghCommand = "gh" } = {},
+  { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {},
 ) {
   if (!roundCapReached || !regularCopilotRounds) {
     return false;

package/scripts/loop/_pr-runner-coordination.mjs

@@ -1,3 +1,5 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { parseRepoSlugParts } from "@dev-loops/core/github/repo-slug";
@@ -9,6 +11,7 @@ import {
 } from "./_steering-state-file.mjs";
 export const RUNNER_COORDINATION_SCHEMA_VERSION = 2;
 export const RUNNER_COORDINATION_SUPPORTED_SCHEMA_VERSIONS = Object.freeze([1, 2]);
+export const RUNNER_COORDINATION_HISTORY_LIMIT = 50; // cap audit trail; heartbeats append per-round, keep the most recent 50 events
 export const RUNNER_OWNERSHIP_ERROR = Object.freeze({
   ACTIVE_RUN_EXISTS: "active_run_exists",
   OWNERSHIP_LOST: "ownership_lost",
@@ -50,7 +53,10 @@ async function loadRunnerStateFile(filePath) {
 }
 async function saveRunnerStateFile(filePath, state) {
   try {
-    return await saveSharedStateFile(filePath, state);
+    const capped = Array.isArray(state.history) && state.history.length > RUNNER_COORDINATION_HISTORY_LIMIT
+      ? { ...state, history: state.history.slice(-RUNNER_COORDINATION_HISTORY_LIMIT) }
+      : state;
+    return await saveSharedStateFile(filePath, capped);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`Failed to write runner coordination state file '${filePath}': ${message}`);
@@ -64,13 +70,62 @@ async function withRunnerStateFileLock(filePath, callback) {
     throw new Error(`Failed to acquire runner coordination state lock for '${filePath}': ${message}`);
   }
 }
+const coordinationRootCache = new Map();
+/**
+ * Resolve the single stable coordination root for a checkout, independent of CWD.
+ *
+ * `git rev-parse --git-common-dir` yields the shared git dir that is identical for
+ * a repo and all its linked worktrees, so its parent is the one main-checkout root
+ * that a worktree runner and a repo-root detector both anchor to — eliminating the
+ * split-copy false-stale stall where each read a different `.pi/runner-coordination`
+ * file. Falls back to the canonicalized (realpath'd) `cwd` when git is
+ * unavailable or the dir is not a checkout, so symlinked and realpath'd
+ * spellings of the same non-git dir still converge on one coordination path.
+ *
+ * `cwd` is realpath'd once at entry: git returns a relative `--git-common-dir` from
+ * a main checkout but an already-realpath'd absolute one from a linked worktree, so
+ * resolving against a symlinked cwd (e.g. macOS /tmp -> /private/tmp) would make the
+ * two sides compute different roots for the same physical repo. Canonicalizing first
+ * makes both sides converge, and doubles as the cache key so symlink-variant cwd
+ * spellings share one cache entry. Cached per canonical cwd for the process.
+ */
+function resolveRepoCoordinationRoot(cwd) {
+  let canonicalCwd = cwd;
+  try {
+    canonicalCwd = fs.realpathSync(cwd);
+  } catch (err) {
+    // realpathSync on an existing checkout dir virtually never fails;
+    // warn (don't throw) so the rare transient failure — which can desync the
+    // coordination path across worktrees — is diagnosable instead of silent.
+    console.warn(
+      `[runner-coordination] realpathSync(${cwd}) failed; using raw cwd, coordination path may diverge across worktrees: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (coordinationRootCache.has(canonicalCwd)) return coordinationRootCache.get(canonicalCwd);
+  let root = canonicalCwd;
+  try {
+    const commonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+      cwd: canonicalCwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (commonDir) {
+      root = path.dirname(path.resolve(canonicalCwd, commonDir));
+    }
+  } catch {
+    // not a git checkout / git unavailable — anchor at the canonical (realpath'd) cwd
+  }
+  coordinationRootCache.set(canonicalCwd, root);
+  return root;
+}
 export function defaultRunnerCoordinationFilePathForTarget({ repo, pr }, cwd = process.cwd()) {
   const { owner, name } = parseRepoSlugParts(repo, {
     errorMessage: `Invalid repo slug for coordination target path: ${JSON.stringify(repo)}`,
     lowercase: true,
   });
   const normalizedPr = normalizePr(pr);
-  return path.join(cwd, ".pi", "runner-coordination", owner, name, `pr-${normalizedPr}.json`);
+  const root = resolveRepoCoordinationRoot(cwd);
+  return path.join(root, ".pi", "runner-coordination", owner, name, `pr-${normalizedPr}.json`);
 }
 export function createRunnerCoordinationState({ repo, pr, runId = null, now = new Date().toISOString() }) {
   const normalizedRepo = normalizeRepoSlug(repo);
@@ -324,6 +379,18 @@ export async function claimRunnerOwnership({
     };
   });
 }
+/**
+ * Verify the caller still owns the PR's runner claim.
+ *
+ * A successful owner-confirmed assert (the active owner's runId matches the
+ * caller's) refreshes `activeRun.updatedAt` — it acts as a heartbeat. Every
+ * other outcome (no record, no active run, ownership lost, missing run id)
+ * is a pure lock-free read with no write. Long-running loops must assert (or
+ * claim) at least once within the stale-max-age window
+ * (`STALE_RUNNER_DEFAULT_MAX_AGE_MS`, 30 minutes by default, overridable via
+ * `DEVLOOPS_STALE_RUNNER_MAX_AGE_MS`; see `_stale-runner-detection.mjs`) to
+ * avoid being seen as stale during a long multi-round gate cycle.
+ */
 export async function assertRunnerOwnership({
   repo,
   pr,
@@ -331,6 +398,7 @@ export async function assertRunnerOwnership({
   cwd = process.cwd(),
   filePath = null,
   requireExisting = false,
+  now = new Date().toISOString(),
 } = {}) {
   const normalizedRepo = normalizeRepoSlug(repo);
   const normalizedPr = normalizePr(pr);
@@ -397,17 +465,48 @@ export async function assertRunnerOwnership({
     });
   }
   if (state.activeRun.runId === normalizedRunId) {
-    return {
-      ok: true,
-      status: "owner_confirmed",
-      repo: normalizedRepo,
-      pr: normalizedPr,
-      runId: normalizedRunId,
-      activeRun: state.activeRun,
-      previousRun: state.previousRun,
-      exitSignals: state.exitSignals,
-      filePath: resolvedPath,
-    };
+    return withRunnerStateFileLock(resolvedPath, async () => {
+      const lockedRaw = await loadRunnerStateFile(resolvedPath);
+      const lockedState = lockedRaw === null
+        ? null
+        : normalizeRunnerCoordinationState(lockedRaw, { repo: normalizedRepo, pr: normalizedPr });
+      if (lockedState?.activeRun?.runId !== normalizedRunId) {
+        // Ownership changed hands between the lockless read above and acquiring
+        // the lock (a concurrent takeover) — don't write; report the new owner.
+        return buildConflict({
+          error: RUNNER_OWNERSHIP_ERROR.OWNERSHIP_LOST,
+          repo: normalizedRepo,
+          pr: normalizedPr,
+          runId: normalizedRunId,
+          activeRun: lockedState?.activeRun ?? null,
+          filePath: resolvedPath,
+          exitSignals: lockedState?.exitSignals ?? [],
+          message: lockedState?.activeRun?.runId
+            ? `PR ${normalizedRepo}#${normalizedPr} is now owned by run ${lockedState.activeRun.runId}; run ${normalizedRunId} must stop.`
+            : `PR ${normalizedRepo}#${normalizedPr} no longer has an active runner ownership record; run ${normalizedRunId} must stop.`,
+        });
+      }
+      const nextState = {
+        ...lockedState,
+        activeRun: {
+          ...lockedState.activeRun,
+          updatedAt: now,
+        },
+        history: [...lockedState.history, { type: "heartbeat", runId: normalizedRunId, at: now }],
+      };
+      await saveRunnerStateFile(resolvedPath, nextState);
+      return {
+        ok: true,
+        status: "owner_confirmed",
+        repo: normalizedRepo,
+        pr: normalizedPr,
+        runId: normalizedRunId,
+        activeRun: nextState.activeRun,
+        previousRun: nextState.previousRun,
+        exitSignals: nextState.exitSignals,
+        filePath: resolvedPath,
+      };
+    });
   }
   return buildConflict({
     error: RUNNER_OWNERSHIP_ERROR.OWNERSHIP_LOST,

package/scripts/loop/check-retro-tooling.mjs

@@ -24,10 +24,13 @@
  *   - dev-loops subcommands and `node scripts/....mjs` invocations. Those scripts
  *     legitimately call gh/GraphQL/etc. internally — that IS the tooling.
  *   - A small explicit allowlist of write-ops that have no internal wrapper today:
- *     `gh pr merge`, `gh pr ready`, `gh issue create`, `gh issue edit`. These are
- *     recorded as `allowedWriteOps` rather than violations so the gate is not
+ *     `gh pr merge`, `gh pr ready`, `gh issue create`. Plus belt-and-suspenders
+ *     entries that DO have wrappers — `gh issue edit` (scripts/github/edit-issue.mjs)
+ *     and `gh label create` (scripts/github/create-label.mjs) — kept so a bare
+ *     invocation surfaced from the wrapper's own subprocess is not a false violation.
+ *     All are recorded as `allowedWriteOps` rather than violations so the gate is not
  *     blocked forever on an unavoidable gap. Document/close the gap with a wrapper
- *     to remove them from the allowlist.
+ *     to remove the no-wrapper entries from the allowlist.
  *
  * VIOLATION (agent-level raw call):
  *   - `gh ...` at the start of a command segment (start of line, or after
@@ -75,19 +78,21 @@ Exit codes:
   2  Argument/runtime error, or invalid --jq filter`;
 
 /**
- * Write-ops that currently have no internal dev-loops wrapper. Recorded
- * distinctly so the gate is not blocked forever on an unavoidable gap.
- * Keep this set SMALL and explicit; remove an entry once a wrapper exists.
+ * Write-ops recorded distinctly (as allowedWriteOps, not violations) so the gate
+ * is not blocked forever on an unavoidable gap. Most have no internal wrapper yet;
+ * a couple DO have wrappers and are kept belt-and-suspenders (see below).
+ * Keep this set SMALL and explicit; remove a no-wrapper entry once a wrapper exists.
  * @type {ReadonlyArray<RegExp>}
  */
 const ALLOWED_WRITE_OPS = Object.freeze([
   /^gh\s+pr\s+merge\b/,
   /^gh\s+pr\s+ready\b/,
   /^gh\s+issue\s+create\b/,
+  // `gh issue edit` (scripts/github/edit-issue.mjs) and `gh label create`
+  // (scripts/github/create-label.mjs) both HAVE wrappers; these entries are
+  // belt-and-suspenders so a bare invocation (e.g. surfaced from the wrapper's
+  // own subprocess) classifies as an allowed write-op, not a violation.
   /^gh\s+issue\s+edit\b/,
-  // `gh label create` HAS a wrapper (scripts/github/create-label.mjs); this
-  // entry is belt-and-suspenders so a bare invocation (e.g. surfaced from the
-  // wrapper's own subprocess) classifies as an allowed write-op, not a violation.
   /^gh\s+label\s+create\b/,
 ]);