mandrel 1.94.0 → 2.1.0

package/.agents/scripts/single-story-confirm-merge.js

@@ -10,7 +10,7 @@
  * auto-merge completes *asynchronously* after the close script exits, so
  * the `agent::done` flip (which closes the issue) is deferred to this
  * confirmation step, invoked by the CI-watch loop in
- * `single-story-deliver.md` Step 5 once `pr-watch-with-update.js` exits.
+ * `helpers/deliver-story.md` once `pr-watch-with-update.js` exits.
  *
  * The script:
  *   1. Resolves the PR number (`--pr <n>`, or probes
@@ -32,17 +32,30 @@
  *
  * Exit codes: 0 ok (merged, pending, or noop), 1 error.
  *
- * @see .agents/workflows/helpers/single-story-deliver.md § Step 5
+ * @see .agents/workflows/helpers/deliver-story.md
  */
 
 import { parseArgs } from 'node:util';
+import { parseSprintArgs } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
+import { formatCliError } from './lib/error-redactor.js';
 import { gh as defaultGh } from './lib/gh-exec.js';
 import { getStoryBranch } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
+import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
+import { MERGED_FLIP_FAILED_BLOCK_CLASS } from './lib/orchestration/lifecycle/emit-merge-flip-failed.js';
 import { parsePrNumber } from './lib/orchestration/single-story-close/phases/code-review.js';
+import { runConfirmMergePhase as defaultRunConfirmMergePhase } from './lib/orchestration/single-story-close/phases/confirm-merge.js';
 import { parseCloseOptions } from './lib/orchestration/single-story-close/phases/options.js';
+import { runPostLandTail } from './lib/orchestration/single-story-close/phases/post-land.js';
+import {
+  buildTerminalEnvelope,
+  emitTerminalEnvelope,
+  exitCodeForTerminal,
+  NEXT_COMMANDS,
+  terminalFromWaitOutcome,
+} from './lib/orchestration/story-deliver-terminal.js';
 import { createProvider } from './lib/provider-factory.js';
 import { confirmStoryMerged } from './lib/single-story/confirm-merge.js';
 
@@ -70,6 +83,28 @@ function readPrFlag() {
   }
 }
 
+/**
+ * `--wait`: resume the bounded merge wait rather than probing once.
+ *
+ * This CLI serves two callers behind one command string. `confirmMerge` wants
+ * a fast idempotent flip for a merge that ALREADY happened (an operator-merge
+ * flow, or a `merged-flip-failed` retry) and must not stall. `resumeLand`
+ * wants to pick up a merge wait the close handed off at its per-invocation
+ * bound — that one must actually wait, and must be able to give up.
+ */
+function readWaitFlag() {
+  try {
+    const { values } = parseArgs({
+      args: process.argv.slice(2),
+      options: { wait: { type: 'boolean', default: false } },
+      strict: false,
+    });
+    return values.wait === true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Resolve the PR number for the Story branch when one was not passed on
  * the CLI. Probes `gh pr list --head <branch> --state all` (the merged PR
@@ -98,6 +133,118 @@ async function resolvePrNumber({ cwd, storyBranch, gh }) {
   }
 }
 
+/**
+ * Story #4578 — async so the runtime-derived friction emit can be awaited.
+ * This CLI is the resume path for a parked worker (`--wait`), so a `pending`
+ * terminal here means a bounded wait expired again with the PR still in
+ * flight: the exact observable the retro was blind to. The emit is
+ * best-effort and cannot throw; awaiting it matters because `runAsCli`
+ * exits via `process.exit` the moment `main` resolves.
+ */
+async function logConfirmResult(result, terminal, config) {
+  // Human-facing dump stays level-gated; the envelope is the machine
+  // contract and must survive AGENT_LOG_LEVEL=silent.
+  Logger.info(
+    `\n--- CONFIRM MERGE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
+  );
+  emitTerminalEnvelope(terminal);
+  await emitTerminalFriction({ envelope: terminal, config });
+  return { success: terminal.status !== 'failed', result, terminal };
+}
+
+/**
+ * Map a `confirmStoryMerged` envelope onto the shared terminal envelope
+ * (Story #4543) so this CLI and the in-close land path report one shape.
+ *
+ * The three confirm outcomes map cleanly:
+ *   - `done` / `noop` (already-done) → `landed`. Both mean the merge is on
+ *     the base branch and the Story is `agent::done`.
+ *   - `pending` (`pr-open` / `no-pr`) → `pending`. Re-run once the merge
+ *     lands; nothing is wrong.
+ *   - `flip-failed` → `blocked` with the shared `merged-flip-failed` class:
+ *     the merge landed, so this is a label-write fault, and the remedy is
+ *     re-running this very command (it is idempotent).
+ *   - `pr-not-merged` (closed without merging) → `blocked`. The PR is gone;
+ *     a re-run cannot fix it, so it needs a human.
+ */
+function buildConfirmTerminal({
+  storyId,
+  storyBranch,
+  baseBranch,
+  prNumber,
+  confirmation,
+  tail,
+  elapsedSeconds,
+}) {
+  // `pr-not-merged` means the PR is CLOSED — reporting it as OPEN put a
+  // fact in the envelope that the blocked reason directly contradicts.
+  const prState = confirmation.merged
+    ? 'MERGED'
+    : confirmation.reason === 'pr-not-merged'
+      ? 'CLOSED'
+      : 'OPEN';
+  const pr =
+    Number.isInteger(prNumber) && prNumber > 0
+      ? { number: prNumber, state: prState }
+      : null;
+  const common = { storyId, storyBranch, baseBranch, pr, elapsedSeconds };
+
+  if (confirmation.action === 'done' || confirmation.action === 'noop') {
+    return buildTerminalEnvelope({
+      ...common,
+      status: 'landed',
+      phase: tail ? 'post-land' : 'done',
+      tail,
+      nextCommand: null,
+    });
+  }
+  if (confirmation.action === 'flip-failed') {
+    return buildTerminalEnvelope({
+      ...common,
+      status: 'blocked',
+      phase: 'confirm-merge',
+      blocked: {
+        blockClass: MERGED_FLIP_FAILED_BLOCK_CLASS,
+        reason:
+          'merge confirmed but the agent::closing → agent::done label write failed',
+        frictionCommentId: null,
+      },
+      nextCommand: NEXT_COMMANDS.confirmMerge(storyId),
+    });
+  }
+  if (confirmation.reason === 'pr-not-merged') {
+    return buildTerminalEnvelope({
+      ...common,
+      status: 'blocked',
+      phase: 'confirm-merge',
+      blocked: {
+        blockClass: 'api-race-other',
+        reason: 'the PR was closed without merging (state=CLOSED)',
+        frictionCommentId: null,
+      },
+      nextCommand: NEXT_COMMANDS.recover(storyId),
+    });
+  }
+  return buildTerminalEnvelope({
+    ...common,
+    status: 'pending',
+    phase: 'confirm-merge',
+    nextCommand:
+      confirmation.reason === 'no-pr'
+        ? NEXT_COMMANDS.recover(storyId)
+        : NEXT_COMMANDS.confirmMerge(storyId),
+  });
+}
+
+async function resolveConfirmPrNumber({ prParam, cwd, storyBranch, gh }) {
+  const rawPr = prParam ?? readPrFlag();
+  let prNumber = Number.parseInt(String(rawPr ?? ''), 10);
+  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+    prNumber = await resolvePrNumber({ cwd, storyBranch, gh });
+  }
+  return Number.isInteger(prNumber) && prNumber > 0 ? prNumber : null;
+}
+
 /**
  * Confirm a standalone Story's merge. Exported for testing.
  */
@@ -105,11 +252,13 @@ export async function runConfirmMerge({
   storyId: storyIdParam,
   cwd: cwdParam,
   pr: prParam,
+  wait: waitParam,
   injectedProvider,
   injectedConfig,
   injectedGh,
   injectedNotify,
   injectedReadPrMergeState,
+  runConfirmMergePhaseFn = defaultRunConfirmMergePhase,
 } = {}) {
   const { storyId, cwd } = parseCloseOptions({
     storyIdParam,
@@ -118,41 +267,107 @@ export async function runConfirmMerge({
 
   if (!storyId) {
     throw new Error(
-      'Usage: node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>] [--cwd <main-repo>]',
+      'Usage: node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>] [--wait] [--cwd <main-repo>]',
     );
   }
+  const wait = waitParam ?? readWaitFlag();
 
+  const startedAtMs = Date.now();
   const config = injectedConfig || resolveConfig({ cwd });
   const provider = injectedProvider || createProvider(config);
   const gh = injectedGh ?? defaultGh;
-  const storyBranch = getStoryBranch(0, storyId);
+  const storyBranch = getStoryBranch(storyId);
+  const baseBranch = config.project?.baseBranch ?? 'main';
 
   progress('INIT', `Confirming merge for standalone Story #${storyId}...`);
 
-  // Resolve the PR number: explicit injection wins; otherwise read the
-  // `--pr` CLI flag; otherwise probe `gh pr list`.
-  const rawPr = prParam ?? readPrFlag();
-  let prNumber = Number.parseInt(String(rawPr ?? ''), 10);
-  if (!Number.isInteger(prNumber) || prNumber <= 0) {
-    prNumber = await resolvePrNumber({ cwd, storyBranch, gh });
-  }
-
-  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+  const prNumber = await resolveConfirmPrNumber({
+    prParam,
+    cwd,
+    storyBranch,
+    gh,
+  });
+  if (prNumber == null) {
     progress(
       'CONFIRM',
       `⚠️ No PR found for ${storyBranch}; cannot confirm merge. Story stays at agent::closing.`,
     );
-    const result = {
+    const noPr = {
       storyId,
       standalone: true,
       action: 'pending',
       reason: 'no-pr',
       merged: false,
     };
-    Logger.info(
-      `\n--- CONFIRM MERGE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
+    return await logConfirmResult(
+      noPr,
+      buildConfirmTerminal({
+        storyId,
+        storyBranch,
+        baseBranch,
+        prNumber: null,
+        confirmation: noPr,
+        tail: null,
+        elapsedSeconds: Math.round((Date.now() - startedAtMs) / 1000),
+      }),
+      config,
+    );
+  }
+
+  // `--wait` (what `NEXT_COMMANDS.resumeLand` passes): resume the merge wait
+  // the close handed off at its per-invocation bound, by running the SAME
+  // phase the in-close path runs. Without this the resume was a single probe
+  // that reported `pending` and exited, so the cumulative `maxBudgetSeconds`
+  // give-up — the only thing that ever emits `merge.unlanded` and flips a
+  // wedged Story to `agent::blocked` — was reachable ONLY inside the original
+  // close invocation. A PR that wedged after the close returned could be
+  // resumed forever, always answering `pending`, never escalating to anyone.
+  //
+  // The phase anchors its cumulative budget at the PR's `createdAt`, so the
+  // resume does not restart the clock — exactly what the envelope's
+  // `waitBudget` contract already promised.
+  if (wait) {
+    const waitOutcome = await runConfirmMergePhaseFn({
+      cwd,
+      storyId,
+      storyBranch,
+      baseBranch,
+      prNumber,
+      prUrl: `${storyBranch} PR #${prNumber}`,
+      // The close already armed it; this CLI is resuming that wait, not
+      // deciding whether to arm.
+      autoMergeEnabled: true,
+      provider,
+      config,
+      progress,
+      injectedGh: gh,
+      injectedNotify,
+      readPrMergeStateFn: injectedReadPrMergeState,
+    });
+    const terminal = terminalFromWaitOutcome({
+      waitOutcome,
+      storyId,
+      storyBranch,
+      baseBranch,
+      prNumber,
+      prUrl: null,
+      autoMergeEnabled: true,
+      // This CLI runs no close gates, so it reports none — `gates` is
+      // "each gate this invocation was responsible for".
+      gates: undefined,
+      elapsedSeconds: Math.round((Date.now() - startedAtMs) / 1000),
+    });
+    return await logConfirmResult(
+      {
+        storyId,
+        standalone: true,
+        action: waitOutcome.terminal,
+        resumed: true,
+        tail: waitOutcome.tail ?? null,
+      },
+      terminal,
+      config,
     );
-    return { success: true, result };
   }
 
   const confirmation = await confirmStoryMerged({
@@ -168,16 +383,90 @@ export async function runConfirmMerge({
     readPrMergeStateFn: injectedReadPrMergeState,
   });
 
-  const result = { standalone: true, prNumber, ...confirmation };
-  Logger.info(
-    `\n--- CONFIRM MERGE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
+  // Story #4543 — reach the SAME shared land tail the in-close path reaches
+  // (`phases/post-land.js`), rather than this CLI's own follow-ups-only
+  // wrapper. That wrapper was the whole reason the two landing surfaces
+  // diverged: it captured follow-ups and nothing else, while the resync and
+  // cleanup steps lived in prose the caller had to remember to run.
+  //
+  // Gated on `merged`, NOT on `action === 'done'`. `done` means "this run
+  // flipped the label"; a Story already at `agent::done` returns
+  // `action: 'noop', merged: true`, and gating on `done` skipped the tail for
+  // exactly that case — the belated-manual-confirm backfill this tail exists
+  // to make possible (see `story-follow-ups.js`, which documents the gap).
+  // Re-running is safe: every step is idempotent (the follow-ups comment is
+  // an upsert, ref cleanup and base fast-forward no-op when already done).
+  const tail =
+    confirmation.merged === true
+      ? await runPostLandTail({
+          storyId,
+          storyBranch,
+          baseBranch,
+          cwd,
+          provider,
+          config,
+          progress,
+        })
+      : null;
+
+  const terminal = buildConfirmTerminal({
+    storyId,
+    storyBranch,
+    baseBranch,
+    prNumber,
+    confirmation,
+    tail,
+    elapsedSeconds: Math.round((Date.now() - startedAtMs) / 1000),
+  });
+  if (confirmation.action === 'done') {
+    progress('DONE', `✅ Story #${storyId} → agent::done (merged).`);
+  }
+  return await logConfirmResult(
+    { ...confirmation, standalone: true, tail },
+    terminal,
+    config,
   );
-  if (result.action === 'done') {
-    progress('DONE', `✅ Standalone Story #${storyId} → agent::done (merged).`);
+}
+
+/**
+ * CLI entry — mirrors `single-story-close.js`: the exit code comes from the
+ * terminal envelope's status, so a caller can tell `pending` (the PR has not
+ * merged yet; re-run me) from `landed` without parsing stdout.
+ *
+ * The catch mirrors close's for the same reason: `confirmStoryMerged`'s PR
+ * read is a live `gh` call that throws on a transient API error, and this CLI
+ * is a *landing surface* — the one `pending` tells the operator to re-run. If
+ * a flaked read exited 1 with no envelope, the surface would be silent exactly
+ * where the envelope is the contract. Both landing surfaces emit one envelope
+ * or none at all; "none at all" is what Story #4543 removes.
+ */
+async function main() {
+  try {
+    const outcome = await runConfirmMerge();
+    return exitCodeForTerminal(outcome?.terminal ?? { status: 'failed' });
+  } catch (err) {
+    const storyId = Number(parseSprintArgs().storyId);
+    // No story id → a usage error; there is nothing to report an envelope
+    // about, so let runAsCli surface it as a plain fatal.
+    if (!Number.isInteger(storyId) || storyId <= 0) throw err;
+    const terminal = buildTerminalEnvelope({
+      storyId,
+      status: 'failed',
+      phase: 'confirm-merge',
+      failure: { reason: String(err?.message ?? err) },
+      nextCommand: NEXT_COMMANDS.recover(storyId),
+      elapsedSeconds: 0,
+    });
+    Logger.error(
+      `[single-story-confirm-merge] Fatal error: ${formatCliError(err)}`,
+    );
+    emitTerminalEnvelope(terminal);
+    await emitTerminalFriction({ envelope: terminal });
+    return exitCodeForTerminal(terminal);
   }
-  return { success: true, result };
 }
 
-runAsCli(import.meta.url, runConfirmMerge, {
+runAsCli(import.meta.url, main, {
   source: 'single-story-confirm-merge',
+  propagateExitCode: true,
 });

package/.agents/scripts/single-story-init.js

@@ -2,14 +2,12 @@
 /* node:coverage ignore file */
 
 /**
- * single-story-init.js — Initialize a standalone Story (no parent Epic).
+ * single-story-init.js — Initialize a Story for v2 `/deliver`.
  *
- * Counterpart to `story-init.js` for the `/single-story-deliver` workflow.
- * The framework's main `story-init.js` requires an `Epic: #N` reference in
- * the Story body to trace hierarchy, seed the Story branch from
- * `epic/<id>`, and gate execution on the epic's dispatch manifest. None of
- * that applies to a standalone Story — a top-level work unit that branches
- * directly from `main` and opens its PR straight to `main`.
+ * Seeds `story-<id>` from `project.baseBranch` (default `main`), materialises
+ * the per-Story worktree when isolation is enabled, upserts a `story-init`
+ * structured comment, and flips the Story to `agent::executing`. There is no
+ * Epic parent, epic branch, or dispatch-manifest gate.
  *
  * What this script does:
  *   1. Validate the Story (type::story, not closed).
@@ -22,17 +20,14 @@
  *      `standalone: true`.
  *   6. Flip the Story to `agent::executing`.
  *
- * What this script does NOT do (and why):
- *   - Skips `validateBlockers` against the body's `Blocked by:` markers —
- *     pre-flight is still the operator's responsibility, but the Epic-scope
- *     blocker chain doesn't fit.
- *   - Skips child-Task transitions — a standalone Story is treated as
- *     atomic (one branch, one commit-set, one PR).
+ * What this script does NOT do:
+ *   - Child-Task transitions — a Story is atomic (one branch, one
+ *     commit-set, one PR to `main`).
  *
  * Usage: `node single-story-init.js --story <STORY_ID> [--dry-run]`
  * Exit codes: 0 ok, 1 error.
  *
- * @see .agents/workflows/helpers/single-story-deliver.md
+ * @see .agents/workflows/helpers/deliver-story.md
  */
 
 import { existsSync } from 'node:fs';
@@ -61,6 +56,7 @@ import {
 } from './lib/orchestration/git-cleanup/phases/fast-forward.js';
 import { verifyRemote } from './lib/orchestration/remote-verifier.js';
 import { acquireStoryLease } from './lib/orchestration/single-story-lease-guard.js';
+import { handleRemoteVerificationFailure } from './lib/orchestration/story-init-remote.js';
 import {
   STATE_LABELS,
   transitionTicketState,
@@ -74,6 +70,7 @@ import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
 // friendly "run npm install" message.
 import { WorktreeManager } from './lib/worktree-manager.js';
 
+export { handleRemoteVerificationFailure } from './lib/orchestration/story-init-remote.js';
 // `makeGhRunner` moved to the shared `single-story-sweep/protection-ctx.js`
 // module (Story #4373) so the three boot callers build an identical
 // protection ctx. Re-exported here to preserve its existing import path.
@@ -114,12 +111,20 @@ const progress = Logger.createProgress('single-story-init', { stderr: true });
 export function assertDeliverableStory(story, storyId) {
   if (!story.labels.includes(TYPE_LABELS.STORY)) {
     throw new Error(
-      `Issue #${storyId} is not a Story (labels: ${story.labels.join(', ')}). Use /deliver or /deliver for Epic-attached work.`,
+      `Issue #${storyId} is not a Story (labels: ${story.labels.join(', ')}). ` +
+        'v2 /deliver accepts type::story tickets only.',
     );
   }
   if (story.state === 'closed') {
     throw new Error(`Story #${storyId} is already closed.`);
   }
+  const body = typeof story.body === 'string' ? story.body : '';
+  if (/\b(?:Epic|Parent):\s*#\d+/i.test(body)) {
+    throw new Error(
+      `Story #${storyId} still declares an Epic/Parent footer. ` +
+        'v2 delivery is Story-only — re-plan as a standalone Story before /deliver.',
+    );
+  }
 }
 
 /**
@@ -218,12 +223,10 @@ export async function reapMergedStoryBranches({
 /**
  * Fetch remote refs, reap merged story branches, and fast-forward the local
  * base branch so new story branches seed from origin's tip. Exported for
- * testing (owns the fast-forward cascade; mirrors `fetchMainRefs` +
- * `ensureEpicBranch` in `branch-initializer.js`).
+ * testing (owns the fast-forward cascade).
  *
- * Routes the `origin` fetch through `cachedGitFetch` so concurrent standalone
- * Story waves share the same per-process coalescing window that Epic-attached
- * stories get via `branch-initializer.js#fetchMainRefs`. Pass `fetchFn` to
+ * Routes the `origin` fetch through `cachedGitFetch` so concurrent Story
+ * waves share a per-process fetch-coalescing window. Pass `fetchFn` to
  * inject a stub in tests without touching real git.
  *
  * @param {object} opts
@@ -408,12 +411,10 @@ export async function provisionWorktree({
   }
 
   try {
-    // Story #2874 — standalone Stories have no parent Epic; pass
-    // `epicId: null` so the helper omits CC_EPIC_ID from env + file
-    // instead of throwing on a 0 sentinel. The trace hook keys its
-    // standalone-trace branch on CC_EPIC_ID being absent.
+    // v2 Stories are standalone — no parent Epic. The helper omits
+    // CC_EPIC_ID from env + file; the trace hook keys its standalone-trace
+    // branch on CC_EPIC_ID being absent.
     setActiveStoryEnv({
-      epicId: null,
       storyId,
       workCwd,
       logger: {
@@ -478,9 +479,7 @@ export async function runSingleStoryInit({
   const provider = injectedProvider || createProvider(config);
 
   const baseBranch = config.project?.baseBranch ?? 'main';
-  // The first arg is unused (legacy epicId slot); pass 0 to satisfy the
-  // numeric-validation guard.
-  const storyBranch = getStoryBranch(0, storyId);
+  const storyBranch = getStoryBranch(storyId);
 
   const runtime = resolveRuntime({ config });
   progress(
@@ -489,8 +488,8 @@ export async function runSingleStoryInit({
   );
   progress('INIT', `Initializing standalone Story #${storyId}...`);
 
-  // Issue #4483 — deterministic remote evidence at the standalone entry
-  // seam (the counterpart to `epic-deliver-preflight.js`'s probe). The
+  // Issue #4483 — deterministic remote evidence at the v2 `/deliver` entry
+  // seam (`single-story-init.js`). The
   // probe is read-only, so it runs under --dry-run too. The CLI records
   // the fact; the workflow owns the `agent::blocked` transition on
   // `remoteVerified: false` — inline delivery to local `main` is never a
@@ -505,6 +504,12 @@ export async function runSingleStoryInit({
 
   const story = await provider.getTicket(storyId);
   assertDeliverableStory(story, storyId);
+  await handleRemoteVerificationFailure({
+    provider,
+    storyId,
+    remote,
+    dryRun,
+  });
 
   progress(
     'CONTEXT',