mandrel 2.59.0 → 2.60.0

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

@@ -18,12 +18,18 @@
  *
  * ## 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.
+ * The init envelope on disk — `<tempRoot>/orchestration/story-init-result-<id>.log`,
+ * written by `single-story-init.js` via `emitTerseResult`. Story #5343 retired
+ * the `story-init` ticket comment (the delivery-comment diet), so the envelope
+ * is the pin's home; it is written before init returns and read at close, well
+ * before the post-land tail purges the temp tree.
+ *
+ * That is a hard cutover, not a dual read. The envelope is written by the same
+ * process, in the same run, that seeds the branch — so if it is gone, the temp
+ * tree was reaped and this is a much later close, exactly the case a stale
+ * `story-init` comment would have answered with equal uncertainty. A missing
+ * pin is never a refusal: it degrades to the currently-resolved config with a
+ * loud, announced warning, and close simply cannot confirm the base.
  *
  * ## Adding another run-scoped key
  *
@@ -36,8 +42,7 @@
  * concurrency cap are deliberately NOT pinned here.
  */
 
-import { parseFencedJsonComment } from './structured-comment-parser.js';
-import { findStructuredComment } from './ticketing.js';
+import { readRunScopedPin } from './story-init-envelope.js';
 
 /**
  * The run-scoped config registry. One row per key whose value belongs to the
@@ -57,7 +62,7 @@ const RUN_SCOPED_CONFIG_KEYS = {
 /**
  * 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.
+ * on its init envelope so close can compare against it later.
  *
  * @param {object} config Resolved config (`resolveConfig` output).
  * @param {typeof RUN_SCOPED_CONFIG_KEYS} [keys] Registry override — the
@@ -74,63 +79,43 @@ export function pinRunScopedConfig(config, keys = RUN_SCOPED_CONFIG_KEYS) {
 }
 
 /**
- * Read the pinned block out of the run's `story-init` receipt.
+ * Compare the receipt's pinned values against the currently-resolved ones,
+ * one registry row at a time. Split out of `resolveRunScopedConfig` so the
+ * row walk and the three outcomes it feeds (confirmed / conflict / unpinned)
+ * read separately.
  *
- * 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.
+ * A row the receipt pins nothing for is `unpinned`, not a conflict: an older
+ * receipt simply predates that registry row, and falling back to current
+ * config for it is correct as long as the fallback is announced.
  *
  * @param {{
- *   provider: object,
- *   storyId: number,
- *   findCommentFn?: typeof findStructuredComment,
+ *   pinned: Record<string, unknown>,
+ *   current: Record<string, unknown>,
+ *   keys: typeof RUN_SCOPED_CONFIG_KEYS,
  * }} args
- * @returns {Promise<{ status: string, values: Record<string, unknown>|null, detail: string|null }>}
+ * @returns {{
+ *   values: Record<string, unknown>,
+ *   conflicts: Array<{ label: string, pinned: unknown, current: unknown }>,
+ *   unpinned: string[],
+ * }}
  */
-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',
-    };
+function comparePinToCurrent({ pinned: pin, current, keys }) {
+  const values = {};
+  const conflicts = [];
+  const unpinned = [];
+  for (const [key, spec] of Object.entries(keys)) {
+    const pinned = pin?.[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] });
+    }
   }
-  // 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 };
+  return { values, conflicts, unpinned };
 }
 
 /**
@@ -169,11 +154,10 @@ function formatRunScopedConflict({ storyId, conflicts }) {
  * this module exists to close.
  *
  * @param {{
- *   provider: object,
  *   storyId: number,
  *   config: object,
  *   keys?: typeof RUN_SCOPED_CONFIG_KEYS,
- *   findCommentFn?: typeof findStructuredComment,
+ *   readPinFn?: typeof readRunScopedPin,
  *   progress?: (tag: string, msg: string) => void,
  * }} args
  * @returns {Promise<{
@@ -186,52 +170,37 @@ function formatRunScopedConflict({ storyId, conflicts }) {
  *   assume the pinned value is the one in play.
  */
 export async function resolveRunScopedConfig({
-  provider,
   storyId,
   config,
   keys = RUN_SCOPED_CONFIG_KEYS,
-  findCommentFn,
+  readPinFn = readRunScopedPin,
   progress,
 }) {
   const current = pinRunScopedConfig(config, keys);
-  const receipt = await readRunScopedConfigReceipt({
-    provider,
-    storyId,
-    findCommentFn,
-  });
+  const receipt = readPinFn({ storyId: Number(storyId), config });
 
-  if (receipt.status !== 'found') {
-    // A missing receipt is a real state, not an error — but the fallback is
+  if (!receipt) {
+    // A missing pin 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.';
+      `Run-scoped config could not be read from the run's init envelope ` +
+      `(no runScopedConfig pin for Story #${storyId}); 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,
+      receiptStatus: 'absent',
       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] });
-    }
-  }
+  const { values, conflicts, unpinned } = comparePinToCurrent({
+    pinned: receipt,
+    current,
+    keys,
+  });
 
   if (conflicts.length > 0) {
     throw new Error(formatRunScopedConflict({ storyId, conflicts }));
@@ -245,21 +214,16 @@ export async function resolveRunScopedConfig({
     return {
       values,
       confirmed: false,
-      receiptStatus: receipt.status,
+      receiptStatus: 'found',
       warning,
     };
   }
 
   progress?.(
     'PIN',
-    `📌 Run-scoped config pinned by the story-init receipt (${describeValues(values, keys)}).`,
+    `📌 Run-scoped config pinned by the init envelope (${describeValues(values, keys)}).`,
   );
-  return {
-    values,
-    confirmed: true,
-    receiptStatus: receipt.status,
-    warning: null,
-  };
+  return { values, confirmed: true, receiptStatus: 'found', warning: null };
 }
 
 /**

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

@@ -259,7 +259,7 @@ export async function handleSyncFailure({
  * `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
+ * against the run's 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.
  *
@@ -302,9 +302,9 @@ export function buildSyncFailureCommentBody({
       : [
           `⚠️ **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',
+          '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`,
+          `check \`temp/orchestration/story-init-result-${storyId}.log\` and \`project.baseBranch\` in`,
           '`.agentrc.json` / `.agentrc.local.json` — then merge that base and re-run:',
           '',
           '```bash',

package/.agents/scripts/lib/orchestration/single-story-close/phases/graphql-preflight.js

@@ -0,0 +1,137 @@
+/**
+ * phases/graphql-preflight.js — the one precondition a standalone close
+ * checks before it spends anything (Story #5355).
+ *
+ * A Story delivered from a Claude Code web session ran the entire
+ * close-validation gate chain, synced from the base branch and pushed, then
+ * died in the `pull-request` phase on `gh pr create` with a raw HTTP 403:
+ * GitHub's GraphQL API is unreachable from that session, and `gh` routes the
+ * whole `gh pr` surface through it. That 403 was a fact about the session,
+ * knowable before the first gate ran, that the operator paid roughly five
+ * minutes of gates to learn.
+ *
+ * ## Why this is not a pre-gate step
+ *
+ * It sits beside `pre-gate-steps.js` and inverts every clause of that
+ * module's contract, which is why it does not live inside it. Those steps
+ * commit to `story-<id>`, run from the gate phase, and may **never** fail the
+ * close, because each is the refresh half of a loop whose enforcement half
+ * runs immediately afterwards. This one commits nothing, runs from the runner
+ * during `init`, and exists precisely to fail the close — before a single
+ * gate is spawned and before anything is pushed. One module, one contract.
+ *
+ * What it must never do is fail a *healthy* close, which is why an ambiguous
+ * probe is fail-open at its source (`probeGraphqlAvailability`) and a
+ * throwing probe is fail-open here.
+ */
+
+import {
+  describeGraphqlPreflight,
+  probeGraphqlAvailability,
+} from '../../../gh-exec.js';
+import { Logger } from '../../../Logger.js';
+import {
+  STATE_LABELS,
+  transitionTicketState,
+  upsertStructuredComment,
+} from '../../ticketing.js';
+
+/**
+ * Announce a refused preflight on the Story: a `friction` comment carrying
+ * the blocker and its remedy, then the `agent::blocked` transition the
+ * terminal envelope's `blocked` status promises the operator.
+ *
+ * Both writes are best-effort and warn rather than throw, for the reason
+ * `handleSyncFailure` gives: a notification-side failure must not replace the
+ * real blocker with a secondary one — and here the notification travels the
+ * very API surface that is already suspect. Both go through the canonical
+ * mutators; a bare `updateTicket` would skip the Projects v2 column sync and
+ * strand the board on the Story's prior status.
+ *
+ * @param {{ provider: object, storyId: number, reason: string,
+ *   progress: (tag: string, msg: string) => void }} args
+ * @returns {Promise<void>}
+ */
+async function announcePreflightBlock({ provider, storyId, reason, progress }) {
+  const body = [
+    '### Close refused during `init`: GitHub GraphQL preflight',
+    '',
+    reason,
+    '',
+    'Nothing was validated, committed, or pushed — the preflight runs before the',
+    'gate chain, so re-running close from a session that can reach GraphQL starts',
+    'from exactly where this Story stands now:',
+    '',
+    '```bash',
+    `node .agents/scripts/single-story-close.js --story ${storyId}`,
+    '```',
+  ].join('\n');
+  try {
+    await upsertStructuredComment(provider, storyId, 'friction', body);
+    progress('PREFLIGHT', `📝 Posted friction comment on #${storyId}.`);
+  } catch (err) {
+    Logger.warn?.(
+      `[single-story-close] ⚠️ Failed to post preflight friction comment on #${storyId}: ${err?.message ?? err}`,
+    );
+  }
+  try {
+    await transitionTicketState(provider, storyId, STATE_LABELS.BLOCKED, {});
+    progress('PREFLIGHT', `🚧 Flipped Story #${storyId} → agent::blocked.`);
+  } catch (err) {
+    Logger.warn?.(
+      `[single-story-close] ⚠️ Failed to flip Story #${storyId} to agent::blocked: ${err?.message ?? err}`,
+    );
+  }
+}
+
+/**
+ * Preflight GitHub's GraphQL reachability before the close spends anything.
+ *
+ * One cheap API read decides it. An `available` verdict returns null and the
+ * close proceeds exactly as a run with no preflight would; a refusing verdict
+ * announces the block on the Story and returns the descriptor the runner
+ * turns into a `blocked` terminal envelope at phase `init`.
+ *
+ * The probe cannot throw, but a caller-injected one can, and a preflight that
+ * takes down a close it was meant to protect is the one outcome worse than
+ * the late 403 — so a throwing probe is logged and treated as available.
+ *
+ * @param {{
+ *   storyId: number,
+ *   provider: object,
+ *   progress: (tag: string, msg: string) => void,
+ *   ghFacade?: { api: Function },
+ *   probe?: typeof probeGraphqlAvailability,
+ * }} args
+ *   `ghFacade` is the run's own `gh` facade, so the preflight asks the same
+ *   boundary the pull-request phase will later ask rather than a second one
+ *   that could answer differently.
+ * @returns {Promise<{ verdict: string, reason: string }|null>} null when the
+ *   close may proceed.
+ */
+export async function runGraphqlPreflight({
+  storyId,
+  provider,
+  progress,
+  ghFacade,
+  probe = probeGraphqlAvailability,
+}) {
+  let verdict;
+  try {
+    verdict = await probe(ghFacade ? { ghFacade } : undefined);
+  } catch (err) {
+    progress(
+      'PREFLIGHT',
+      `⚠️ GraphQL preflight could not run (close continues): ${err?.message ?? err}`,
+    );
+    return null;
+  }
+  if (verdict?.available !== false) {
+    progress('PREFLIGHT', `✅ GitHub GraphQL reachable (${verdict?.reason}).`);
+    return null;
+  }
+  const reason = describeGraphqlPreflight(verdict);
+  progress('PREFLIGHT', `🛑 ${reason}`);
+  await announcePreflightBlock({ provider, storyId, reason, progress });
+  return { verdict: verdict.verdict, reason };
+}

package/.agents/scripts/lib/orchestration/single-story-close/runner.js

@@ -30,6 +30,7 @@ import { runBaseSyncPhase } from './phases/base-sync.js';
 import { runCloseValidationPhase } from './phases/close-validation.js';
 import { parsePrNumber, runStoryScopeReview } from './phases/code-review.js';
 import { runConfirmMergePhase } from './phases/confirm-merge.js';
+import { runGraphqlPreflight } from './phases/graphql-preflight.js';
 import { parseCloseOptions, resolveWaitForMerge } from './phases/options.js';
 import { ensurePullRequestWith } from './phases/pull-request.js';
 import { pushStoryBranch } from './phases/push.js';
@@ -95,9 +96,18 @@ async function emitTerminal({ terminal, result, config }) {
  *
  * A null `stateReason` keeps the `completed` reading — GitHub defaults to it,
  * and issues closed before the field existed carry null.
+ *
+ * The operator-facing `NOOP` line is emitted here rather than at the call
+ * site: both halves read the same field, and deciding what `not_planned`
+ * means in two places is how the log and the envelope come to disagree about
+ * one Story.
  */
 async function alreadyClosedResult(storyId, stateReason = null, config) {
   if (stateReason === 'not_planned') {
+    progress(
+      'NOOP',
+      `Story #${storyId} is closed as not planned — nothing to land.`,
+    );
     const result = {
       storyId,
       standalone: true,
@@ -120,6 +130,7 @@ async function alreadyClosedResult(storyId, stateReason = null, config) {
     return { success: false, result, terminal };
   }
 
+  progress('NOOP', `Story #${storyId} is already closed. Nothing to do.`);
   const result = {
     storyId,
     standalone: true,
@@ -140,6 +151,61 @@ async function alreadyClosedResult(storyId, stateReason = null, config) {
   return { success: true, result, terminal };
 }
 
+/**
+ * The block class a refused GraphQL preflight reports (Story #5355).
+ *
+ * `api-race-other` is the shared classifier's documented fallback for "a
+ * transient GraphQL/API error, an ambiguous probe result, or a genuinely
+ * novel condition", and a preflight refusal is the third of those. It is
+ * reused rather than joined by a new class on purpose: the class vocabulary
+ * is pinned by `story-deliver-terminal.schema.json`, and this refusal is
+ * required to validate against the shipped schema unchanged. The `reason`
+ * string — not the class — is what names the blocker and its remedy.
+ */
+const PREFLIGHT_BLOCK_CLASS = 'api-race-other';
+
+/**
+ * Terminal for a close the GraphQL preflight refused during `init`.
+ *
+ * Returned rather than thrown: a throw would surface as `failed` at the CLI
+ * boundary, and this is not a crash — it is a classified block detected
+ * before the pipeline spent anything, with the Story already flipped to
+ * `agent::blocked` and a friction comment carrying the remedy. The next
+ * command is the same close, which is exactly right: from a session that can
+ * reach GraphQL it runs to completion from where the Story stands now.
+ *
+ * @param {{ storyId: number, preflight: { verdict: string, reason: string },
+ *   config: object, startedAtMs: number }} args
+ * @returns {Promise<{ success: false, result: object, terminal: object }>}
+ */
+async function preflightBlockedResult({
+  storyId,
+  preflight,
+  config,
+  startedAtMs,
+}) {
+  const result = {
+    storyId,
+    standalone: true,
+    action: 'noop',
+    reason: `graphql-preflight-${preflight.verdict}`,
+  };
+  const terminal = buildTerminalEnvelope({
+    storyId,
+    status: 'blocked',
+    phase: 'init',
+    blocked: {
+      blockClass: PREFLIGHT_BLOCK_CLASS,
+      reason: preflight.reason,
+      frictionCommentId: null,
+    },
+    nextCommand: NEXT_COMMANDS.close(storyId),
+    elapsedSeconds: elapsedSecondsSince(startedAtMs),
+  });
+  await emitTerminal({ terminal, result, config });
+  return { success: false, result, terminal };
+}
+
 /**
  * Project the baselines entries out of close-validation's per-gate outcomes,
  * keyed by the gate's own name (Story #5172).
@@ -534,6 +600,7 @@ export async function runSingleStoryClose({
   injectedGh,
   injectedGitSpawn,
   injectedReleaseLease,
+  injectedGraphqlProbe,
 } = {}) {
   const options = parseCloseOptions({
     storyIdParam,
@@ -586,6 +653,7 @@ export async function runSingleStoryClose({
       injectedGh,
       injectedGitSpawn,
       injectedReleaseLease,
+      injectedGraphqlProbe,
     });
   } catch (err) {
     if (err && typeof err === 'object') {
@@ -837,6 +905,7 @@ async function runClosePipeline({
   injectedGh,
   injectedGitSpawn,
   injectedReleaseLease,
+  injectedGraphqlProbe,
 }) {
   const startedAtMs = Date.now();
   const config = injectedConfig || resolveConfig({ cwd: options.cwd });
@@ -846,12 +915,6 @@ async function runClosePipeline({
   progress('INIT', `Closing standalone Story #${options.storyId}...`);
   const story = await provider.getTicket(options.storyId);
   if (story.state === 'closed') {
-    progress(
-      'NOOP',
-      story.stateReason === 'not_planned'
-        ? `Story #${options.storyId} is closed as not planned — nothing to land.`
-        : `Story #${options.storyId} is already closed. Nothing to do.`,
-    );
     return await alreadyClosedResult(
       options.storyId,
       story.stateReason,
@@ -859,8 +922,41 @@ async function runClosePipeline({
     );
   }
 
+  // Story #4257 — the base-sync conflict and review-critical exits throw
+  // before the clean-close lease release at the tail of this function.
+  // Built here, ahead of the first blocked-prone step, so the preflight
+  // refusal below releases the lease on the same terms those exits do.
+  const leaseArgs = {
+    provider,
+    storyId: options.storyId,
+    config,
+    injectedReleaseLease,
+  };
+
+  // Story #5355 — one cheap GraphQL read, before anything is resolved,
+  // validated, committed or pushed. `gh` routes the whole `gh pr` surface
+  // through GraphQL, so a session that cannot reach it cannot land this
+  // Story however green its gates are; discovering that here costs one API
+  // call instead of the entire close-validation chain plus a push.
+  const preflight = await runGraphqlPreflight({
+    storyId: options.storyId,
+    provider,
+    progress,
+    ghFacade: injectedGh,
+    probe: injectedGraphqlProbe,
+  });
+  if (preflight) {
+    await releaseLease(leaseArgs);
+    return await preflightBlockedResult({
+      storyId: options.storyId,
+      preflight,
+      config,
+      startedAtMs,
+    });
+  }
+
   // Story #4891 — the base branch this run was SEEDED from, read back off the
-  // run's `story-init` receipt rather than re-resolved from a config file that
+  // run's init receipt on disk rather than re-resolved from a config file that
   // may have changed during the whole implementation window. Throws (fail
   // closed, naming both values) when the pin and current config disagree —
   // deliberately here, before the gate chain, format-autofix and base-sync,
@@ -868,7 +964,6 @@ async function runClosePipeline({
   // gates the base-merge remediation advice further down.
   const { values: runScoped, confirmed: baseConfirmed } =
     await resolveRunScopedConfig({
-      provider,
       storyId: options.storyId,
       config,
       progress,
@@ -880,16 +975,8 @@ async function runClosePipeline({
     config,
     storyId: options.storyId,
   });
-  // Story #4257 — the base-sync conflict and review-critical exits throw
-  // before the clean-close lease release at the tail of this function.
-  // Wrap both blocked-prone phases so the lease is released best-effort
-  // before the throw propagates; the original error is preserved.
-  const leaseArgs = {
-    provider,
-    storyId: options.storyId,
-    config,
-    injectedReleaseLease,
-  };
+  // Both blocked-prone phases are wrapped so the lease is released
+  // best-effort before the throw propagates; the original error is preserved.
   const { validationGates } = await releaseLeaseOnBlock(
     () =>
       runPrePushPhases({

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -139,9 +139,10 @@ export const NEXT_COMMANDS = Object.freeze({
    * The only entry here that is a slash command rather than a script, and
    * deliberately so: the other entries resume a Story that exists, while this
    * one names work that has no Story yet and needs planning before it can have
-   * one. It is quoted for a shell but addressed to a **fresh session** — see
-   * the workflow's escalation section for why running it in the escalating
-   * session is forbidden.
+   * one. It is quoted for a shell. Story #4746 addressed it to a **fresh
+   * session**; Story #5344 permits the escalating session to run it too, seeded
+   * with `escalation.reasons` — see the workflow's escalation section for the
+   * seeding contract and for the observation that motivated the old ban.
    */
   escalateToPlan: (prompt) => `/mandrel-plan "${quoteForPlan(prompt)}"`,
 });