mandrel 2.23.0 → 2.25.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js

@@ -11,7 +11,7 @@
  * Story is already `agent::done`, so confirm short-circuits `noop` and the
  * capture's `action === 'done'` gate never opens).
  *
- * This module folds all four steps into one phase both landing surfaces
+ * This module folds every such step into one phase both landing surfaces
  * reach — the in-close wait (`phases/confirm-merge.js`) and the standalone
  * `single-story-confirm-merge.js` CLI — so the two paths cannot diverge and
  * "landed" means the whole tail ran.
@@ -45,6 +45,7 @@ import {
   planFastForward as defaultPlanFastForward,
 } from '../../git-cleanup/phases/fast-forward.js';
 import { reassertStatusColumn as defaultReassertStatusColumn } from '../../reassert-status-column.js';
+import { releaseStoryLease as defaultReleaseStoryLease } from '../../single-story-lease-guard.js';
 import { captureStoryFollowUps as defaultCaptureStoryFollowUps } from '../../story-follow-ups.js';
 
 /**
@@ -241,6 +242,54 @@ async function stepTempPurge({ storyId, config, purgeStoryTempArtifactsFn }) {
   return { ok: errors.length === 0, detail: errors.join('; ') || null };
 }
 
+/**
+ * Release the Story's assignee-lease now that the merge is confirmed
+ * (Story #4860).
+ *
+ * The close used to release here-ish — immediately after the PR was opened
+ * and armed, before the merge wait ran — so a Story's ticket read *unassigned*
+ * for the entire window its PR was open, and indefinitely on the
+ * operator-merge path where a human owns the land. The claim is the only
+ * ticket-visible record of who owns in-flight work, so dropping it at PR
+ * creation is dropping it at exactly the wrong moment.
+ *
+ * It lives in the tail rather than in either landing surface because the tail
+ * is the one seam **both** reach — the in-close merge wait
+ * (`phases/confirm-merge.js`) and the standalone
+ * `single-story-confirm-merge.js` CLI. Homing it anywhere else re-opens the
+ * surface divergence this module exists to close.
+ *
+ * Idempotent by construction: `releaseStoryLease` no-ops when the resolved
+ * operator is no longer the recorded owner, so a re-run (or the belated
+ * manual confirm that backfills an already-`agent::done` Story) reports the
+ * no-op reason rather than yanking a claim someone else has since taken.
+ *
+ * A `released: false` no-op is **not** a step failure: an already-released
+ * ticket is the desired end state, and reporting it as `false` would train
+ * readers to ignore the field. Only a throw — an unreachable API, an
+ * unresolvable operator identity — degrades the step, and like every tail
+ * step that degrades the report, never the land.
+ */
+async function stepLeaseRelease({
+  storyId,
+  provider,
+  config,
+  progress,
+  releaseStoryLeaseFn,
+}) {
+  const outcome = await releaseStoryLeaseFn({ provider, storyId, config });
+  progress?.(
+    'POST-LAND',
+    outcome?.released
+      ? `🔓 Story #${storyId} lease released (merge confirmed).`
+      : `⏭  Story #${storyId} lease not released (${outcome?.reason ?? 'unknown'}).`,
+  );
+  return {
+    ok: true,
+    detail: outcome?.released ? null : (outcome?.reason ?? null),
+  };
+}
+
 /**
  * Run the whole post-land tail. Never throws.
  *
@@ -280,7 +329,8 @@ async function stepTempPurge({ storyId, config, purgeStoryTempArtifactsFn }) {
  * @param {Function} [args.executeFastForwardFn]    Test seam.
  * @param {Function} [args.acquireLockWithWaitFn]   Test seam.
  * @param {Function} [args.purgeStoryTempArtifactsFn] Test seam.
- * @returns {Promise<{ followUps: boolean, statusResync: boolean, refCleanup: boolean, baseFastForward: boolean, tempPurge: boolean, details: Record<string, string|null> }>}
+ * @param {Function} [args.releaseStoryLeaseFn]     Test seam.
+ * @returns {Promise<{ followUps: boolean, statusResync: boolean, refCleanup: boolean, baseFastForward: boolean, tempPurge: boolean, leaseRelease: boolean, details: Record<string, string|null> }>}
  */
 export async function runPostLandTail({
   storyId,
@@ -299,6 +349,7 @@ export async function runPostLandTail({
   executeFastForwardFn = defaultExecuteFastForward,
   acquireLockWithWaitFn = defaultAcquireLockWithWait,
   purgeStoryTempArtifactsFn = defaultPurgeStoryTempArtifacts,
+  releaseStoryLeaseFn = defaultReleaseStoryLease,
 }) {
   progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
 
@@ -401,18 +452,35 @@ export async function runPostLandTail({
     { name: 'temp purge', progress },
   );
 
+  // Story #4860 — the merge is confirmed, so the operator's claim on this
+  // Story has finally done its job. Released here rather than at PR creation
+  // so the ticket stays assigned for the whole time its PR is open.
+  const leaseRelease = await step(
+    () =>
+      stepLeaseRelease({
+        storyId,
+        provider,
+        config,
+        progress,
+        releaseStoryLeaseFn,
+      }),
+    { name: 'lease release', progress },
+  );
+
   const tail = {
     followUps: followUps.ok,
     statusResync: statusResync.ok,
     refCleanup: refCleanup.ok,
     baseFastForward: baseFastForward.ok,
     tempPurge: tempPurge.ok,
+    leaseRelease: leaseRelease.ok,
     details: {
       followUps: followUps.detail,
       statusResync: statusResync.detail,
       refCleanup: refCleanup.detail,
       baseFastForward: baseFastForward.detail,
       tempPurge: tempPurge.detail,
+      leaseRelease: leaseRelease.detail,
     },
   };
   const degraded = Object.entries(tail)

package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js

@@ -1,8 +1,9 @@
 /**
- * phases/pull-request.js — open or reuse the PR for a standalone Story.
+ * phases/pull-request.js — open, reuse, or decline to open the PR for a
+ * standalone Story.
  *
- * Probes for an existing open PR with `head = storyBranch`; creates one if
- * none exists. Returns the PR URL.
+ * Probes for an existing PR with `head = storyBranch`; creates one if none
+ * exists. Returns `{ url, alreadyMerged, created }`.
  *
  * `gh pr view --head` is not available on all `gh` versions, so we probe
  * with `gh pr list --head <branch>` and fall back to `gh pr create`.
@@ -13,17 +14,99 @@
  * error classification, timeout handling, and JSON parsing surface
  * instead of carrying its own `execFileSync('gh', …)` plumbing.
  *
+ * ## An already-merged PR is not an absent PR (Story #4873)
+ *
+ * The probe used to ask for `--state open` only. On the recovery path that is
+ * a false negative with teeth: a resumed close pushes the branch, the push
+ * turns the checks green, armed auto-merge lands the ORIGINAL PR server-side,
+ * and the resumed close then sees no OPEN PR on the head — so it opened a
+ * SECOND PR against a branch that is now byte-identical to base and
+ * squash-merged a zero-file commit onto `main`. Both halves of that are now
+ * closed:
+ *
+ *   1. The probe reads `--state all` and reports a MERGED PR on this head as
+ *      the outcome (`alreadyMerged: true`), so the caller lands on the merge
+ *      that already happened instead of manufacturing a new one. An OPEN PR
+ *      still wins over a merged one — a re-opened head is a live PR.
+ *   2. Creation is REFUSED outright when the head-versus-base diff contains no
+ *      files. An empty diff means there is nothing to merge, so a PR opened on
+ *      it can only ever produce an empty commit.
+ *
+ * The empty-diff guard fails **open**, not closed: `computeChangeSet` returns
+ * `files: null` when it cannot enumerate the diff at all, and absence of
+ * evidence must never block a legitimate PR — only a positively-observed empty
+ * file list refuses.
+ *
  * The function still accepts an injected `gh` facade so tests can wire
  * a fake without spawning real children.
  */
 
 import { gh as defaultGh } from '../../../gh-exec.js';
 import { Logger } from '../../../Logger.js';
+import { computeChangeSet as defaultComputeChangeSet } from '../../change-set.js';
 import { normalizePrTitle } from './normalize-pr-title.js';
 
 /**
- * Probe for an existing open PR with `head = storyBranch`; create one if
- * none exists. Returns the PR URL. Exported for testing.
+ * Pick the PR this head branch should resolve to from a `gh pr list
+ * --state all` projection. A live PR always wins; otherwise the first MERGED
+ * PR is the outcome to report. A head whose only PRs were CLOSED without
+ * merging resolves to nothing — there is a new PR to open.
+ *
+ * A row carrying a url but no recognizable `state` reads as live, not as
+ * nothing: the projection this phase asks for always includes `state`, so an
+ * absent one means an older/other `gh`, and the old `--state open` probe
+ * treated every returned row as a reusable open PR. Guessing "no PR" there is
+ * the failure mode with teeth — it opens a duplicate.
+ *
+ * Pure, and module-private on purpose: `ensurePullRequestWith` is the only
+ * caller and the only surface worth pinning, so the precedence is asserted
+ * through it rather than through a test-only export the production
+ * dead-export ratchet would then flag.
+ *
+ * @param {Array<{url?: string, state?: string, mergedAt?: string}>} rows
+ * @returns {{ url: string, state: 'OPEN'|'MERGED' }|null}
+ */
+function pickHeadPullRequest(rows) {
+  if (!Array.isArray(rows)) return null;
+  let merged = null;
+  for (const row of rows) {
+    const url = String(row?.url ?? '').trim();
+    if (!url) continue;
+    const state = String(row?.state ?? '').toUpperCase();
+    if (state === 'MERGED' || (state !== 'OPEN' && row?.mergedAt)) {
+      merged ??= { url, state: 'MERGED' };
+      continue;
+    }
+    if (state === 'CLOSED') continue;
+    return { url, state: 'OPEN' };
+  }
+  return merged;
+}
+
+/**
+ * Enumerate the head-versus-base diff and report whether it is positively
+ * empty. `null` (diff unenumerable) is NOT empty — see the module header.
+ *
+ * The diff is taken against `origin/<baseBranch>` when that ref resolves,
+ * because the local base ref can trail the remote by exactly the merge that
+ * makes this diff empty — the very state the guard exists to catch. It falls
+ * back to the local ref, and finally to "unknown", when the remote ref cannot
+ * be enumerated.
+ *
+ * @returns {{ empty: boolean, baseRef: string|null }}
+ */
+function probeEmptyDiff({ cwd, baseBranch, storyBranch, computeChangeSet }) {
+  for (const baseRef of [`origin/${baseBranch}`, baseBranch]) {
+    const set = computeChangeSet({ baseRef, headRef: storyBranch, cwd });
+    if (!set.enumerated) continue;
+    return { empty: (set.files ?? []).length === 0, baseRef };
+  }
+  return { empty: false, baseRef: null };
+}
+
+/**
+ * Probe for an existing PR with `head = storyBranch`; create one if none
+ * exists. Exported for testing.
  *
  * @param {{
  *   cwd: string,
@@ -32,9 +115,10 @@ import { normalizePrTitle } from './normalize-pr-title.js';
  *   storyBranch: string,
  *   baseBranch: string,
  *   gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
+ *   computeChangeSetFn?: typeof defaultComputeChangeSet,
  *   progress?: (tag: string, msg: string) => void,
  * }} args
- * @returns {Promise<string>}
+ * @returns {Promise<{ url: string, alreadyMerged: boolean, created: boolean }>}
  */
 export async function ensurePullRequestWith({
   cwd: _cwd,
@@ -43,6 +127,7 @@ export async function ensurePullRequestWith({
   storyBranch,
   baseBranch,
   gh = defaultGh,
+  computeChangeSetFn = defaultComputeChangeSet,
   progress = () => {},
 }) {
   // `cwd` is preserved on the call signature for backwards compatibility
@@ -51,22 +136,26 @@ export async function ensurePullRequestWith({
   // before invoking the phase, so the effective cwd matches the legacy
   // `execFileSync('gh', …, { cwd })` shape.
   try {
-    // `gh pr list --head <branch> --state open --json url` returns a
-    // JSON array of `{ url }` rows; an empty array means no open PR on
-    // this head. We pick the first entry's URL (matching the legacy
-    // `-q '.[0].url // empty'` projection on our side) so the typed
-    // `gh.pr.list` facade can stay generic.
+    // `gh pr list --head <branch> --state all --json url,state,mergedAt`
+    // returns a JSON array of rows; an empty array means this head has never
+    // had a PR. `--state all` (not `open`) is load-bearing — see the module
+    // header's duplicate-empty-PR note.
     const rows = await gh.pr.list(
-      ['--head', storyBranch, '--state', 'open'],
-      ['url'],
+      ['--head', storyBranch, '--state', 'all'],
+      ['url', 'state', 'mergedAt'],
     );
-    const existing =
-      Array.isArray(rows) && rows.length > 0
-        ? String(rows[0]?.url ?? '').trim()
-        : '';
-    if (existing) {
-      progress('PR', `Reusing existing PR: ${existing}`);
-      return existing;
+    const existing = pickHeadPullRequest(rows);
+    if (existing?.state === 'OPEN') {
+      progress('PR', `Reusing existing PR: ${existing.url}`);
+      return { url: existing.url, alreadyMerged: false, created: false };
+    }
+    if (existing?.state === 'MERGED') {
+      progress(
+        'PR',
+        `✅ PR for ${storyBranch} is already MERGED: ${existing.url} — ` +
+          'reporting that outcome instead of opening a second PR.',
+      );
+      return { url: existing.url, alreadyMerged: true, created: false };
     }
   } catch (err) {
     // `gh pr list` failure is recoverable — fall through to create. Log
@@ -76,6 +165,25 @@ export async function ensurePullRequestWith({
     );
   }
 
+  // Nothing to merge → nothing to open. Refused before `gh pr create` so the
+  // failure names the empty diff rather than surfacing later as a zero-file
+  // squash commit on the base branch.
+  const emptyDiff = probeEmptyDiff({
+    cwd: _cwd ?? process.cwd(),
+    baseBranch,
+    storyBranch,
+    computeChangeSet: computeChangeSetFn,
+  });
+  if (emptyDiff.empty) {
+    throw new Error(
+      `[single-story-close] refusing to open a pull request for ${storyBranch}: ` +
+        `the head-versus-base diff (${emptyDiff.baseRef}...${storyBranch}) contains no files. ` +
+        'An empty diff has nothing to merge, and a PR opened on it can only squash an empty ' +
+        'commit onto the base branch. If the work already landed, confirm the merge instead: ' +
+        `node .agents/scripts/single-story-confirm-merge.js --story ${storyId}`,
+    );
+  }
+
   progress('PR', `Opening PR for ${storyBranch} → ${baseBranch}...`);
   // The repo squash-merges and GitHub uses the PR title as the squash
   // subject on `main`. A raw human issue title is not a Conventional
@@ -110,7 +218,7 @@ export async function ensurePullRequestWith({
     ]);
     const url = (createResult?.stdout ?? '').trim();
     progress('PR', `✅ Opened: ${url}`);
-    return url;
+    return { url, alreadyMerged: false, created: true };
   } catch (err) {
     throw new Error(
       `[single-story-close] \`gh pr create\` failed: ${err?.message ?? err}`,

package/.agents/scripts/lib/orchestration/single-story-close/runner.js

@@ -12,6 +12,7 @@ import { createProvider } from '../../provider-factory.js';
 import { flipLabelAndNotify } from '../../single-story/story-merged-notify.js';
 import { WorktreeManager } from '../../worktree-manager.js';
 import { runCodeReview as runCodeReviewDefault } from '../code-review.js';
+import { resolveRunScopedConfig } from '../run-scoped-config.js';
 import { releaseStoryLease } from '../single-story-lease-guard.js';
 import {
   buildTerminalEnvelope,
@@ -144,6 +145,7 @@ async function runPrePushPhases({
   worktreePath,
   config,
   baseBranch,
+  baseConfirmed,
   storyBranch,
   storyId,
   provider,
@@ -185,6 +187,7 @@ async function runPrePushPhases({
       cwd,
       worktreePath,
       baseBranch,
+      baseConfirmed,
       storyBranch,
       storyId,
       provider,
@@ -210,7 +213,7 @@ async function openAndReviewPr({
   setPhase('push');
   pushStoryBranch({ cwd, storyBranch, gitSync, progress });
   setPhase('pull-request');
-  const prUrl = await ensurePullRequestWith({
+  const { url: prUrl, alreadyMerged } = await ensurePullRequestWith({
     cwd,
     storyId,
     storyTitle: story.title,
@@ -220,6 +223,13 @@ async function openAndReviewPr({
     progress,
   });
   const prNumber = parsePrNumber(prUrl);
+  // Story #4873 — the head's PR already merged (an armed PR that landed while
+  // a previous close invocation was between phases). There is nothing left to
+  // review and nothing left to arm; the confirm phase probes the PR, observes
+  // MERGED, and lands the Story on the merge that actually happened.
+  if (alreadyMerged) {
+    return { prUrl, prNumber, alreadyMerged: true };
+  }
   setPhase('code-review');
   const reviewOutcome = await runStoryScopeReview({
     cwd,
@@ -245,7 +255,7 @@ async function openAndReviewPr({
         'Auto-merge was not enabled. Remediate the findings posted to the PR and re-run `/deliver`.',
     );
   }
-  return { prUrl, prNumber };
+  return { prUrl, prNumber, alreadyMerged: false };
 }
 
 async function releaseLease({
@@ -353,8 +363,8 @@ function closeResult({
     note: waitedForMerge
       ? 'Close-and-land: PR merge confirmed. Story flipped agent::closing → agent::done, the issue closed (confirmStoryMerged), and the post-land tail ran.'
       : autoMergeEnabled
-        ? 'PR open against baseBranch with auto-merge enabled. Story rests at agent::closing (issue stays OPEN). GitHub will squash-merge when required checks pass; run single-story-confirm-merge.js after the merge confirms to flip agent::done and close the issue (the Closes #<id> footer also auto-closes it).'
-        : 'PR open against baseBranch. Story rests at agent::closing (issue stays OPEN). Operator merges via GitHub UI; run single-story-confirm-merge.js after the merge confirms to flip agent::done (the Closes #<id> footer also auto-closes the issue).',
+        ? 'PR open against baseBranch with auto-merge enabled. Story rests at agent::closing (issue stays OPEN and assigned to the operator). GitHub will squash-merge when required checks pass; run single-story-confirm-merge.js after the merge confirms to flip agent::done, release the lease, and close the issue (the Closes #<id> footer also auto-closes it).'
+        : 'PR open against baseBranch. Story rests at agent::closing (issue stays OPEN and assigned to the operator). Operator merges via GitHub UI; run single-story-confirm-merge.js after the merge confirms to flip agent::done and release the lease (the Closes #<id> footer also auto-closes the issue).',
   };
 }
 
@@ -443,7 +453,6 @@ async function runClosePipeline({
   const startedAtMs = Date.now();
   const config = injectedConfig || resolveConfig({ cwd: options.cwd });
   const provider = injectedProvider || createProvider(config);
-  const baseBranch = config.project?.baseBranch ?? 'main';
   const storyBranch = getStoryBranch(options.storyId);
 
   progress('INIT', `Closing standalone Story #${options.storyId}...`);
@@ -462,6 +471,22 @@ async function runClosePipeline({
     );
   }
 
+  // Story #4891 — the base branch this run was SEEDED from, read back off the
+  // run's `story-init` receipt rather than re-resolved from a config file that
+  // may have changed during the whole implementation window. Throws (fail
+  // closed, naming both values) when the pin and current config disagree —
+  // deliberately here, before the gate chain, format-autofix and base-sync,
+  // so a wrong base is never merged into the Story branch. `baseConfirmed`
+  // gates the base-merge remediation advice further down.
+  const { values: runScoped, confirmed: baseConfirmed } =
+    await resolveRunScopedConfig({
+      provider,
+      storyId: options.storyId,
+      config,
+      progress,
+    });
+  const baseBranch = runScoped.baseBranch;
+
   const worktreePath = resolveWorktreePath({
     cwd: options.cwd,
     config,
@@ -483,6 +508,7 @@ async function runClosePipeline({
         ...options,
         config,
         baseBranch,
+        baseConfirmed,
         storyBranch,
         provider,
         worktreePath,
@@ -493,7 +519,7 @@ async function runClosePipeline({
     leaseArgs,
   );
 
-  const { prUrl, prNumber } = await releaseLeaseOnBlock(
+  const { prUrl, prNumber, alreadyMerged } = await releaseLeaseOnBlock(
     () =>
       openAndReviewPr({
         cwd: options.cwd,
@@ -527,20 +553,31 @@ async function runClosePipeline({
     WorktreeManager,
   });
   setPhase('auto-merge');
+  // An already-merged head PR (Story #4873) has nothing to arm — `gh pr merge`
+  // against it fails, which would report the arm as a fault and block a Story
+  // whose work is already on the base branch. Skip the arm and let the confirm
+  // phase observe the merge that happened.
   const {
     autoMergeEnabled,
     autoMergeReason,
     localCleanupDeferred,
     directMerged,
-  } = await runAutoMergePhase({
-    cwd: options.cwd,
-    prNumber,
-    prUrl,
-    noAutoMerge: options.noAutoMerge,
-    autoMergePolicy: getCiDelivery(config).autoMerge,
-    gh: injectedGh,
-    progress,
-  });
+  } = alreadyMerged
+    ? {
+        autoMergeEnabled: true,
+        autoMergeReason: null,
+        localCleanupDeferred: false,
+        directMerged: false,
+      }
+    : await runAutoMergePhase({
+        cwd: options.cwd,
+        prNumber,
+        prUrl,
+        noAutoMerge: options.noAutoMerge,
+        autoMergePolicy: getCiDelivery(config).autoMerge,
+        gh: injectedGh,
+        progress,
+      });
   await flipLabelAndNotify({
     provider,
     notifyFn: injectedNotify,
@@ -552,7 +589,18 @@ async function runClosePipeline({
     config,
     progress,
   });
-  const leaseReleased = await releaseLease(leaseArgs);
+  // Story #4860 — the clean-path lease release USED to sit here, immediately
+  // after the arm and the `agent::closing` flip. That dropped the operator's
+  // claim the moment the PR opened, so a ticket read unassigned for the whole
+  // time its PR was in flight — and forever on the operator-merge path, where
+  // nothing downstream ever re-claimed it. The release now belongs to the
+  // post-land tail, which runs only on a CONFIRMED merge and which both
+  // landing surfaces reach. Every non-merged ending below — the
+  // `merge.unlanded` block, an exhausted wait budget, `--no-wait-merge`,
+  // `--no-auto-merge` — deliberately RETAINS the claim: the PR is open and the
+  // work still has an owner. The only releases that survive here are
+  // `releaseLeaseOnBlock`'s two throwing exits above, which fire before the PR
+  // is ever armed (Story #4257's hand-off property).
 
   // Close-and-land (Story #4428; default since `delivery.routing.closeAndLand`
   // — Story #4539): poll the just-armed PR to merge confirmation, or block
@@ -625,7 +673,11 @@ async function runClosePipeline({
       autoMergeEnabled,
       autoMergeReason,
       worktreeReaped,
-      leaseReleased,
+      // Story #4860 — the release is a post-land tail step now, so the tail's
+      // own per-step boolean IS the answer. A wait that ended anything other
+      // than landed never ran the tail, and correctly reports `false`: the
+      // claim is still held, by design.
+      leaseReleased: waitOutcome.tail?.leaseRelease === true,
       localCleanupDeferred,
       directMerged,
       waitedForMerge: true,
@@ -663,7 +715,10 @@ async function runClosePipeline({
     autoMergeEnabled,
     autoMergeReason,
     worktreeReaped,
-    leaseReleased,
+    // Story #4860 — this is the no-wait ending: the PR is open and a human
+    // owns the merge, so the Story stays assigned until the confirm-merge
+    // surface lands it and runs the tail.
+    leaseReleased: false,
     localCleanupDeferred,
     directMerged,
   });

package/.agents/scripts/lib/reserved-test-ids.js

@@ -0,0 +1,77 @@
+/**
+ * lib/reserved-test-ids.js — the framework's one declaration of which
+ * Epic / Story ids are **synthetic** (Story #4892).
+ *
+ * The band `999000–999999` has been reserved for test fixtures since the
+ * post-test temp reaper shipped, but it lived as a private regexp inside
+ * `cleanup-repo-test-temp.js` (`/^epic-999\d{3}$/`) and nothing else could
+ * consult it. Two independent surfaces need the same rule, and spelling it
+ * twice is how they would drift:
+ *
+ *   1. **Write side.** A test that spawns a real CLI at the repository root
+ *      inherits the real state directory, so its fixture telemetry can land
+ *      in the operator's live `temp/` signals tree. The post-run guard in
+ *      `check-test-temp-hygiene.js` fails the run when a stream file owned by
+ *      a reserved id survives there.
+ *   2. **Read side.** The retro composer renders the distinct Stories a
+ *      friction bucket spans as recurrence evidence in a body that is filed
+ *      as a real GitHub issue. A reserved id is synthetic by construction, so
+ *      it can never be resolved to a real issue and must never be published
+ *      as evidence (issue #4870 named `#999999` as a contributing Story).
+ *
+ * Deliberately dependency-free: the write side is a CLI guard and the read
+ * side is a pure composer, so the shared rule must not drag config, fs, or
+ * git resolution into either.
+ */
+
+/** First id in the reserved test-fixture band. */
+const RESERVED_TEST_ID_MIN = 999000;
+
+/** Last id in the reserved test-fixture band. */
+const RESERVED_TEST_ID_MAX = 999999;
+
+/**
+ * Human-readable band, for guard failure messages that have to tell an
+ * operator which ids they may not use for real work.
+ */
+export const RESERVED_TEST_ID_BAND = `${RESERVED_TEST_ID_MIN}–${RESERVED_TEST_ID_MAX}`;
+
+/**
+ * Is `id` inside the reserved test-fixture band?
+ *
+ * Exact-band membership, because this is the predicate the temp reaper and
+ * the pollution guard share: both classify an on-disk directory that a test
+ * created, and over-reaching (treating every large id as reserved) would let
+ * one of them delete or condemn a directory the band never claimed.
+ *
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isReservedTestId(id) {
+  return (
+    Number.isInteger(id) &&
+    id >= RESERVED_TEST_ID_MIN &&
+    id <= RESERVED_TEST_ID_MAX
+  );
+}
+
+/**
+ * May `id` be published as ticket evidence in operator-visible output?
+ *
+ * The floor is the reserved band, not the band itself: an id at or above
+ * `RESERVED_TEST_ID_MIN` is synthetic by construction (the framework reserves
+ * that space for fixtures, and no repository has minted that many issues), so
+ * nothing at or beyond the floor can be resolved to a real issue. A
+ * non-integer or non-positive id is not a ticket reference at all.
+ *
+ * This is a plausibility bound, not an existence probe: it is the strongest
+ * statement a caller with no ticket-provider access can make, and it is what
+ * keeps the invariant true at every call site instead of only where somebody
+ * remembered to wire a probe.
+ *
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isPublishableTicketId(id) {
+  return Number.isInteger(id) && id > 0 && id < RESERVED_TEST_ID_MIN;
+}