mandrel 2.53.0 → 2.55.0

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

@@ -15,6 +15,7 @@ import { createProvider } from '../../provider-factory.js';
 import { flipLabelAndNotify } from '../../single-story/story-merged-notify.js';
 import { WorktreeManager } from '../../worktree-manager.js';
 import { runCodeReview as runCodeReviewDefault } from '../code-review.js';
+import { MERGED_FLIP_FAILED_BLOCK_CLASS } from '../lifecycle/emit-merge-flip-failed.js';
 import { resolveRunScopedConfig } from '../run-scoped-config.js';
 import { releaseStoryLease } from '../single-story-lease-guard.js';
 import {
@@ -23,6 +24,7 @@ import {
   NEXT_COMMANDS,
   terminalFromWaitOutcome,
 } from '../story-deliver-terminal.js';
+import { deriveCloseNote } from './close-note.js';
 import { runAutoMergePhase } from './phases/auto-merge.js';
 import { runBaseSyncPhase } from './phases/base-sync.js';
 import { runCloseValidationPhase } from './phases/close-validation.js';
@@ -203,6 +205,7 @@ async function runPrePushPhases({
   injectedSync,
   injectedGitSpawn,
   setPhase = () => {},
+  setObservedGates = () => {},
 }) {
   setPhase('wrong-tree-guard');
   await runWrongTreeGuardPhase({
@@ -235,18 +238,34 @@ async function runPrePushPhases({
     return { validationGates: null };
   }
   setPhase('close-validation');
-  const validation = await runCloseValidationPhase({
-    cwd,
-    worktreePath,
-    config,
-    baseBranch,
-    storyBranch,
-    storyId,
-    progress,
-    runCloseValidation,
-    buildDefaultGates,
-  });
-  return { validationGates: validation?.gates ?? null };
+  let validation;
+  try {
+    validation = await runCloseValidationPhase({
+      cwd,
+      worktreePath,
+      config,
+      baseBranch,
+      storyBranch,
+      storyId,
+      progress,
+      runCloseValidation,
+      buildDefaultGates,
+    });
+  } catch (err) {
+    // Story #5279 — the failed terminal REPORTS gates rather than
+    // reconstructing them, so hand it what this run observed. The phase tags
+    // `closeGate` with the entry that died; that one name is the whole of
+    // what the run observed about gate outcomes, and therefore the whole of
+    // what the envelope may claim. Anything else it might have named is a
+    // gate the run never proved ran at all.
+    if (typeof err?.closeGate === 'string') {
+      setObservedGates({ [err.closeGate]: 'failed' });
+    }
+    throw err;
+  }
+  const gates = validation?.gates ?? null;
+  setObservedGates(gates);
+  return { validationGates: gates };
 }
 
 async function openAndReviewPr({
@@ -402,6 +421,38 @@ async function releaseLeaseOnBlock(run, leaseArgs) {
   }
 }
 
+/**
+ * Did this run OBSERVE the PR merge? (Story #5279)
+ *
+ * `merged` used to be whatever the caller happened to pass, and the two
+ * finishers passed different halves of the truth. Three observations say a
+ * merge happened, and each of them reported `merged: false` on at least one
+ * path:
+ *
+ *   - the confirm phase watched it land (`waitOutcome.confirmed`);
+ *   - it landed and only the `agent::done` label write failed
+ *     (`merged-flip-failed`) — the terminal envelope for that same run
+ *     already reports `pr.state: MERGED` from the probe, so a result denying
+ *     the merge made the two halves of one run contradict each other;
+ *   - the arm phase direct-squash-merged it synchronously because the
+ *     repository has no native auto-merge (`directMerged`), which the
+ *     no-wait finisher never consulted at all.
+ *
+ * Deliberately observation-only: it reads what the run saw, never what the
+ * run intended. A `null`/absent `waitOutcome` is the no-wait finisher, whose
+ * sole observation is the direct merge.
+ *
+ * @param {{ waitOutcome?: object|null, directMerged?: boolean }} args
+ * @returns {boolean}
+ */
+function deriveObservedMerge({ waitOutcome = null, directMerged = false }) {
+  return (
+    waitOutcome?.confirmed === true ||
+    waitOutcome?.blockClass === MERGED_FLIP_FAILED_BLOCK_CLASS ||
+    directMerged === true
+  );
+}
+
 function closeResult({
   storyId,
   storyBranch,
@@ -416,6 +467,7 @@ function closeResult({
   directMerged = false,
   waitedForMerge = false,
   merged = false,
+  landCompleted = merged,
 }) {
   return {
     storyId,
@@ -440,11 +492,20 @@ function closeResult({
     directMerged,
     waitedForMerge,
     merged,
-    note: waitedForMerge
-      ? 'Close-and-land: PR merge confirmed. Story flipped agent::closing → agent::done, the issue closed (confirmStoryMerged), and the post-land tail ran.'
-      : autoMergeEnabled
-        ? 'PR open against baseBranch with auto-merge enabled. Story rests at agent::closing (issue stays OPEN and assigned to the operator). GitHub will squash-merge when required checks pass; run single-story-confirm-merge.js after the merge confirms to flip agent::done, release the lease, and close the issue (the Closes #<id> footer also auto-closes it).'
-        : 'PR open against baseBranch. Story rests at agent::closing (issue stays OPEN and assigned to the operator). Operator merges via GitHub UI; run single-story-confirm-merge.js after the merge confirms to flip agent::done and release the lease (the Closes #<id> footer also auto-closes the issue).',
+    // Story #5266 — derived from `merged` / `directMerged` / `autoMergeEnabled`,
+    // never from `waitedForMerge`. A wait that expired unmerged used to write
+    // "PR merge confirmed" beside `merged: false`, and this log is what the
+    // operator reads first. See close-note.js for the invariant.
+    // Story #5279 — `landCompleted` keeps that invariant intact now that
+    // `merged: true` no longer implies the flip and the tail ran: a direct
+    // merge under `--no-wait-merge`, and a `merged-flip-failed` block, are
+    // both merged WITHOUT a completed land.
+    note: deriveCloseNote({
+      merged,
+      directMerged,
+      autoMergeEnabled,
+      landCompleted,
+    }),
   };
 }
 
@@ -458,6 +519,7 @@ export async function runSingleStoryClose({
   noWaitForMerge: noWaitForMergeParam,
   maxWaitSeconds: maxWaitSecondsParam,
   mergeWatchMode: mergeWatchModeParam,
+  rerunAdvisory: rerunAdvisoryParam,
   overrideReviewBlock: overrideReviewBlockParam,
   injectedProvider,
   injectedConfig,
@@ -478,11 +540,12 @@ export async function runSingleStoryClose({
     noWaitForMergeParam,
     maxWaitSecondsParam,
     mergeWatchModeParam,
+    rerunAdvisoryParam,
     overrideReviewBlockParam,
   });
   if (!options.storyId) {
     throw new Error(
-      'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>] [--override-review-block <reason>]',
+      'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>] [--rerun-advisory <n>] [--override-review-block <reason>]',
     );
   }
 
@@ -493,13 +556,23 @@ export async function runSingleStoryClose({
   // the `failed` terminal envelope. Tagging rather than swallowing is what
   // lets `failed` name its phase without inventing a second success path.
   let phase = 'init';
+  // Story #5279 — the per-gate outcomes this run OBSERVED, tagged onto a
+  // throwing error alongside the phase so `failedTerminalFor` reports gates
+  // instead of reconstructing which ones "must have" run. Stays null until
+  // close-validation reports, so a run that died before it claims no gates at
+  // all rather than inventing names for gates that were never registered.
+  let observedGates = null;
   const setPhase = (next) => {
     phase = next;
   };
+  const setObservedGates = (gates) => {
+    observedGates = gates;
+  };
   try {
     return await runClosePipeline({
       options,
       setPhase,
+      setObservedGates,
       injectedProvider,
       injectedConfig,
       injectedNotify,
@@ -510,8 +583,9 @@ export async function runSingleStoryClose({
       injectedReleaseLease,
     });
   } catch (err) {
-    if (err && typeof err === 'object' && !err.closePhase) {
-      err.closePhase = phase;
+    if (err && typeof err === 'object') {
+      if (!err.closePhase) err.closePhase = phase;
+      if (!err.closeGates && observedGates) err.closeGates = observedGates;
     }
     throw err;
   }
@@ -596,6 +670,7 @@ async function finishWithMergeWait(prCtx, deps) {
     config: prCtx.config,
     maxWaitSeconds: deps.maxWaitSeconds,
     mergeWatchMode: deps.mergeWatchMode,
+    rerunAdvisory: deps.rerunAdvisory,
     progress,
     injectedGh: deps.injectedGh,
     injectedNotify: deps.injectedNotify,
@@ -628,7 +703,15 @@ async function finishWithMergeWait(prCtx, deps) {
     localCleanupDeferred: prCtx.localCleanupDeferred,
     directMerged: prCtx.directMerged,
     waitedForMerge: true,
-    merged: waitOutcome.confirmed === true,
+    // Story #5279 — `confirmed` alone denied the merge behind a
+    // `merged-flip-failed` block, whose own envelope (above) reports
+    // `pr.state: MERGED` off the probe.
+    merged: deriveObservedMerge({
+      waitOutcome,
+      directMerged: prCtx.directMerged,
+    }),
+    // Only the confirmed ending runs the flip, the issue close and the tail.
+    landCompleted: waitOutcome.confirmed === true,
   });
   await emitTerminal({ terminal, result, config: prCtx.config });
   reportWaitTerminal(terminal, { storyId: prCtx.storyId, prUrl: prCtx.prUrl });
@@ -646,6 +729,11 @@ async function finishWithMergeWait(prCtx, deps) {
  * @returns {Promise<{ success: boolean, result: object, terminal: object }>}
  */
 async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
+  // Story #5279 — a repository with no native auto-merge is direct
+  // squash-merged synchronously by the arm phase, so this ending can and does
+  // hold an OBSERVED merge. It used to report `merged: false` and hard-code
+  // `pr.state: 'OPEN'` for a PR the same run had just merged.
+  const merged = deriveObservedMerge({ directMerged: prCtx.directMerged });
   const result = closeResult({
     storyId: prCtx.storyId,
     storyBranch: prCtx.storyBranch,
@@ -661,6 +749,10 @@ async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
     leaseReleased: false,
     localCleanupDeferred: prCtx.localCleanupDeferred,
     directMerged: prCtx.directMerged,
+    merged,
+    // Whatever the merge state, this ending never flips `agent::done`, never
+    // closes the issue and never runs the tail — `nextCommand` does.
+    landCompleted: false,
   });
   const terminal = buildTerminalEnvelope({
     storyId: prCtx.storyId,
@@ -671,7 +763,7 @@ async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
     pr: {
       number: prCtx.prNumber,
       url: prCtx.prUrl ?? null,
-      state: 'OPEN',
+      state: merged ? 'MERGED' : 'OPEN',
       autoMergeEnabled: Boolean(prCtx.autoMergeEnabled),
     },
     gates: prCtx.gates,
@@ -731,6 +823,7 @@ function reportOperatorMergeSkip({
 async function runClosePipeline({
   options,
   setPhase,
+  setObservedGates,
   injectedProvider,
   injectedConfig,
   injectedNotify,
@@ -805,6 +898,7 @@ async function runClosePipeline({
         injectedSync,
         injectedGitSpawn,
         setPhase,
+        setObservedGates,
       }),
     leaseArgs,
   );
@@ -947,6 +1041,7 @@ async function runClosePipeline({
       provider,
       maxWaitSeconds: options.maxWaitSeconds,
       mergeWatchMode: options.mergeWatchMode,
+      rerunAdvisory: options.rerunAdvisory,
       setPhase,
       injectedGh,
       injectedNotify,

package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js

@@ -64,7 +64,11 @@ import {
 import { getQuality } from '../../config-resolver.js';
 import { gitSync as defaultGitSync } from '../../git-utils.js';
 import { Logger as DefaultLogger } from '../../Logger.js';
-import { currentBranch, listChangedFiles } from './format-autofix.js';
+import {
+  currentBranch,
+  listChangedFiles,
+  listDirtyPaths,
+} from './format-autofix.js';
 
 const TAG = '[baseline-writeback]';
 
@@ -92,6 +96,7 @@ const GUARD_REASONS = new Set([
   'gate-disabled',
   'no-changed-files',
   'wrong-branch',
+  'dirty-tree',
   'no-baseline',
   'no-scorer',
 ]);
@@ -267,7 +272,14 @@ function commitBaseline({ cwd, git, relPath, subject, body }) {
       stdio: ['ignore', 'pipe', 'pipe'],
     });
   } catch (err) {
-    git(['checkout', '--', relPath], {
+    // `git checkout -- <path>` restores the WORKTREE from the index — and the
+    // index is exactly what the `git add` above just overwrote, so on a
+    // rejected commit it restored the file to the value it was meant to be
+    // rolled back FROM. The rollback was a no-op that looked like one, and the
+    // rewritten row survived as a staged edit into whatever the gates scored
+    // next. `restore --staged --worktree` resets both to HEAD, which is what
+    // "leave the tree as the close found it" actually means.
+    git(['restore', '--staged', '--worktree', '--', relPath], {
       cwd,
       stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -289,24 +301,84 @@ function commitBaseline({ cwd, git, relPath, subject, body }) {
  * so a mis-wired `worktreePath` can never leave a modified baseline in a tree
  * whose history we then refuse to touch.
  *
- * @param {{ gate: object|undefined, workTree: string, storyBranch: string, git: Function, changed: string[] }} ctx
+ * The dirty-tree guard is the same refusal `runScopedFormatAutofix` makes and
+ * for the same reason, sharpened to one path: this step's only write target is
+ * the baseline file, and it commits that file by name. An uncommitted edit
+ * sitting on it — a hand-run `maintainability:reanchor`, a half-resolved merge,
+ * an operator mid-edit — would be swept into a `baseline-refresh:` commit
+ * authored by close and attributed to rows this branch improved. That commit is
+ * the one `refresh-ack.js` VOUCHES for, so an absorbed edit is not merely
+ * unrelated: it arrives pre-acknowledged, which is the precise laundering this
+ * whole Story exists to close.
+ *
+ * @param {{ gate: object|undefined, workTree: string, storyBranch: string, git: Function, changed: string[], relPath: string }} ctx
  * @returns {string|null}
  */
-function precheck({ gate, workTree, storyBranch, git, changed }) {
+function precheck({ gate, workTree, storyBranch, git, changed, relPath }) {
   if (gate?.enabled === false) return 'gate-disabled';
   if (changed.length === 0) return 'no-changed-files';
   const onBranch = currentBranch(workTree, git);
   if (onBranch !== storyBranch) return 'wrong-branch';
+  if (isDirty({ workTree, git, relPath })) return 'dirty-tree';
   return null;
 }
 
+/**
+ * Is the baseline file already modified in the worktree or the index?
+ *
+ * Fails CLOSED on an unreadable status: a step that cannot tell whether it is
+ * about to absorb someone else's edit must not proceed, and skipping costs
+ * only a stale upward row that the nightly full-scope re-score still catches.
+ *
+ * @param {{ workTree: string, git: Function, relPath: string }} ctx
+ * @returns {boolean}
+ */
+function isDirty({ workTree, git, relPath }) {
+  try {
+    return listDirtyPaths(workTree, git).includes(relPath);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * The ref the branch's changed-file set is measured against.
+ *
+ * `origin/<baseBranch>` when the remote-tracking ref exists, the local branch
+ * otherwise. A local `main` in a long-lived checkout — and in every Story
+ * worktree, which is seeded once and never pulled again — drifts behind the
+ * remote, and a stale base widens the three-dot range to include commits that
+ * landed on the base after the branch forked. Every file in that widening is
+ * then scored and written back by whichever Story happens to close next, which
+ * is precisely the "absorb unrelated drift into the next PR" failure
+ * constraint 3 in the preamble forbids.
+ *
+ * @param {{ workTree: string, git: Function, baseBranch: string }} ctx
+ * @returns {string}
+ */
+function resolveScopeBase({ workTree, git, baseBranch }) {
+  try {
+    git(
+      ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${baseBranch}`],
+      {
+        cwd: workTree,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      },
+    );
+    return `origin/${baseBranch}`;
+  } catch {
+    return baseBranch;
+  }
+}
+
 /**
  * Persist improved maintainability rows for the files this branch changed, and
  * fold them into one `baseline-refresh:` commit on the Story branch.
  *
  * Every no-op is reported by name rather than silently: `gate-disabled`,
- * `no-changed-files`, `wrong-branch`, `no-baseline`, `no-scored-rows`,
- * `no-improvements`, `unchanged`. The caller logs the reason and proceeds —
+ * `no-changed-files`, `wrong-branch`, `dirty-tree`, `no-baseline`,
+ * `no-scored-rows`, `no-improvements`, `unchanged`. The caller logs the reason and proceeds —
  * this step is never allowed to fail a close, because `check-baselines` is
  * still the gate and this is only the refresh half of the loop.
  *
@@ -364,12 +436,22 @@ export async function runBaselineUpwardWriteback({
 
   const changed = listChangedFiles({
     cwd: workTree,
-    baseBranch,
+    baseBranch: resolveScopeBase({ workTree, git, baseBranch }),
     storyBranch,
     git,
   }).filter((file) => SCORABLE.test(file));
 
-  const blocked = precheck({ gate, workTree, storyBranch, git, changed });
+  const writePath = resolveWritePath({ cwd: workTree });
+  const relPath = path.relative(workTree, writePath).split(path.sep).join('/');
+
+  const blocked = precheck({
+    gate,
+    workTree,
+    storyBranch,
+    git,
+    changed,
+    relPath,
+  });
   if (blocked) return skip(logger, blocked);
 
   const baselineRows = loadBaselineRows({ cwd: workTree });
@@ -399,7 +481,8 @@ export async function runBaselineUpwardWriteback({
     storyId,
     logger,
     refreshBaseline,
-    resolveWritePath,
+    writePath,
+    relPath,
   });
 }
 
@@ -420,10 +503,10 @@ async function persist({
   storyId,
   logger,
   refreshBaseline,
-  resolveWritePath,
+  writePath,
+  relPath,
 }) {
   const improvedPaths = improved.map((row) => row.path);
-  const writePath = resolveWritePath({ cwd: workTree });
   const { wrote } = await refreshBaseline({
     kind: KIND,
     cwd: workTree,
@@ -436,7 +519,6 @@ async function persist({
   // nothing worth a log line above debug.
   if (!wrote) return skip(logger, 'unchanged');
 
-  const relPath = path.relative(workTree, writePath).split(path.sep).join('/');
   const { sha } = commitBaseline({
     cwd: workTree,
     git,

package/.agents/scripts/lib/orchestration/story-close/format-autofix.js

@@ -59,11 +59,16 @@ export const FORMAT_AUTOFIX_TIMEOUT_EXIT_CODE = 124;
  * (e.g. ` M file` for unstaged-modified) so we slice a fixed 3 chars off
  * the front rather than trimming.
  *
+ * Exported since Story #5277: `baseline-upward-writeback.js` needs the same
+ * "is this path already dirty?" test before it rewrites a baseline row, and a
+ * second porcelain parser is exactly the near-duplicate the duplication gate
+ * exists to refuse.
+ *
  * @param {string} cwd
  * @param {(args: string[], opts: object) => string} git
  * @returns {string[]}
  */
-function listDirtyPaths(cwd, git) {
+export function listDirtyPaths(cwd, git) {
   const out = git(['status', '--porcelain'], {
     cwd,
     encoding: 'utf8',

package/.agents/scripts/lib/orchestration/ticket-validator.js

@@ -601,19 +601,28 @@ function assertAcyclic(slugAdjacency) {
   }
 }
 
-function attachFindingsAndErrors(tickets, findings, errors) {
-  Object.defineProperty(tickets, 'findings', {
-    value: findings,
-    enumerable: false,
-    configurable: true,
-    writable: true,
-  });
-  Object.defineProperty(tickets, 'errors', {
-    value: errors,
-    enumerable: false,
-    configurable: true,
-    writable: true,
-  });
+function attachFindingsAndErrors(
+  tickets,
+  findings,
+  errors,
+  normalizations = [],
+) {
+  for (const [key, value] of [
+    ['findings', findings],
+    ['errors', errors],
+    // Story #5265: the auto-normalizations the assumption gate applied. They
+    // used to end at a `Logger.warn` and die with the process, so persist's
+    // emitted result reported a plan whose declarations it had silently
+    // rewritten as if nothing had been rewritten.
+    ['normalizations', normalizations],
+  ]) {
+    Object.defineProperty(tickets, key, {
+      value,
+      enumerable: false,
+      configurable: true,
+      writable: true,
+    });
+  }
 }
 
 export function validateAndNormalizeTickets(tickets, opts = {}) {
@@ -671,6 +680,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
   // unit tests keep their semantics; production call-sites always pass
   // it.
   let assumptionErrors = [];
+  let assumptionNormalizations = [];
   if (opts.baseBranchRef) {
     const assumptionReport = validateStoryFileAssumptions({
       tickets,
@@ -699,6 +709,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
       );
     }
     assumptionErrors = assumptionReport.errors;
+    assumptionNormalizations = assumptionReport.normalizations ?? [];
   }
 
   const sizingFindings = computeSizingFindings({
@@ -741,7 +752,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
     errors.push(`File assumption mismatch: ${e}`);
   }
 
-  attachFindingsAndErrors(tickets, findings, errors);
+  attachFindingsAndErrors(tickets, findings, errors, assumptionNormalizations);
   return tickets;
 }
 

package/.agents/scripts/lib/orchestration/ticketing/bulk.js

@@ -401,25 +401,59 @@ async function cascadeCompletion(provider, ticketId, opts = {}) {
  * Derive the parent `agent::*` state from the composition of its children.
  *
  * Rules (Story #2676):
- * - Any child carrying `agent::blocked` → parent should be `agent::blocked`.
+ * - Any **open** child carrying `agent::blocked` → parent should be
+ *   `agent::blocked`.
  * - Otherwise, every child is `agent::done` (or closed) → parent should be
  *   `agent::done`.
- * - Otherwise, any child carrying `agent::executing` or `agent::closing` →
- *   parent should be `agent::executing`.
+ * - Otherwise, any **open** child carrying `agent::executing` or
+ *   `agent::closing` → parent should be `agent::executing`.
  * - Otherwise (e.g. all children still `agent::ready`) → return `null` to
  *   signal "leave the parent unchanged". A parent already partway through
  *   the lifecycle MUST NOT be downgraded just because one child reverted.
  *
+ * **A closed child contributes no `agent::*` state** (Story #5255). Its label
+ * records the state it was in when it stopped, not outstanding work, and
+ * nothing clears it on the way out: a Story re-planned out of `agent::blocked`
+ * is closed as superseded still wearing that label, and the blocked rule then
+ * pinned its container Epic open forever — `epic-rollup.js` bails before its
+ * close path on any derived state other than `agent::done`, so the Epic
+ * reported `pending` every run with every child long since closed. Filtering
+ * here rather than at that one call site is what also covers a child closed by
+ * hand with a stale state label attached. The all-done branch already counted
+ * `state === 'closed'` as done, so a closed child keeps exactly that meaning
+ * and loses only its vote on the other two.
+ *
  * The function is pure and exported so the rule can be exercised in
  * isolation by unit tests without dragging the cascade I/O surface in.
  *
  * @param {Array<{ labels?: string[], state?: string }>} siblings
  * @returns {string|null} A `STATE_LABELS.*` value, or `null` for no-op.
  */
+/**
+ * The labels that still describe **live** work on this child.
+ *
+ * Empty for a closed child: its `agent::*` label records the state it stopped
+ * in, not outstanding work, and the two live-state rules in
+ * {@link deriveParentState} must not read it. The all-done rule reads the
+ * child's labels directly, so a closed child keeps counting as done.
+ *
+ * Module-level rather than another local arrow inside `deriveParentState`:
+ * the CRAP baseline keys anonymous functions positionally within their
+ * enclosing scope, so adding or removing one there renumbers every later
+ * arrow and reports the shift as drift on code that did not change.
+ *
+ * @param {{ labels?: string[], state?: string }} sibling
+ * @returns {string[]}
+ */
+function liveChildLabels(sibling) {
+  if (sibling?.state === 'closed') return [];
+  return Array.isArray(sibling?.labels) ? sibling.labels : [];
+}
+
 export function deriveParentState(siblings) {
   if (!Array.isArray(siblings) || siblings.length === 0) return null;
   const labelsOf = (s) => (Array.isArray(s?.labels) ? s.labels : []);
-  if (siblings.some((s) => labelsOf(s).includes(STATE_LABELS.BLOCKED))) {
+  if (siblings.some((s) => liveChildLabels(s).includes(STATE_LABELS.BLOCKED))) {
     return STATE_LABELS.BLOCKED;
   }
   const allDone = siblings.every(
@@ -428,13 +462,43 @@ export function deriveParentState(siblings) {
   if (allDone) return STATE_LABELS.DONE;
   const anyActive = siblings.some(
     (s) =>
-      labelsOf(s).includes(STATE_LABELS.EXECUTING) ||
-      labelsOf(s).includes(STATE_LABELS.CLOSING),
+      liveChildLabels(s).includes(STATE_LABELS.EXECUTING) ||
+      liveChildLabels(s).includes(STATE_LABELS.CLOSING),
   );
   if (anyActive) return STATE_LABELS.EXECUTING;
   return null;
 }
 
+/**
+ * Did any of these children actually **land**?
+ *
+ * `deriveParentState` answers `agent::done` for a child set in which every
+ * child is done *or closed*, and it is right to: a closed child is finished
+ * work as far as the parent's lifecycle goes. But "finished" and "landed" are
+ * different claims, and the close path spends the difference. A cohort
+ * re-planned out of existence closes every child as superseded, carrying no
+ * `agent::done` and having merged nothing — and the container above it then
+ * closed as `completed`, over a log line claiming every child Story landed.
+ * Both the state reason and the sentence were false.
+ *
+ * So the two questions are asked separately: `deriveParentState` decides
+ * *whether* the parent is finished, this decides *how* it finished. A single
+ * landed child is enough — a container that delivered some of its work and
+ * superseded the rest completed, partially, and `not_planned` is reserved for
+ * the case where nothing was delivered at all.
+ *
+ * @param {Array<{ labels?: string[] }>} children
+ * @returns {boolean} True when at least one child carries `agent::done`.
+ */
+export function anyChildLanded(children) {
+  if (!Array.isArray(children)) return false;
+  return children.some((child) =>
+    (Array.isArray(child?.labels) ? child.labels : []).includes(
+      STATE_LABELS.DONE,
+    ),
+  );
+}
+
 /**
  * Parent-state cascade for non-terminal transitions. Story #2676.
  *