mandrel 2.20.0 → 2.22.0

package/.agents/scripts/lib/orchestration/deliver-recover.js

@@ -35,12 +35,31 @@
  * resumption speak one language instead of two dialects for one state.
  */
 
+import nodeFs from 'node:fs';
+
+import {
+  closeGateLogPath,
+  storyTerminalEnvelopePath,
+} from '../config/temp-paths.js';
 import { gh as defaultGh } from '../gh-exec.js';
 import { gitSpawn as defaultGitSpawn, getStoryBranch } from '../git-utils.js';
 import { deriveChecksStatus } from './merge-poll.js';
 import { NEXT_COMMANDS } from './story-deliver-terminal.js';
 import { STATE_LABELS } from './ticketing.js';
 
+/**
+ * How recently the gate log must have been appended for the close that writes
+ * it to count as live (Story #4816).
+ *
+ * The window is generous on purpose. Gate output arrives in bursts — a single
+ * `npm test` gate can run for a long stretch between lines — so a tight window
+ * would read a slow-but-healthy close as dead and re-open the exact
+ * misdiagnosis this exists to remove. Being wrong in the other direction is
+ * cheap: the verdict for a live close is "re-run this read-only probe", which
+ * costs nothing if the close has in fact already exited.
+ */
+const CLOSE_IN_FLIGHT_WINDOW_MS = 120_000;
+
 /**
  * Probe the ticket: state labels, issue open/closed, and the lease holder.
  *
@@ -131,6 +150,171 @@ export async function probePr({ storyBranch, gh = defaultGh }) {
   }
 }
 
+/**
+ * Probe the two on-disk artifacts a close leaves behind (Story #4816): the
+ * persisted terminal envelope and the gate log.
+ *
+ * These exist because the label-and-PR probes above cannot see the difference
+ * between an implementation that died and a close that is still running —
+ * both read `agent::executing` with no PR for the whole gate chain. The
+ * artifacts can: a persisted envelope means the close already reached a
+ * verdict, and a recently-appended gate log means one is mid-chain right now.
+ * Gate-log freshness is exactly the signal operators were already using by
+ * hand to tell the two apart, which is the argument for reading it here
+ * instead of expecting them to know.
+ *
+ * Never throws: an unreadable or absent artifact is a `null` reading, and the
+ * table falls back to the label-only verdict it always had.
+ *
+ * @param {{
+ *   storyId: number,
+ *   config?: object,
+ *   fsImpl?: typeof nodeFs,
+ *   nowMs?: number,
+ *   windowMs?: number,
+ * }} args
+ * @returns {{
+ *   envelope: object|null,
+ *   envelopePath: string|null,
+ *   envelopeMtimeMs: number|null,
+ *   gateLogPath: string|null,
+ *   gateLogAgeMs: number|null,
+ *   gateLogMtimeMs: number|null,
+ *   gateLogFresh: boolean,
+ * }}
+ */
+export function probeCloseArtifacts({
+  storyId,
+  config,
+  fsImpl = nodeFs,
+  nowMs = Date.now(),
+  windowMs = CLOSE_IN_FLIGHT_WINDOW_MS,
+}) {
+  const empty = {
+    envelope: null,
+    envelopePath: null,
+    envelopeMtimeMs: null,
+    gateLogPath: null,
+    gateLogAgeMs: null,
+    gateLogMtimeMs: null,
+    gateLogFresh: false,
+  };
+  let envelopePath = null;
+  let gateLogPath = null;
+  try {
+    envelopePath = storyTerminalEnvelopePath(storyId, config);
+    gateLogPath = closeGateLogPath(storyId, config);
+  } catch {
+    return empty;
+  }
+
+  let envelope = null;
+  let envelopeMtimeMs = null;
+  try {
+    const parsed = JSON.parse(fsImpl.readFileSync(envelopePath, 'utf8'));
+    // A parsed non-object (or an array) is not an envelope; treat it as
+    // absent rather than handing the table something it cannot read fields
+    // off of.
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      envelope = parsed;
+      envelopeMtimeMs = fsImpl.statSync(envelopePath).mtimeMs;
+    }
+  } catch {
+    envelope = null;
+    envelopeMtimeMs = null;
+  }
+
+  let gateLogMtimeMs = null;
+  try {
+    gateLogMtimeMs = fsImpl.statSync(gateLogPath).mtimeMs;
+  } catch {
+    gateLogMtimeMs = null;
+  }
+  const gateLogAgeMs =
+    gateLogMtimeMs === null ? null : Math.max(0, nowMs - gateLogMtimeMs);
+
+  return {
+    envelope,
+    envelopePath,
+    envelopeMtimeMs,
+    gateLogPath,
+    gateLogAgeMs,
+    gateLogMtimeMs,
+    gateLogFresh: gateLogAgeMs !== null && gateLogAgeMs <= windowMs,
+  };
+}
+
+/**
+ * Is a close running right now, outranking whatever a persisted envelope says?
+ *
+ * A persisted envelope is definitive about the close that wrote it — but a
+ * Story can be closed more than once (a `pending` wait resumed, a red gate
+ * fixed and re-run), and a *stale* envelope from the previous attempt must not
+ * out-argue a gate log the current attempt is appending to as we read. So the
+ * live signal wins whenever the gate log is both fresh and fresher than the
+ * envelope.
+ *
+ * @param {object} artifacts A {@link probeCloseArtifacts} reading.
+ * @returns {boolean}
+ */
+function closeLooksLive(artifacts) {
+  if (!artifacts?.gateLogFresh) return false;
+  if (artifacts.envelopeMtimeMs === null) return true;
+  return artifacts.gateLogMtimeMs > artifacts.envelopeMtimeMs;
+}
+
+/**
+ * The verdict for a Story whose close already finished but whose envelope
+ * never reached the caller — the orphaned-turn shape (Story #4816).
+ *
+ * Nothing is re-derived here: the envelope on disk is the same
+ * schema-validated object the close emitted, so its own `status` and
+ * `nextCommand` are relayed rather than a second opinion invented from
+ * labels. A `landed` envelope carries a null next command, and the honest
+ * follow-up for a landed-but-mislabelled Story is the idempotent confirm.
+ */
+function envelopeOnDiskVerdict({ storyId, artifacts, evidence }) {
+  const { envelope, envelopePath } = artifacts;
+  return {
+    shape: 'close-envelope-on-disk',
+    nextCommand: envelope.nextCommand ?? NEXT_COMMANDS.confirmMerge(storyId),
+    detail:
+      `The close for this Story already reached a terminal verdict — \`${envelope.status}\` ` +
+      `at phase \`${envelope.phase}\` — but the label still reads mid-flight, which is the ` +
+      `signature of a worker turn that ended before it could relay the envelope. The close ` +
+      `itself is not in doubt: read the full envelope at \`${envelopePath}\` rather than ` +
+      `re-deriving its state, and run the command below (the envelope's own \`nextCommand\`, ` +
+      `or the idempotent confirm when it landed and named none).`,
+    evidence,
+  };
+}
+
+/**
+ * The verdict for a close that is running as we probe (Story #4816).
+ *
+ * The next command is this probe again. That is not a shrug: there is no
+ * attach-to-a-running-close surface, the close needs nothing from anyone, and
+ * every *other* command an operator might reach for here is actively harmful
+ * — which is why the detail names the re-init hazard explicitly instead of
+ * leaving it implied.
+ */
+function closeInFlightVerdict({ storyId, artifacts, evidence }) {
+  const seconds = Math.round((artifacts.gateLogAgeMs ?? 0) / 1000);
+  return {
+    shape: 'close-in-flight',
+    nextCommand: NEXT_COMMANDS.recover(storyId),
+    detail:
+      `A close is RUNNING for this Story right now: \`${artifacts.gateLogPath}\` was appended ` +
+      `${seconds}s ago. \`agent::executing\` with no PR does NOT mean the work stalled here — ` +
+      `the implementation is done and the close is mid-gate-chain, before its push. ` +
+      `**Do not run \`single-story-init.js\`**: re-initializing the worktree ` +
+      `underneath a live close risks a second close racing the first on one PR (double label ` +
+      `flip, double post-land tail). Let it finish — it emits its own terminal envelope and ` +
+      `persists a copy — then re-run the command below for a settled verdict.`,
+    evidence,
+  };
+}
+
 /**
  * The decision table. Pure: every input is an already-observed probe, so the
  * mapping is testable without git, GitHub, or a clock.
@@ -138,10 +322,22 @@ export async function probePr({ storyBranch, gh = defaultGh }) {
  * Returns exactly one `{ shape, nextCommand, evidence[], detail }` — never a
  * list of candidates.
  *
- * @param {{ storyId: number, ticket: object, branch: object, pr: object|null }} probes
+ * @param {{
+ *   storyId: number,
+ *   ticket: object,
+ *   branch: object,
+ *   pr: object|null,
+ *   closeArtifacts?: object,
+ * }} probes
  * @returns {{ shape: string, nextCommand: string|null, detail: string, evidence: string[] }}
  */
-export function decideRecovery({ storyId, ticket, branch, pr }) {
+export function decideRecovery({
+  storyId,
+  ticket,
+  branch,
+  pr,
+  closeArtifacts,
+}) {
   const evidence = [
     `label=${ticket?.stateLabel ?? 'none'}`,
     `issue=${ticket?.issueState ?? 'unknown'}`,
@@ -151,6 +347,13 @@ export function decideRecovery({ storyId, ticket, branch, pr }) {
     `branch.remote=${branch?.remote ?? false}`,
     `worktree=${branch?.worktreePath ?? 'none'}`,
     `lease=${ticket?.lease ?? 'unclaimed'}`,
+    `closeEnvelope=${closeArtifacts?.envelope ? closeArtifacts.envelope.status : 'none'}`,
+    `gateLogAge=${
+      closeArtifacts?.gateLogAgeMs === null ||
+      closeArtifacts?.gateLogAgeMs === undefined
+        ? 'none'
+        : `${Math.round(closeArtifacts.gateLogAgeMs / 1000)}s`
+    }`,
   ];
 
   const label = ticket?.stateLabel;
@@ -242,12 +445,33 @@ export function decideRecovery({ storyId, ticket, branch, pr }) {
         evidence,
       };
     }
+    // Story #4816 — the close artifacts get the first word here, and ONLY
+    // here. Every other row of this table describes a state whose evidence is
+    // already unambiguous; `executing` + no PR is the one row that reads
+    // identically for a dead implementation and for a close that is halfway
+    // through its gate chain, and answering it from labels alone is what sent
+    // operators to re-init on top of a live close.
+    if (closeLooksLive(closeArtifacts)) {
+      return closeInFlightVerdict({
+        storyId,
+        artifacts: closeArtifacts,
+        evidence,
+      });
+    }
+    if (closeArtifacts?.envelope) {
+      return envelopeOnDiskVerdict({
+        storyId,
+        artifacts: closeArtifacts,
+        evidence,
+      });
+    }
     return {
       shape: 'executing-no-pr',
       nextCommand: NEXT_COMMANDS.implement(storyId),
       detail:
-        `Story is \`agent::executing\` with no PR. Implementation never finished. Re-init ` +
-        `(idempotent — it reuses the existing branch and worktree) and resume in the ` +
+        `Story is \`agent::executing\` with no PR, and no close left an artifact behind (no ` +
+        `persisted terminal envelope, no recent gate log) — implementation never finished. ` +
+        `Re-init (idempotent — it reuses the existing branch and worktree) and resume in the ` +
         `worktree it prints.`,
       evidence,
     };
@@ -280,6 +504,11 @@ const TRANSIENT_SHAPES = new Set([
   'closing-no-pr',
   'closing-pr-pending',
   'closing-pr-red',
+  // Story #4816 — the definition of this shape is "a process is mutating this
+  // Story right now", so it is the most transient row in the table: the second
+  // probe often catches the push and PR landing and returns a settled verdict
+  // instead.
+  'close-in-flight',
 ]);
 
 /**
@@ -330,6 +559,7 @@ async function probeAndDecide({
   config,
   gh,
   gitSpawnFn,
+  fsImpl,
 }) {
   const ticket = await probeTicket({ provider, storyId });
   if (!ticket.ok) {
@@ -339,8 +569,22 @@ async function probeAndDecide({
   }
   const branch = probeBranch({ cwd, storyBranch, config, gitSpawnFn });
   const pr = await probePr({ storyBranch, gh });
-  const decision = decideRecovery({ storyId, ticket, branch, pr });
-  return { probes: { ticket, branch, pr }, decision };
+  // Re-read on every round: the whole point of the stability pass is that a
+  // second look can catch a close that has since flushed a gate line or
+  // written its envelope.
+  const closeArtifacts = probeCloseArtifacts({
+    storyId,
+    config,
+    ...(fsImpl ? { fsImpl } : {}),
+  });
+  const decision = decideRecovery({
+    storyId,
+    ticket,
+    branch,
+    pr,
+    closeArtifacts,
+  });
+  return { probes: { ticket, branch, pr, closeArtifacts }, decision };
 }
 
 /**
@@ -365,6 +609,7 @@ async function probeAndDecide({
  *   settling).
  * @param {number} [args.stabilityDelayMs] Settle window between the probes.
  * @param {Function} [args.sleepFn] Test seam for the settle wait.
+ * @param {typeof nodeFs} [args.fsImpl] Test seam for the close-artifact reads.
  * @returns {Promise<object>}
  */
 export async function recoverStory({
@@ -374,6 +619,7 @@ export async function recoverStory({
   config,
   gh = defaultGh,
   gitSpawnFn,
+  fsImpl,
   reprobe = true,
   stabilityDelayMs = STABILITY_DELAY_MS,
   sleepFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -387,6 +633,7 @@ export async function recoverStory({
     config,
     gh,
     gitSpawnFn,
+    fsImpl,
   };
 
   const first = await probeAndDecide(probeArgs);

package/.agents/scripts/lib/orchestration/light-suitability.js

@@ -30,8 +30,10 @@
  *   2. **Over-scope stops, never silently proceeds ({@link
  *      resolveLightGateOutcome}).** An over-ceiling prompt does **not**
  *      hard-fail — it STOPS and asks the operator to escalate to `/plan` or
- *      proceed light. Under `--yes` (unattended) it fails closed to
- *      recommending `/plan`.
+ *      proceed light. Both answers are executable: `proceed-light` is recorded
+ *      through {@link resolveOperatorOverride}, which waives a *size
+ *      prediction* only, never a risk rule, and only with a human present.
+ *      Under `--yes` (unattended) it fails closed to recommending `/plan`.
  *   3. **Diff-derived backstop ({@link checkLightDiffBackstop}).** After
  *      implementation the **actual** change set is re-checked with
  *      {@link module:lib/orchestration/review-depth.deriveChangeLevel} plus a
@@ -48,9 +50,34 @@
  * @module lib/orchestration/light-suitability
  */
 
-import { deriveStoryShape, STORY_SHAPE_CEILINGS } from './complexity-gate.js';
+import {
+  deriveStoryShape,
+  SHAPE_CODES,
+  STORY_SHAPE_CEILINGS,
+} from './complexity-gate.js';
 import { deriveChangeLevel } from './review-depth.js';
 
+/**
+ * The shape objections an attended operator may waive (Story #4815) — an
+ * **allowlist**, deliberately, so a rule added to
+ * {@link module:lib/orchestration/complexity-gate.SHAPE_CODES} later is
+ * non-negotiable until someone decides otherwise here. A denylist would make
+ * every new rule silently overridable.
+ *
+ * These four are the *size predictions*: coarse by design (§ Scope by effort),
+ * and already bounded for real by {@link checkLightDiffBackstop} against the
+ * landed diff. Everything absent is absent on purpose — `migration-span` and
+ * `sensitive-path` are **risk**, not size, and the unknown-footprint codes
+ * describe a shape that was never judged, so there is no false positive to
+ * appeal.
+ */
+export const OVERRIDABLE_SHAPE_CODES = Object.freeze([
+  SHAPE_CODES.CHANGE_KINDS,
+  SHAPE_CODES.MAGNITUDE,
+  SHAPE_CODES.UNCERTAINTY,
+  SHAPE_CODES.DEPLOYABLE_SPAN,
+]);
+
 /**
  * File-count ceiling for the **actual landed** change set the diff backstop
  * ({@link checkLightDiffBackstop}) enforces. This is the light path's **only**
@@ -192,6 +219,88 @@ export function deriveLightSuitability({
   };
 }
 
+/**
+ * Adjudicate an operator's recorded `proceed-light` answer to the gate's own
+ * question (Story #4815). The gate has always *offered* `proceed-light` as one
+ * of two options; before this there was no input that could carry the answer,
+ * so the only way past a coarse prediction was to re-shape the declaration
+ * until the gate stopped objecting — precisely the under-declaring the coarse
+ * design anticipates.
+ *
+ * Applying it takes **all** of:
+ *
+ *   1. **The gate actually objected.** An override cannot pre-authorize a
+ *      scope nothing rejected.
+ *   2. **The run is attended.** `--yes` means nobody is at the keyboard, so
+ *      there is no operator whose answer this could be (§ Escalation is
+ *      terminal). Checked here as well as at the CLI, so the pure core carries
+ *      the guarantee rather than the shell.
+ *   3. **The objection is a size prediction** — a code in
+ *      {@link OVERRIDABLE_SHAPE_CODES}. Sensitivity and migration span are
+ *      risk and stay absolute however small the change.
+ *   4. **The ledgered verdict is already `lite`.** The override substitutes for
+ *      the *shape* half of the conjunction only; an unaudited "trust me, it's
+ *      small" buys nothing it did not buy before.
+ *
+ * A refusal is reported, never silent — an operator who typed the flag must
+ * learn why it did not take. Pure and total.
+ *
+ * @param {{
+ *   suitability?: object,
+ *   yes?: boolean,
+ *   operatorOverride?: unknown,
+ * }} [args] `operatorOverride` is the operator's recorded reason; blank or
+ *   absent means no override was requested.
+ * @returns {{
+ *   applied: boolean,
+ *   record: { recordedReason: string, overriddenCode: string, overriddenReason: string }|null,
+ *   note: string|null,
+ * }}
+ */
+export function resolveOperatorOverride({
+  suitability,
+  yes = false,
+  operatorOverride,
+} = {}) {
+  const recordedReason =
+    typeof operatorOverride === 'string' ? operatorOverride.trim() : '';
+  const refuse = (note) => ({ applied: false, record: null, note });
+
+  if (recordedReason === '') return refuse(null);
+  if (suitability?.suitable === true) {
+    return refuse(
+      'operator override ignored — the gate raised no objection to override',
+    );
+  }
+  if (yes === true) {
+    return refuse(
+      'operator override refused — it is attended-only, and --yes means nobody is at the keyboard; over-scope still fails closed to /plan',
+    );
+  }
+
+  const code = suitability?.shape?.code ?? null;
+  if (!OVERRIDABLE_SHAPE_CODES.includes(code)) {
+    return refuse(
+      `operator override refused — "${code ?? 'unknown'}" is not an overridable size prediction (overridable: ${OVERRIDABLE_SHAPE_CODES.join(', ')}); risk rules and unknown footprints are non-negotiable`,
+    );
+  }
+  if (suitability?.ledger?.route !== 'lite') {
+    return refuse(
+      'operator override refused — it substitutes for the predicted shape only; the model verdict must still be a ledgered lite with a recorded reason',
+    );
+  }
+
+  return {
+    applied: true,
+    record: {
+      recordedReason,
+      overriddenCode: code,
+      overriddenReason: suitability?.shape?.reasons?.[0] ?? '',
+    },
+    note: `operator override applied — proceeding light despite "${code}"; recorded reason: ${recordedReason}. The diff backstop still bounds the actual change set.`,
+  };
+}
+
 /**
  * Resolve what the light gate does with a suitability decision (Story #4740
  * AC-3). Over-scope never hard-fails: it STOPS and asks the operator to choose,
@@ -200,17 +309,43 @@ export function deriveLightSuitability({
  *
  *   - suitable          → `proceed-light`
  *   - over-scope + attended (`yes:false`)  → `ask-operator` (escalate | proceed)
+ *   - over-scope + attended + an applied operator override (Story #4815)
+ *                                          → `proceed-light`, carrying the
+ *                                            decision in `override`
  *   - over-scope + unattended (`yes:true`) → `escalate-plan`
  *
+ * The override is adjudicated by {@link resolveOperatorOverride} and cannot
+ * reach the unattended branch: `escalate-plan` is resolved first and the
+ * override refuses itself under `yes` anyway.
+ *
  * Pure and total.
  *
- * @param {{ suitability?: { suitable?: boolean, reasons?: string[] }, yes?: boolean }} [args]
- * @returns {{ action: 'proceed-light'|'ask-operator'|'escalate-plan', options?: string[], reasons: string[] }}
+ * @param {{
+ *   suitability?: { suitable?: boolean, reasons?: string[] },
+ *   yes?: boolean,
+ *   operatorOverride?: unknown,
+ * }} [args]
+ * @returns {{
+ *   action: 'proceed-light'|'ask-operator'|'escalate-plan',
+ *   options?: string[],
+ *   override?: object,
+ *   reasons: string[],
+ * }}
  */
-export function resolveLightGateOutcome({ suitability, yes = false } = {}) {
+export function resolveLightGateOutcome({
+  suitability,
+  yes = false,
+  operatorOverride,
+} = {}) {
+  const override = resolveOperatorOverride({
+    suitability,
+    yes,
+    operatorOverride,
+  });
   const reasons = Array.isArray(suitability?.reasons)
     ? [...suitability.reasons]
     : [];
+  if (override.note !== null) reasons.push(override.note);
 
   if (suitability?.suitable === true) {
     return {
@@ -232,6 +367,17 @@ export function resolveLightGateOutcome({ suitability, yes = false } = {}) {
     };
   }
 
+  if (override.applied) {
+    return {
+      action: 'proceed-light',
+      override: override.record,
+      reasons: [
+        ...reasons,
+        'predicted scope exceeded a light ceiling and the operator answered proceed-light — proceeding on the recorded override',
+      ],
+    };
+  }
+
   return {
     action: 'ask-operator',
     options: ['escalate-plan', 'proceed-light'],
@@ -417,18 +563,53 @@ function toReceiptChanges(changedFiles) {
   return entries;
 }
 
+/**
+ * Render an applied operator override as an audit paragraph for the receipt
+ * body (Story #4815). An override that leaves no trace on the ticket is an
+ * invisible decision: the whole point of routing it through the receipt is
+ * that a later reader can see the gate objected, on what grounds, and who
+ * decided to proceed anyway.
+ *
+ * @param {unknown} override The `record` from {@link resolveOperatorOverride}.
+ * @returns {string} A leading-space-prefixed sentence, or `''` when absent.
+ */
+function renderOverrideNote(override) {
+  if (!override || typeof override !== 'object') return '';
+  const { overriddenCode, overriddenReason, recordedReason } = override;
+  if (typeof recordedReason !== 'string' || recordedReason.trim() === '') {
+    return '';
+  }
+  return (
+    ` OPERATOR SCOPE OVERRIDE: the suitability gate objected on ` +
+    `"${overriddenCode}" (${overriddenReason}) and the operator answered ` +
+    `proceed-light — recorded reason: ${recordedReason.trim()}. The ` +
+    `prediction was waived, not the diff backstop, which still bounds the ` +
+    `landed change set.`
+  );
+}
+
 /**
  * Build the minimal receipt `type::story` ticket for the light path
  * (Story #4740 AC-5) — the input `assemblePlanStories` / `createStoryIssues`
  * consume, so the light path reuses the plan-persist story-creation surface
  * rather than reimplementing issue authoring. The body carries the operator
- * prompt (goal + spec) and the diff-derived footprint (`changes[]`), so history
- * and `refs #<id>` on the commit survive.
+ * prompt (goal + spec), the diff-derived footprint (`changes[]`), and any
+ * operator scope override, so history and `refs #<id>` on the commit survive.
  *
- * @param {{ prompt?: unknown, changedFiles?: unknown, amends?: unknown }} [args]
+ * @param {{
+ *   prompt?: unknown,
+ *   changedFiles?: unknown,
+ *   amends?: unknown,
+ *   override?: unknown,
+ * }} [args]
  * @returns {{ slug: string, title: string, body: object, labels: string[] }}
  */
-export function buildReceiptStoryTicket({ prompt, changedFiles, amends } = {}) {
+export function buildReceiptStoryTicket({
+  prompt,
+  changedFiles,
+  amends,
+  override,
+} = {}) {
   const text = typeof prompt === 'string' ? prompt.trim() : '';
   if (text === '') {
     throw new Error(
@@ -438,6 +619,7 @@ export function buildReceiptStoryTicket({ prompt, changedFiles, amends } = {}) {
   const amendsId = normalizeAmends(amends);
   const amendNote = amendsId !== null ? ` Amends #${amendsId}.` : '';
   const changes = toReceiptChanges(changedFiles);
+  const overrideNote = renderOverrideNote(override);
 
   return {
     slug: slugifyPrompt(text),
@@ -448,7 +630,8 @@ export function buildReceiptStoryTicket({ prompt, changedFiles, amends } = {}) {
       spec:
         `Delivered via /deliver-light as a validated single-session change — ` +
         `the /plan session is removed for genuinely small work while every ` +
-        `single-story-close gate runs byte-identical.${amendNote} ` +
+        `single-story-close gate runs byte-identical.${amendNote}` +
+        `${overrideNote} ` +
         `Operator prompt: ${text}`,
       changes,
       acceptance: [

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -317,21 +317,24 @@ export function buildStoriesEnvelope({
   const inSetDone = sorted.filter(isSatisfiedBlocker).map((s) => s.id);
   return {
     kind: 'stories',
-    // `dispatchMode` (Story #4722): the resolver derives the per-Story
-    // execution mode from the fetched Story BODY's own shape (the shared
-    // shape function in `complexity-gate.js`) so `/deliver` reads one field —
-    // `inline` (lite-shaped: no story-worker / acceptance-critic sub-agent
-    // boots) or `subagent` (everything else, the conservative default). The
-    // `route::lite` label is a human-visible hint only, never the control
-    // signal: a lost label cannot misroute delivery. Model-side fan-out
-    // only; close gates are untouched.
+    // `dispatchMode` (Story #4722, #4736, #4829): the resolver reports the
+    // per-Story execution mode so `/deliver` reads one field — `inline` (run
+    // deliver-story in the router's own session: no story-worker /
+    // acceptance-critic sub-agent boots) or `subagent` (the conservative
+    // default). Model-side fan-out only; close gates are untouched.
     //
-    // `storyCount` (Story #4736) carries the run's topology into that same
-    // decision: a run resolving exactly ONE Story is inline whatever its
-    // shape, because the isolation a sub-agent buys only matters against a
-    // concurrently-dispatched sibling. It is the resolved set size — not the
-    // undelivered remainder — so the mode a caller reads for a given `--ids`
-    // list never changes as siblings land mid-run.
+    // `storyCount` is the premise that decides it, and it is this call site's
+    // load-bearing argument: `inline` names the router's ONE session, so it is
+    // granted only to a run resolving exactly ONE Story, which has no
+    // concurrent sibling to share that session with. Passing the resolved set
+    // size here is therefore what makes the envelope self-consistent with the
+    // ready set `stories-wave-tick.js` computes from the same `dag`: a set of
+    // more than one can never come back with a Story claiming the session
+    // (Story #4829 — it previously could, whenever the body was lite-shaped).
+    // It is the resolved set size, NOT the undelivered remainder, so the mode
+    // a caller reads for a given `--ids` list never changes as siblings land
+    // mid-run. The `route::lite` label is a human-visible hint only, never the
+    // control signal.
     stories: sorted.map(({ id, title, body, url, labels, state }) => ({
       id,
       title,