mandrel 1.87.0 → 1.89.0

package/.agents/scripts/lib/signals/span-tree.js

@@ -51,20 +51,21 @@
  */
 
 function tsOf(evt) {
-  // Schema accepts both `ts` (canonical) and `timestamp` (legacy).
-  return evt?.ts ?? evt?.timestamp ?? null;
+  // Canonical envelope only (Epic #4406) — the legacy `timestamp` alias
+  // was deleted from every writer in the same PR.
+  return evt?.ts ?? null;
 }
 
 function epicOf(evt) {
-  return evt?.epic ?? evt?.epicId ?? null;
+  return evt?.epicId ?? null;
 }
 
 function storyOf(evt) {
-  return evt?.story ?? evt?.storyId ?? null;
+  return evt?.storyId ?? null;
 }
 
 function taskOf(evt) {
-  return evt?.task ?? evt?.taskId ?? null;
+  return evt?.taskId ?? null;
 }
 
 /**

package/.agents/scripts/lib/story-plan.js

@@ -193,6 +193,7 @@ export async function loadBodyTemplate(projectRoot) {
  *   bodyTemplate: string,
  *   duplicateCandidates: Array<object>,
  *   techStack?: string|null,
+ *   corpusContext?: { docsDigest: string|null, relevantSections: Array<object> }|null,
  *   maxResults?: number,
  * }} opts
  */
@@ -203,6 +204,7 @@ export function buildContextEnvelope({
   bodyTemplate,
   duplicateCandidates,
   techStack = null,
+  corpusContext = null,
   maxResults = DEFAULT_DUPLICATE_MAX_RESULTS,
 }) {
   return {
@@ -218,6 +220,7 @@ export function buildContextEnvelope({
       candidates: duplicateCandidates,
     },
     techStack,
+    corpusContext,
     deliverContract: {
       workflow: '.agents/workflows/helpers/single-story-deliver.md',
       requiredLabels: ['type::story', `persona::${persona}`],

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

@@ -425,7 +425,13 @@ export function planTick(state, records, inFlight) {
       inFlight.length === 0
     ) {
       signals.push({
+        // `index` is what the perf-aggregator's `bucketWaves` keys on to
+        // bracket a wave's wall-clock (Epic #4406 / Story #4413). Without
+        // it every wave-start collapsed to NaN and the waveParallelism
+        // table rendered structurally empty. The continuous ready-set
+        // scheduler runs a single logical wave, so `index: 0`.
         kind: 'wave-start',
+        index: 0,
         stories: records.map((s) => ({ id: s.id, title: s.title })),
       });
     }
@@ -443,7 +449,7 @@ export function planTick(state, records, inFlight) {
     nextAction = { kind: 'observe', waitingOn };
   } else if (allDone) {
     // Every Story is done and nothing is in flight: the run is complete.
-    signals.push({ kind: 'wave-complete' });
+    signals.push({ kind: 'wave-complete', index: 0 });
     nextAction = { kind: 'epic-complete' };
   } else {
     // Ready set empty, nothing in flight, but not all Stories are done — a
@@ -739,7 +745,9 @@ function defaultSignalEmit(epicId, ctx) {
   return async (signal) => {
     await appendEpicSignal({
       epicId,
-      signal: { ts: new Date().toISOString(), epic: epicId, ...signal },
+      // Canonical envelope (Epic #4406 / Story #4413): the single
+      // `epicId` key — the legacy `epic` alias is gone.
+      signal: { ts: new Date().toISOString(), epicId, ...signal },
       config: ctx?.config,
     });
   };

package/.agents/scripts/lifecycle-emit.js

@@ -130,14 +130,27 @@ export function parseArgv(argv) {
 }
 
 /**
- * Build the bus emit payload from parsed argv. `event` is consumed.
- * `--epic` is mapped to `epicId` (integer). All other flags are
- * mapped from kebab-case to camelCase with light value coercion.
+ * Argv keys that are runtime OPTIONS consumed by `main()` /
+ * `runLifecycleEmit()` directly rather than forwarded into the emitted
+ * bus payload. `--headless` (Story #4427) is the first member: every
+ * lifecycle event schema declares `additionalProperties: false`, so a
+ * flag that selects delivery-run behavior (rather than describing the
+ * event itself) would fail schema validation if it leaked into the
+ * payload.
+ */
+const RUNTIME_OPTION_KEYS = Object.freeze(['event', 'headless']);
+
+/**
+ * Build the bus emit payload from parsed argv. `event` and `headless`
+ * (see `RUNTIME_OPTION_KEYS`) are consumed as runtime options, not
+ * payload fields. `--epic` is mapped to `epicId` (integer). All other
+ * flags are mapped from kebab-case to camelCase with light value
+ * coercion.
  */
 export function buildPayload(parsed) {
   const payload = {};
   for (const [key, raw] of Object.entries(parsed)) {
-    if (key === 'event') continue;
+    if (RUNTIME_OPTION_KEYS.includes(key)) continue;
     if (key === 'epic') {
       const n = Number.parseInt(raw, 10);
       if (!Number.isInteger(n) || n < 1) {
@@ -261,11 +274,16 @@ export async function emitBlockedSignal({
       config,
       signal: {
         kind: 'friction',
+        ts: new Date().toISOString(),
+        epicId,
+        category: 'lifecycle-listener-failure',
+        emitter: { tool: 'lifecycle-emit.js' },
         severity: 'high',
         event,
-        message: `lifecycle-emit: ${event} produced failed listener classification(s): ${reasons}`,
-        outcomes: failedOutcomes,
-        timestamp: new Date().toISOString(),
+        details: {
+          message: `lifecycle-emit: ${event} produced failed listener classification(s): ${reasons}`,
+          outcomes: failedOutcomes,
+        },
       },
     });
   } catch (err) {
@@ -321,6 +339,11 @@ export async function emitBlockedSignal({
  *   alongside an injected `bus` (when the caller owns listener wiring) —
  *   lets a test inject a bus + a chain carrying a `failed`-classifying
  *   listener to exercise the non-zero-exit path without the real roster.
+ * @param {boolean} [opts.headless] Explicit must-land signal (Story
+ *   #4427), forwarded to `buildDefaultListenerChain({ headless })` (and
+ *   from there to `MergeWatcher`) when this call constructs the default
+ *   chain. Defaults to `false` — attended-mode behavior is unchanged.
+ *   Ignored when the caller injects its own `bus`/`chain`.
  *
  * @returns {Promise<{ event: string, payload: object, seqId: number,
  *   outcomes: Array<object>, failed: boolean }>} The `outcomes[]` array
@@ -340,6 +363,7 @@ export async function runLifecycleEmit({
   config,
   emitBlockedSignalFn = emitBlockedSignal,
   chain: injectedChain,
+  headless = false,
 } = {}) {
   if (typeof event !== 'string' || event.length === 0) {
     throw new Error('lifecycle-emit: --event is required');
@@ -404,6 +428,7 @@ export async function runLifecycleEmit({
       checkpointer: resolvedCheckpointer,
       config: resolvedConfig,
       logger,
+      headless,
     });
   }
   const { seqId } = await targetBus.emit(event, payload ?? {});
@@ -464,7 +489,13 @@ async function main() {
   }
   const event = parsed.event;
   const payload = buildPayload(parsed);
-  const out = await runLifecycleEmit({ event, payload });
+  // `--headless true` is a runtime option (Story #4427), not a payload
+  // field — see RUNTIME_OPTION_KEYS. Threaded explicitly through
+  // runLifecycleEmit → buildDefaultListenerChain → MergeWatcher so the
+  // epic-path must-land terminal step reads a caller-supplied input
+  // rather than an ambient global.
+  const headless = parsed.headless === 'true';
+  const out = await runLifecycleEmit({ event, payload, headless });
   process.stdout.write(`${JSON.stringify(out)}\n`);
   // Exit non-zero when any listener classification came back `failed` so
   // the workflow's "re-run on non-zero" loop closes the partial-finalize

package/.agents/scripts/providers/github/issues.js

@@ -150,6 +150,14 @@ export class IssuesGateway {
   /**
    * List Epic-typed issues. Filter shape preserved from the old code.
    *
+   * `filters.pageCap` / `filters.perPage` pass through to `paginateRest`
+   * so a caller that only needs a bounded shortlist (e.g. the
+   * standalone-Story corpus lookup in `planning-corpus.js`, which ranks
+   * candidates down to a top-5 shortlist) can cap the scan instead of
+   * inheriting the default 50-page / 5000-item ceiling. Omitted, both
+   * fall back to `paginateRest`'s own defaults — unchanged behavior for
+   * existing callers (e.g. `duplicate-search.js`).
+   *
    * @field-manifest /repos/{owner}/{repo}/issues?labels=type::epic: number,
    *                 title, labels, state, state_reason, pull_request
    */
@@ -160,7 +168,10 @@ export class IssuesGateway {
       labels: TYPE_LABELS.EPIC,
     });
     const endpoint = `/repos/${this.owner}/${this.repo}/issues?${params}`;
-    const issues = await paginateRest(this._gh, endpoint);
+    const issues = await paginateRest(this._gh, endpoint, {
+      pageCap: filters.pageCap,
+      perPage: filters.perPage,
+    });
     return issues
       .filter((issue) => !issue.pull_request)
       .map(issueToEpicListItem);

package/.agents/scripts/resolve-doc-tiers.js

@@ -0,0 +1,83 @@
+/**
+ * CLI: resolve the repository's documentation read-tiers (Story #4438).
+ *
+ * Thin wrapper over `lib/doc-tiers.js#resolveDocTiers` that prints the tier
+ * map — `{ tiers: { alwaysLoaded, mandatoryRead, digestVisible, onDemand } }`,
+ * every entry `{ path, bytes }` — as JSON. Consumed by the `audit-documentation`
+ * lens (read-tier severity weighting), the `check-context-budget.js` ratchet,
+ * and operators inspecting the always-loaded closure.
+ *
+ * Flags:
+ *   --json   emit the tier map as JSON to stdout (default rendering is also
+ *            JSON; the flag is accepted for parity with the sibling ratchets
+ *            and future non-JSON renderings).
+ *   --root <path>  resolve tiers against an explicit repo root (default: the
+ *                  resolved PROJECT_ROOT).
+ *
+ * Exit code is always 0 on success — this is a reporter, not a gate.
+ */
+
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
+import { resolveDocTiers } from './lib/doc-tiers.js';
+
+/**
+ * Parse argv for `--root <path>` and `--json`.
+ *
+ * @param {string[]} argv
+ * @returns {{ rootPath: string | null, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let rootPath = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--root') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        rootPath = next;
+        i += 1;
+      }
+    } else if (a === '--json') {
+      json = true;
+    }
+  }
+  return { rootPath, json };
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive it against a fixture root
+ * with an injected sink and config.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   config?: object,
+ *   root?: string,
+ *   stdout?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} always 0
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  config,
+  root,
+  stdout = process.stdout,
+} = {}) {
+  const { rootPath } = parseArgv(argv);
+  const resolvedConfig = config ?? resolveConfig();
+  const resolvedRoot = root ?? rootPath ?? PROJECT_ROOT;
+  const result = resolveDocTiers(resolvedConfig, { root: resolvedRoot });
+  stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'resolve-doc-tiers',
+  propagateExitCode: true,
+  errorPrefix: '[resolve-doc-tiers] ❌ Fatal error',
+});

package/.agents/scripts/retro-run.js

@@ -37,6 +37,46 @@ import { createLedgerWriter } from './lib/orchestration/lifecycle/ledger-writer.
 import { runRetro } from './lib/orchestration/retro-runner.js';
 import { createProvider } from './lib/provider-factory.js';
 
+/**
+ * Pure: resolve the framework/consumer repo slugs (`"<owner>/<repo>"`)
+ * from a resolved config's `github` block, for threading into the retro's
+ * routed-proposal composer.
+ *
+ * - `consumerRepo` is the project's OWN repo (`github.owner/github.repo`).
+ *   It has **no** silent fallback: when `github.owner` / `github.repo` are
+ *   absent the slug is `''`, which `gatherRetroSignals` treats as "disable
+ *   the consumer pane loudly" rather than routing consumer-tagged friction
+ *   at the framework mirror (Story #4417).
+ * - `frameworkRepo` is the distinct framework mirror
+ *   (`github.frameworkRepo.{owner,repo}`) when configured, otherwise `''`
+ *   — `gatherRetroSignals` then falls back to its `DEFAULT_FRAMEWORK_REPO`
+ *   constant (a stable, known default is legitimate for the framework).
+ *
+ * Exported for tests.
+ *
+ * @param {object} [config]
+ * @returns {{ frameworkRepo: string, consumerRepo: string }}
+ */
+export function resolveRetroRepos(config) {
+  const gh = config?.github ?? {};
+  const consumerRepo =
+    typeof gh.owner === 'string' &&
+    gh.owner.length > 0 &&
+    typeof gh.repo === 'string' &&
+    gh.repo.length > 0
+      ? `${gh.owner}/${gh.repo}`
+      : '';
+  const fw = gh.frameworkRepo ?? {};
+  const frameworkRepo =
+    typeof fw.owner === 'string' &&
+    fw.owner.length > 0 &&
+    typeof fw.repo === 'string' &&
+    fw.repo.length > 0
+      ? `${fw.owner}/${fw.repo}`
+      : '';
+  return { frameworkRepo, consumerRepo };
+}
+
 const HELP = `Usage: node .agents/scripts/retro-run.js --epic <epicId> [--full-retro]
 
 Composes and posts the Epic retro structured comment for Epic #<epicId>,
@@ -125,11 +165,22 @@ export async function runRetroCli({
     : createLedgerWriter({ epicId, tempRoot });
   ledger.register(bus);
 
+  // Story #4417 — thread the framework/consumer repo slugs resolved from
+  // `config.github` into the retro so the routed-proposal composer files
+  // consumer-tagged friction at the project's own repo (not the framework
+  // mirror), and disables the consumer pane loudly when unresolved.
+  const { frameworkRepo, consumerRepo } = resolveRetroRepos(config);
+
   const result = await runRetroFn({
     epicId,
     provider,
     bus,
     forceFull: fullRetro,
+    frameworkRepo,
+    consumerRepo,
+    // Story #4418 — thread the resolved config so the retro auto-filer can
+    // read the `delivery.feedbackLoop.retroProposals` toggle.
+    config,
     logger,
   });
 

package/.agents/scripts/signals-view.js

@@ -161,7 +161,7 @@ function formatDuration(ms) {
 }
 
 function describeEvent(evt) {
-  const ts = evt?.ts ?? evt?.timestamp ?? '(no ts)';
+  const ts = evt?.ts ?? '(no ts)';
   const kind = evt?.kind ?? '(no kind)';
   const phase = evt?.phase ? ` phase=${evt.phase}` : '';
   const category = evt?.category ? ` category=${evt.category}` : '';

package/.agents/scripts/single-story-close.js

@@ -23,6 +23,14 @@
  *                          the post-merge confirmation step,
  *                          `single-story-confirm-merge.js`)
  *   8. worktree-reap     — drop the per-Story worktree
+ *   9. confirm-merge      — Story #4428, headless-only (`--wait-merge`):
+ *                          poll the just-armed PR to merge confirmation
+ *                          (reusing `confirmStoryMerged`) or terminate
+ *                          `agent::blocked` with a classified
+ *                          `merge.unlanded` lifecycle event. Attended runs
+ *                          (the default, no `--wait-merge`) skip this
+ *                          phase entirely and keep resting at
+ *                          `agent::closing`, exactly as before.
  *
  * Existing tests import the re-exported helpers
  * (`runSingleStoryClose`, `ensurePullRequest`, `parsePrNumber`,
@@ -33,8 +41,19 @@
  *   node single-story-close.js --story <STORY_ID> [--cwd <main-repo>]
  *                              [--skip-validation] [--skip-sync]
  *                              [--no-auto-merge] [--no-full-scope-crap]
+ *                              [--wait-merge | --no-wait-merge]
  *
- * Exit codes: 0 ok, 1 error.
+ * `--wait-merge` is the headless must-land signal (Story #4428, Epic
+ * #4425): the invoking surface (a headless `/single-story-deliver` run, a
+ * CI-driven wrapper, or `/deliver`'s standalone multi-Story fan-out) opts
+ * in explicitly — attended runs never pass it, so the default exit shape
+ * (rest at `agent::closing`, issue OPEN) is unchanged. `--no-wait-merge` is
+ * the explicit opt-out that always wins over `--wait-merge`, for a caller
+ * that wants to manage merge confirmation externally even in an otherwise
+ * headless context.
+ *
+ * Exit codes: 0 ok, 1 error (including a headless `--wait-merge` run that
+ * gave up without a confirmed merge — see phase 9 above).
  *
  * @see .agents/workflows/helpers/single-story-deliver.md
  */

package/.agents/scripts/standalone-feedback-rollup.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+
+/**
+ * standalone-feedback-rollup.js — end-of-run feedback rollup for the
+ * `/deliver` standalone multi-Story path (Epic #4406 / Story #4416).
+ *
+ * The standalone delivery path (`helpers/deliver-stories`) drives one or
+ * more Epic-free Stories to green, and each per-Story sub-agent appends
+ * `friction` records to its **standalone** signals stream at
+ * `temp/standalone/stories/story-<sid>/signals.ndjson` (written via
+ * `appendSignal({ epicId: null, storyId })`). Before this rollup that
+ * tree was write-only — nothing ever read it back. This CLI closes the
+ * gap: it scans the standalone streams for the delivered Story set and
+ * emits a per-category friction summary that `deliver-stories.md`
+ * surfaces in its Phase 3 run summary.
+ *
+ * Usage:
+ *   node standalone-feedback-rollup.js --stories <id,...>
+ *
+ * Contract:
+ *   - Stream paths resolve **exclusively** through the `temp-paths`
+ *     helpers via `forEachLine(null, storyId, cb, config)` — the `null`
+ *     Epic sentinel routes to the standalone tree. No hand-built path
+ *     strings.
+ *   - Aggregates `friction` records by their **top-level** `category`
+ *     (Epic #4406 canonical envelope shape); a record with no category
+ *     buckets under `Unknown`.
+ *   - **Never fails a run.** A missing or empty stream degrades to an
+ *     empty contribution; the CLI always prints a JSON summary and
+ *     exits 0. Observability MUST NOT take down the delivering flow.
+ *
+ * Output (stdout, one JSON object):
+ *   {
+ *     "kind": "standalone-feedback-rollup",
+ *     "stories": [<id>, ...],
+ *     "totalFriction": <int>,
+ *     "byCategory": { "<category>": <count>, ... },
+ *     "perStory": { "<id>": { "friction": <int>, "missing": <bool> }, ... }
+ *   }
+ *
+ * @see .agents/scripts/lib/observability/signals-writer.js (forEachLine, appendSignal)
+ * @see .agents/scripts/lib/config/temp-paths.js (signalsFile — null Epic sentinel)
+ * @see .agents/workflows/helpers/deliver-stories.md (Phase 3 summary wiring)
+ */
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { forEachLine } from './lib/observability/signals-writer.js';
+
+const FRICTION_KIND = 'friction';
+const UNKNOWN_CATEGORY = 'Unknown';
+
+/**
+ * Parse `--stories <id,...>` into an ordered, de-duplicated array of
+ * positive-integer Story IDs. Accepts a single comma-separated value or
+ * repeated `--stories` flags. Non-integer / non-positive tokens are
+ * rejected so a typo surfaces as an input error rather than a silently
+ * empty rollup.
+ *
+ * @param {string[]} args
+ * @returns {{ stories: number[] }}
+ */
+export function parseArguments(args) {
+  const raw = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--stories') {
+      const value = args[++i];
+      if (typeof value === 'string') {
+        raw.push(...value.split(','));
+      }
+    }
+  }
+
+  const seen = new Set();
+  const stories = [];
+  for (const token of raw) {
+    const trimmed = token.trim();
+    if (trimmed.length === 0) continue;
+    const id = Number(trimmed);
+    if (!Number.isInteger(id) || id <= 0) {
+      throw new Error(
+        `--stories expects comma-separated positive integers; got ${JSON.stringify(trimmed)}`,
+      );
+    }
+    if (seen.has(id)) continue;
+    seen.add(id);
+    stories.push(id);
+  }
+
+  if (stories.length === 0) {
+    throw new Error(
+      'Usage: node standalone-feedback-rollup.js --stories <id,...>',
+    );
+  }
+
+  return { stories };
+}
+
+/**
+ * Read one standalone Story's signals stream and aggregate its `friction`
+ * records by top-level `category`, mutating the shared `byCategory` tally.
+ *
+ * Degrades to a zero contribution on a missing / empty / unreadable
+ * stream — `forEachLine` already swallows fs + JSON faults and reports a
+ * missing file via `{ missing: true }` rather than throwing.
+ *
+ * @param {number} storyId
+ * @param {Record<string, number>} byCategory Mutated in place.
+ * @param {object} config
+ * @returns {Promise<{ friction: number, missing: boolean }>}
+ */
+async function rollupStory(storyId, byCategory, config) {
+  let friction = 0;
+  // `epicId: null` routes forEachLine → signalsFile(null, storyId, config)
+  // → the standalone tree. Never a hand-built path string.
+  const result = await forEachLine(
+    null,
+    storyId,
+    (record) => {
+      if (
+        record === null ||
+        typeof record !== 'object' ||
+        record.kind !== FRICTION_KIND
+      ) {
+        return;
+      }
+      const category =
+        typeof record.category === 'string' && record.category.length > 0
+          ? record.category
+          : UNKNOWN_CATEGORY;
+      byCategory[category] = (byCategory[category] ?? 0) + 1;
+      friction += 1;
+    },
+    config,
+  );
+
+  return { friction, missing: Boolean(result?.missing) };
+}
+
+/**
+ * Aggregate friction across every named standalone Story stream.
+ *
+ * @param {number[]} stories
+ * @param {object} [config]
+ * @returns {Promise<{
+ *   kind: string,
+ *   stories: number[],
+ *   totalFriction: number,
+ *   byCategory: Record<string, number>,
+ *   perStory: Record<string, { friction: number, missing: boolean }>,
+ * }>}
+ */
+export async function buildRollup(stories, config) {
+  const byCategory = {};
+  const perStory = {};
+  let totalFriction = 0;
+
+  for (const storyId of stories) {
+    const { friction, missing } = await rollupStory(
+      storyId,
+      byCategory,
+      config,
+    );
+    perStory[storyId] = { friction, missing };
+    totalFriction += friction;
+  }
+
+  return {
+    kind: 'standalone-feedback-rollup',
+    stories,
+    totalFriction,
+    byCategory,
+    perStory,
+  };
+}
+
+export async function main(args = process.argv.slice(2)) {
+  const { stories } = parseArguments(args);
+  const config = resolveConfig();
+  const summary = await buildRollup(stories, config);
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+  return 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'StandaloneFeedbackRollup',
+  propagateExitCode: true,
+});

package/.agents/scripts/story-close.js

@@ -10,6 +10,9 @@
  * envelope. Pipeline shape:
  *
  *   1. parse + resolveCloseInputs (lib/orchestration/story-close/close-inputs.js)
+ *   1.5. already-done no-op guard (inline below) — a Story already at
+ *      `agent::done` AND closed short-circuits here so no phase below it
+ *      ever flips the label away from `agent::done` or reopens the issue.
  *   2. preflight                  (phases/preflight.js)
  *   3. state-flip → closing       (inline helper below)
  *   4. capture starting branch    (phases/branch-restore.js)
@@ -152,6 +155,51 @@ export async function runStoryClose({
     storyBranch,
   } = resolved;
 
+  // Phase 0 — idempotency guard. A re-run against a Story that is already
+  // fully closed must be a safe no-op. Without this guard, Phase 3 below
+  // (`transitionToClosing`) unconditionally flips the label to
+  // `agent::closing` — and `transitionTicketState`
+  // (lib/orchestration/ticketing/transition.js) unconditionally sends
+  // `state: 'open'` for any non-`agent::done` target — so re-running close
+  // against an already-closed Story reopens the GitHub issue and strips
+  // `agent::done` *before* the post-merge pipeline even starts. If the
+  // pipeline then throws or a phase silently no-ops (the merge is already
+  // fully reaped, so there is nothing left to redo), the Story is left
+  // regressed at `agent::closing`/OPEN instead of a safe no-op.
+  //
+  // The "already fully closed" test mirrors the deepest-level guard in the
+  // post-merge `ticketClosurePhase` (post-merge/phases/ticket-closure.js):
+  // label `agent::done` AND issue `state === 'closed'`, an AND — never a
+  // state-alone check. The `state === 'closed'` disjunct is deliberately
+  // excluded per the hard-won reasoning in
+  // `lib/single-story/confirm-merge.js`: a Story can arrive here closed at
+  // the GitHub layer (a `Closes #<id>` PR footer, or a prior close that set
+  // `state: closed` but was killed before the label flip landed) while its
+  // label is legitimately still `agent::closing`. Treating that as
+  // already-done would skip the very `closing → done` re-assertion the
+  // re-run exists to perform, stranding the label. Requiring BOTH signals
+  // no-ops only a genuinely finished Story.
+  const alreadyDone =
+    Array.isArray(story?.labels) &&
+    story.labels.includes(STATE_LABELS.DONE) &&
+    story?.state === 'closed';
+  if (alreadyDone) {
+    progress(
+      'SKIP',
+      `Story #${storyId} is already ${STATE_LABELS.DONE} and closed — no-op re-run.`,
+    );
+    return {
+      success: true,
+      result: {
+        storyId,
+        epicId,
+        action: 'noop',
+        reason: 'already-done',
+        merged: true,
+      },
+    };
+  }
+
   const notifyFn = (ticketId, payload, opts = {}) =>
     notify(ticketId, payload, { config, provider, ...opts });