mandrel 2.0.0 → 2.2.0

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

@@ -6,17 +6,24 @@ import { getCiDelivery } from '../../config/ci.js';
 import { resolveConfig } from '../../config-resolver.js';
 import { getStoryBranch, gitSync } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
+import { emitTerminalFriction } from '../../observability/runtime-friction.js';
 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 { releaseStoryLease } from '../single-story-lease-guard.js';
+import {
+  buildTerminalEnvelope,
+  emitTerminalEnvelope,
+  NEXT_COMMANDS,
+  terminalFromWaitOutcome,
+} from '../story-deliver-terminal.js';
 import { runAutoMergePhase } from './phases/auto-merge.js';
 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 { parseCloseOptions } from './phases/options.js';
+import { parseCloseOptions, resolveWaitForMerge } from './phases/options.js';
 import { ensurePullRequestWith } from './phases/pull-request.js';
 import { pushStoryBranch } from './phases/push.js';
 import { handleCriticalReviewBlock } from './phases/review-block.js';
@@ -25,16 +32,94 @@ import { runWrongTreeGuardPhase } from './phases/wrong-tree-guard.js';
 
 const progress = Logger.createProgress('single-story-close', { stderr: true });
 
-function alreadyClosedResult(storyId) {
-  return {
-    success: true,
-    result: {
+/**
+ * Emit the terminal envelope on stdout alongside the legacy close result.
+ *
+ * Both are printed: the envelope is the contract callers parse (Story
+ * #4543), while `STORY CLOSE RESULT` stays byte-compatible for the existing
+ * surfaces that grep it. One writer, one place — so the envelope can never
+ * be emitted from a path that forgot it.
+ *
+ * Story #4578 — the same one-place property is why the runtime-derived
+ * friction emit hangs here: a close that ends `failed`, or parks `pending`
+ * on an exhausted merge-wait budget, is friction the retro must see, and
+ * routing it through the single emitter means no terminal path can forget
+ * it. `emitTerminalFriction` decides what (if anything) is worth a record —
+ * see `frictionForTerminal` for why `blocked` and a `--no-wait-merge`
+ * `pending` are deliberately NOT flagged here.
+ *
+ * Async, and awaited by every caller: the CLI exits via `process.exit` the
+ * moment `main` resolves, so a fire-and-forget append would be discarded.
+ * The emit is best-effort internally and cannot throw.
+ */
+async function emitTerminal({ terminal, result, config }) {
+  // The human-facing result dump stays level-gated; the terminal envelope is
+  // the machine contract and must survive AGENT_LOG_LEVEL=silent.
+  if (result) {
+    Logger.info(
+      `\n--- STORY CLOSE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
+    );
+  }
+  emitTerminalEnvelope(terminal);
+  await emitTerminalFriction({ envelope: terminal, config });
+}
+
+/**
+ * Terminal for a Story that was already closed before this run started.
+ *
+ * `state: 'closed'` alone does NOT mean the work landed. GitHub closes an
+ * issue as `completed` (the `Closes #<id>` footer firing on merge — the work
+ * IS on the base branch) or as `not_planned` (superseded by a re-plan,
+ * abandoned — nothing ever merged). Reporting the second as `landed` told
+ * `/deliver` that work had reached `main` when no PR ever merged, which would
+ * also satisfy any dependent Story waiting on it. Fail loudly instead: being
+ * handed an abandoned Story is an input error only the operator can resolve.
+ *
+ * A null `stateReason` keeps the `completed` reading — GitHub defaults to it,
+ * and issues closed before the field existed carry null.
+ */
+async function alreadyClosedResult(storyId, stateReason = null, config) {
+  if (stateReason === 'not_planned') {
+    const result = {
       storyId,
       standalone: true,
       action: 'noop',
-      reason: 'already-closed',
-    },
+      reason: 'closed-not-planned',
+    };
+    const terminal = buildTerminalEnvelope({
+      storyId,
+      status: 'failed',
+      phase: 'init',
+      failure: {
+        reason:
+          `Story #${storyId} is closed as not planned (superseded or abandoned) — ` +
+          'there is nothing to land. Re-plan it as a new Story, or pass a Story that is still open.',
+      },
+      nextCommand: null,
+      elapsedSeconds: 0,
+    });
+    await emitTerminal({ terminal, result, config });
+    return { success: false, result, terminal };
+  }
+
+  const result = {
+    storyId,
+    standalone: true,
+    action: 'noop',
+    reason: 'already-closed',
   };
+  // Idempotent re-run against a Story closed as completed. `landed` is the
+  // honest status — the issue closed on merge, so the work is on the base
+  // branch — and there is nothing left to command.
+  const terminal = buildTerminalEnvelope({
+    storyId,
+    status: 'landed',
+    phase: 'done',
+    nextCommand: null,
+    elapsedSeconds: 0,
+  });
+  await emitTerminal({ terminal, result, config });
+  return { success: true, result, terminal };
 }
 
 function resolveWorktreePath({ cwd, config, storyId }) {
@@ -55,7 +140,9 @@ async function runPrePushPhases({
   skipSync,
   injectedSync,
   injectedGitSpawn,
+  setPhase = () => {},
 }) {
+  setPhase('wrong-tree-guard');
   await runWrongTreeGuardPhase({
     cwd,
     worktreePath,
@@ -66,6 +153,7 @@ async function runPrePushPhases({
     gitSpawn: injectedGitSpawn,
   });
   if (!skipValidation) {
+    setPhase('close-validation');
     await runCloseValidationPhase({
       cwd,
       worktreePath,
@@ -81,6 +169,7 @@ async function runPrePushPhases({
     progress('VALIDATE', '⏭ Skipped (--skip-validation).');
   }
   if (!skipSync) {
+    setPhase('base-sync');
     await runBaseSyncPhase({
       cwd,
       worktreePath,
@@ -105,8 +194,11 @@ async function openAndReviewPr({
   provider,
   injectedGh,
   injectedRunCodeReview,
+  setPhase = () => {},
 }) {
+  setPhase('push');
   pushStoryBranch({ cwd, storyBranch, gitSync, progress });
+  setPhase('pull-request');
   const prUrl = await ensurePullRequestWith({
     cwd,
     storyId,
@@ -117,6 +209,7 @@ async function openAndReviewPr({
     progress,
   });
   const prNumber = parsePrNumber(prUrl);
+  setPhase('code-review');
   const reviewOutcome = await runStoryScopeReview({
     cwd,
     storyId,
@@ -176,8 +269,12 @@ async function releaseLease({
  * The two recoverable-blocked close exits (base-sync conflict in
  * `runBaseSyncPhase`, and a critical-blocker review halt in
  * `openAndReviewPr`) throw before the clean-close lease release at the
- * tail of `runSingleStoryClose`, stranding the operator's lease until its
- * TTL expires. That fail-closed-refuses a different operator who picks up
+ * tail of `runSingleStoryClose`, stranding the operator's lease
+ * indefinitely. The standalone lease does **not** expire by TTL: it is
+ * fail-closed by design (`lease-guard-shared.js` anchors `heartbeatAt` to
+ * now, so `isClaimLive` is true for any foreign assignee regardless of the
+ * configured TTL), so a stranded claim is cleared only by `--steal` or
+ * de-assignment. That fail-closed-refuses a different operator who picks up
  * the blocked Story — exactly the hand-off case. Releasing here closes
  * that gap.
  *
@@ -232,7 +329,7 @@ function closeResult({
     waitedForMerge,
     merged,
     note: waitedForMerge
-      ? 'Headless must-land: PR merge confirmed. Story flipped agent::closing → agent::done and the issue closed (confirmStoryMerged).'
+      ? '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). GitHub will squash-merge when required checks pass; run single-story-confirm-merge.js after the merge confirms to flip agent::done and close the issue (the Closes #<id> footer also auto-closes it).'
         : 'PR open against baseBranch. Story rests at agent::closing (issue stays OPEN). Operator merges via GitHub UI; run single-story-confirm-merge.js after the merge confirms to flip agent::done (the Closes #<id> footer also auto-closes the issue).',
@@ -245,9 +342,9 @@ export async function runSingleStoryClose({
   skipValidation: skipValidationParam,
   skipSync: skipSyncParam,
   noAutoMerge: noAutoMergeParam,
-  noFullScopeCrap: noFullScopeCrapParam,
   waitForMerge: waitForMergeParam,
   noWaitForMerge: noWaitForMergeParam,
+  maxWaitSeconds: maxWaitSecondsParam,
   injectedProvider,
   injectedConfig,
   injectedNotify,
@@ -263,16 +360,65 @@ export async function runSingleStoryClose({
     skipValidationParam,
     skipSyncParam,
     noAutoMergeParam,
-    noFullScopeCrapParam,
     waitForMergeParam,
     noWaitForMergeParam,
+    maxWaitSecondsParam,
   });
   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] [--no-full-scope-crap] [--wait-merge|--no-wait-merge]',
+      '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>]',
     );
   }
 
+  // Story #4543 — track the phase so a crash is attributable. The runner
+  // deliberately keeps THROWING (the library contract every caller and test
+  // relies on: a failed gate must not look like a return value); it only tags
+  // the error with the phase it died in, and the CLI boundary turns that into
+  // the `failed` terminal envelope. Tagging rather than swallowing is what
+  // lets `failed` name its phase without inventing a second success path.
+  let phase = 'init';
+  const setPhase = (next) => {
+    phase = next;
+  };
+  try {
+    return await runClosePipeline({
+      options,
+      setPhase,
+      injectedProvider,
+      injectedConfig,
+      injectedNotify,
+      injectedSync,
+      injectedRunCodeReview,
+      injectedGh,
+      injectedGitSpawn,
+      injectedReleaseLease,
+    });
+  } catch (err) {
+    if (err && typeof err === 'object' && !err.closePhase) {
+      err.closePhase = phase;
+    }
+    throw err;
+  }
+}
+
+/**
+ * The close pipeline proper. Split out of `runSingleStoryClose` so the
+ * phase-tagging wrapper above stays a thin, obviously-correct boundary rather
+ * than a try block wrapped around a hundred lines of pipeline.
+ */
+async function runClosePipeline({
+  options,
+  setPhase,
+  injectedProvider,
+  injectedConfig,
+  injectedNotify,
+  injectedSync,
+  injectedRunCodeReview,
+  injectedGh,
+  injectedGitSpawn,
+  injectedReleaseLease,
+}) {
+  const startedAtMs = Date.now();
   const config = injectedConfig || resolveConfig({ cwd: options.cwd });
   const provider = injectedProvider || createProvider(config);
   const baseBranch = config.project?.baseBranch ?? 'main';
@@ -283,9 +429,15 @@ export async function runSingleStoryClose({
   if (story.state === 'closed') {
     progress(
       'NOOP',
-      `Story #${options.storyId} is already closed. Nothing to do.`,
+      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,
+      config,
     );
-    return alreadyClosedResult(options.storyId);
   }
 
   const worktreePath = resolveWorktreePath({
@@ -314,6 +466,7 @@ export async function runSingleStoryClose({
         worktreePath,
         injectedSync,
         injectedGitSpawn,
+        setPhase,
       }),
     leaseArgs,
   );
@@ -329,9 +482,11 @@ export async function runSingleStoryClose({
         provider,
         injectedGh,
         injectedRunCodeReview,
+        setPhase,
       }),
     leaseArgs,
   );
+  setPhase('auto-merge');
   const { autoMergeEnabled, autoMergeReason } = await runAutoMergePhase({
     cwd: options.cwd,
     prNumber,
@@ -362,32 +517,68 @@ export async function runSingleStoryClose({
   });
   const leaseReleased = await releaseLease(leaseArgs);
 
-  // Story #4428 — headless must-land: `--wait-merge` polls the just-armed
-  // PR to merge confirmation (or an explicit `agent::blocked` +
-  // `merge.unlanded`) instead of resting at `agent::closing`. Attended
-  // (non-headless) runs never set this flag, so the exit shape below is
-  // unreachable and the pre-existing early-return is byte-identical.
-  if (options.waitForMerge) {
+  // Close-and-land (Story #4428; default since `delivery.routing.closeAndLand`
+  // — Story #4539): poll the just-armed PR to merge confirmation, or block
+  // explicitly with `merge.unlanded`, instead of resting at `agent::closing`.
+  // This is the DEFAULT path for attended and headless runs alike.
+  //
+  // Resolved here rather than at parse time because two inputs do not exist
+  // until now: the resolved config (whose cwd the parse produces) and the
+  // actual arm outcome. A PR the operator deliberately left un-armed
+  // (`--no-auto-merge` / `autoMerge: "strict"`) has nothing to land, so it
+  // rests at `agent::closing` for the human instead of burning the poll
+  // budget and then blocking a healthy Story.
+  const { waitForMerge, reason: waitForMergeReason } = resolveWaitForMerge({
+    waitForMergeExplicit: options.waitForMergeExplicit,
+    noWaitForMerge: options.noWaitForMerge,
+    config,
+    autoMergeReason,
+  });
+  if (waitForMergeReason === 'operator-merge') {
+    progress(
+      'MERGE',
+      `⏭  Not waiting for merge (${autoMergeReason}) — the operator owns this merge; ` +
+        `Story #${options.storyId} rests at agent::closing.` +
+        (options.waitForMergeExplicit === true
+          ? ' --wait-merge cannot land a PR that was deliberately left un-armed.'
+          : ''),
+    );
+  }
+  const gates = {
+    validation: options.skipValidation ? 'skipped' : 'passed',
+    baseSync: options.skipSync ? 'skipped' : 'passed',
+    codeReview: 'passed',
+  };
+
+  if (waitForMerge) {
+    setPhase('confirm-merge');
     const waitOutcome = await runConfirmMergePhase({
       cwd: options.cwd,
       storyId: options.storyId,
+      storyBranch,
+      baseBranch,
       prNumber,
       prUrl,
       autoMergeEnabled,
       autoMergeReason,
       provider,
       config,
+      maxWaitSeconds: options.maxWaitSeconds,
       progress,
       injectedGh,
       injectedNotify,
     });
-    if (!waitOutcome.confirmed) {
-      throw new Error(
-        `[single-story-close] Headless must-land: PR ${prUrl} did not reach a confirmed merge ` +
-          `(blockClass=${waitOutcome.blockClass}). Story #${options.storyId} was transitioned to ` +
-          `agent::blocked with a merge.unlanded lifecycle event. Reason: ${waitOutcome.reason}`,
-      );
-    }
+    const terminal = terminalFromWaitOutcome({
+      waitOutcome,
+      storyId: options.storyId,
+      storyBranch,
+      baseBranch,
+      prNumber,
+      prUrl,
+      autoMergeEnabled,
+      gates,
+      elapsedSeconds: Math.round((Date.now() - startedAtMs) / 1000),
+    });
     const result = closeResult({
       storyId: options.storyId,
       storyBranch,
@@ -399,16 +590,29 @@ export async function runSingleStoryClose({
       worktreeReaped,
       leaseReleased,
       waitedForMerge: true,
-      merged: true,
+      merged: waitOutcome.confirmed === true,
     });
-    Logger.info(
-      `\n--- STORY CLOSE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
-    );
-    progress(
-      'DONE',
-      `✅ Standalone Story #${options.storyId}: PR merged → ${prUrl}`,
-    );
-    return { success: true, result };
+    await emitTerminal({ terminal, result, config });
+
+    if (terminal.status === 'landed') {
+      progress('DONE', `✅ Story #${options.storyId}: PR merged → ${prUrl}`);
+    } else if (terminal.status === 'pending') {
+      // NOT a failure and NOT a block — the wait reached the edge of its
+      // host slot with the PR healthy and in flight. The CLI maps this to
+      // its own exit code so a caller can resume without classifying.
+      progress(
+        'PENDING',
+        `⏸  Story #${options.storyId}: PR ${prUrl} still in flight — resume with: ${terminal.nextCommand}`,
+      );
+    } else {
+      progress(
+        'BLOCKED',
+        `🛑 Story #${options.storyId}: PR ${prUrl} did not land ` +
+          `(blockClass=${terminal.blocked?.blockClass}). Story is at agent::blocked. ` +
+          `Next: ${terminal.nextCommand}`,
+      );
+    }
+    return { success: terminal.status === 'landed', result, terminal };
   }
 
   const result = closeResult({
@@ -422,13 +626,30 @@ export async function runSingleStoryClose({
     worktreeReaped,
     leaseReleased,
   });
-
-  Logger.info(
-    `\n--- STORY CLOSE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
-  );
+  // `--no-wait-merge` / operator-merge: the PR is open and the human owns
+  // the land. That is a `pending` terminal by definition — the work is not
+  // done, nothing is broken, and one named command finishes it — rather
+  // than a fourth status invented for this one case.
+  const terminal = buildTerminalEnvelope({
+    storyId: options.storyId,
+    status: 'pending',
+    phase: 'auto-merge',
+    storyBranch,
+    baseBranch,
+    pr: {
+      number: prNumber,
+      url: prUrl ?? null,
+      state: 'OPEN',
+      autoMergeEnabled: Boolean(autoMergeEnabled),
+    },
+    gates,
+    nextCommand: NEXT_COMMANDS.confirmMerge(options.storyId),
+    elapsedSeconds: Math.round((Date.now() - startedAtMs) / 1000),
+  });
+  await emitTerminal({ terminal, result, config });
   progress(
     'DONE',
-    `✅ Standalone Story #${options.storyId}: PR ready → ${prUrl}`,
+    `✅ Story #${options.storyId}: PR ready → ${prUrl} (${waitForMergeReason})`,
   );
-  return { success: true, result };
+  return { success: true, result, terminal };
 }

package/.agents/scripts/lib/orchestration/single-story-lease-guard.js

@@ -116,7 +116,7 @@ export async function acquireStoryLease({
     anchorHeartbeatToNow: true,
     renderRefusal: (result) =>
       `single-story lease: Story #${storyId} is currently held by @${result.owner}. ` +
-      'Another /single-story-deliver run owns this Story. Coordinate with that ' +
+      'Another /deliver run owns this Story. Coordinate with that ' +
       'operator, or re-run with --steal to forcibly transfer the claim once you ' +
       'have confirmed the other run is dead. (The standalone path has no Epic ' +
       'heartbeat ledger, so a foreign assignee always blocks unless stolen.)',

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

@@ -328,7 +328,7 @@ export function runFormatAutofix({
 }
 
 /**
- * List the files changed between `epicBranch` and `storyBranch` using the
+ * List the files changed between `baseBranch` and `storyBranch` using the
  * three-dot merge-base diff. Delegates parsing to `diffNameOnly` from
  * `changed-files.js` so the stdout → path-list conversion lives in one place.
  *
@@ -336,10 +336,10 @@ export function runFormatAutofix({
  * `(args: string[], opts: object) => string`. A bridge adapter wraps it into
  * the `gitSpawn(cwd, ...args)` shape that `diffNameOnly` expects.
  *
- * @param {{ cwd: string, epicBranch: string, storyBranch: string, git: Function }} opts
+ * @param {{ cwd: string, baseBranch: string, storyBranch: string, git: Function }} opts
  * @returns {string[]}
  */
-function listChangedFiles({ cwd, epicBranch, storyBranch, git }) {
+function listChangedFiles({ cwd, baseBranch, storyBranch, git }) {
   // Bridge the (args, opts) → string interface into gitSpawn(cwd, ...args).
   const gitSpawn = (_cwd, ...args) => {
     try {
@@ -358,7 +358,7 @@ function listChangedFiles({ cwd, epicBranch, storyBranch, git }) {
     }
   };
   return diffNameOnly({
-    range: `${epicBranch}...${storyBranch}`,
+    range: `${baseBranch}...${storyBranch}`,
     cwd,
     gitSpawn,
   });
@@ -401,7 +401,7 @@ function listChangedFiles({ cwd, epicBranch, storyBranch, git }) {
  *   cwd: string,
  *   worktreePath?: string,
  *   storyId: number|string,
- *   epicBranch: string,
+ *   baseBranch: string,
  *   storyBranch: string,
  *   config?: object,
  *   logger?: object,
@@ -420,7 +420,7 @@ export function runScopedFormatAutofix({
   cwd,
   worktreePath,
   storyId,
-  epicBranch,
+  baseBranch,
   storyBranch,
   config,
   logger = DefaultLogger,
@@ -428,8 +428,8 @@ export function runScopedFormatAutofix({
   gitSync,
 } = {}) {
   if (!cwd) throw new Error('runScopedFormatAutofix: cwd is required');
-  if (!epicBranch)
-    throw new Error('runScopedFormatAutofix: epicBranch is required');
+  if (!baseBranch)
+    throw new Error('runScopedFormatAutofix: baseBranch is required');
   if (!storyBranch)
     throw new Error('runScopedFormatAutofix: storyBranch is required');
 
@@ -449,13 +449,13 @@ export function runScopedFormatAutofix({
 
   const changed = listChangedFiles({
     cwd: workTree,
-    epicBranch,
+    baseBranch,
     storyBranch,
     git,
   });
   if (changed.length === 0) {
     logger.info?.(
-      `${SCOPED_TAG} skipped — no changed files between ${epicBranch} and ${storyBranch}.`,
+      `${SCOPED_TAG} skipped — no changed files between ${baseBranch} and ${storyBranch}.`,
     );
     return { ran: false, committed: false, reason: 'no-changed-files' };
   }