mandrel 2.54.0 → 2.56.0

package/.agents/scripts/lib/orchestration/plan-persist/epic-adoption.js

@@ -145,6 +145,7 @@ export async function adoptContainerEpic({
     provider,
     epicNumber: target.id,
     childIds,
+    created: all,
   });
 
   Logger.info(
@@ -164,6 +165,24 @@ export async function adoptContainerEpic({
 /**
  * Write the appended checklist back to the Epic body.
  *
+ * **The body is re-read `fresh` immediately before the append.** `target.body`
+ * was captured by `resolveAdoptionTarget` before the first Story was created,
+ * which on a cohort of any size is many seconds and several writes ago. An
+ * append computed against that snapshot and PATCHed wholesale silently drops
+ * every checklist row another writer added in between — a concurrent persist
+ * run adopting the same Epic, or an operator ticking a child off by hand. The
+ * body is a full-document write, so a stale base is not a merge conflict; it
+ * is a silent revert.
+ *
+ * This **narrows** the read-then-PATCH window; it does not close it. Nothing
+ * here is atomic, and GitHub's issue API offers no compare-and-swap, so a
+ * write landing between this read and this PATCH is still lost. Narrowing it
+ * from "the whole create phase" to "one round-trip" is the available fix; a
+ * real one needs an API that does not exist.
+ *
+ * The PATCH is skipped when the append changes nothing, so re-running an
+ * adoption that already landed writes nothing at all.
+ *
  * Non-fatal: the Stories are already live, and the native sub-issue edges
  * written next are the other half of the linkage. Losing the checklist costs
  * the body-only fallback path, not the grouping.
@@ -179,8 +198,9 @@ async function appendChecklist({ provider, target, childIds }) {
     );
     return;
   }
-  const next = appendEpicChildIds(target.body, childIds);
-  if (next === target.body) return;
+  const base = await readFreshEpicBody({ provider, target });
+  const next = appendEpicChildIds(base, childIds);
+  if (next === base) return;
   try {
     await provider.updateTicket(target.id, { body: next });
   } catch (err) {
@@ -190,3 +210,30 @@ async function appendChecklist({ provider, target, childIds }) {
     );
   }
 }
+
+/**
+ * Re-read the Epic's body, bypassing any provider cache.
+ *
+ * `{ fresh: true }` is the whole point: the adoption path already read this
+ * issue once, so a cached read would hand back the very snapshot this function
+ * exists to replace. Falls back to the snapshot when the re-read fails or the
+ * provider has no `getTicket` — a stale base still appends the run's own
+ * children, which beats not linking them.
+ *
+ * @param {{ provider: object, target: { id: number, body: string } }} opts
+ * @returns {Promise<string>}
+ */
+async function readFreshEpicBody({ provider, target }) {
+  if (typeof provider?.getTicket !== 'function') return target.body;
+  try {
+    const fresh = await provider.getTicket(target.id, { fresh: true });
+    if (typeof fresh?.body === 'string') return fresh.body;
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] could not re-read Epic #${target.id} before appending its ` +
+        `checklist (${err?.message ?? err}); appending to the body read earlier. ` +
+        'A child linked by another writer since then may be dropped.',
+    );
+  }
+  return target.body;
+}

package/.agents/scripts/lib/orchestration/plan-persist/epic-ops.js

@@ -123,10 +123,10 @@ async function ensureEpicLabel({ provider }) {
  * @returns {Promise<{ id: number, url?: string }|null>}
  */
 async function findExistingEpic({ provider, fingerprint }) {
-  if (typeof provider?.listIssuesByLabel !== 'function') return null;
+  if (typeof provider?.listTicketsByLabel !== 'function') return null;
   try {
     const marker = epicFingerprintMarker(fingerprint);
-    const found = await provider.listIssuesByLabel({
+    const found = await provider.listTicketsByLabel({
       state: 'open',
       labels: TYPE_LABELS.EPIC,
     });
@@ -134,9 +134,12 @@ async function findExistingEpic({ provider, fingerprint }) {
       String(issue?.body ?? '').includes(marker),
     );
     if (!hit) return null;
-    const id = Number(hit.number ?? hit.id);
+    // The declared ticket shape: `id` is the issue number. The `number`-then-
+    // `id` fallback this replaced would have adopted the resumed container by
+    // database id — a number that exists, resolves to nothing, fails no guard.
+    const id = Number(hit.id);
     if (!Number.isInteger(id) || id <= 0) return null;
-    return { id, url: hit.html_url ?? hit.url ?? undefined };
+    return { id, url: hit.url ?? undefined };
   } catch (err) {
     Logger.warn(
       `[plan-persist] Epic resume lookup failed (${err.message}); creating a new container.`,
@@ -145,6 +148,26 @@ async function findExistingEpic({ provider, fingerprint }) {
   }
 }
 
+/**
+ * Index a cohort's already-known database ids by issue number.
+ *
+ * A resumed run's adopted Stories carry no `internalId` — they were found by
+ * listing, not created — so they are simply absent from the map and fall
+ * through to the lookup. Absence means "not known here", never "has none".
+ *
+ * @param {Array<{ id?: number, internalId?: number }>|undefined} created
+ * @returns {Map<number, number>}
+ */
+function internalIdsFrom(created) {
+  const map = new Map();
+  for (const story of Array.isArray(created) ? created : []) {
+    if (Number.isInteger(story?.id) && typeof story?.internalId === 'number') {
+      map.set(story.id, story.internalId);
+    }
+  }
+  return map;
+}
+
 /**
  * Link the created Stories under the Epic as native sub-issue edges.
  *
@@ -156,10 +179,18 @@ async function findExistingEpic({ provider, fingerprint }) {
  * children exactly the way creation does — one mirroring rule, not two that
  * drift.
  *
- * @param {{ provider: object, epicNumber: number, childIds: number[] }} opts
+ * `created` is optional and carries the cohort's `createIssue` responses, so
+ * the linker can skip the id lookup for every child this run made itself.
+ *
+ * @param {{ provider: object, epicNumber: number, childIds: number[], created?: Array<{ id: number, internalId?: number }> }} opts
  * @returns {Promise<{ added: number, skipped: number, failed: number }|null>}
  */
-export async function mirrorSubIssueEdges({ provider, epicNumber, childIds }) {
+export async function mirrorSubIssueEdges({
+  provider,
+  epicNumber,
+  childIds,
+  created = [],
+}) {
   if (
     typeof provider?.getDependencyWriteContext !== 'function' ||
     typeof provider?.getTicket !== 'function'
@@ -176,6 +207,7 @@ export async function mirrorSubIssueEdges({ provider, epicNumber, childIds }) {
     const summary = await linkStoriesToEpic({
       epicNumber,
       childIssueNumbers: childIds,
+      knownInternalIds: internalIdsFrom(created),
       getTicket: (issueNumber) => provider.getTicket(issueNumber),
       owner,
       repo,
@@ -285,6 +317,7 @@ export async function createContainerEpic({
       provider,
       epicNumber: existing.id,
       childIds,
+      created,
     });
     return {
       id: existing.id,
@@ -303,11 +336,14 @@ export async function createContainerEpic({
     labels: [TYPE_LABELS.EPIC],
   });
 
-  const epicNumber = result.number ?? result.id;
+  // `createIssue` declares both `id` and `number` and sets them to the same
+  // issue number; reading one of them is the whole contract.
+  const epicNumber = result.id;
   const edges = await mirrorSubIssueEdges({
     provider,
     epicNumber,
     childIds,
+    created,
   });
 
   Logger.info(

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

@@ -38,7 +38,7 @@
  */
 
 import { rm } from 'node:fs/promises';
-import { getLimits, PROJECT_ROOT } from '../../config-resolver.js';
+import { getLimits, getPaths, PROJECT_ROOT } from '../../config-resolver.js';
 import { gitSpawn } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
 import { sweepTempRetention } from '../../temp-retention.js';
@@ -68,6 +68,7 @@ import {
   renderHardConflictError,
 } from '../ticket-validator-conflicts.js';
 import { upsertStructuredComment } from '../ticketing.js';
+import { recordAuditFilings, withAuditLabels } from './audit-provenance.js';
 import {
   resolveContainerEpic,
   resolveCrossPlanLinks,
@@ -88,6 +89,7 @@ import {
   PLAN_SUMMARY_COMMENT_TYPE,
 } from './summary.js';
 import { closeSupersededTickets } from './supersede-ops.js';
+import { predictWaveSerialisation } from './wave-serialisation.js';
 
 /** Checkpoint schema version written on each Story's story-plan-state. */
 const PLAN_CHECKPOINT_SCHEMA_VERSION_V2 = 2;
@@ -212,6 +214,7 @@ async function runSupersedePhase(args) {
       reason: `phase-error: ${err.message}`,
       closed: [],
       planned: [],
+      epicRollup: { closed: [], pending: [] },
       skipped: [],
       failed: (args.sourceTicketIds ?? []).map((ticket) => ({
         ticket,
@@ -778,7 +781,8 @@ export async function runPlanPersist({
   });
 
   // Split policy + inline Spec fold (over-budget Specs fail closed — no docs/).
-  const { stories } = assemblePlanStories(rawStories, {
+  const seedContent = planContextEnvelope?.seed?.content ?? '';
+  const { stories: assembled } = assemblePlanStories(rawStories, {
     sharedSpec: techSpecContent,
     planAcceptance: planAcceptance ?? undefined,
     sourceTicketIds,
@@ -789,9 +793,16 @@ export async function runPlanPersist({
     // is the **fallback** — it is carried onto every Story that did not
     // attribute its own `provenance`, which keeps an un-attributed plan exactly
     // as recall-safe as it was. Empty for a `--tickets` run, a no-op there.
-    provenanceSource: planContextEnvelope?.seed?.content ?? '',
+    provenanceSource: seedContent,
   });
 
+  // Stamp the `audit::*` labels the dedup corpus is listed by. Without them a
+  // Story this path files is absent from the pool an indexed sweep matches
+  // against, and an indexed run answers exact lookups from that pool without
+  // ever reaching the provider — so the provenance footers alone leave it
+  // invisible (Story #5307). A non-audit seed carries none: a no-op there.
+  const stories = withAuditLabels(assembled, seedContent);
+
   // Story #5045: the cross-Story conflict passes re-run over the assembled,
   // footer-stamped bodies — the artifact persist actually writes — before any
   // GitHub call, so a policy upgrade still refuses the plan pre-creation.
@@ -822,6 +833,10 @@ export async function runPlanPersist({
       opts: { dryRun, routeLabel: isLiteRoute ? LITE_ROUTE_LABEL : null },
     });
 
+  // What this run filed, recorded where the next audit sweep reads it
+  // (Story #5307). A dry run created nothing, and the call knows it.
+  recordAuditFilings({ stories, created, tickets: rawStories, dryRun });
+
   const primary = created[0];
   const waveTable = buildWaveTable(
     stories.map((s) => ({
@@ -831,6 +846,17 @@ export async function runPlanPersist({
     })),
   );
 
+  // Story #5265: the table says which Stories share an order; the dispatcher
+  // decides which of those actually run together, and it decides on the
+  // evidence-widened footprint. Run its own predicate over the assembled
+  // bodies — the exact artifact the tick will read back off GitHub — so the
+  // comment names the serialisation instead of promising parallelism the
+  // next tick refuses. `tempRoot` is threaded for the same reason the tick
+  // threads it: the scrape must ignore this project's scratch root.
+  const waveCollisions = predictWaveSerialisation(waveTable, stories, {
+    tempRoot: getPaths(config).tempRoot,
+  });
+
   // Story #4541: `readPlanMetrics` is declared `(epicId, config)` but was
   // called with `config` first, so the ledger path resolver received the
   // config object as an `epicId` and threw its guard on every single run —
@@ -860,6 +886,7 @@ export async function runPlanPersist({
     // collisions the conflict passes found belong on the same surface, or the
     // promise is the only half anyone reads.
     conflictFindings: assembledConflicts,
+    waveCollisions,
   });
 
   if (!dryRun) {
@@ -890,6 +917,10 @@ export async function runPlanPersist({
     stories,
     created,
     sourceTicketIds,
+    // Story #5280 — closing a source ticket is a child state change, so the
+    // phase re-derives the container above it. It needs the config the rollup
+    // reads its board and operator handle from.
+    config,
     dryRun,
     closeSuperseded,
   });
@@ -915,6 +946,11 @@ export async function runPlanPersist({
     reachability,
     freshness,
     waveTable,
+    // Story #5265 AC-2/AC-4: both halves of what persist concluded but used
+    // to keep to itself — the `refactors-existing` declarations it rewrote,
+    // and the same-order pairs the dispatcher will serialize.
+    assumptionNormalizations: validated.normalizations ?? [],
+    waveCollisions,
     supersede,
     epic: containerEpic,
   };

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -1098,6 +1098,11 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
       id,
       title: story.title,
       url: result.url,
+      // Kept, not discarded (Story #5280). `createIssue` hands back the
+      // database id, which is the only identifier the native sub-issue write
+      // accepts — and dropping it here is what made the Epic linker re-read
+      // every Story this run had just created to recover it.
+      internalId: result.internalId,
       // True when the provider's retry probe adopted an issue a lost-response
       // first attempt had already filed — pre-existing either way.
       adopted: result.adopted === true,

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

@@ -14,6 +14,7 @@
  */
 
 import { computeStoryWaves } from '../dependency-analyzer.js';
+import { renderPredictedSerialisationLines } from './wave-serialisation.js';
 
 /**
  * Structured-comment type for the persist summary.
@@ -129,6 +130,7 @@ export function buildPlanSummaryCommentBody({
   planMetricsLine = null,
   stories = null,
   conflictFindings = null,
+  waveCollisions = null,
   // legacy unused knobs kept so older test call sites don't crash mid-migration
   single = null,
   amend = null,
@@ -180,6 +182,7 @@ export function buildPlanSummaryCommentBody({
     '#### Delivery order (`depends_on`)',
     '',
     ...renderWaveTableLines(waveTable),
+    ...renderPredictedSerialisationLines(waveCollisions),
     ...renderSharedEditorLines(conflictFindings),
     '',
     `_Deliver with \`${deliverCommand}\` — \`/mandrel-deliver\` resolves the dependency graph from live state, so edges may point at Stories from earlier plan runs._`,

package/.agents/scripts/lib/orchestration/plan-persist/supersede-ops.js

@@ -50,6 +50,7 @@ import {
   concurrentMap,
   FANOUT_CONCURRENCY,
 } from '../../util/concurrent-map.js';
+import { rollUpEpicForStory } from '../epic-rollup.js';
 import { upsertStructuredComment } from '../ticketing.js';
 
 /** Structured-comment type marking a source issue as superseded. */
@@ -444,6 +445,9 @@ async function closeOneSupersededTicket({
  *   slug is the only identifier that means anything before the writes land.
  * @property {Array<{ ticket: number, reason: string }>} skipped
  * @property {Array<{ ticket: number, reason: string }>} failed
+ * @property {{ closed: number[], pending: number[] }} epicRollup Container
+ *   Epics this phase's closes resolved. Empty on a dry run and on a phase that
+ *   closed nothing.
  */
 
 function emptyReport(overrides) {
@@ -455,10 +459,53 @@ function emptyReport(overrides) {
     planned: [],
     skipped: [],
     failed: [],
+    epicRollup: { closed: [], pending: [] },
     ...overrides,
   };
 }
 
+/**
+ * Re-derive the container Epic above every ticket this phase just closed.
+ *
+ * Closing a source ticket is a child state change like any other, and it was
+ * the one edge with no rollup behind it. Superseding a cohort therefore left
+ * its container open indefinitely: every child was closed, so no delivery
+ * would ever run and no land tail would ever fire the derivation. The Epic sat
+ * open above finished work until someone noticed.
+ *
+ * Runs **after** the closes land, never alongside them: the rollup reads each
+ * child's state back, so racing it against the writes it is meant to observe
+ * would derive from a tree half of which has not been written yet.
+ *
+ * Sequential, sharing one `skipEpicIds` set, because siblings share a
+ * container — without it the second ticket re-derives, and re-closes, the Epic
+ * the first already closed. `rollUpEpicForStory` never throws, so no guard is
+ * needed here beyond the phase-level one the caller already holds.
+ *
+ * @param {{ closedIds: number[], provider: object, config?: object }} opts
+ * @returns {Promise<{ closed: number[], pending: number[] }>}
+ */
+async function rollUpContainersFor({ closedIds, provider, config }) {
+  const seen = new Set();
+  const closed = new Set();
+  const pending = new Set();
+  for (const storyId of closedIds) {
+    const outcome = await rollUpEpicForStory({
+      storyId,
+      provider,
+      config,
+      skipEpicIds: seen,
+    });
+    for (const epic of outcome.epics) seen.add(epic.epicId);
+    for (const epicId of outcome.closed) closed.add(epicId);
+    for (const epicId of outcome.pending) pending.add(epicId);
+  }
+  // A container reported pending by one ticket's rollup and closed by a later
+  // one is closed: the last answer saw the whole cohort.
+  for (const epicId of closed) pending.delete(epicId);
+  return { closed: [...closed], pending: [...pending] };
+}
+
 /**
  * Comment on and close every superseded source ticket.
  *
@@ -471,6 +518,7 @@ function emptyReport(overrides) {
  * @param {Array<{ slug: string, supersedes: Array<{ id: number, note: string|null }> }>} args.stories
  * @param {Array<{ slug: string, id: number, title: string }>} args.created
  * @param {number[]} args.sourceTicketIds
+ * @param {object} [args.config] Resolved `.agentrc.json`, for the Epic rollup.
  * @param {boolean} [args.dryRun=false]
  * @param {boolean} [args.closeSuperseded=true]
  * @returns {Promise<SupersedeReport>}
@@ -480,6 +528,7 @@ export async function closeSupersededTickets({
   stories,
   created,
   sourceTicketIds,
+  config,
   dryRun = false,
   closeSuperseded = true,
 }) {
@@ -532,6 +581,14 @@ export async function closeSupersededTickets({
     recordSupersedeOutcome(report, units[index], result);
   });
 
+  if (report.closed.length > 0) {
+    report.epicRollup = await rollUpContainersFor({
+      closedIds: report.closed,
+      provider,
+      config,
+    });
+  }
+
   logSupersedeReport(report);
   return report;
 }
@@ -613,4 +670,10 @@ function logSupersedeReport(report) {
         'close it by hand.',
     );
   }
+  if (report.epicRollup.closed.length > 0) {
+    Logger.info(
+      `[plan-persist] container Epic(s) closed by the supersede rollup: ` +
+        `${report.epicRollup.closed.map((id) => `#${id}`).join(', ')}.`,
+    );
+  }
 }

package/.agents/scripts/lib/orchestration/plan-persist/wave-serialisation.js

@@ -0,0 +1,110 @@
+/**
+ * wave-serialisation.js — what the dispatcher will actually do with the wave
+ * table plan-persist prints (Story #5265).
+ *
+ * Kept out of `summary.js` because it answers a different question. The
+ * summary module renders receipts persist already computed; this one runs the
+ * *runtime's* collision predicate over the assembled Story bodies to work out
+ * which of the table's promises the next tick will refuse to keep.
+ *
+ * @module lib/orchestration/plan-persist/wave-serialisation
+ */
+
+import {
+  detectCollision,
+  OVERLAP_SOURCES,
+  renderScrapeAttribution,
+} from '../../wave-runner/footprint.js';
+
+/**
+ * Predict which same-wave pairs the dispatch guard will actually refuse to
+ * co-dispatch (Story #5265).
+ *
+ * The wave table answers a `depends_on` question, and the runtime answers a
+ * different one: `stories-wave-tick.js` withholds on {@link detectCollision},
+ * whose footprint is the declared `changes[]` **plus** every path scraped out
+ * of the Story's title, spec and serialized body — and that body carries
+ * `## Verify`, so two Stories that merely run the same gate script share a
+ * path neither will edit. The table therefore promised parallelism the very
+ * next tick refused, with nothing anywhere reconciling the two.
+ *
+ * This runs the runtime's own exported predicate — not a reimplementation of
+ * it — pairwise within each wave, so the prediction cannot drift from the
+ * behaviour it predicts.
+ *
+ * @param {ReturnType<typeof buildWaveTable>} waveTable
+ * @param {Array<{ slug: string, title?: string, body?: string, spec?: string, changes?: Array }>} stories
+ * @param {{ tempRoot?: string }} [options]
+ * @returns {Array<{ wave: number, slugs: [string, string], paths: string[], source: string, attribution: object[] }>}
+ */
+export function predictWaveSerialisation(waveTable, stories, options = {}) {
+  const bySlug = new Map(
+    (Array.isArray(stories) ? stories : []).map((s) => [s.slug, s]),
+  );
+  const out = [];
+  for (const { wave, stories: members } of Array.isArray(waveTable)
+    ? waveTable
+    : []) {
+    for (let i = 0; i < members.length; i += 1) {
+      for (let j = i + 1; j < members.length; j += 1) {
+        const a = bySlug.get(members[i].slug);
+        const b = bySlug.get(members[j].slug);
+        if (!a || !b) continue;
+        const collision = detectCollision(a, b, options);
+        if (collision) {
+          out.push({
+            wave,
+            slugs: [members[i].slug, members[j].slug],
+            ...collision,
+          });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Render the predicted serialisation beside the wave table (Story #5265).
+ *
+ * Same shape as {@link renderSharedEditorLines} on purpose: both are caveats
+ * against the same promise, and an operator should read them the same way.
+ * The difference is what they know — the shared-editor pass names paths two
+ * Stories both *write*, this one names every pair the dispatcher will refuse
+ * to run together whatever the reason, including the pairs whose only shared
+ * path was scraped out of a `## Verify` line.
+ *
+ * @param {ReturnType<typeof predictWaveSerialisation>} collisions
+ * @returns {string[]}
+ */
+export function renderPredictedSerialisationLines(collisions) {
+  const list = Array.isArray(collisions) ? collisions : [];
+  if (list.length === 0) return [];
+  const rows = list.map((c) => {
+    const scraped = renderScrapeAttribution(c.attribution);
+    return `| \`${c.slugs[0]}\` + \`${c.slugs[1]}\` | ${c.paths
+      .map((p) => `\`${p}\``)
+      .join(', ')} | ${c.source} | ${scraped ? `\`${scraped}\`` : '—'} |`;
+  });
+  const scrapedOnly = list.filter(
+    (c) => c.source === OVERLAP_SOURCES.SCRAPED,
+  ).length;
+  return [
+    '',
+    `#### ⚠️ Predicted serialisation (${list.length} same-order pair(s))`,
+    '',
+    '| Stories | Colliding paths | Overlap source | Scraped from |',
+    '| --- | --- | --- | --- |',
+    ...rows,
+    '',
+    '_The dispatcher compares the **evidence-widened** footprint — declared ' +
+      '`changes[]` plus every path named in the title, `## Spec` and the rest ' +
+      'of the body — so these pairs are shown in one order above but will be ' +
+      `dispatched one at a time. ${scrapedOnly} pair(s) collide only on ` +
+      'scraped paths; the "Scraped from" column names the field each such ' +
+      'path was read out of, so a shared `## Verify` command is ' +
+      'distinguishable from a genuine unpredicted edit target. The guard is ' +
+      'deliberately not narrowed to `changes[]`: the declaration is a lower ' +
+      'bound (Story #4875) and under-serialising is the worse failure._',
+  ];
+}