mandrel 1.94.0 → 2.0.0

package/.agents/scripts/providers/github/issues.js

@@ -16,11 +16,10 @@
  */
 
 import { Logger } from '../../lib/Logger.js';
-import { TYPE_LABELS } from '../../lib/label-constants.js';
 import { concurrentMap } from '../../lib/util/concurrent-map.js';
 import { isNotFoundError } from './branch-protection.js';
 import { withTransientRetry } from './errors.js';
-import { issueToEpic, issueToEpicListItem } from './mappers.js';
+import { issueToEpic } from './mappers.js';
 import {
   defaultRetryWarn,
   paginateRest,
@@ -114,13 +113,15 @@ export class IssuesGateway {
    * are returned (no `state:` qualifier is appended) so a closed-fingerprint
    * match can surface as `regression-of-closed`.
    *
-   * Returns the trimmed `[{ number, state, body }]` projection the dedup
-   * port expects. `state` is normalised to the REST lowercase form
-   * (`open` / `closed`).
+   * Returns the trimmed `[{ number, state, body, title, html_url }]`
+   * projection. Dedup callers use `{ number, state, body }`; duplicate-
+   * search also needs `title` / `html_url`. `state` is normalised to the
+   * REST lowercase form (`open` / `closed`). Results are capped at one
+   * Search API page (`per_page=100`).
    *
    * @param {{ query: string, owner?: string, repo?: string }} params
-   * @returns {Promise<Array<{ number: number, state: string, body: string }>>}
-   * @field-manifest GET /search/issues: total_count, items[number, state, body]
+   * @returns {Promise<Array<{ number: number, state: string, body: string, title: string, html_url?: string }>>}
+   * @field-manifest GET /search/issues: total_count, items[number, state, body, title, html_url]
    */
   async searchIssues({ query, owner, repo } = {}) {
     if (typeof query !== 'string' || query.trim().length === 0) {
@@ -133,7 +134,8 @@ export class IssuesGateway {
     // issue body where the `<!-- audit-fingerprints: ... -->` footer lives.
     const qualifiers = [`repo:${scopeOwner}/${scopeRepo}`, 'type:issue'];
     const q = `${query.trim()} ${qualifiers.join(' ')}`;
-    const endpoint = `/search/issues?q=${encodeURIComponent(q)}`;
+    const params = new URLSearchParams({ q, per_page: '100' });
+    const endpoint = `/search/issues?${params}`;
     const result = await withTransientRetry(
       () => this._gh.api({ method: 'GET', endpoint }),
       { label: `searchIssues ${query}`, onRetry: defaultRetryWarn },
@@ -144,37 +146,19 @@ export class IssuesGateway {
       number: item.number,
       state: item.state ?? 'open',
       body: item.body ?? '',
+      title: item.title ?? '',
+      html_url: item.html_url ?? undefined,
     }));
   }
 
   /**
-   * List Epic-typed issues. Filter shape preserved from the old code.
-   *
-   * `filters.pageCap` / `filters.perPage` pass through to `paginateRest`
-   * so a caller that only needs a bounded shortlist (e.g. the
-   * standalone-Story corpus lookup in `planning-corpus.js`, which ranks
-   * candidates down to a top-5 shortlist) can cap the scan instead of
-   * inheriting the default 50-page / 5000-item ceiling. Omitted, both
-   * fall back to `paginateRest`'s own defaults — unchanged behavior for
-   * existing callers (e.g. `duplicate-search.js`).
-   *
-   * @field-manifest /repos/{owner}/{repo}/issues?labels=type::epic: number,
-   *                 title, labels, state, state_reason, pull_request
+   * Historical Epic enumeration surface. Stage 5 removed the Epic type from
+   * the taxonomy; callers that have not yet collapsed their planning corpus
+   * reads receive an empty list rather than querying a deleted label.
    */
   /* node:coverage ignore next */
-  async getEpics(filters = {}) {
-    const params = new URLSearchParams({
-      state: filters.state ?? 'all',
-      labels: TYPE_LABELS.EPIC,
-    });
-    const endpoint = `/repos/${this.owner}/${this.repo}/issues?${params}`;
-    const issues = await paginateRest(this._gh, endpoint, {
-      pageCap: filters.pageCap,
-      perPage: filters.perPage,
-    });
-    return issues
-      .filter((issue) => !issue.pull_request)
-      .map(issueToEpicListItem);
+  async getEpics(_filters = {}) {
+    return [];
   }
 
   /**

package/.agents/scripts/providers/github/mappers.js

@@ -109,15 +109,3 @@ export function issueToListItem(issue) {
     state: issue.state,
   };
 }
-
-export function issueToEpicListItem(issue) {
-  const labels = normalizeLabels(issue);
-  return {
-    id: issue.number,
-    title: issue.title,
-    labels,
-    labelSet: new Set(labels),
-    state: issue.state,
-    state_reason: issue.state_reason,
-  };
-}

package/.agents/scripts/providers/github/tickets.js

@@ -336,12 +336,9 @@ export class TicketGateway {
       dependencies: ticketData.dependencies ?? [],
     });
 
-    // Mirror the Epic create path (issues.js:160 → `labels: TYPE_LABELS.EPIC`):
-    // inject TYPE_LABELS.STORY so a spec that omits the labels array cannot
+    // Inject TYPE_LABELS.STORY so a spec that omits the labels array cannot
     // produce an unlabeled, undispatchable Story. Dedupe to avoid duplicates
-    // when the caller already carries the label. (Story #4324 retired the
-    // `context::*` ticket classes, so every ticket created through this
-    // factory is a Story.)
+    // when the caller already carries the label.
     const callerLabels = ticketData.labels ?? [];
     const labels = callerLabels.includes(TYPE_LABELS.STORY)
       ? callerLabels

package/.agents/scripts/resolve-plan-run.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+/**
+ * resolve-plan-run.js — resolve Stories labeled `plan-run::<id>` for
+ * `/deliver --run <planRunId>` (v2 Stage 4).
+ *
+ * Thin CLI over `lib/orchestration/resolve-plan-run.js`.
+ *
+ * Usage:
+ *   node .agents/scripts/resolve-plan-run.js --run <planRunId>
+ *   node .agents/scripts/resolve-plan-run.js --run <planRunId> --state all
+ *   node .agents/scripts/resolve-plan-run.js --run <planRunId> --pretty
+ *
+ * Exit codes: 0 ok, 1 usage/error, 2 no Stories found for the run.
+ */
+
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import {
+  assertIssueState,
+  buildPlanRunEnvelope,
+  fetchPlanRunIssues,
+  normalizePlanRunLabel,
+  planRunIdFromLabel,
+  resolvePlanRunFromIssues,
+} from './lib/orchestration/resolve-plan-run.js';
+import { createProvider } from './lib/provider-factory.js';
+
+export {
+  buildPlanRunEnvelope,
+  fetchPlanRunIssues,
+  normalizePlanRunLabel,
+  planRunIdFromLabel,
+  resolvePlanRunFromIssues,
+};
+
+const HELP = `\
+Usage:
+  resolve-plan-run.js --run <planRunId> [--state open|all|closed] [--pretty]
+
+Resolve Stories labeled plan-run::<planRunId> for /deliver --run.
+
+Options:
+  --run <id>     Plan-run token (with or without the plan-run:: prefix).
+  --state <s>    Issue state filter (default: open).
+  --pretty       Pretty-print the JSON envelope.
+  --help         Show this help.
+`;
+
+function writeEnvelope(envelope, pretty) {
+  const text = pretty
+    ? `${JSON.stringify(envelope, null, 2)}\n`
+    : `${JSON.stringify(envelope)}\n`;
+  process.stdout.write(text);
+}
+
+/**
+ * Resolve config once and pass it to the provider factory. Kept as an
+ * injectable seam so the CLI contract is covered without network access.
+ *
+ * @param {object} [deps]
+ * @param {Function} [deps.resolveConfigFn]
+ * @param {Function} [deps.createProviderFn]
+ * @returns {object}
+ */
+export function resolvePlanRunProvider({
+  resolveConfigFn = resolveConfig,
+  createProviderFn = createProvider,
+} = {}) {
+  const config = resolveConfigFn();
+  return createProviderFn(config);
+}
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      run: { type: 'string' },
+      state: { type: 'string', default: 'open' },
+      pretty: { type: 'boolean', default: false },
+      help: { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  });
+
+  if (values.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (!values.run) {
+    process.stderr.write(HELP);
+    throw new Error('resolve-plan-run: --run <planRunId> is required');
+  }
+
+  const state = assertIssueState(values.state);
+  const planRunLabel = normalizePlanRunLabel(values.run);
+  const planRunId = planRunIdFromLabel(planRunLabel);
+
+  const provider = resolvePlanRunProvider();
+  const issues = await fetchPlanRunIssues(provider, { planRunLabel, state });
+  const envelope = buildPlanRunEnvelope(issues, { planRunId, planRunLabel });
+  writeEnvelope(envelope, values.pretty);
+
+  if (envelope.stories.length === 0) {
+    process.stderr.write(
+      `resolve-plan-run: no type::story issues with label ${planRunLabel} (state=${state})\n`,
+    );
+    return 2;
+  }
+  return 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'resolve-plan-run',
+  propagateExitCode: true,
+});

package/.agents/scripts/signals-view.js

@@ -5,7 +5,7 @@
  * Task #1463).
  *
  * Reads signals via `lib/signals/read`, materialises a span-tree via
- * `lib/signals/buildSpanTree`, and prints a readable Epic → Story → Task →
+ * `lib/signals/buildSpanTree`, and prints a readable run → Story →
  * events tree to stdout. The output is **plain text via
  * `process.stdout.write`** — no Ink, no blessed, no terminal-control
  * escape sequences — so it works on Windows + bash hosts (see
@@ -16,10 +16,10 @@
  * stdout uses `process.stdout.write`, not the console).
  *
  * Usage:
- *   node .agents/scripts/signals-view.js <epic-id> [--story <id>]
+ *   node .agents/scripts/signals-view.js <run-id> [--story <id>]
  *
  * Args:
- *   <epic-id>            Positive integer Epic ID. Required.
+ *   <run-id>             Positive integer run ID. Required.
  *   --story <id>         Optional positive integer Story ID. When set,
  *                        narrows the printed tree to a single Story
  *                        subtree.
@@ -27,7 +27,7 @@
  * Exit codes:
  *   0  — happy path, OR missing signals file (friendly message printed,
  *        no stack trace).
- *   1  — bad arguments (non-integer epic, missing positional, etc.).
+ *   1  — bad arguments (non-integer run, missing positional, etc.).
  *
  * Tempfile contract:
  *   The viewer resolves the on-disk signals path via the configured
@@ -57,7 +57,7 @@ function println(line) {
 }
 
 const USAGE =
-  'Usage: node .agents/scripts/signals-view.js <epic-id> [--story <id>] [--temp-root <path>]';
+  'Usage: node .agents/scripts/signals-view.js <run-id> [--story <id>] [--temp-root <path>]';
 
 /**
  * Parse a token as a strict positive integer (no leading +, no float, no
@@ -86,7 +86,7 @@ const HELP_FLAGS = new Set(['--help', '-h']);
  * print a friendly message and exit 1 without a stack trace.
  *
  * Delegates the flag walking to `parseStandardCliArgs` and post-validates
- * the diagnose-specific invariants (single positional epic-id, strictly
+ * the signals-view-specific invariants (single positional run-id, strictly
  * positive integers for both ids).
  *
  * @param {string[]} argv
@@ -94,7 +94,7 @@ const HELP_FLAGS = new Set(['--help', '-h']);
  */
 export function parseArgs(argv) {
   if (!Array.isArray(argv) || argv.length === 0) {
-    return err(`missing <epic-id>. ${USAGE}`);
+    return err(`missing <run-id>. ${USAGE}`);
   }
   if (argv.some((t) => HELP_FLAGS.has(t))) return err(USAGE);
 
@@ -118,7 +118,7 @@ export function parseArgs(argv) {
   // Exactly one positional, which must be a strictly positive integer
   // (no leading `+`, no float, no trailing junk).
   if (positionals.length === 0) {
-    return err(`missing <epic-id>. ${USAGE}`);
+    return err(`missing <run-id>. ${USAGE}`);
   }
   if (positionals.length > 1) {
     return err(`unexpected token ${JSON.stringify(positionals[1])}. ${USAGE}`);
@@ -126,7 +126,7 @@ export function parseArgs(argv) {
   const epic = parseStrictPositiveInt(positionals[0]);
   if (epic == null) {
     return err(
-      `<epic-id> must be a positive integer; got ${JSON.stringify(positionals[0])}. ${USAGE}`,
+      `<run-id> must be a positive integer; got ${JSON.stringify(positionals[0])}. ${USAGE}`,
     );
   }
 
@@ -180,7 +180,7 @@ function describeEvent(evt) {
  */
 export function renderTree(tree, opts = {}) {
   const filter = opts.storyFilter ?? null;
-  println(`Epic #${tree.epic ?? '?'}`);
+  println(`Run #${tree.epic ?? '?'}`);
   const stories =
     filter == null ? tree.stories : tree.stories.filter((s) => s.id === filter);
 
@@ -226,12 +226,16 @@ export async function main(argv, deps = {}) {
     println(parsed.error);
     return 1;
   }
-  const { epic, story, tempRoot } = parsed;
+  const { epic: runId, story, tempRoot } = parsed;
   const read = deps.read ?? signals.read;
   const buildSpanTree = deps.buildSpanTree ?? signals.buildSpanTree;
   const config = buildConfig(tempRoot);
 
-  const iter = read(story != null ? { epic, story, config } : { epic, config });
+  // The reader API still accepts the historical `epic` key while resolving
+  // the run directory through temp-paths (`temp/run-<id>/`).
+  const iter = read(
+    story != null ? { epic: runId, story, config } : { epic: runId, config },
+  );
 
   // Eagerly collect to detect the missing-file case before we start
   // printing — when the iterator yields nothing we want a friendly
@@ -241,7 +245,7 @@ export async function main(argv, deps = {}) {
     tree = await buildSpanTree(iter);
   } catch (err) {
     println(
-      `signals: failed to read signals for Epic #${epic}: ${
+      `signals: failed to read signals for run #${runId}: ${
         err instanceof Error ? err.message : String(err)
       }`,
     );
@@ -250,7 +254,7 @@ export async function main(argv, deps = {}) {
 
   if (tree.stories.length === 0) {
     const scope = story != null ? ` (Story #${story})` : '';
-    println(`No signals found for Epic #${epic}${scope}.`);
+    println(`No signals found for run #${runId}${scope}.`);
     return 0;
   }
 
@@ -258,15 +262,16 @@ export async function main(argv, deps = {}) {
   // `story` is omitted. If the requested Story filter doesn't match any
   // observed Story id, treat that as the missing-file case too.
   if (story != null && !tree.stories.some((s) => s.id === story)) {
-    println(`No signals found for Epic #${epic} (Story #${story}).`);
+    println(`No signals found for run #${runId} (Story #${story}).`);
     return 0;
   }
 
-  // Pin the Epic id on the tree to the requested one — `buildSpanTree`
-  // pins it from the first observed event, which is normally the same,
-  // but if every event lacks an `epic` field the tree's `epic` would be
+  // Pin the run id on the tree to the requested one — `buildSpanTree`
+  // stores it in the legacy `epic` field from the first observed event,
+  // which is normally the same, but if every event lacks that field the
+  // tree's `epic` would be
   // `null` while we still know what was requested.
-  if (tree.epic == null) tree = { ...tree, epic };
+  if (tree.epic == null) tree = { ...tree, epic: runId };
 
   renderTree(tree, { storyFilter: story });
   return 0;

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

@@ -1,13 +1,11 @@
 #!/usr/bin/env node
 
 /**
- * single-story-close.js — Close a standalone Story (no parent Epic).
+ * single-story-close.js — Close a Story against `main` (v2 `/deliver` path).
  *
- * Thin CLI entry for the `/single-story-deliver` workflow. Counterpart to
- * `story-close.js`, but skips the Epic-attached machinery (epic-merge-lock,
- * dispatchRecovery, auto-refresh, post-merge pipeline) because a standalone
- * Story has no parent to cascade to and reaches `main` via a human-approved
- * PR rather than an in-script merge.
+ * Thin CLI entry for `/deliver` / `helpers/deliver-story`. Opens a PR from
+ * `story-<id>` to `project.baseBranch`, runs Story-scope review, and arms
+ * auto-merge. There is no Epic parent, epic-merge-lock, or wave merge.
  *
  * Pipeline (each step is a phase under
  * `./lib/orchestration/single-story-close/phases/`):
@@ -44,18 +42,17 @@
  *                              [--wait-merge | --no-wait-merge]
  *
  * `--wait-merge` is the headless must-land signal (Story #4428, Epic
- * #4425): the invoking surface (a headless `/single-story-deliver` run, a
- * CI-driven wrapper, or `/deliver`'s standalone multi-Story fan-out) opts
- * in explicitly — attended runs never pass it, so the default exit shape
- * (rest at `agent::closing`, issue OPEN) is unchanged. `--no-wait-merge` is
- * the explicit opt-out that always wins over `--wait-merge`, for a caller
- * that wants to manage merge confirmation externally even in an otherwise
- * headless context.
+ * #4425): the invoking surface (a headless `/deliver` run or a CI-driven
+ * wrapper) opts in explicitly — attended runs never pass it, so the default
+ * exit shape (rest at `agent::closing`, issue OPEN) is unchanged.
+ * `--no-wait-merge` is the explicit opt-out that always wins over
+ * `--wait-merge`, for a caller that wants to manage merge confirmation
+ * externally even in an otherwise headless context.
  *
  * Exit codes: 0 ok, 1 error (including a headless `--wait-merge` run that
  * gave up without a confirmed merge — see phase 9 above).
  *
- * @see .agents/workflows/helpers/single-story-deliver.md
+ * @see .agents/workflows/helpers/deliver-story.md
  */
 
 import { runAsCli } from './lib/cli-utils.js';

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,7 +32,7 @@
  *
  * 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';
@@ -45,6 +45,7 @@ import { parsePrNumber } from './lib/orchestration/single-story-close/phases/cod
 import { parseCloseOptions } from './lib/orchestration/single-story-close/phases/options.js';
 import { createProvider } from './lib/provider-factory.js';
 import { confirmStoryMerged } from './lib/single-story/confirm-merge.js';
+import { withConfirmFollowUps } from './lib/single-story/confirm-merge-follow-ups.js';
 
 const progress = Logger.createProgress('single-story-confirm-merge', {
   stderr: true,
@@ -98,6 +99,22 @@ async function resolvePrNumber({ cwd, storyBranch, gh }) {
   }
 }
 
+function logConfirmResult(result) {
+  Logger.info(
+    `\n--- CONFIRM MERGE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
+  );
+  return { success: true, result };
+}
+
+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.
  */
@@ -125,34 +142,28 @@ export async function runConfirmMerge({
   const config = injectedConfig || resolveConfig({ cwd });
   const provider = injectedProvider || createProvider(config);
   const gh = injectedGh ?? defaultGh;
-  const storyBranch = getStoryBranch(0, storyId);
+  const storyBranch = getStoryBranch(storyId);
 
   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 = {
+    return logConfirmResult({
       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 { success: true, result };
+    });
   }
 
   const confirmation = await confirmStoryMerged({
@@ -168,14 +179,19 @@ 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`,
-  );
+  const result = await withConfirmFollowUps({
+    confirmation,
+    storyId,
+    prNumber,
+    provider,
+    config,
+    cwd,
+    progress,
+  });
   if (result.action === 'done') {
     progress('DONE', `✅ Standalone Story #${storyId} → agent::done (merged).`);
   }
-  return { success: true, result };
+  return logConfirmResult(result);
 }
 
 runAsCli(import.meta.url, runConfirmMerge, {

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.',
+    );
+  }
 }
 
 /**
@@ -478,9 +483,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 +492,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 +508,12 @@ export async function runSingleStoryInit({
 
   const story = await provider.getTicket(storyId);
   assertDeliverableStory(story, storyId);
+  await handleRemoteVerificationFailure({
+    provider,
+    storyId,
+    remote,
+    dryRun,
+  });
 
   progress(
     'CONTEXT',