mandrel 2.0.0 → 2.1.0

package/.agents/scripts/single-story-confirm-merge.js

@@ -36,16 +36,28 @@
  */
 
 import { parseArgs } from 'node:util';
+import { parseSprintArgs } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
+import { formatCliError } from './lib/error-redactor.js';
 import { gh as defaultGh } from './lib/gh-exec.js';
 import { getStoryBranch } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
+import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
+import { MERGED_FLIP_FAILED_BLOCK_CLASS } from './lib/orchestration/lifecycle/emit-merge-flip-failed.js';
 import { parsePrNumber } from './lib/orchestration/single-story-close/phases/code-review.js';
+import { runConfirmMergePhase as defaultRunConfirmMergePhase } from './lib/orchestration/single-story-close/phases/confirm-merge.js';
 import { parseCloseOptions } from './lib/orchestration/single-story-close/phases/options.js';
+import { runPostLandTail } from './lib/orchestration/single-story-close/phases/post-land.js';
+import {
+  buildTerminalEnvelope,
+  emitTerminalEnvelope,
+  exitCodeForTerminal,
+  NEXT_COMMANDS,
+  terminalFromWaitOutcome,
+} from './lib/orchestration/story-deliver-terminal.js';
 import { createProvider } from './lib/provider-factory.js';
 import { confirmStoryMerged } from './lib/single-story/confirm-merge.js';
-import { withConfirmFollowUps } from './lib/single-story/confirm-merge-follow-ups.js';
 
 const progress = Logger.createProgress('single-story-confirm-merge', {
   stderr: true,
@@ -71,6 +83,28 @@ function readPrFlag() {
   }
 }
 
+/**
+ * `--wait`: resume the bounded merge wait rather than probing once.
+ *
+ * This CLI serves two callers behind one command string. `confirmMerge` wants
+ * a fast idempotent flip for a merge that ALREADY happened (an operator-merge
+ * flow, or a `merged-flip-failed` retry) and must not stall. `resumeLand`
+ * wants to pick up a merge wait the close handed off at its per-invocation
+ * bound — that one must actually wait, and must be able to give up.
+ */
+function readWaitFlag() {
+  try {
+    const { values } = parseArgs({
+      args: process.argv.slice(2),
+      options: { wait: { type: 'boolean', default: false } },
+      strict: false,
+    });
+    return values.wait === true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Resolve the PR number for the Story branch when one was not passed on
  * the CLI. Probes `gh pr list --head <branch> --state all` (the merged PR
@@ -99,11 +133,107 @@ async function resolvePrNumber({ cwd, storyBranch, gh }) {
   }
 }
 
-function logConfirmResult(result) {
+/**
+ * Story #4578 — async so the runtime-derived friction emit can be awaited.
+ * This CLI is the resume path for a parked worker (`--wait`), so a `pending`
+ * terminal here means a bounded wait expired again with the PR still in
+ * flight: the exact observable the retro was blind to. The emit is
+ * best-effort and cannot throw; awaiting it matters because `runAsCli`
+ * exits via `process.exit` the moment `main` resolves.
+ */
+async function logConfirmResult(result, terminal, config) {
+  // Human-facing dump stays level-gated; the envelope is the machine
+  // contract and must survive AGENT_LOG_LEVEL=silent.
   Logger.info(
     `\n--- CONFIRM MERGE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
   );
-  return { success: true, result };
+  emitTerminalEnvelope(terminal);
+  await emitTerminalFriction({ envelope: terminal, config });
+  return { success: terminal.status !== 'failed', result, terminal };
+}
+
+/**
+ * Map a `confirmStoryMerged` envelope onto the shared terminal envelope
+ * (Story #4543) so this CLI and the in-close land path report one shape.
+ *
+ * The three confirm outcomes map cleanly:
+ *   - `done` / `noop` (already-done) → `landed`. Both mean the merge is on
+ *     the base branch and the Story is `agent::done`.
+ *   - `pending` (`pr-open` / `no-pr`) → `pending`. Re-run once the merge
+ *     lands; nothing is wrong.
+ *   - `flip-failed` → `blocked` with the shared `merged-flip-failed` class:
+ *     the merge landed, so this is a label-write fault, and the remedy is
+ *     re-running this very command (it is idempotent).
+ *   - `pr-not-merged` (closed without merging) → `blocked`. The PR is gone;
+ *     a re-run cannot fix it, so it needs a human.
+ */
+function buildConfirmTerminal({
+  storyId,
+  storyBranch,
+  baseBranch,
+  prNumber,
+  confirmation,
+  tail,
+  elapsedSeconds,
+}) {
+  // `pr-not-merged` means the PR is CLOSED — reporting it as OPEN put a
+  // fact in the envelope that the blocked reason directly contradicts.
+  const prState = confirmation.merged
+    ? 'MERGED'
+    : confirmation.reason === 'pr-not-merged'
+      ? 'CLOSED'
+      : 'OPEN';
+  const pr =
+    Number.isInteger(prNumber) && prNumber > 0
+      ? { number: prNumber, state: prState }
+      : null;
+  const common = { storyId, storyBranch, baseBranch, pr, elapsedSeconds };
+
+  if (confirmation.action === 'done' || confirmation.action === 'noop') {
+    return buildTerminalEnvelope({
+      ...common,
+      status: 'landed',
+      phase: tail ? 'post-land' : 'done',
+      tail,
+      nextCommand: null,
+    });
+  }
+  if (confirmation.action === 'flip-failed') {
+    return buildTerminalEnvelope({
+      ...common,
+      status: 'blocked',
+      phase: 'confirm-merge',
+      blocked: {
+        blockClass: MERGED_FLIP_FAILED_BLOCK_CLASS,
+        reason:
+          'merge confirmed but the agent::closing → agent::done label write failed',
+        frictionCommentId: null,
+      },
+      nextCommand: NEXT_COMMANDS.confirmMerge(storyId),
+    });
+  }
+  if (confirmation.reason === 'pr-not-merged') {
+    return buildTerminalEnvelope({
+      ...common,
+      status: 'blocked',
+      phase: 'confirm-merge',
+      blocked: {
+        blockClass: 'api-race-other',
+        reason: 'the PR was closed without merging (state=CLOSED)',
+        frictionCommentId: null,
+      },
+      nextCommand: NEXT_COMMANDS.recover(storyId),
+    });
+  }
+  return buildTerminalEnvelope({
+    ...common,
+    status: 'pending',
+    phase: 'confirm-merge',
+    nextCommand:
+      confirmation.reason === 'no-pr'
+        ? NEXT_COMMANDS.recover(storyId)
+        : NEXT_COMMANDS.confirmMerge(storyId),
+  });
 }
 
 async function resolveConfirmPrNumber({ prParam, cwd, storyBranch, gh }) {
@@ -122,11 +252,13 @@ export async function runConfirmMerge({
   storyId: storyIdParam,
   cwd: cwdParam,
   pr: prParam,
+  wait: waitParam,
   injectedProvider,
   injectedConfig,
   injectedGh,
   injectedNotify,
   injectedReadPrMergeState,
+  runConfirmMergePhaseFn = defaultRunConfirmMergePhase,
 } = {}) {
   const { storyId, cwd } = parseCloseOptions({
     storyIdParam,
@@ -135,14 +267,17 @@ export async function runConfirmMerge({
 
   if (!storyId) {
     throw new Error(
-      'Usage: node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>] [--cwd <main-repo>]',
+      'Usage: node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>] [--wait] [--cwd <main-repo>]',
     );
   }
+  const wait = waitParam ?? readWaitFlag();
 
+  const startedAtMs = Date.now();
   const config = injectedConfig || resolveConfig({ cwd });
   const provider = injectedProvider || createProvider(config);
   const gh = injectedGh ?? defaultGh;
   const storyBranch = getStoryBranch(storyId);
+  const baseBranch = config.project?.baseBranch ?? 'main';
 
   progress('INIT', `Confirming merge for standalone Story #${storyId}...`);
 
@@ -157,13 +292,82 @@ export async function runConfirmMerge({
       'CONFIRM',
       `⚠️ No PR found for ${storyBranch}; cannot confirm merge. Story stays at agent::closing.`,
     );
-    return logConfirmResult({
+    const noPr = {
       storyId,
       standalone: true,
       action: 'pending',
       reason: 'no-pr',
       merged: false,
+    };
+    return await logConfirmResult(
+      noPr,
+      buildConfirmTerminal({
+        storyId,
+        storyBranch,
+        baseBranch,
+        prNumber: null,
+        confirmation: noPr,
+        tail: null,
+        elapsedSeconds: Math.round((Date.now() - startedAtMs) / 1000),
+      }),
+      config,
+    );
+  }
+
+  // `--wait` (what `NEXT_COMMANDS.resumeLand` passes): resume the merge wait
+  // the close handed off at its per-invocation bound, by running the SAME
+  // phase the in-close path runs. Without this the resume was a single probe
+  // that reported `pending` and exited, so the cumulative `maxBudgetSeconds`
+  // give-up — the only thing that ever emits `merge.unlanded` and flips a
+  // wedged Story to `agent::blocked` — was reachable ONLY inside the original
+  // close invocation. A PR that wedged after the close returned could be
+  // resumed forever, always answering `pending`, never escalating to anyone.
+  //
+  // The phase anchors its cumulative budget at the PR's `createdAt`, so the
+  // resume does not restart the clock — exactly what the envelope's
+  // `waitBudget` contract already promised.
+  if (wait) {
+    const waitOutcome = await runConfirmMergePhaseFn({
+      cwd,
+      storyId,
+      storyBranch,
+      baseBranch,
+      prNumber,
+      prUrl: `${storyBranch} PR #${prNumber}`,
+      // The close already armed it; this CLI is resuming that wait, not
+      // deciding whether to arm.
+      autoMergeEnabled: true,
+      provider,
+      config,
+      progress,
+      injectedGh: gh,
+      injectedNotify,
+      readPrMergeStateFn: injectedReadPrMergeState,
     });
+    const terminal = terminalFromWaitOutcome({
+      waitOutcome,
+      storyId,
+      storyBranch,
+      baseBranch,
+      prNumber,
+      prUrl: null,
+      autoMergeEnabled: true,
+      // This CLI runs no close gates, so it reports none — `gates` is
+      // "each gate this invocation was responsible for".
+      gates: undefined,
+      elapsedSeconds: Math.round((Date.now() - startedAtMs) / 1000),
+    });
+    return await logConfirmResult(
+      {
+        storyId,
+        standalone: true,
+        action: waitOutcome.terminal,
+        resumed: true,
+        tail: waitOutcome.tail ?? null,
+      },
+      terminal,
+      config,
+    );
   }
 
   const confirmation = await confirmStoryMerged({
@@ -179,21 +383,90 @@ export async function runConfirmMerge({
     readPrMergeStateFn: injectedReadPrMergeState,
   });
 
-  const result = await withConfirmFollowUps({
-    confirmation,
+  // Story #4543 — reach the SAME shared land tail the in-close path reaches
+  // (`phases/post-land.js`), rather than this CLI's own follow-ups-only
+  // wrapper. That wrapper was the whole reason the two landing surfaces
+  // diverged: it captured follow-ups and nothing else, while the resync and
+  // cleanup steps lived in prose the caller had to remember to run.
+  //
+  // Gated on `merged`, NOT on `action === 'done'`. `done` means "this run
+  // flipped the label"; a Story already at `agent::done` returns
+  // `action: 'noop', merged: true`, and gating on `done` skipped the tail for
+  // exactly that case — the belated-manual-confirm backfill this tail exists
+  // to make possible (see `story-follow-ups.js`, which documents the gap).
+  // Re-running is safe: every step is idempotent (the follow-ups comment is
+  // an upsert, ref cleanup and base fast-forward no-op when already done).
+  const tail =
+    confirmation.merged === true
+      ? await runPostLandTail({
+          storyId,
+          storyBranch,
+          baseBranch,
+          cwd,
+          provider,
+          config,
+          progress,
+        })
+      : null;
+
+  const terminal = buildConfirmTerminal({
     storyId,
+    storyBranch,
+    baseBranch,
     prNumber,
-    provider,
-    config,
-    cwd,
-    progress,
+    confirmation,
+    tail,
+    elapsedSeconds: Math.round((Date.now() - startedAtMs) / 1000),
   });
-  if (result.action === 'done') {
-    progress('DONE', `✅ Standalone Story #${storyId} → agent::done (merged).`);
+  if (confirmation.action === 'done') {
+    progress('DONE', `✅ Story #${storyId} → agent::done (merged).`);
+  }
+  return await logConfirmResult(
+    { ...confirmation, standalone: true, tail },
+    terminal,
+    config,
+  );
+}
+
+/**
+ * CLI entry — mirrors `single-story-close.js`: the exit code comes from the
+ * terminal envelope's status, so a caller can tell `pending` (the PR has not
+ * merged yet; re-run me) from `landed` without parsing stdout.
+ *
+ * The catch mirrors close's for the same reason: `confirmStoryMerged`'s PR
+ * read is a live `gh` call that throws on a transient API error, and this CLI
+ * is a *landing surface* — the one `pending` tells the operator to re-run. If
+ * a flaked read exited 1 with no envelope, the surface would be silent exactly
+ * where the envelope is the contract. Both landing surfaces emit one envelope
+ * or none at all; "none at all" is what Story #4543 removes.
+ */
+async function main() {
+  try {
+    const outcome = await runConfirmMerge();
+    return exitCodeForTerminal(outcome?.terminal ?? { status: 'failed' });
+  } catch (err) {
+    const storyId = Number(parseSprintArgs().storyId);
+    // No story id → a usage error; there is nothing to report an envelope
+    // about, so let runAsCli surface it as a plain fatal.
+    if (!Number.isInteger(storyId) || storyId <= 0) throw err;
+    const terminal = buildTerminalEnvelope({
+      storyId,
+      status: 'failed',
+      phase: 'confirm-merge',
+      failure: { reason: String(err?.message ?? err) },
+      nextCommand: NEXT_COMMANDS.recover(storyId),
+      elapsedSeconds: 0,
+    });
+    Logger.error(
+      `[single-story-confirm-merge] Fatal error: ${formatCliError(err)}`,
+    );
+    emitTerminalEnvelope(terminal);
+    await emitTerminalFriction({ envelope: terminal });
+    return exitCodeForTerminal(terminal);
   }
-  return logConfirmResult(result);
 }
 
-runAsCli(import.meta.url, runConfirmMerge, {
+runAsCli(import.meta.url, main, {
   source: 'single-story-confirm-merge',
+  propagateExitCode: true,
 });

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

@@ -223,12 +223,10 @@ export async function reapMergedStoryBranches({
 /**
  * Fetch remote refs, reap merged story branches, and fast-forward the local
  * base branch so new story branches seed from origin's tip. Exported for
- * testing (owns the fast-forward cascade; mirrors `fetchMainRefs` +
- * `ensureEpicBranch` in `branch-initializer.js`).
+ * testing (owns the fast-forward cascade).
  *
- * Routes the `origin` fetch through `cachedGitFetch` so concurrent standalone
- * Story waves share the same per-process coalescing window that Epic-attached
- * stories get via `branch-initializer.js#fetchMainRefs`. Pass `fetchFn` to
+ * Routes the `origin` fetch through `cachedGitFetch` so concurrent Story
+ * waves share a per-process fetch-coalescing window. Pass `fetchFn` to
  * inject a stub in tests without touching real git.
  *
  * @param {object} opts
@@ -413,12 +411,10 @@ export async function provisionWorktree({
   }
 
   try {
-    // Story #2874 — standalone Stories have no parent Epic; pass
-    // `epicId: null` so the helper omits CC_EPIC_ID from env + file
-    // instead of throwing on a 0 sentinel. The trace hook keys its
-    // standalone-trace branch on CC_EPIC_ID being absent.
+    // v2 Stories are standalone — no parent Epic. The helper omits
+    // CC_EPIC_ID from env + file; the trace hook keys its standalone-trace
+    // branch on CC_EPIC_ID being absent.
     setActiveStoryEnv({
-      epicId: null,
       storyId,
       workCwd,
       logger: {

package/.agents/scripts/stories-wave-tick.js

@@ -37,7 +37,8 @@
  *     totalStories: number,
  *     concurrencyCap: number,
  *     inFlight: number,
- *     cycleError: string | null
+ *     cycleError: string | null,
+ *     wedged: { reason, stories: [{ id, unmetBlockers }] } | null
  *   }
  *
  * The standalone loop calls this once per beat: after each Story closes it
@@ -54,7 +55,13 @@
  * deterministic config source (`delivery.deliverRunner.concurrencyCap`) and
  * one scheduling kernel with every `/deliver` multi-Story invocation.
  *
- * On cycle detection, exits with code 2 and sets cycleError in the envelope.
+ * Exit codes: 0 ok · 1 input error · 2 dependency cycle (`cycleError`) ·
+ * 3 wedged (`wedged`) — ready is empty, nothing is in flight, and undone
+ * Stories are waiting on blockers that are not done. A cycle is a
+ * self-referential DAG the operator must fix; a wedge is a well-formed DAG
+ * whose gates cannot be satisfied from the supplied `--done` set (usually a
+ * blocker outside the delivered set that has not landed). Both are distinct
+ * from the ordinary `ready: []` that means "waiting on in-flight work".
  */
 
 import { readFileSync } from 'node:fs';
@@ -68,6 +75,13 @@ import { AGENT_LABELS } from './lib/label-constants.js';
 import { buildStoryAdjacency } from './lib/story-adjacency.js';
 import { selectReadySet } from './lib/wave-runner/ready-set.js';
 
+/**
+ * Exit code for a wedged run — deliberately distinct from the cycle exit (2)
+ * so a caller can tell "your DAG is self-referential" from "your DAG is fine
+ * but its gates can never be satisfied from this `--done` set".
+ */
+export const WEDGED_EXIT_CODE = 3;
+
 const HELP = `Usage: node .agents/scripts/stories-wave-tick.js --dag '<json>' | --dag-file <path> [--concurrency <n>] [--done <csv>] [--in-flight <n>]
 
 Continuous ready-set planner for standalone Story delivery. Consumes a
@@ -102,13 +116,17 @@ Output envelope:
     "totalStories": 2,
     "concurrencyCap": 3,
     "inFlight": 0,
-    "cycleError": null
+    "cycleError": null,
+    "wedged": null
   }
 
 Exit codes:
   0 - Success, ready set emitted
   1 - Invalid input (missing/malformed DAG, invalid --concurrency/--in-flight/--done)
   2 - Cycle detected in dependency graph
+  3 - Wedged: ready is empty, nothing is in flight, and undone Stories are
+      waiting on blockers that are not done. Distinct from an ordinary empty
+      ready set (which means "waiting on in-flight work") and from a cycle.
 `;
 
 /**
@@ -322,6 +340,7 @@ export function buildReadySetEnvelope(
     concurrencyCap,
     inFlight,
     cycleError: null,
+    wedged: null,
   };
 
   if (totalStories === 0) {
@@ -365,7 +384,62 @@ export function buildReadySetEnvelope(
     globalCap: concurrencyCap,
   }).map((rec) => rec.id);
 
-  return { envelope: { ...base, ready }, exitCode: 0 };
+  // Wedge detection (Story #4540). `ready: []` is normal while work is in
+  // flight — the loop is simply waiting. But ready-empty AND nothing in
+  // flight AND undone Stories remaining means no beat can ever make
+  // progress: the run is stuck, and the previous behaviour was to return
+  // exit 0 with an empty ready set forever, indistinguishable from
+  // "waiting". Name the stuck ids and their unmet blockers.
+  //
+  // Distinct from `cycleError`/exit 2: a cycle is a self-referential DAG,
+  // whereas this is a DAG whose gates are real but unsatisfiable from the
+  // supplied `done` set (typically a blocker outside the delivered set that
+  // has not landed).
+  const wedge = detectWedge({ nodes, doneIds, ready, inFlight });
+  if (wedge) {
+    return {
+      envelope: { ...base, ready, wedged: wedge },
+      exitCode: WEDGED_EXIT_CODE,
+    };
+  }
+
+  return { envelope: { ...base, ready, wedged: null }, exitCode: 0 };
+}
+
+/**
+ * Identify a run that cannot progress: nothing dispatchable, nothing in
+ * flight, work remaining.
+ *
+ * @param {{ nodes: object[], doneIds: Set<number>, ready: number[], inFlight: number }} args
+ * @returns {{ reason: string, stories: Array<{ id: number, unmetBlockers: number[] }> }|null}
+ */
+export function detectWedge({ nodes, doneIds, ready, inFlight }) {
+  if (ready.length > 0 || inFlight > 0) return null;
+  const undone = nodes.filter((n) => !doneIds.has(n.id));
+  if (undone.length === 0) return null;
+
+  const stories = undone
+    .map((n) => ({
+      id: n.id,
+      unmetBlockers: (n.dependsOn ?? []).filter((dep) => !doneIds.has(dep)),
+    }))
+    .filter((s) => s.unmetBlockers.length > 0);
+
+  // Undone work with no unmet blockers would have been dispatched; if that
+  // is the whole set, the cap or in-flight accounting explains the empty
+  // ready set rather than a wedge.
+  if (stories.length === 0) return null;
+
+  const detail = stories
+    .map((s) => `#${s.id} ← ${s.unmetBlockers.map((d) => `#${d}`).join(', ')}`)
+    .join('; ');
+  return {
+    reason:
+      `No Story can be dispatched: nothing is in flight and ${stories.length} ` +
+      `Story(ies) are waiting on blockers that are not done — ${detail}. ` +
+      `A blocker outside the delivered set must land first, or be included in --ids.`,
+    stories,
+  };
 }
 
 /**
@@ -405,6 +479,7 @@ export function runStoriesWaveTick({
       concurrencyCap,
       inFlight: inFlightValue,
       cycleError: null,
+      wedged: null,
       inputError: message,
     },
     exitCode: 1,

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

@@ -12,7 +12,7 @@
  *
  * Operator planning:
  *   node .agents/scripts/plan-context.js --seed "…" | --seed-file <path> | --tickets <ids>
- *   node .agents/scripts/plan-persist.js --stories … --risk-verdict …
+ *   node .agents/scripts/plan-persist.js --stories …
  */
 
 import { readFile } from 'node:fs/promises';
@@ -146,7 +146,7 @@ async function runEmitContext({
   // corpus digest reads the project's actual docs directory regardless
   // of the directory this CLI happens to be invoked from — matching the
   // sibling resolution pattern in
-  // epic-plan-spec/phases/authoring-context.js.
+  // planning/authoring-context.js.
   const docsRoot = path.resolve(
     PROJECT_ROOT,
     config?.project?.paths?.docsRoot ?? 'docs',
@@ -157,7 +157,7 @@ async function runEmitContext({
       loadBodyTemplate(projectRoot),
       fetchOpenStories(provider),
       readTechStackSummary(projectRoot),
-      buildCorpusContext({ seed, provider, docsContextFiles, docsRoot }),
+      buildCorpusContext({ docsContextFiles, docsRoot }),
     ]);
 
   const duplicateCandidates = rankDuplicateCandidates({

package/.agents/scripts/update-ticket-state.js

@@ -8,15 +8,7 @@
 import { parseArgs } from 'node:util';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
-import {
-  enqueueLabel,
-  outboxPathFor,
-} from './lib/orchestration/bookkeeping-outbox.js';
-import {
-  cascadeCompletion,
-  STATE_LABELS,
-  transitionTicketState,
-} from './lib/orchestration/ticketing.js';
+import { transitionTicketState } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 
 // ── CLI Main Block ────────────────────────────────────────────────────────
@@ -31,8 +23,6 @@ if (
       ticket: { type: 'string' },
       state: { type: 'string' },
       'remove-label': { type: 'string' },
-      buffer: { type: 'boolean' },
-      epic: { type: 'string' },
     },
     strict: false,
   });
@@ -66,50 +56,18 @@ if (
       return;
     }
 
-    // Headless buffering (Epic #4476 M5): buffer an intermediate state flip to
-    // the per-Epic outbox instead of a live GitHub round-trip; finalize's
-    // bookkeeping-reconcile.js drains it once. `agent::blocked` (the HITL gate,
-    // §1.J) and `agent::done` (its cascade must run live) ALWAYS surface
-    // immediately and are never buffered. Requires --epic to locate the outbox.
-    if (
-      values.buffer &&
-      state !== STATE_LABELS.BLOCKED &&
-      state !== STATE_LABELS.DONE
-    ) {
-      const epicId = Number.parseInt(values.epic ?? '', 10);
-      if (!Number.isInteger(epicId) || epicId <= 0) {
-        throw new Error('--buffer requires --epic <id>');
-      }
-      enqueueLabel({
-        outboxPath: outboxPathFor(epicId, config),
-        ticketId,
-        state,
-      });
-      Logger.info(
-        `[State-Sync] Buffered #${ticketId} → ${state} (headless; drained at finalize)`,
-      );
-      return;
-    }
-
     Logger.info(
       `[State-Sync] Transitioning ticket #${ticketId} to ${state}...`,
     );
+    // Story #4545 — no second cascade here. `transitionTicketState` already
+    // fires the upward cascade on every transition (bulk.js registers
+    // `cascadeParentState` as transition.js's cascade runner, and the DONE
+    // branch delegates to `cascadeCompletion`), so the explicit call this
+    // used to make re-walked the same parents and re-spent the same API
+    // calls a second time on every done transition — under a Story-only
+    // model where no orchestration parent exists to find.
     await transitionTicketState(provider, ticketId, state);
 
-    if (state === STATE_LABELS.DONE) {
-      Logger.info(`[State-Sync] Cascading completion from #${ticketId}...`);
-      const cascade = await cascadeCompletion(provider, ticketId);
-      // Hoisted out of the `for...of` initializer because typhonjs-escomplex
-      // mis-parses optional chaining there (it would zero out this file's
-      // maintainability score).
-      const cascadeFailures = cascade?.failed ?? [];
-      for (const { parentId, error } of cascadeFailures) {
-        Logger.warn(
-          `[State-Sync] ⚠️  Cascade partial-failure on parent #${parentId}: ${error}`,
-        );
-      }
-    }
-
     // Optional secondary label removal alongside the state transition
     // (e.g. clear `status::blocked` when transitioning back to ready).
     if (removeLabel) {