mandrel 2.53.0 → 2.55.0

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';
@@ -88,6 +88,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 +213,7 @@ async function runSupersedePhase(args) {
       reason: `phase-error: ${err.message}`,
       closed: [],
       planned: [],
+      epicRollup: { closed: [], pending: [] },
       skipped: [],
       failed: (args.sourceTicketIds ?? []).map((ticket) => ({
         ticket,
@@ -831,6 +833,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 +873,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 +904,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 +933,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

@@ -28,6 +28,15 @@
  *      partial failure reports which tickets were and were not closed so the
  *      operator can finish by hand.
  *
+ * The close also strips the source ticket's `agent::*` label (Story #5255).
+ * A retired ticket has no agent state, and the one it kept was read as live
+ * work: `agent::blocked` is the state a Story must be in to be re-planned, so
+ * this path closes exactly the tickets carrying it, and a closed-but-blocked
+ * child pinned its container Epic open on every rollup thereafter. The
+ * derivation in `ticketing/bulk.js` now ignores closed children's labels too —
+ * that half covers the tickets already closed and the ones closed by hand;
+ * this one stops new ones being written.
+ *
  * Idempotency is keyed off the `superseded-by` structured-comment marker
  * (`upsertStructuredComment`), not a bare `postComment`, so a re-run cannot
  * double-comment.
@@ -36,10 +45,12 @@
  */
 
 import { Logger } from '../../Logger.js';
+import { AGENT_LABELS } from '../../label-constants.js';
 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. */
@@ -55,6 +66,40 @@ const SUPERSEDED_BY_COMMENT_TYPE = 'superseded-by';
  */
 export const SUPERSEDE_CLOSE_REASON = 'not_planned';
 
+/**
+ * Every `agent::*` label, as the set the supersede close strips.
+ *
+ * A retired ticket has no agent state. `agent::done` would be the wrong
+ * substitute — the work was re-planned, never delivered — so the label is
+ * removed rather than rewritten, and the ticket ends carrying only its
+ * `type::`/domain labels and the supersede comment that explains it.
+ */
+const AGENT_STATE_LABELS = Object.freeze(Object.values(AGENT_LABELS));
+
+/**
+ * The single `updateTicket` mutation that retires a source ticket.
+ *
+ * Closing and clearing the state ride one write: two calls could leave the
+ * ticket closed but still wearing `agent::blocked`, which is the shape that
+ * pinned a container Epic open forever (Story #5255).
+ *
+ * A ticket with no `agent::*` label gets the bare close, unchanged from before
+ * that Story — `updateTicket` merges a `labels` mutation by reading the issue
+ * back, so an unconditional empty `remove` would buy a wasted round-trip per
+ * superseded ticket. `_ticketSnapshot` feeds that merge the copy
+ * `probeSourceTicket` already fetched.
+ *
+ * @param {{ labels?: unknown }} ticket The probe's fresh copy.
+ * @returns {object} Mutations for `provider.updateTicket`.
+ */
+function supersedeCloseMutations(ticket) {
+  const close = { state: 'closed', state_reason: SUPERSEDE_CLOSE_REASON };
+  const labels = Array.isArray(ticket?.labels) ? ticket.labels : [];
+  const remove = AGENT_STATE_LABELS.filter((label) => labels.includes(label));
+  if (remove.length === 0) return close;
+  return { ...close, labels: { remove }, _ticketSnapshot: ticket };
+}
+
 /**
  * Coerce one `supersedes[]` entry into `{ id, note }`.
  *
@@ -329,13 +374,22 @@ export function buildSupersedeCommentBody({
 /**
  * Resolve the live state of a source ticket.
  *
- * @returns {Promise<{ ok: true, state: string } | { ok: false, reason: string }>}
+ * The ticket itself rides along so the close can strip the `agent::*` label
+ * without a second read: `updateTicket`'s label merge takes a
+ * `_ticketSnapshot` for exactly this, and this probe has already paid for the
+ * fresh copy.
+ *
+ * @returns {Promise<{ ok: true, state: string, ticket: object } | { ok: false, reason: string }>}
  */
 async function probeSourceTicket(provider, id) {
   try {
     const ticket = await provider.getTicket(id, { fresh: true });
     if (!ticket) return { ok: false, reason: 'not-found' };
-    return { ok: true, state: String(ticket.state ?? 'open').toLowerCase() };
+    return {
+      ok: true,
+      state: String(ticket.state ?? 'open').toLowerCase(),
+      ticket,
+    };
   } catch (err) {
     return { ok: false, reason: `inaccessible: ${err.message}` };
   }
@@ -370,10 +424,7 @@ async function closeOneSupersededTicket({
         sourceTicketIds,
       }),
     );
-    await provider.updateTicket(id, {
-      state: 'closed',
-      state_reason: SUPERSEDE_CLOSE_REASON,
-    });
+    await provider.updateTicket(id, supersedeCloseMutations(probe.ticket));
     return { outcome: 'closed' };
   } catch (err) {
     return { outcome: 'failed', reason: err.message };
@@ -394,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) {
@@ -405,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.
  *
@@ -421,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>}
@@ -430,6 +528,7 @@ export async function closeSupersededTickets({
   stories,
   created,
   sourceTicketIds,
+  config,
   dryRun = false,
   closeSuperseded = true,
 }) {
@@ -482,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;
 }
@@ -563,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._',
+  ];
+}