mandrel 2.24.0 → 2.25.0

package/.agents/scripts/lib/orchestration/run-scoped-config.js

@@ -0,0 +1,276 @@
+/**
+ * run-scoped-config.js — pin the config values a delivery run was seeded
+ * from, and fail closed when the file they came from changed underneath it.
+ *
+ * The problem this exists for: `single-story-init.js` resolves config and
+ * seeds `story-<id>` from `project.baseBranch`; `single-story-close` used to
+ * re-resolve the SAME key and run close-validation, format-autofix, the gate
+ * baseline and base-sync against its own second answer. Nothing pinned the
+ * first value and nothing checked the two agreed — and the window between
+ * them is however long implementation takes. A concurrent session editing
+ * `.agentrc.json` / `.agentrc.local.json` mid-run therefore base-synced a
+ * Story against a base it was never seeded from, which surfaced only as an
+ * ordinary content conflict with nothing pointing at config.
+ *
+ * The base a Story was seeded from is a property of **that run**, not of
+ * whatever the config file says later. So init pins it and close reads the
+ * pin back.
+ *
+ * ## Where the pin lives
+ *
+ * The `story-init` structured comment, not a temp log: the post-land tail
+ * purges the temp tree, while the ticket comment survives every close re-run
+ * and every recovery path. `single-story-init.js` already upserts that
+ * comment; `pinRunScopedConfig` supplies the block it records, and
+ * `resolveRunScopedConfig` reads it back through the existing
+ * `findStructuredComment` seam.
+ *
+ * ## Adding another run-scoped key
+ *
+ * Add one row to `RUN_SCOPED_CONFIG_KEYS`. Both halves — the pin init writes
+ * and the comparison close makes — enumerate that registry, so a new key
+ * needs no second mechanism, no reader change and no writer change. Only
+ * `baseBranch` is enforced today because only its corruption is destructive
+ * (a wrong base merged into the Story branch permanently contaminates the
+ * branch and its PR diff); ceremony profile, quality floors and the
+ * concurrency cap are deliberately NOT pinned here.
+ */
+
+import { parseFencedJsonComment } from './structured-comment-parser.js';
+import { findStructuredComment } from './ticketing.js';
+
+/**
+ * The run-scoped config registry. One row per key whose value belongs to the
+ * run that seeded the Story rather than to the current contents of the config
+ * file. `read` resolves the key from a resolved config (including its
+ * default); `label` is the dotted config path the operator has to go fix.
+ *
+ * @type {Record<string, { read: (config: object) => unknown, label: string }>}
+ */
+const RUN_SCOPED_CONFIG_KEYS = {
+  baseBranch: {
+    read: (config) => config?.project?.baseBranch ?? 'main',
+    label: 'project.baseBranch',
+  },
+};
+
+/**
+ * Snapshot the run-scoped config values from a resolved config. This is the
+ * write half of the pin: `single-story-init.js` records the returned object
+ * in the `story-init` receipt so close can compare against it later.
+ *
+ * @param {object} config Resolved config (`resolveConfig` output).
+ * @param {typeof RUN_SCOPED_CONFIG_KEYS} [keys] Registry override — the
+ *   default is the module registry; supplying one is how a caller (or a test)
+ *   exercises the registry-driven property without a second mechanism.
+ * @returns {Record<string, unknown>} the pinned values, keyed by config key.
+ */
+export function pinRunScopedConfig(config, keys = RUN_SCOPED_CONFIG_KEYS) {
+  const pinned = {};
+  for (const [key, spec] of Object.entries(keys)) {
+    pinned[key] = spec.read(config);
+  }
+  return pinned;
+}
+
+/**
+ * Read the pinned block out of the run's `story-init` receipt.
+ *
+ * Three distinct non-success states, all reported rather than collapsed —
+ * the whole point of this module is that a fallback is never silent:
+ *   - `absent`: no `story-init` comment on the ticket. Real and expected —
+ *     the upsert is best-effort (init logs and continues on failure), and a
+ *     recovery path may close a Story whose init predates this receipt.
+ *   - `unreadable`: the comment exists but carries no parseable JSON payload.
+ *   - `provider-error`: the comment read itself failed.
+ *
+ * @param {{
+ *   provider: object,
+ *   storyId: number,
+ *   findCommentFn?: typeof findStructuredComment,
+ * }} args
+ * @returns {Promise<{ status: string, values: Record<string, unknown>|null, detail: string|null }>}
+ */
+async function readRunScopedConfigReceipt({
+  provider,
+  storyId,
+  findCommentFn = findStructuredComment,
+}) {
+  let comment;
+  try {
+    comment = await findCommentFn(provider, Number(storyId), 'story-init');
+  } catch (err) {
+    return {
+      status: 'provider-error',
+      values: null,
+      detail: `story-init comment could not be read (${err?.message ?? err})`,
+    };
+  }
+  if (!comment) {
+    return {
+      status: 'absent',
+      values: null,
+      detail: 'no story-init comment on the ticket',
+    };
+  }
+  const payload = parseFencedJsonComment(comment);
+  if (!payload || typeof payload !== 'object') {
+    return {
+      status: 'unreadable',
+      values: null,
+      detail: 'story-init comment carries no parseable JSON payload',
+    };
+  }
+  // Receipts written before the `runScopedConfig` block existed carry the
+  // pinned values as top-level payload fields (`baseBranch` has been recorded
+  // there since Story #831). Reading the payload itself as the fallback block
+  // is what lets a Story initialized by an older init still close against its
+  // own pinned base instead of degrading to the fallback warning.
+  const block =
+    payload.runScopedConfig && typeof payload.runScopedConfig === 'object'
+      ? payload.runScopedConfig
+      : payload;
+  return { status: 'found', values: block, detail: null };
+}
+
+/**
+ * Build the refusal message for a mid-run config change. Names BOTH values
+ * for every conflicting key — the pinned one and the one config resolves to
+ * now — because "which base was this branch actually seeded from" is the
+ * question the operator could not previously answer.
+ *
+ * @param {{ storyId: number, conflicts: Array<{ label: string, pinned: unknown, current: unknown }> }} args
+ * @returns {string}
+ */
+function formatRunScopedConflict({ storyId, conflicts }) {
+  const rows = conflicts.map(
+    ({ label, pinned, current }) =>
+      `${label}: pinned at init = \`${String(pinned)}\`, currently resolves to \`${String(current)}\``,
+  );
+  return (
+    `[single-story-close] Refusing to close Story #${storyId}: run-scoped config changed mid-run. ` +
+    `${rows.join('; ')}. ` +
+    'The Story branch was seeded from the pinned value, so closing against the current one would ' +
+    'base-sync it onto a base it was never seeded from. No base-sync, format-autofix or gate run was ' +
+    'performed. A concurrent session most likely edited `.agentrc.json` / `.agentrc.local.json` during ' +
+    'the implementation window: restore the pinned value and re-run close, or re-init the Story against ' +
+    'the new value deliberately.'
+  );
+}
+
+/**
+ * Resolve the run-scoped config for a close, preferring the run's pin over a
+ * fresh resolution of the config file.
+ *
+ * Throws on disagreement — fail closed, before any gate, format-autofix or
+ * base-sync has run, with both values named. Never silently prefers either
+ * side: preferring the pin would base-sync correctly but hide a config change
+ * the operator needs to know about, and preferring current config is the bug
+ * this module exists to close.
+ *
+ * @param {{
+ *   provider: object,
+ *   storyId: number,
+ *   config: object,
+ *   keys?: typeof RUN_SCOPED_CONFIG_KEYS,
+ *   findCommentFn?: typeof findStructuredComment,
+ *   progress?: (tag: string, msg: string) => void,
+ * }} args
+ * @returns {Promise<{
+ *   values: Record<string, unknown>,
+ *   confirmed: boolean,
+ *   receiptStatus: string,
+ *   warning: string|null,
+ * }>} `confirmed` is true only when every key came from the receipt and
+ *   agreed with current config — i.e. when downstream remediation may safely
+ *   assume the pinned value is the one in play.
+ */
+export async function resolveRunScopedConfig({
+  provider,
+  storyId,
+  config,
+  keys = RUN_SCOPED_CONFIG_KEYS,
+  findCommentFn,
+  progress,
+}) {
+  const current = pinRunScopedConfig(config, keys);
+  const receipt = await readRunScopedConfigReceipt({
+    provider,
+    storyId,
+    findCommentFn,
+  });
+
+  if (receipt.status !== 'found') {
+    // A missing receipt is a real state, not an error — but the fallback is
+    // announced, because a silent one reintroduces exactly the bug above.
+    const warning =
+      `Run-scoped config could not be read from the run's init receipt ` +
+      `(${receipt.detail}); falling back to the currently-resolved config ` +
+      `(${describeValues(current, keys)}). This close cannot confirm the Story ` +
+      'was seeded from these values.';
+    progress?.('PIN', `⚠️ ${warning}`);
+    return {
+      values: current,
+      confirmed: false,
+      receiptStatus: receipt.status,
+      warning,
+    };
+  }
+
+  const values = {};
+  const conflicts = [];
+  const unpinned = [];
+  for (const [key, spec] of Object.entries(keys)) {
+    const pinned = receipt.values?.[key];
+    if (pinned === undefined || pinned === null) {
+      unpinned.push(spec.label);
+      values[key] = current[key];
+      continue;
+    }
+    values[key] = pinned;
+    if (pinned !== current[key]) {
+      conflicts.push({ label: spec.label, pinned, current: current[key] });
+    }
+  }
+
+  if (conflicts.length > 0) {
+    throw new Error(formatRunScopedConflict({ storyId, conflicts }));
+  }
+
+  if (unpinned.length > 0) {
+    const warning =
+      `The run's init receipt pins no value for ${unpinned.join(', ')}; ` +
+      `falling back to the currently-resolved config (${describeValues(values, keys)}).`;
+    progress?.('PIN', `⚠️ ${warning}`);
+    return {
+      values,
+      confirmed: false,
+      receiptStatus: receipt.status,
+      warning,
+    };
+  }
+
+  progress?.(
+    'PIN',
+    `📌 Run-scoped config pinned by the story-init receipt (${describeValues(values, keys)}).`,
+  );
+  return {
+    values,
+    confirmed: true,
+    receiptStatus: receipt.status,
+    warning: null,
+  };
+}
+
+/**
+ * Render `label=value` pairs for the operator-facing lines above.
+ *
+ * @param {Record<string, unknown>} values
+ * @param {typeof RUN_SCOPED_CONFIG_KEYS} keys
+ * @returns {string}
+ */
+function describeValues(values, keys) {
+  return Object.entries(keys)
+    .map(([key, spec]) => `${spec.label}=\`${String(values[key])}\``)
+    .join(', ');
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js

@@ -35,6 +35,7 @@ import {
  *   cwd: string,
  *   worktreePath: string|null,
  *   baseBranch: string,
+ *   baseConfirmed?: boolean,
  *   storyBranch: string,
  *   storyId: number,
  *   provider: object,
@@ -46,6 +47,7 @@ export async function runBaseSyncPhase({
   cwd,
   worktreePath,
   baseBranch,
+  baseConfirmed = false,
   storyBranch,
   storyId,
   provider,
@@ -69,6 +71,7 @@ export async function runBaseSyncPhase({
       storyId,
       syncCwd,
       baseBranch,
+      baseConfirmed,
       storyBranch,
       result: syncResult,
       progress,
@@ -95,6 +98,7 @@ export async function runBaseSyncPhase({
  *   storyId: number,
  *   syncCwd: string,
  *   baseBranch: string,
+ *   baseConfirmed?: boolean,
  *   storyBranch: string,
  *   result: { kind: string, conflictFiles?: string[], stderr?: string },
  *   progress: (tag: string, msg: string) => void,
@@ -105,6 +109,7 @@ export async function handleSyncFailure({
   storyId,
   syncCwd,
   baseBranch,
+  baseConfirmed = false,
   storyBranch,
   result,
   progress,
@@ -113,6 +118,7 @@ export async function handleSyncFailure({
     storyId,
     storyBranch,
     baseBranch,
+    baseConfirmed,
     syncCwd,
     result,
   });
@@ -147,13 +153,23 @@ export async function handleSyncFailure({
  * Build the markdown body posted on a base-sync failure. Pure; exported
  * for tests so the operator-recoverable surface stays reviewable.
  *
- * @param {{ storyId: number, storyBranch: string, baseBranch: string, syncCwd: string, result: { kind: string, conflictFiles?: string[], stderr?: string } }} args
+ * Story #4891 — `baseConfirmed` gates the merge-the-base recovery block, and
+ * defaults to `false` so it fails closed. Telling the operator to run
+ * `git merge origin/<baseBranch>` is actively harmful when `<baseBranch>` is
+ * not the base the Story was seeded from: it permanently contaminates the
+ * branch and its PR diff with an unrelated base. Close confirms the base
+ * against the run's `story-init` receipt before that advice is emitted; when
+ * it could not (receipt absent, unreadable, or unpinned), the operator is
+ * told to establish the real base first instead.
+ *
+ * @param {{ storyId: number, storyBranch: string, baseBranch: string, baseConfirmed?: boolean, syncCwd: string, result: { kind: string, conflictFiles?: string[], stderr?: string } }} args
  * @returns {string}
  */
 export function buildSyncFailureCommentBody({
   storyId,
   storyBranch,
   baseBranch,
+  baseConfirmed = false,
   syncCwd,
   result,
 }) {
@@ -170,15 +186,30 @@ export function buildSyncFailureCommentBody({
     `sync against \`origin/${baseBranch}\` could not complete. The Story has`,
     `been transitioned to \`agent::blocked\`. To resume:`,
     '',
-    '```bash',
-    `cd ${syncCwd}`,
-    `git fetch origin ${baseBranch}`,
-    `git merge --no-edit origin/${baseBranch}`,
-    '# resolve any conflicts, then:',
-    `git add -A ; git commit --no-edit`,
-    '# re-run close:',
-    `node .agents/scripts/single-story-close.js --story ${storyId}`,
-    '```',
+    ...(baseConfirmed
+      ? [
+          '```bash',
+          `cd ${syncCwd}`,
+          `git fetch origin ${baseBranch}`,
+          `git merge --no-edit origin/${baseBranch}`,
+          '# resolve any conflicts, then:',
+          `git add -A ; git commit --no-edit`,
+          '# re-run close:',
+          `node .agents/scripts/single-story-close.js --story ${storyId}`,
+          '```',
+        ]
+      : [
+          `⚠️ **No merge advice: \`${baseBranch}\` is unconfirmed.** This close could not`,
+          `read the base branch \`${storyBranch}\` was seeded from off the run's`,
+          '`story-init` receipt, so merging that base in could contaminate the branch',
+          'and its PR diff with an unrelated base. Establish the real base first —',
+          `check the \`story-init\` comment on this issue and \`project.baseBranch\` in`,
+          '`.agentrc.json` / `.agentrc.local.json` — then merge that base and re-run:',
+          '',
+          '```bash',
+          `node .agents/scripts/single-story-close.js --story ${storyId}`,
+          '```',
+        ]),
   ];
   if (kind === 'conflict' && fileList.length > 0) {
     lines.push('', '**Conflicting files:**', '', ...fileList);

package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js

@@ -95,6 +95,7 @@ import {
   confirmStoryMerged as defaultConfirmStoryMerged,
   readPrMergeState as defaultReadPrMergeState,
 } from '../../../single-story/confirm-merge.js';
+import { pollUntil } from '../../../util/poll-loop.js';
 import {
   emitMergeFlipFailed as defaultEmitMergeFlipFailed,
   MERGED_FLIP_FAILED_BLOCK_CLASS,
@@ -363,7 +364,8 @@ function formatUnlandedFriction({
   const remedy =
     blockClass === 'checks-failed'
       ? `A required check is **red**. Fix the failure and push a new commit on \`story-${storyId}\`; ` +
-        `auto-merge stays armed across retries. Watch the checks with:\n\n` +
+        `the red disarms auto-merge, and only a green on a new head SHA re-arms it — ` +
+        `re-running the failed job is forbidden. Watch the checks with:\n\n` +
         `\`\`\`bash\n${NEXT_COMMANDS.watchCi(storyId, prNumber)}\n\`\`\``
       : `Resolve the underlying condition (branch protection, required checks, ` +
         `or a manual merge), then resume the land:\n\n` +
@@ -851,7 +853,20 @@ export async function runConfirmMergePhase({
       `cumulative budget=${maxBudgetSeconds}s)...`,
   );
 
-  while (true) {
+  /**
+   * One poll iteration. Returns `{ done: false }` to keep polling, or
+   * `{ done: true, outcome }` with the phase's terminal. Story #4873 lifted
+   * this body out of a bespoke unbounded loop so the cadence is owned by the
+   * shared {@link pollUntil} primitive — the loop below sleeps, aborts, and
+   * counts ticks in exactly one place for every wait in the codebase. Every
+   * budget, floor, and classification decision is unchanged; only who owns the
+   * `await sleep(...)` moved.
+   *
+   * A throw from any of the terminal handlers is captured rather than allowed
+   * to escape into `pollUntil` (which treats a throwing `fn` as a non-match
+   * and would spin forever on it); the caller re-throws it after the loop.
+   */
+  async function runMergePoll() {
     const probe = await readPrWaitProbeFn({
       prNumber,
       gh: injectedGh,
@@ -875,26 +890,44 @@ export async function runConfirmMergePhase({
       maxBudgetSeconds,
     };
 
+    // Heartbeat (Story #4873). A backgrounded close writes this phase's
+    // progress to its own output file, and between the opening banner and the
+    // terminal there used to be NOTHING for minutes at a time — so an
+    // orchestrator watching that file could not tell a healthy in-flight wait
+    // from a wedged process without going back to GitHub itself. One line per
+    // poll makes the file's own growth the liveness signal.
+    progress?.(
+      'CONFIRM',
+      `⏱  poll ${polls}: PR #${prNumber} state=${probe.state ?? 'unknown'} ` +
+        `checks=${probe.checksStatus ?? 'unknown'} ` +
+        `mergeState=${probe.mergeStateStatus ?? 'unknown'} ` +
+        `(${waitBudget.waitedSeconds}s of ${maxWaitSeconds}s this invocation; ` +
+        `${waitBudget.cumulativeSeconds}s of ${maxBudgetSeconds}s cumulative)` +
+        (probe.error ? ` — probe error: ${probe.error}` : ''),
+    );
+
     if (probe.state === 'MERGED' || probe.mergedAt) {
-      return onMergeObserved({
-        storyId,
-        storyBranch,
-        baseBranch,
-        prNumber,
-        prUrl,
-        cwd,
-        config,
-        provider,
-        progress,
-        injectedGh,
-        injectedNotify,
-        readPrMergeStateFn,
-        confirmStoryMergedFn,
-        runPostLandTailFn,
-        emitMergeFlipFailedFn,
-        prProbe: probe,
-        elapsedSeconds: Math.round(waitedMs / 1000),
-      });
+      return doneWith(
+        await onMergeObserved({
+          storyId,
+          storyBranch,
+          baseBranch,
+          prNumber,
+          prUrl,
+          cwd,
+          config,
+          provider,
+          progress,
+          injectedGh,
+          injectedNotify,
+          readPrMergeStateFn,
+          confirmStoryMergedFn,
+          runPostLandTailFn,
+          emitMergeFlipFailedFn,
+          prProbe: probe,
+          elapsedSeconds: Math.round(waitedMs / 1000),
+        }),
+      );
     }
 
     // Everything below funnels into ONE terminal exit (Story #4710): each
@@ -987,16 +1020,18 @@ export async function runConfirmMergePhase({
     }
 
     if (unlanded) {
-      return blockOnUnlanded({
-        storyId,
-        prNumber,
-        prUrl,
-        ...unlanded,
-        provider,
-        progress,
-        classifyMergeBlockFn,
-        emitMergeUnlandedFn,
-      });
+      return doneWith(
+        await blockOnUnlanded({
+          storyId,
+          prNumber,
+          prUrl,
+          ...unlanded,
+          provider,
+          progress,
+          classifyMergeBlockFn,
+          emitMergeUnlandedFn,
+        }),
+      );
     }
 
     // This invocation's bound expired → PENDING. Deliberately NOT a block:
@@ -1011,16 +1046,43 @@ export async function runConfirmMergePhase({
           `${waitBudget.cumulativeSeconds}s of ${maxBudgetSeconds}s cumulative). PR #${prNumber} still in flight ` +
           `(checks=${probe.checksStatus ?? 'unknown'}). Story stays at agent::closing — resumable.`,
       );
-      return {
+      return doneWith({
         confirmed: false,
         terminal: 'pending',
         reason: `merge wait bound reached with the PR still in flight (checks=${probe.checksStatus ?? 'unknown'})`,
         prProbe: probe,
         waitBudget,
         elapsedSeconds: waitBudget.waitedSeconds,
-      };
+      });
     }
 
-    await sleepFn(intervalMs);
+    return { done: false };
   }
+
+  const tick = await pollUntil({
+    fn: async () => {
+      try {
+        return await runMergePoll();
+      } catch (err) {
+        // A terminal handler threw. `pollUntil` treats a throwing `fn` as a
+        // non-match and would poll forever on it, so the throw is carried out
+        // as a match and re-raised below.
+        return { done: true, thrown: err };
+      }
+    },
+    predicate: (result) => result?.done === true,
+    intervalMs,
+    // The wait owns its own bounds (`maxWaitSeconds` → `pending`,
+    // `maxBudgetSeconds` → blocked), and both are decided from the probe
+    // inside the tick. A second, cruder wall-clock timeout here would throw
+    // past those classifications.
+    sleepFn: (ms) => sleepFn(ms),
+  });
+  if (tick.thrown) throw tick.thrown;
+  return tick.outcome;
+}
+
+/** Wrap a phase terminal as the poll loop's match. */
+function doneWith(outcome) {
+  return { done: true, outcome };
 }