mandrel 2.25.0 → 2.26.0

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -31,15 +31,13 @@ import {
   renderAcceptanceSpecSystemPrompt,
   renderTechSpecSystemPrompt,
 } from '../templates/spec-author-prompts.js';
-import { concurrentMap } from '../util/concurrent-map.js';
+import { concurrentMap, FANOUT_CONCURRENCY } from '../util/concurrent-map.js';
 import { buildComplexitySignals } from './complexity-gate.js';
 import { parseDeliverySlicingTable } from './consolidation-precondition.js';
 import { buildDocsDigest } from './docs-digest.js';
 import { buildAuthoringContext } from './planning/authoring-context.js';
 import { buildDecomposerSystemPrompt } from './planning/decomposer-context.js';
 
-/** Bounded concurrency for `--tickets` source-ticket hydration. */
-const SOURCE_TICKET_FETCH_CONCURRENCY = 4;
 /**
  * Envelope byte ceiling (regression guard for the design's named PR2 risk:
  * two envelopes → one bigger one). This is the **only** live bound on
@@ -229,7 +227,8 @@ export function renderStoriesTemplate({ complexitySignals = null } = {}) {
           'codes, security invariants, and load-bearing constraints with ' +
           'their why. Implementation choices belong to the deliverer unless ' +
           'load-bearing. No per-file behavior paragraphs, no current-state ' +
-          'narration. Keep it under ~250 words (soft advisory budget). ' +
+          'narration. Aim for ~250 words; an advisory warning fires past 350, ' +
+          'and it never fails the persist. ' +
           'Delete this field when acceptance[] carries the whole contract.',
         changes: buildTemplateChanges(complexitySignals),
         non_goals: [],
@@ -813,6 +812,84 @@ async function searchStoryDuplicates({
   }
 }
 
+/**
+ * Gather the three independent envelope inputs — the open-Story duplicate
+ * search, the folded authoring context, and the inline docs digest — under
+ * bounded concurrency (Story #4952).
+ *
+ * None of the three reads a value the others produce, so the result is a pure
+ * function of `seed` and the injected config: the assembled envelope is
+ * **byte-identical** to the serial build for the same inputs, whichever order
+ * the three happen to settle in. `concurrentMap` preserves input order, so the
+ * destructuring below is positional and stable.
+ *
+ * `docsContextFiles` is emptied for the `buildAuthoringContext` call: the
+ * per-plan digest-file path needs a plan id that does not exist yet — the
+ * inline digest gathered alongside it replaces that pointer.
+ *
+ * @param {{
+ *   seed: string,
+ *   epicTitle: string,
+ *   excludeIds?: Iterable<number|string>,
+ *   provider: object,
+ *   config: object,
+ *   settings: object,
+ *   cwd?: string,
+ * }} args
+ * @returns {Promise<{
+ *   duplicates: Array<object>,
+ *   authoring: object,
+ *   docsContext: { mode: 'digest-inline', digest: string }|null,
+ * }>}
+ */
+async function gatherEnvelopeInputs({
+  seed,
+  epicTitle,
+  excludeIds = [],
+  provider,
+  config,
+  settings,
+  cwd,
+}) {
+  const paths = settings?.paths ?? {};
+  const [duplicates, authoring, inlineDigest] = await concurrentMap(
+    [
+      () => searchStoryDuplicates({ seed, provider, config, excludeIds }),
+      () =>
+        buildAuthoringContext(
+          0,
+          /* provider (unused behind the prefetch seam) */ {},
+          { ...settings, docsContextFiles: [] },
+          {
+            epic: { id: 0, title: epicTitle, body: seed },
+            github: config.github ?? null,
+            cwd,
+          },
+        ),
+      () =>
+        buildDocsDigest({
+          docsContextFiles: settings?.docsContextFiles,
+          docsRoot: paths.docsRoot,
+        }),
+    ],
+    (gather) => gather(),
+    // The per-mode envelope gathers (Story #4952): the duplicate search, the
+    // authoring-context fold and the docs digest have no data dependency on
+    // one another, so their serialization was incidental and `/plan` paid it
+    // with the operator waiting at Gate #1.
+    { concurrency: FANOUT_CONCURRENCY },
+  );
+
+  return {
+    duplicates,
+    authoring,
+    docsContext:
+      inlineDigest == null
+        ? null
+        : { mode: 'digest-inline', digest: inlineDigest },
+  };
+}
+
 /**
  * Build the seed-file (ideation) envelope. No parent ticket
  * exists yet — creation moves to the persist half — so the open-Story
@@ -836,37 +913,17 @@ async function buildSeedFileModeEnvelope({
     );
   }
 
-  const duplicates = await searchStoryDuplicates({
+  // Dup search, the authoring-context fold grounded in the seed prose, and the
+  // inline docs digest are independent — gathered concurrently (Story #4952).
+  const { duplicates, authoring, docsContext } = await gatherEnvelopeInputs({
     seed: content,
+    epicTitle: seedFilePath ?? 'seed',
     provider,
     config,
+    settings,
+    cwd,
   });
 
-  // Fold the authoring-context builders grounded in the seed prose.
-  // `docsContextFiles` is emptied for this call: the per-plan digest-file
-  // path needs a plan id that does not exist yet — the inline digest
-  // below replaces it.
-  const authoring = await buildAuthoringContext(
-    0,
-    /* provider (unused behind the prefetch seam) */ {},
-    { ...settings, docsContextFiles: [] },
-    {
-      epic: { id: 0, title: seedFilePath ?? 'seed', body: content },
-      github: config.github ?? null,
-      cwd,
-    },
-  );
-
-  const paths = settings?.paths ?? {};
-  const inlineDigest = await buildDocsDigest({
-    docsContextFiles: settings?.docsContextFiles,
-    docsRoot: paths.docsRoot,
-  });
-  const docsContext =
-    inlineDigest == null
-      ? null
-      : { mode: 'digest-inline', digest: inlineDigest };
-
   const limits = getLimits(config);
   const heuristics = resolveRiskHeuristics(config);
 
@@ -892,7 +949,7 @@ async function buildSeedFileModeEnvelope({
     docsContext,
     bddRunner: authoring.bddRunner,
     bddScenarios: authoring.bddScenarios,
-    memoryFreshness: authoring.memoryFreshness,
+    memoryPoolAdvisory: authoring.memoryPoolAdvisory,
     priorFeedback: authoring.priorFeedback,
     ticketSchema: TICKET_SCHEMA_DESCRIPTOR,
     maxTickets: limits.maxTickets,
@@ -975,7 +1032,8 @@ async function fetchSourceTickets(ticketIds, provider) {
         state: ticket.state ?? undefined,
       };
     },
-    { concurrency: SOURCE_TICKET_FETCH_CONCURRENCY },
+    // `--tickets` source-ticket hydration: one independent read per id.
+    { concurrency: FANOUT_CONCURRENCY },
   );
 }
 
@@ -1001,37 +1059,18 @@ async function buildTicketsModeEnvelope({
     .map((t) => `# ${t.title}\n\n${t.body}`)
     .join('\n\n---\n\n');
 
-  const duplicates = await searchStoryDuplicates({
+  // Same three independent gathers as seed-file mode, concurrent under the
+  // same bound (Story #4952); only the source-ticket hydration above is a
+  // genuine data dependency, because `seed` is derived from it.
+  const { duplicates, authoring, docsContext } = await gatherEnvelopeInputs({
     seed,
+    epicTitle: sourceTickets[0]?.title ?? 'tickets',
+    excludeIds: ticketIds,
     provider,
     config,
-    excludeIds: ticketIds,
-  });
-
-  const authoring = await buildAuthoringContext(
-    0,
-    {},
-    { ...settings, docsContextFiles: [] },
-    {
-      epic: {
-        id: 0,
-        title: sourceTickets[0]?.title ?? 'tickets',
-        body: seed,
-      },
-      github: config.github ?? null,
-      cwd,
-    },
-  );
-
-  const paths = settings?.paths ?? {};
-  const inlineDigest = await buildDocsDigest({
-    docsContextFiles: settings?.docsContextFiles,
-    docsRoot: paths.docsRoot,
+    settings,
+    cwd,
   });
-  const docsContext =
-    inlineDigest == null
-      ? null
-      : { mode: 'digest-inline', digest: inlineDigest };
 
   const limits = getLimits(config);
   const heuristics = resolveRiskHeuristics(config);
@@ -1053,7 +1092,7 @@ async function buildTicketsModeEnvelope({
     docsContext,
     bddRunner: authoring.bddRunner,
     bddScenarios: authoring.bddScenarios,
-    memoryFreshness: authoring.memoryFreshness,
+    memoryPoolAdvisory: authoring.memoryPoolAdvisory,
     priorFeedback: authoring.priorFeedback,
     ticketSchema: TICKET_SCHEMA_DESCRIPTOR,
     maxTickets: limits.maxTickets,
@@ -1147,12 +1186,26 @@ async function buildAmendmentModeEnvelope({
 
   const heuristics = resolveRiskHeuristics(config);
   const limits = getLimits(config);
-  const duplicates = await searchStoryDuplicates({
-    seed: priorBody,
-    provider,
-    config,
-    excludeIds: [amendsId],
-  });
+  // Story #4952 — this builder's independent-gather set has exactly one
+  // member. `provider.getTicket` above is a hard data dependency (the prior
+  // body IS the seed), and the mode deliberately carries no authoring-context
+  // fold and no docs digest — the prior artifacts are the grounding. It still
+  // goes through the same bounded gather as the other two builders so one file
+  // does not carry two ways of gathering independent envelope inputs.
+  const [duplicates] = await concurrentMap(
+    [
+      () =>
+        searchStoryDuplicates({
+          seed: priorBody,
+          provider,
+          config,
+          excludeIds: [amendsId],
+        }),
+    ],
+    (gather) => gather(),
+    // Same independent-gather fan-out as the seed-mode envelope above.
+    { concurrency: FANOUT_CONCURRENCY },
+  );
 
   return {
     mode: 'amends',

package/.agents/scripts/lib/orchestration/plan-persist/fan-out-gate.js

@@ -7,6 +7,7 @@
 
 import { Logger } from '../../Logger.js';
 import {
+  CONFLICT_KINDS,
   renderFanOutEvidence,
   renderFanOutRemedy,
   renderHardConflictError,
@@ -54,6 +55,15 @@ export function enforceFanOutGate(
 }
 
 /**
+ * Report every soft finding the validator produced, each under its own kind.
+ *
+ * Only the {@link CONFLICT_KINDS} are cross-Story conflicts. The advisory
+ * kinds — `spec-word-budget` and the sizing findings — are single-Story
+ * nudges, and announcing them as conflicts overstated them and taught readers
+ * to discount the whole channel (Story #4907). `fan-out-warning` is excluded
+ * throughout: {@link enforceFanOutGate} owns it and has already either thrown
+ * or logged the override.
+ *
  * @param {object[]} findings
  * @param {string} [tag]
  */
@@ -62,10 +72,26 @@ export function surfaceSoftConflictFindings(findings, tag = 'plan-persist') {
     (f) => f?.severity === 'soft' && f?.kind !== 'fan-out-warning',
   );
   if (soft.length === 0) return;
-  Logger.warn(
-    `[${tag}] ${soft.length} soft cross-Story conflict finding(s) — review before approving the plan:`,
-  );
-  for (const finding of soft) {
-    Logger.warn(`[${tag}] soft conflict: ${renderHardConflictError(finding)}`);
+  const conflicts = soft.filter((f) => CONFLICT_KINDS.has(f?.kind));
+  const advisories = soft.filter((f) => !CONFLICT_KINDS.has(f?.kind));
+  if (conflicts.length > 0) {
+    Logger.warn(
+      `[${tag}] ${conflicts.length} soft cross-Story conflict finding(s) — review before approving the plan:`,
+    );
+    for (const finding of conflicts) {
+      Logger.warn(
+        `[${tag}] soft conflict: ${renderHardConflictError(finding)}`,
+      );
+    }
+  }
+  if (advisories.length > 0) {
+    Logger.warn(
+      `[${tag}] ${advisories.length} advisory finding(s) — the persist proceeds:`,
+    );
+    for (const finding of advisories) {
+      Logger.warn(
+        `[${tag}] advisory (${finding.kind}): ${renderHardConflictError(finding)}`,
+      );
+    }
   }
 }

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -38,11 +38,14 @@
  */
 
 import { rm } from 'node:fs/promises';
-import path from 'node:path';
 import { getLimits, PROJECT_ROOT } from '../../config-resolver.js';
 import { gitSpawn } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
 import { sweepTempRetention } from '../../temp-retention.js';
+import {
+  concurrentMap,
+  FANOUT_CONCURRENCY,
+} from '../../util/concurrent-map.js';
 import {
   deriveStoryShape,
   LITE_ROUTE_LABEL,
@@ -410,6 +413,198 @@ export async function reapStalePlanDirs({
   return { reaped: result.purged.map((entry) => entry.path) };
 }
 
+/**
+ * Fail closed on a payload that cannot be persisted, and warn on an
+ * explicitly-authorized over-budget one. Extracted from `runPlanPersist`
+ * (Story #4926) so the entry point carries the flow, not the guards.
+ *
+ * @param {unknown} rawStories
+ * @param {{ maxTickets: number, allowOverBudget: boolean }} limits
+ * @returns {void}
+ * @throws {Error} On an empty payload or an unauthorized over-budget one.
+ */
+function assertPersistablePlan(rawStories, { maxTickets, allowOverBudget }) {
+  if (!Array.isArray(rawStories) || rawStories.length === 0) {
+    throw new Error(
+      '[plan-persist] stories payload must be a non-empty array ' +
+        '(--stories <file>). Default is one Story.',
+    );
+  }
+  if (rawStories.length <= maxTickets) return;
+  if (!allowOverBudget) {
+    throw new Error(
+      `[plan-persist] Stories (${rawStories.length}) exceed the reviewability ` +
+        `budget (${maxTickets}). Re-scope, or rerun with --allow-over-budget.`,
+    );
+  }
+  Logger.warn(
+    `[plan-persist] Persisting an over-budget plan: ${rawStories.length} ` +
+      `Stories vs. budget ${maxTickets} (--allow-over-budget).`,
+  );
+}
+
+/**
+ * Enforce the draft-reachability critic: orphans throw, a skip is ledgered.
+ *
+ * @param {{ status: string, reasons: string[], orphans?: object[] }} reachability
+ * @param {object} config
+ * @returns {Promise<void>}
+ * @throws {Error} `PLAN_REACHABILITY_ORPHANS` when the draft orphans a Story.
+ */
+async function enforceReachability(reachability, config) {
+  if (reachability.status === 'orphans') {
+    const err = new Error(renderReachabilityOrphans(reachability));
+    err.code = 'PLAN_REACHABILITY_ORPHANS';
+    err.orphans = reachability.orphans;
+    throw err;
+  }
+  Logger.info(`[plan-persist] reachability: ${reachability.reasons[0]}`);
+  if (reachability.status === 'skipped') {
+    await appendCriticSkip(
+      {
+        critic: 'reachability',
+        reasons: reachability.reasons,
+        cli: 'plan-persist',
+      },
+      config,
+    );
+  }
+}
+
+/**
+ * Write the per-Story checkpoint, upsert the plan-summary comment, and flip
+ * every created Story to `agent::ready`. Terminal ordering is load-bearing:
+ * `agent::ready` lands last so it can honestly mean "fully persisted"
+ * (Story #4541). A dry run performs none of it.
+ *
+ * **The checkpoints fan out; the phase boundary does not** (Story #4952). The
+ * per-Story upserts are independent of one another and run under bounded
+ * concurrency, but the `await` on that whole fan-out is what keeps the
+ * Story #4541 invariant intact: *every* checkpoint is on its ticket before the
+ * first `agent::ready` flip is issued, so `ready` still means "fully
+ * persisted" and a `/deliver` that picks a Story up cannot read a null
+ * checkpoint. Concurrency inside the phase is safe; overlapping the phases is
+ * the race this ordering exists to close.
+ *
+ * @param {object} args
+ * @returns {Promise<void>}
+ */
+async function persistStoryArtifacts({
+  provider,
+  created,
+  primary,
+  route,
+  summaryBody,
+}) {
+  const cohort = created.map((createdStory) => ({
+    slug: createdStory.slug,
+    id: createdStory.id,
+  }));
+  await concurrentMap(
+    created,
+    (story) =>
+      writeCheckpointV2(provider, story.id, {
+        persist: {
+          completedAt: new Date().toISOString(),
+          storyCount: created.length,
+          primaryStoryId: primary.id,
+          stories: cohort,
+        },
+        // Ledger the authored route verdict — the recorded reason and the
+        // per-Story shape evidence, including a shape-refused claim — on plan
+        // state (Story #4722). No authored verdict writes no block: absence
+        // is the standard full path.
+        ...(route ? { route } : {}),
+      }),
+    // The per-Story checkpoint upserts (Story #4952): each targets a
+    // different issue and reads nothing another writes, so this loop was
+    // serial only by construction — but see {@link persistStoryArtifacts}
+    // for the phase ordering that is *not* incidental.
+    { concurrency: FANOUT_CONCURRENCY },
+  );
+  await upsertStructuredComment(
+    provider,
+    primary.id,
+    PLAN_SUMMARY_COMMENT_TYPE,
+    summaryBody,
+  );
+  await markStoriesReady({ provider, created });
+}
+
+/**
+ * Remove this run's plan directory on terminal success, then sweep the
+ * abandoned ones terminal-success cleanup can never reach (Story #4541).
+ *
+ * @param {{ config: object, planDir: string|null, skipCleanup: boolean }} args
+ * @returns {Promise<void>}
+ */
+async function cleanupPlanDirs({ config, planDir, skipCleanup }) {
+  if (!skipCleanup && planDir) {
+    try {
+      await rm(planDir, { recursive: true, force: true });
+    } catch (err) {
+      Logger.warn(`[plan-persist] temp cleanup skipped: ${err.message}`);
+    }
+  }
+  await reapStalePlanDirs({ config, keepDir: skipCleanup ? planDir : null });
+}
+
+/**
+ * Log the effective complexity route (Story #4722). Lite is upheld by the
+ * shape backstop; anything else reports why it fell back to full.
+ *
+ * @param {object|null} route
+ * @param {boolean} isLiteRoute
+ * @returns {void}
+ */
+function logEffectiveRoute(route, isLiteRoute) {
+  if (isLiteRoute) {
+    Logger.info(
+      `[plan-persist] ceremony-lite route upheld by the shape backstop: ` +
+        `created Stories carry the ${LITE_ROUTE_LABEL} hint ` +
+        `(recorded reason: ${route.authored.reason}). /deliver re-derives ` +
+        'the route from each Story body — the label is never the control signal.',
+    );
+    return;
+  }
+  if (route) {
+    Logger.warn(
+      `[plan-persist] ${route.reasons.join('; ')} — persisting as full ` +
+        '(no route hint label).',
+    );
+  }
+}
+
+/**
+ * Log the operator-facing persist epilogue: adoption, the ready primary, the
+ * deliver command, and the cohort grouping label.
+ *
+ * @param {{ created: object[], primary: object, planRunLabel: string }} args
+ * @returns {void}
+ */
+function logPersistEpilogue({ created, primary, planRunLabel }) {
+  const adopted = created.filter((story) => story.adopted);
+  if (adopted.length > 0) {
+    Logger.info(
+      `[plan-persist] resumed ${adopted.length} of ${created.length} Story(ies) ` +
+        `from a previous persist: ${adopted.map((s2) => `#${s2.id}`).join(', ')}.`,
+    );
+  }
+  Logger.info(
+    `[plan-persist] Persisted ${created.length} Story(ies)` +
+      `; primary #${primary.id} is agent::ready.`,
+  );
+  Logger.info(
+    `[plan-persist] Deliver with: /deliver ${created.map((s2) => s2.id).join(' ')}`,
+  );
+  // Metadata only — a GitHub filter for the cohort this run authored, never
+  // a delivery-resolution input (/deliver stays ids-only, Story #4540).
+  Logger.info(
+    `[plan-persist] Cohort grouping label: ${planRunLabel} — filter with ` +
+      `label:${planRunLabel}`,
+  );
+}
+
 /**
  * Execute the flat Story persist end to end.
  *
@@ -475,26 +670,10 @@ export async function runPlanPersist({
   // through the shared standalone ledger (Story #4541).
   const runStartedAt = opts.metricsSince ?? new Date().toISOString();
 
-  if (!Array.isArray(rawStories) || rawStories.length === 0) {
-    throw new Error(
-      '[plan-persist] stories payload must be a non-empty array ' +
-        '(--stories <file>). Default is one Story.',
-    );
-  }
-
-  const maxTickets = getLimits(config).maxTickets;
-  if (rawStories.length > maxTickets && !allowOverBudget) {
-    throw new Error(
-      `[plan-persist] Stories (${rawStories.length}) exceed the reviewability ` +
-        `budget (${maxTickets}). Re-scope, or rerun with --allow-over-budget.`,
-    );
-  }
-  if (rawStories.length > maxTickets && allowOverBudget) {
-    Logger.warn(
-      `[plan-persist] Persisting an over-budget plan: ${rawStories.length} ` +
-        `Stories vs. budget ${maxTickets} (--allow-over-budget).`,
-    );
-  }
+  assertPersistablePlan(rawStories, {
+    maxTickets: getLimits(config).maxTickets,
+    allowOverBudget,
+  });
 
   Logger.info(
     `[plan-persist] Running cross-validation on ${rawStories.length} Story ticket(s)...`,
@@ -516,23 +695,7 @@ export async function runPlanPersist({
     tickets: rawStories,
     config,
   });
-  if (reachability.status === 'orphans') {
-    const err = new Error(renderReachabilityOrphans(reachability));
-    err.code = 'PLAN_REACHABILITY_ORPHANS';
-    err.orphans = reachability.orphans;
-    throw err;
-  }
-  Logger.info(`[plan-persist] reachability: ${reachability.reasons[0]}`);
-  if (reachability.status === 'skipped') {
-    await appendCriticSkip(
-      {
-        critic: 'reachability',
-        reasons: reachability.reasons,
-        cli: 'plan-persist',
-      },
-      config,
-    );
-  }
+  await enforceReachability(reachability, config);
 
   // Split policy + inline Spec fold (over-budget Specs fail closed — no docs/).
   const { stories } = assemblePlanStories(rawStories, {
@@ -559,19 +722,7 @@ export async function runPlanPersist({
     injectedRules,
   });
   const isLiteRoute = route?.route === 'lite';
-  if (isLiteRoute) {
-    Logger.info(
-      `[plan-persist] ceremony-lite route upheld by the shape backstop: ` +
-        `created Stories carry the ${LITE_ROUTE_LABEL} hint ` +
-        `(recorded reason: ${route.authored.reason}). /deliver re-derives ` +
-        'the route from each Story body — the label is never the control signal.',
-    );
-  } else if (route) {
-    Logger.warn(
-      `[plan-persist] ${route.reasons.join('; ')} — persisting as full ` +
-        '(no route hint label).',
-    );
-  }
+  logEffectiveRoute(route, isLiteRoute);
 
   const { created, planRunLabel } = await createStoryIssues({
     provider,
@@ -616,35 +767,13 @@ export async function runPlanPersist({
   });
 
   if (!dryRun) {
-    for (const story of created) {
-      await writeCheckpointV2(provider, story.id, {
-        persist: {
-          completedAt: new Date().toISOString(),
-          storyCount: created.length,
-          primaryStoryId: primary.id,
-          stories: created.map((createdStory) => ({
-            slug: createdStory.slug,
-            id: createdStory.id,
-          })),
-        },
-        // Ledger the authored route verdict — the recorded reason and the
-        // per-Story shape evidence, including a shape-refused claim — on plan
-        // state (Story #4722). No authored verdict writes no block: absence
-        // is the standard full path.
-        ...(route ? { route } : {}),
-      });
-    }
-    await upsertStructuredComment(
+    await persistStoryArtifacts({
       provider,
-      primary.id,
-      PLAN_SUMMARY_COMMENT_TYPE,
+      created,
+      primary,
+      route,
       summaryBody,
-    );
-
-    // Terminal step: every checkpoint above is now on every Story, so
-    // `agent::ready` can honestly mean "fully persisted" (Story #4541).
-    // Anything that picks a Story up from here reads a real checkpoint.
-    await markStoriesReady({ provider, created });
+    });
   }
 
   const supersede = await runSupersedePhase({
@@ -660,37 +789,8 @@ export async function runPlanPersist({
   // any) rather than reading as a clean no-op — Story #4554.
   supersede.sourceTicketOrigin = sourceTicketOrigin;
 
-  if (!skipCleanup && planDir) {
-    try {
-      await rm(planDir, { recursive: true, force: true });
-    } catch (err) {
-      Logger.warn(`[plan-persist] temp cleanup skipped: ${err.message}`);
-    }
-  }
-  // Terminal-success cleanup only ever removes *this* run's planDir, so
-  // abandoned ones accumulated forever. Sweep them (Story #4541).
-  await reapStalePlanDirs({ config, keepDir: skipCleanup ? planDir : null });
-
-  const adopted = created.filter((story) => story.adopted);
-  if (adopted.length > 0) {
-    Logger.info(
-      `[plan-persist] resumed ${adopted.length} of ${created.length} Story(ies) ` +
-        `from a previous persist: ${adopted.map((s2) => `#${s2.id}`).join(', ')}.`,
-    );
-  }
-  Logger.info(
-    `[plan-persist] Persisted ${created.length} Story(ies)` +
-      `; primary #${primary.id} is agent::ready.`,
-  );
-  Logger.info(
-    `[plan-persist] Deliver with: /deliver ${created.map((s2) => s2.id).join(' ')}`,
-  );
-  // Metadata only — a GitHub filter for the cohort this run authored, never
-  // a delivery-resolution input (/deliver stays ids-only, Story #4540).
-  Logger.info(
-    `[plan-persist] Cohort grouping label: ${planRunLabel} — filter with ` +
-      `label:${planRunLabel}`,
-  );
+  await cleanupPlanDirs({ config, planDir, skipCleanup });
+  logPersistEpilogue({ created, primary, planRunLabel });
 
   return {
     stories: created,