mandrel 2.54.0 → 2.56.0

package/.agents/scripts/lib/skills/walk-skill-files.js

@@ -48,8 +48,15 @@ export const LOCAL_SKILLS_SEGMENTS = Object.freeze([
  * The pattern is deliberately strict: ids resolve to filesystem paths, so
  * anything that could escape a root (`..`, absolute paths, backslashes) or
  * smuggle a shell metacharacter is rejected rather than normalized.
+ *
+ * Exported because `config-settings-schema.js` mirrors it as the `pattern`
+ * on `qa.environments.*.signInSeam.skill`, so a malformed id is rejected at
+ * config-validation time rather than surviving to a path join (Story #5285).
+ * It is one regex with two enforcement points, never two regexes: the AJV
+ * `pattern` keyword takes the source string, so the schema must import this
+ * value rather than restate it.
  */
-const SKILL_ID_RE = /^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)+$/;
+export const SKILL_ID_RE = /^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)+$/;
 
 /**
  * Recursively enumerate `SKILL.md` paths under a directory.
@@ -145,17 +152,27 @@ export function collectLocalSkillFiles(repoRoot) {
  * first and the local zone second (payload-wins, matching
  * {@link collectAllSkillFiles}).
  *
- * Returns `null` rather than throwing so callers own the error message —
- * a config resolver wants to name the offending config key, a workflow
- * wants to name the seam.
+ * Returns rather than throwing so callers own the error message — a config
+ * resolver wants to name the offending config key, a workflow wants to name
+ * the seam. The two failures are **distinguishable** (Story #5285):
+ *
+ *   - `null` — a well-formed id that resolves under neither root. The remedy
+ *     is to author the skill, so the caller says so.
+ *   - `{ reason: 'invalid-id' }` — an id the pattern rejects (`../../secrets`,
+ *     `Core/Foo`, a bare `core`). No filesystem lookup happens, and telling
+ *     the operator to author `../../secrets/SKILL.md` would be advice that
+ *     cannot be followed. The remedy is to fix the id.
  *
  * @param {string} repoRoot
  * @param {string} skillId Tier-relative id, e.g. `stack/qa/acme-sso`.
- * @returns {{ path: string, root: string } | null} absolute `SKILL.md`
- *   path and the POSIX repo-relative root it resolved under.
+ * @returns {{ path: string, root: string } | { reason: 'invalid-id' } | null}
+ *   the absolute `SKILL.md` path and the POSIX repo-relative root it resolved
+ *   under, the malformed-id marker, or `null` when nothing resolved.
  */
 export function resolveSkillFile(repoRoot, skillId) {
-  if (typeof skillId !== 'string' || !SKILL_ID_RE.test(skillId)) return null;
+  if (typeof skillId !== 'string' || !SKILL_ID_RE.test(skillId)) {
+    return { reason: 'invalid-id' };
+  }
   for (const segments of [PAYLOAD_SKILLS_SEGMENTS, LOCAL_SKILLS_SEGMENTS]) {
     const candidate = path.join(repoRoot, ...segments, skillId, 'SKILL.md');
     try {

package/.agents/scripts/lib/test-temp.js

@@ -51,12 +51,69 @@ export const SUITE_ROOT_PREFIX = 'mandrel-suite-';
  */
 export const SUITE_ROOTS_KEY = '#suiteRoots';
 
+/** Default `warn` sink: one line on stderr, shared by every seam below. */
+const stderrWarn = (msg) => process.stderr.write(`${msg}\n`);
+
+/**
+ * Remove one directory, reporting a failure rather than throwing it.
+ *
+ * Both reapers need exactly this: a suite that passed must not start
+ * failing because a directory could not be unlinked (a Windows file lock, a
+ * read-only mount). The leak is the lesser defect, and the guard reports it
+ * separately.
+ *
+ * @param {string} target absolute path to remove
+ * @param {string} label what `target` is, for the failure message
+ * @param {typeof fs} fsImpl
+ * @param {(msg: string) => void} warn
+ * @returns {void}
+ */
+function rmQuietly(target, label, fsImpl, warn) {
+  try {
+    fsImpl.rmSync(target, { recursive: true, force: true });
+  } catch (err) {
+    warn(`[test-temp] failed to reap ${label} ${target}: ${err.message}`);
+  }
+}
+
 /** Per-process suite root, or `null` before the first `makeTempDir`. */
 let _suiteRoot = null;
 
 /** Guards against registering the exit reaper more than once. */
 let _reaperRegistered = false;
 
+/** Lead-in of the one warning a root disappearing mid-run produces. */
+const VANISHED =
+  '[test-temp] suite temp root disappeared mid-run (removed by something ' +
+  'outside this process):';
+
+/**
+ * Suite roots this process minted and later found gone.
+ *
+ * Recovery is the right behaviour — see {@link suiteTempRoot} — but a silent
+ * recovery is not. Incident #5272 was a required check going red with an
+ * unattributable `ENOENT`, and the hardening written to expose it made the
+ * run *quieter*: the re-mint succeeded, the suite went green, and the fact
+ * that something outside the process is deleting the temp tree left no trace
+ * anyone would look at. This list is that trace, and the exit reaper turns it
+ * into a verdict.
+ */
+const _vanishedRoots = [];
+
+/** Exit code a run that lost a suite root reports, when nothing worse did. */
+const VANISHED_EXIT_CODE = 1;
+
+/**
+ * Default `setExitCode` sink. Never lowers an exit code already set: a real
+ * test failure is the more informative verdict.
+ *
+ * @param {number} code
+ * @returns {void}
+ */
+function raiseExitCode(code) {
+  if (!process.exitCode) process.exitCode = code;
+}
+
 /**
  * Test-only: forget the per-process suite root without removing it, so a
  * test can exercise the creation branch repeatedly in one process.
@@ -64,10 +121,40 @@ let _reaperRegistered = false;
 export function _resetSuiteTempRootForTests() {
   _suiteRoot = null;
   _reaperRegistered = false;
+  _vanishedRoots.length = 0;
+}
+
+/**
+ * Report every root that vanished under this process, and fail the run.
+ *
+ * Called from the exit reaper, so it is the last word on a run that
+ * otherwise passed. The exit code is only raised when nothing else already
+ * failed: a real test failure is the more informative verdict and must not
+ * be overwritten by this one.
+ *
+ * @param {{ warn?: (msg: string) => void, setExitCode?: (code: number) => void }} [deps]
+ * @returns {void}
+ */
+function reportVanishedRoots({
+  warn = stderrWarn,
+  setExitCode = raiseExitCode,
+} = {}) {
+  if (_vanishedRoots.length === 0) return;
+  warn(
+    `[test-temp] FAIL — ${_vanishedRoots.length} suite temp root(s) disappeared mid-run:\n` +
+      _vanishedRoots.map((root) => `  - ${root}`).join('\n') +
+      '\n[test-temp] the suite recovered by re-minting, so the tests passed — but something outside this process is deleting the temp tree, and a fixture that hits the window between the removal and the re-mint fails with an unattributable ENOENT (#5272). Find the pruner before trusting this run.',
+  );
+  setExitCode(VANISHED_EXIT_CODE);
 }
 
 /**
- * Test-only: report whether this process currently owns a suite root.
+ * Report the suite root this process currently owns, without minting one.
+ *
+ * Test-only in spirit, but also the honest way for a failing fixture to say
+ * whether the root still exists when it reports a copy failure: asking
+ * {@link suiteTempRoot} would *create* one and destroy the evidence.
+ *
  * @returns {string|null}
  */
 export function _currentSuiteTempRoot() {
@@ -77,29 +164,23 @@ export function _currentSuiteTempRoot() {
 /**
  * Remove this process's suite root and everything under it.
  *
- * A teardown failure is reported on stderr and swallowed: a suite that
- * passed must not start failing because a directory could not be unlinked
- * (a Windows file lock, a read-only mount). The leak is the lesser defect
- * and the guard reports it separately.
+ * A teardown failure is reported on stderr and swallowed — see
+ * {@link rmQuietly}.
  *
  * Only the process that minted the root can reach a non-null `_suiteRoot`,
- * so this is creator-only by construction.
+ * so this is creator-only by construction. It reads that variable *live*
+ * rather than a path captured at arming time, which is what keeps a root
+ * re-created mid-run (see {@link suiteTempRoot}) reapable and a root it has
+ * replaced unreachable — a stale path is never passed to `rmSync`.
  *
  * @param {{ fsImpl?: typeof fs, warn?: (msg: string) => void }} [deps]
  * @returns {string|null} the removed root, or `null` when there was none
  */
-export function reapSuiteTempRoot({
-  fsImpl = fs,
-  warn = (msg) => process.stderr.write(`${msg}\n`),
-} = {}) {
+export function reapSuiteTempRoot({ fsImpl = fs, warn = stderrWarn } = {}) {
   const root = _suiteRoot;
   if (root === null) return null;
   _suiteRoot = null;
-  try {
-    fsImpl.rmSync(root, { recursive: true, force: true });
-  } catch (err) {
-    warn(`[test-temp] failed to reap suite temp root ${root}: ${err.message}`);
-  }
+  rmQuietly(root, 'suite temp root', fsImpl, warn);
   return root;
 }
 
@@ -110,21 +191,79 @@ export function reapSuiteTempRoot({
  * cannot exist without its teardown already armed — including when the
  * suite fails, since a failing `node --test` run still exits normally.
  *
- * @param {{ fsImpl?: typeof fs, tmpdir?: () => string, onExit?: (fn: () => void) => void }} [deps]
+ * ## Why the memoised path is re-checked every call
+ *
+ * The root lives under a temp tree this process does not own exclusively
+ * (see the module docstring: a `/tmp` shared with self-hosted runners, an
+ * OS or operator pruner). Memoising the path without re-checking it made a
+ * single external removal terminal: every later `makeTempDir` in the
+ * process failed with an `ENOENT` naming an interior path, and with 204
+ * call sites reaching this helper one deletion cascaded through the rest
+ * of the file. Re-creating is strictly better than failing — nothing in
+ * the suite holds a handle to the root itself, only to directories minted
+ * beneath it, which the removal already took.
+ *
+ * The reaper armed at first use needs no re-arming: it reads `_suiteRoot`
+ * live, so it already covers whatever root this process owns at exit.
+ * Re-creation leaves the replaced path unreachable, so the creator-only
+ * invariant holds — this process still reaps only a root it minted, and
+ * never one it has replaced.
+ *
+ * @param {{ fsImpl?: typeof fs, tmpdir?: () => string, onExit?: (fn: () => void) => void, warn?: (msg: string) => void, setExitCode?: (code: number) => void }} [deps]
  * @returns {string} absolute path to the suite root
  */
-export function suiteTempRoot({
+export function suiteTempRoot(deps = {}) {
+  const fsImpl = deps.fsImpl ?? fs;
+  if (_suiteRoot !== null && fsImpl.existsSync(_suiteRoot)) return _suiteRoot;
+  return mintSuiteRoot(deps);
+}
+
+/**
+ * Mint the process's suite root — the first one, or a replacement for one
+ * that disappeared underneath it — and arm the reaper if nothing has.
+ *
+ * Separate from {@link suiteTempRoot} so the hot path stays the single
+ * existence check callers pay on every `makeTempDir`, and the recovery it
+ * guards reads as the exceptional branch it is.
+ *
+ * @param {{ fsImpl?: typeof fs, tmpdir?: () => string, onExit?: (fn: () => void) => void, warn?: (msg: string) => void, setExitCode?: (code: number) => void }} deps
+ * @returns {string} absolute path to the new suite root
+ */
+function mintSuiteRoot({
   fsImpl = fs,
   tmpdir = os.tmpdir,
   onExit = (fn) => process.once('exit', fn),
+  warn = stderrWarn,
+  setExitCode = raiseExitCode,
 } = {}) {
-  if (_suiteRoot !== null) return _suiteRoot;
+  const vanished = _suiteRoot;
+  const base = tmpdir();
+  // Recovery re-creates the suite's OWN root and nothing above it. An
+  // earlier revision called `mkdirSync(base, { recursive: true })` here, so a
+  // process whose OS temp root had been removed silently re-created `/tmp`
+  // — with this process's umask rather than the sticky 1777 the system sets
+  // — and carried on. That is a broken machine reported as a passing suite;
+  // name it instead.
+  if (!fsImpl.existsSync(base))
+    throw new Error(
+      `[test-temp] OS temp root ${base} does not exist; refusing to create it. Something removed the system temp directory (or TMPDIR points at a path that was never created) — fix the environment rather than letting the suite mint it.`,
+    );
   _suiteRoot = fsImpl.mkdtempSync(
-    path.join(tmpdir(), `${SUITE_ROOT_PREFIX}${process.pid}-`),
+    path.join(base, `${SUITE_ROOT_PREFIX}${process.pid}-`),
   );
+  // Say it once, loudly: this is the only trace that something outside the
+  // process touched the temp tree, and the incident it explains (#5272) was
+  // filed against the wrong mechanism for want of it.
+  if (vanished !== null) {
+    _vanishedRoots.push(vanished);
+    warn(`${VANISHED} ${vanished}; re-created as ${_suiteRoot}`);
+  }
   if (!_reaperRegistered) {
     _reaperRegistered = true;
-    onExit(() => reapSuiteTempRoot({ fsImpl }));
+    onExit(() => {
+      reapSuiteTempRoot({ fsImpl, warn });
+      reportVanishedRoots({ warn, setExitCode });
+    });
   }
   return _suiteRoot;
 }
@@ -137,8 +276,12 @@ export function suiteTempRoot({
  * path is absolute and unique, so call sites change only where the
  * directory comes from, never how it is used.
  *
+ * A vanished suite root is re-created by {@link suiteTempRoot} first, so
+ * this never fails with an `ENOENT` naming a directory the caller did not
+ * ask for.
+ *
  * @param {string} [prefix='t-'] label kept for readability in a stack trace
- * @param {{ fsImpl?: typeof fs, tmpdir?: () => string, onExit?: (fn: () => void) => void }} [deps]
+ * @param {{ fsImpl?: typeof fs, tmpdir?: () => string, onExit?: (fn: () => void) => void, warn?: (msg: string) => void }} [deps]
  * @returns {string} absolute path to the new directory
  */
 export function makeTempDir(prefix = 't-', deps = {}) {
@@ -157,7 +300,7 @@ export function makeTempDir(prefix = 't-', deps = {}) {
  * never reap it, or it deletes its parent's scratch mid-run.
  *
  * Teardown failures are swallowed for the same reason as
- * {@link reapSuiteTempRoot}: a leak must not turn a passing suite red.
+ * {@link reapSuiteTempRoot} — see {@link rmQuietly}.
  *
  * @param {string} dirPath absolute path this process minted
  * @param {{ fsImpl?: typeof fs, onExit?: (fn: () => void) => void, warn?: (msg: string) => void }} [deps]
@@ -168,16 +311,10 @@ export function reapOnExit(
   {
     fsImpl = fs,
     onExit = (fn) => process.once('exit', fn),
-    warn = (msg) => process.stderr.write(`${msg}\n`),
+    warn = stderrWarn,
   } = {},
 ) {
-  onExit(() => {
-    try {
-      fsImpl.rmSync(dirPath, { recursive: true, force: true });
-    } catch (err) {
-      warn(`[test-temp] failed to reap scratch dir ${dirPath}: ${err.message}`);
-    }
-  });
+  onExit(() => rmQuietly(dirPath, 'scratch dir', fsImpl, warn));
 }
 
 /**

package/.agents/scripts/lib/validation-evidence.js

@@ -265,6 +265,43 @@ export function recordPass(
   return record;
 }
 
+/**
+ * The content identity of a working tree, as an evidence `inputFingerprint`
+ * (Story #5278).
+ *
+ * `commitSha` is the wrong key for "have these inputs already been checked".
+ * Close's own base-sync moves HEAD immediately before the gates run, so every
+ * gate the worker paid for is re-run against a commit whose *content* the
+ * evidence already covers whenever the sync brought nothing in — the record
+ * is discarded as `sha-mismatch` and lint, typecheck and the suite are all
+ * paid for twice.
+ *
+ * `git rev-parse HEAD^{tree}` is the exact answer: the tree object id is a
+ * hash of the committed content and nothing else, so it is stable across a
+ * fast-forward, a rebase, an empty merge and a commit-message amend, and it
+ * differs the instant any tracked byte does. It deliberately ignores
+ * uncommitted changes for the same reason `commitSha` did — the gates run on
+ * a committed Story branch.
+ *
+ * Returns `null` when the tree cannot be read, which routes every caller to
+ * the pre-#5278 SHA-only behaviour rather than to a false match.
+ *
+ * @param {string} cwd Absolute worktree root.
+ * @param {Function} [gitSpawnFn] `(cwd, ...args) => { status, stdout }`.
+ * @returns {string|null} `tree:<oid>`, or `null` when unavailable.
+ */
+export function treeFingerprint(cwd, gitSpawnFn) {
+  if (typeof gitSpawnFn !== 'function') return null;
+  try {
+    const res = gitSpawnFn(cwd, 'rev-parse', 'HEAD^{tree}');
+    if (res?.status !== 0) return null;
+    const oid = String(res.stdout ?? '').trim();
+    return /^[0-9a-f]{40,64}$/.test(oid) ? `tree:${oid}` : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Decide whether a gate can be skipped given the current HEAD + command
  * config. Skip is granted only on full triple-match: gateName + commitSha +

package/.agents/scripts/lib/wave-runner/footprint.js

@@ -174,25 +174,106 @@ function isUnderTempRoot(path, tempRoot) {
  * narrowing the scrape can never co-dispatch a pair the declared comparison
  * would have caught.
  *
+ * Each path is returned **with the field it was scraped from** (Story #5265).
+ * "This pair collided on a path neither declared" is only half an
+ * explanation: the operator's next question is always *where did that path
+ * come from*, and until they can answer it they cannot tell an unpredicted
+ * edit target from a citation the guard read as one. The measured case is a
+ * gate script every Story merely **runs** in `verify[]` — attribution turns
+ * that from an unexplained serialisation into a one-glance verdict.
+ *
  * @param {object} story
  * @param {object} [options]
  * @param {string} [options.tempRoot='temp'] Resolved `project.paths.tempRoot`.
- * @returns {Set<string>}
+ * @returns {Map<string, Set<string>>} Path → the field label(s) that named it.
  */
 function storyEvidencePaths(story, { tempRoot = DEFAULT_TEMP_ROOT } = {}) {
-  const out = new Set();
-  for (const field of [story?.title, story?.body, story?.spec]) {
-    if (typeof field !== 'string') continue;
-    const scannable = field
-      .replace(PROVENANCE_FOOTER_RE, ' ')
-      .replace(MARKDOWN_LINK_URL_RE, ']()');
-    for (const [token] of scannable.matchAll(PROSE_PATH_RE)) {
-      if (!isUnderTempRoot(token, tempRoot)) out.add(token);
+  const out = new Map();
+  for (const [field, text] of attributedSegments(story)) {
+    for (const [token] of text.matchAll(PROSE_PATH_RE)) {
+      if (isUnderTempRoot(token, tempRoot)) continue;
+      const fields = out.get(token);
+      if (fields) fields.add(field);
+      else out.set(token, new Set([field]));
     }
   }
   return out;
 }
 
+/**
+ * A markdown section heading in a serialized Story body — the attribution
+ * grain (Story #5265).
+ *
+ * `body` alone would be a true but useless label: a Story body is the whole
+ * document, so every scraped path would report the same field. The section is
+ * where the distinction actually lives — a path under `## Changes` is a
+ * declaration restated, one under `## Verify` is a command line, one under
+ * `## Non-Goals` is explicitly *not* an edit target.
+ */
+const BODY_SECTION_RE = /^#{2,6}[ \t]+(\S.*?)[ \t]*$/gm;
+
+/**
+ * Strip the two token sources that are structurally incapable of naming an
+ * edit target. Applied to the whole field **before** segmentation, so the
+ * scanned text is byte-identical to what the pre-attribution scrape read and
+ * a stripped footer can never be mistaken for a section boundary.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function stripNonIntentTokens(text) {
+  return text
+    .replace(PROVENANCE_FOOTER_RE, ' ')
+    .replace(MARKDOWN_LINK_URL_RE, ']()');
+}
+
+/**
+ * Split a Story body into `[label, text]` segments at its `##` headings.
+ *
+ * The heading line stays with the section it opens rather than being consumed
+ * as a delimiter: a heading can itself name a path, and dropping that text
+ * would *narrow* the footprint — the one direction this layer must never move
+ * (Story #4875 / #5265 AC-8). Text before the first heading keeps the bare
+ * `body` label.
+ *
+ * @param {string} body
+ * @returns {Array<[string, string]>}
+ */
+function bodySegments(body) {
+  const out = [];
+  let cursor = 0;
+  let label = 'body';
+  for (const match of body.matchAll(BODY_SECTION_RE)) {
+    if (match.index > cursor)
+      out.push([label, body.slice(cursor, match.index)]);
+    label = `body:${match[1].trim()}`;
+    cursor = match.index;
+  }
+  out.push([label, body.slice(cursor)]);
+  return out;
+}
+
+/**
+ * Every scannable `[fieldLabel, text]` pair on a Story record: `title` and
+ * `spec` whole, `body` split by section.
+ *
+ * @param {object} story
+ * @returns {Array<[string, string]>}
+ */
+function attributedSegments(story) {
+  const out = [];
+  if (typeof story?.title === 'string') {
+    out.push(['title', stripNonIntentTokens(story.title)]);
+  }
+  if (typeof story?.body === 'string') {
+    out.push(...bodySegments(stripNonIntentTokens(story.body)));
+  }
+  if (typeof story?.spec === 'string') {
+    out.push(['spec', stripNonIntentTokens(story.spec)]);
+  }
+  return out;
+}
+
 /**
  * A Story's declared footprint **and** the evidence-widened one.
  *
@@ -203,15 +284,54 @@ function storyEvidencePaths(story, { tempRoot = DEFAULT_TEMP_ROOT } = {}) {
  * the scrape produced may be an artifact of how a body was worded. An operator
  * reading an unfilled slot needs to tell those apart.
  *
+ * `evidence` carries the third answer (Story #5265): *which field* produced
+ * each scraped path, so a collision can say where the token was written
+ * rather than only that nobody declared it.
+ *
  * @param {object} story
  * @param {object} [options]
- * @returns {{ declared: Set<string>, widened: Set<string> }}
+ * @returns {{ declared: Set<string>, widened: Set<string>, evidence: Map<string, Set<string>> }}
  */
 function storyFootprints(story, options) {
   const declared = storyFootprint(story);
+  const evidence = storyEvidencePaths(story, options);
   const widened = new Set(declared);
-  for (const path of storyEvidencePaths(story, options)) widened.add(path);
-  return { declared, widened };
+  for (const path of evidence.keys()) widened.add(path);
+  return { declared, widened, evidence };
+}
+
+/**
+ * The field labels that scraped `path` on one side — empty when that side
+ * **declared** it, because a declaration is not evidence and reporting the
+ * prose restatement of a declared path would read as if the scrape had caused
+ * the collision.
+ *
+ * @param {{ declared: Set<string>, evidence: Map<string, Set<string>> }} side
+ * @param {string} path
+ * @returns {string[]}
+ */
+function scrapedFields(side, path) {
+  if (side.declared.has(path)) return [];
+  return [...(side.evidence.get(path) ?? [])];
+}
+
+/**
+ * Per-path provenance for one colliding path (Story #5265): whether both
+ * sides declared it, and — when at least one side did not — the field labels
+ * the scrape found it in, unioned across the two sides and sorted.
+ *
+ * @param {object} fa
+ * @param {object} fb
+ * @param {string} path
+ * @param {boolean} declared
+ * @returns {{ path: string, declared: boolean, fields: string[] }}
+ */
+function attributePath(fa, fb, path, declared) {
+  const fields = new Set([
+    ...scrapedFields(fa, path),
+    ...scrapedFields(fb, path),
+  ]);
+  return { path, declared, fields: [...fields].sort() };
 }
 
 /**
@@ -269,12 +389,19 @@ function recordGlobs(hits, side) {
  * run for hours — and `resolve-stories.js` substitutes an UNKNOWN sentinel for
  * any body it cannot parse, so one malformed Story would make a run serial.
  *
+ * `attribution` (Story #5265) reports the same `paths`, one entry each, with
+ * the provenance a consumer needs to explain the withhold: `declared` says
+ * whether both sides named the path in `changes[]`, and `fields` names the
+ * field label(s) the scrape read it from otherwise (`title`, `spec`, or
+ * `body:<section>`). It is strictly additive — `paths` and `source` are
+ * unchanged, so no pair that collided before collides differently now.
+ *
  * @param {object} a
  * @param {object} b
  * @param {object} [options]
  * @param {boolean} [options.concreteOnly=false] Skip glob paths on both sides.
  * @param {string} [options.tempRoot]
- * @returns {{ paths: string[], source: string }|null}
+ * @returns {{ paths: string[], source: string, attribution: Array<{ path: string, declared: boolean, fields: string[] }> }|null}
  */
 export function detectCollision(
   a,
@@ -297,10 +424,36 @@ export function detectCollision(
     recordGlobs(hits, fb);
   }
   if (hits.size === 0) return null;
+  const paths = [...hits.keys()].sort();
   return {
-    paths: [...hits.keys()].sort(),
+    paths,
     source: [...hits.values()].some(Boolean)
       ? OVERLAP_SOURCES.DECLARED
       : OVERLAP_SOURCES.SCRAPED,
+    attribution: paths.map((path) =>
+      attributePath(fa, fb, path, hits.get(path)),
+    ),
   };
 }
+
+/**
+ * Render one collision's scraped-path provenance as a single operator-facing
+ * clause, or `''` when every colliding path was declared by both sides.
+ *
+ * Shared by every report that names a withhold so the tick's envelope note
+ * and plan-persist's predicted-serialisation table read identically — the two
+ * surfaces describe the same computation and an operator comparing them
+ * should not have to translate (Story #5265).
+ *
+ * @param {Array<{ path: string, declared: boolean, fields: string[] }>} attribution
+ * @returns {string}
+ */
+export function renderScrapeAttribution(attribution) {
+  const scraped = (Array.isArray(attribution) ? attribution : []).filter(
+    (entry) => Array.isArray(entry?.fields) && entry.fields.length > 0,
+  );
+  if (scraped.length === 0) return '';
+  return scraped
+    .map((entry) => `${entry.path} ← ${entry.fields.join(', ')}`)
+    .join('; ');
+}

package/.agents/scripts/lib/wave-runner/live-probe.js

@@ -264,7 +264,13 @@ export async function probeLiveState({
   self,
   warn,
 }) {
-  const stories = await fetchStories(provider, ids);
+  // `allowUnlabelled` deliberately: the `agent::*` guard is an ADMISSION check
+  // at the entry resolution, where an operator names ids, and this is a
+  // per-beat REPORT on work already admitted. A Story dispatched a moment ago
+  // is legitimately unlabelled until `single-story-init.js` flips it — the
+  // init window this probe models explicitly — and refusing it here would fail
+  // a healthy beat mid-run over a Story the run already accepted.
+  const stories = await fetchStories(provider, ids, { allowUnlabelled: true });
   const nativeEdges = native
     ? await readNativeEdges({ provider, stories, owner, repo })
     : new Map();

package/.agents/scripts/lib/wave-runner/ready-set.js

@@ -301,7 +301,7 @@ function reservesConcretePath(held, candidate, options = {}) {
  * @returns {{
  *   selected: StoryRecord[],
  *   withheldByInFlight: Array<{id: number, blockedBy: number}>,
- *   footprintWithholds: Array<{id: number, blockedBy: number, scope: string, source: string, paths: string[], enforced: boolean}>,
+ *   footprintWithholds: Array<{id: number, blockedBy: number, scope: string, source: string, paths: string[], attribution: object[], enforced: boolean}>,
  *   guardMode: 'enforce'|'advisory'
  * }}
  *   `selected` is the dispatch set: a subset of `stories`, ascending by id,