mandrel 2.60.0 → 2.62.0

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

@@ -2,35 +2,11 @@
 /* node:coverage ignore file */
 
 /**
- * single-story-init.js — Initialize a Story for v2 `/mandrel-deliver`.
- *
- * 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).
- *   2. Acquire the assignee lease, then refuse a Story already labelled
- *      `agent::executing` this run does not hold (unless `--steal`).
- *   3. Flip the Story to `agent::executing` — BEFORE provisioning, so the
- *      claim is label-visible to concurrent operators' probes during the
- *      multi-minute install window (Story #4620). A provisioning failure after
- *      this reverts the label and releases the lease.
- *   4. Fetch origin.
- *   5. Create the Story branch from `project.baseBranch` (default
- *      `main`) — local-only, no remote push at this stage.
- *   6. Materialise a worktree at `.worktrees/story-<id>/` when worktree
- *      isolation is enabled; otherwise check out the branch in-place.
- *   7. Upsert a `story-init` structured comment carrying
- *      `standalone: true`.
- *
- * 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.
+ * single-story-init.js — initialize a Story for `/mandrel-deliver`: validate,
+ * take the lease, flip to `agent::executing` (before provisioning, so the
+ * claim is visible during the install window; a later failure rolls it back),
+ * seed `story-<id>` from the base branch locally, and materialise the
+ * worktree when isolation is on.
  *
  * @see .agents/workflows/helpers/deliver-story.md
  */
@@ -74,27 +50,16 @@ import {
 import { createProvider } from './lib/provider-factory.js';
 import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
 import { resolveSweepLockPath } from './lib/single-story-sweep/sweep-lock.js';
-// `sweepMergedStoryBranches` is imported dynamically below — its transitive
-// graph reaches `picomatch` (via `git-cleanup.js`). Loading it statically
-// would crash module resolution before `assertDepsInstalled()` can emit a
-// friendly "run npm install" message.
+// `sweepMergedStoryBranches` is imported dynamically: its graph reaches
+// `picomatch`, which would crash before `assertDepsInstalled()` can report.
 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.
 export { makeGhRunner } from './lib/single-story-sweep/protection-ctx.js';
 
 /**
- * Fail fast with a clear, actionable message when project deps are missing.
- * Uses only Node builtins so it stays loadable when `node_modules/` is empty.
- *
- * Why: a wiped `node_modules/` previously surfaced as
- * `ERR_MODULE_NOT_FOUND: Cannot find package 'picomatch'` from deep inside
- * the sweep graph — opaque for operators. This guard probes a representative
- * runtime dep (declared in `.agents/runtime-deps.json`) and tells the operator
- * exactly what to run.
+ * Fail fast with an actionable message when deps are missing, instead of an
+ * opaque `ERR_MODULE_NOT_FOUND` from deep in the sweep graph. Builtins only.
  */
 function assertDepsInstalled(projectRoot) {
   const probe = path.join(projectRoot, 'node_modules', 'picomatch');
@@ -111,12 +76,8 @@ function assertDepsInstalled(projectRoot) {
 const progress = Logger.createProgress('single-story-init', { stderr: true });
 
 /**
- * Validate that the fetched ticket is a standalone Story this script can
- * deliver. Throws with the canonical operator-facing message otherwise.
- * Exported for testing.
- *
- * @param {{ labels: string[], state: string }} story Fetched ticket.
- * @param {number} storyId Story number (for error messages).
+ * @param {{ labels: string[], state: string }} story
+ * @param {number} storyId
  */
 export function assertDeliverableStory(story, storyId) {
   if (!story.labels.includes(TYPE_LABELS.STORY)) {
@@ -138,26 +99,14 @@ export function assertDeliverableStory(story, storyId) {
 }
 
 /**
- * Defense-in-depth refusal for a Story already labelled `agent::executing`
- * that this run does not already hold.
- *
- * The assignee lease is the primary cross-run guard, but the label and the
- * assignee can drift apart: a prior run that crashed *after* the early
- * `agent::executing` flip but *before* (or without) taking/holding the lease
- * leaves the Story labelled executing with no live foreign lease to trip the
- * lease preflight. Left unchecked, a fresh run would seed the branch and
- * worktree straight over that drift. Refuse unless the caller already holds the
- * lease (`reason === 'already-held'`, i.e. a legitimate idempotent re-init) or
- * passed `--steal`.
- *
- * Runs *after* the lease acquire (so it can read the acquire's reason) but
- * *before* any git mutation. On refusal it releases the lease this run just
- * took so the ticket is left exactly as found — a clean state for the operator
- * to inspect before re-running with `--steal`.
+ * Refuse a Story labelled `agent::executing` that this run does not hold:
+ * label and assignee can drift (a run that crashed after the flip), so the
+ * lease alone misses it. Runs after the acquire, before any git mutation, and
+ * releases the just-taken lease on refusal so the ticket is left as found.
  *
  * @param {object} args
- * @param {{ labels?: string[] }} args.story        Fetched Story ticket.
- * @param {{ reason: string, previousOwner: string|null }} args.lease  Acquire result.
+ * @param {{ labels?: string[] }} args.story
+ * @param {{ reason: string, previousOwner: string|null }} args.lease
  * @param {boolean} args.stealRequested
  * @param {number} args.storyId
  * @param {object} args.provider
@@ -176,7 +125,6 @@ export async function assertNotForeignExecuting({
     story.labels.includes(STATE_LABELS.EXECUTING);
   if (!labelled || stealRequested || lease.reason === 'already-held') return;
 
-  // Back out the lease we just took so the refusal leaves the ticket unchanged.
   try {
     await releaseStoryLease({ provider, storyId, config });
   } catch (err) {
@@ -195,18 +143,11 @@ export async function assertNotForeignExecuting({
 }
 
 /**
- * Publish this run's claim as the `agent::executing` label **before** the
- * multi-minute worktree install, so a concurrent operator's probe sees the
- * claim during the install window instead of reading `agent::ready` and
- * dispatching the Story a second time.
- *
- * Best-effort: the assignee lease is the real guard, so a failed flip logs and
- * proceeds rather than aborting init. Routes through `transitionTicketState`
- * so the Projects v2 Status column follows the label (Story #2548).
+ * Best-effort: the lease is the real guard, so a failed flip only logs.
  *
  * @param {object} provider
  * @param {number} storyId
- * @param {object} story  Prefetched snapshot (round-trip elimination).
+ * @param {object} story Prefetched snapshot.
  * @returns {Promise<void>}
  */
 async function flipStoryToExecuting(provider, storyId, story) {
@@ -224,15 +165,8 @@ async function flipStoryToExecuting(provider, storyId, story) {
 }
 
 /**
- * Roll any container Epic listing this Story up from its children.
- *
- * A container carries no `agent::*` label, so the Status sync that follows
- * the flip above cannot reach it — its column is derived from its children
- * instead. This is the edge where the first child of an Epic starts moving,
- * which is what puts the Epic on the board as In Progress with an owner.
- *
- * Best-effort by construction: the rollup never throws, and a container left
- * at a stale column must never cost the Story its init.
+ * Roll a container Epic's status up from its children (it carries no
+ * `agent::*` label of its own). Never throws.
  *
  * @param {object} provider
  * @param {number} storyId
@@ -252,11 +186,8 @@ async function rollUpContainerEpic(provider, storyId, config) {
 }
 
 /**
- * Undo this run's claim when provisioning fails after the early
- * `agent::executing` flip: revert the label to `agent::ready` and release the
- * lease, both best-effort. Without this a crashed init would strand the Story
- * as phantom-executing — claimed and labelled in-flight but with no live run —
- * which every other operator's probe would then withhold indefinitely.
+ * Best-effort revert of label and lease after a provisioning failure, so the
+ * Story is not stranded as phantom-executing (withheld by every probe).
  *
  * @param {object} provider
  * @param {number} storyId
@@ -287,22 +218,10 @@ async function rollbackClaimOnInitFailure(provider, storyId, config) {
 }
 
 /**
- * Decide how to seed the Story branch given local / remote presence. Pure and
- * exported for testing (Story #3483 AC3: an existing `story-<id>` branch must
- * be **reused**, never re-created — re-creating throws `branch already exists`).
- *
- * Delegates the (local, remote) decision to the shared `classifyBranchSeed`
- * classifier (Story #3513) so this path and the Epic-attached
- * `branch-initializer.js#planStoryBranchSeed` share one decision tree. The
- * shared classifier returns `'local'` for the local-present case; this path
- * names that outcome `'reuse'`.
+ * An existing local ref must be reused, never re-created (`git branch` throws).
  *
  * @param {{ localHas: boolean, remoteHas: boolean }} presence
  * @returns {'reuse'|'fetch'|'create'}
- *   - `reuse`  — a local ref already exists; the caller must not run
- *                `git branch` (which would throw on the existing ref).
- *   - `fetch`  — only the remote ref exists; materialise the local ref.
- *   - `create` — neither exists; branch from baseBranch.
  */
 export function decideStoryBranchSeed({ localHas, remoteHas }) {
   const action = classifyBranchSeed({ localHas, remoteHas });
@@ -310,22 +229,10 @@ export function decideStoryBranchSeed({ localHas, remoteHas }) {
 }
 
 /**
- * Reap previously-merged `story-*` branches before starting a new one, so
- * stale local + origin refs do not accumulate across runs. The sweep
- * excludes the current run's `storyBranch` and never blocks init: any
- * sweep failure is logged but does not throw.
- *
- * Story #2011 hardens this surface in two ways:
- *   - Per-candidate protection: branches with unpushed work, dirty
- *     worktrees, or still-open Story tickets are skipped (and listed
- *     in `sweep.protected` for the operator).
- *   - Cross-session lock: a single lockfile under `tempRoot` prevents
- *     two concurrent `/single-story-deliver` invocations from racing.
- *     Story #5112 made that lockfile shared with `boot-sweep.js` — the
- *     other entry point into the same merged-branch reap — by routing
- *     both through `resolveSweepLockPath`.
- *
- * Exported for testing.
+ * Reap merged `story-*` branches (excluding the current one). Never blocks
+ * init. Protected candidates (unpushed work, dirty worktree, open Story) are
+ * skipped; the lockfile is shared with `boot-sweep.js` via
+ * `resolveSweepLockPath` so concurrent reaps cannot race.
  */
 export async function reapMergedStoryBranches({
   cwd,
@@ -383,13 +290,8 @@ 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).
- *
- * 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.
+ * Fetch, reap, and fast-forward the local base branch so new Story branches
+ * seed from origin's tip.
  *
  * @param {object} opts
  * @param {string} opts.cwd
@@ -400,9 +302,7 @@ export async function reapMergedStoryBranches({
  * @param {Function|undefined} opts.injectedSweep
  * @param {Function} opts.progress
  * @param {import('./lib/git/cached-fetch.js').FetchCache} [opts.fetchCache]
- *   Override the module-level cache — used by tests that need a fresh, isolated
- *   cache. Production callers omit this so all Stories in a wave share the
- *   module singleton.
+ *   Test override; production shares the module singleton.
  */
 export async function materializeBaseBranch({
   cwd,
@@ -435,8 +335,6 @@ export async function materializeBaseBranch({
     injectedSweep,
   });
 
-  // Ensure baseBranch exists locally so we can branch from it. If only
-  // remote-tracking is present, materialize the local ref.
   if (!branchExistsLocally(baseBranch, cwd)) {
     const r = gitSpawn(cwd, 'fetch', 'origin', `${baseBranch}:${baseBranch}`);
     if (r.status !== 0) {
@@ -447,11 +345,7 @@ export async function materializeBaseBranch({
     return;
   }
 
-  // `git fetch origin` updates remote-tracking refs only; local `main` stays
-  // at the pre-merge tip until fast-forwarded. Use the same helper as
-  // `/git-cleanup --fast-forward-main` (checkout base + `merge --ff-only`) so
-  // new `story-*` branches seed from origin's tip when the main checkout is
-  // clean (Story #2744).
+  // `git fetch` leaves local base at the old tip until fast-forwarded.
   const ffPlan = planFastForward({ cwd, baseBranch });
   const ff = executeFastForward({
     cwd,
@@ -481,15 +375,8 @@ export async function materializeBaseBranch({
 }
 
 /**
- * Seed the Story branch from the base branch. Three cases, idempotent in all:
- *   - already local → reuse (do NOT re-create an existing ref)
- *   - remote only   → fetch
- *   - neither       → create from baseBranch
- *
- * `cachedGitFetch(cwd, 'origin')` is assumed to have run before this call
- * (via `materializeBaseBranch`), so remote-tracking refs are authoritative.
- * Uses a local tracking-ref check rather than a network `ls-remote` round-trip.
- * Exported for testing (owns the seedAction switch + throws).
+ * Idempotent seed. Assumes `materializeBaseBranch` already fetched, so
+ * tracking refs are authoritative (no `ls-remote`).
  *
  * @param {object} opts
  * @param {string} opts.cwd
@@ -498,11 +385,7 @@ export async function materializeBaseBranch({
  * @param {Function} opts.progress
  */
 export function seedStoryBranch({ cwd, storyBranch, baseBranch, progress }) {
-  // Standalone path: no concurrent creator to race, so create failures are
-  // fatal (`swallowCreateRace: false`) and a failed fetch throws. The
-  // seed-action switch shell is single-homed in `seedStoryBranchRef`
-  // (Story #4255); this caller only supplies its `baseRef`, its git seams
-  // bound to `cwd`, and its own log/error vocabulary.
+  // No concurrent creator to race here, so create failures are fatal.
   seedStoryBranchRef({
     storyBranch,
     baseRef: baseBranch,
@@ -523,9 +406,7 @@ export function seedStoryBranch({ cwd, storyBranch, baseBranch, progress }) {
 }
 
 /**
- * Provision a worktree (or check out the branch in single-tree mode).
- * Returns the resolved `workCwd`, `worktreeCreated`, and `installStatus`.
- * Exported for testing (owns the worktree/single-tree routing).
+ * Provision a worktree, or check out the branch in single-tree mode.
  *
  * @param {object} opts
  * @param {object} opts.runtime
@@ -567,16 +448,12 @@ export async function provisionWorktree({
       `${ensured.created ? '✨ Created' : '♻️  Reusing'} worktree: ${ensured.path}`,
     );
   } else {
-    // Single-tree mode: check out the branch on the main checkout.
     gitSync(cwd, 'checkout', storyBranch);
   }
 
   return { workCwd, worktreeCreated, installStatus };
 }
 
-/**
- * Initialize a standalone Story. Exported for testing.
- */
 export async function runSingleStoryInit({
   storyId: storyIdParam,
   dryRun: dryRunParam,
@@ -584,15 +461,9 @@ export async function runSingleStoryInit({
   injectedProvider,
   injectedConfig,
   injectedSweep,
-  // Story #3483: lets tests drive the lease preflight deterministically.
-  // `injectedAcquireLease` swaps the guard. `steal` forcibly transfers a
-  // foreign claim — the lease fails closed (audit #3513), so a foreign
-  // assignee blocks unless stolen.
   injectedAcquireLease,
   steal = false,
   injectedVerifyRemote,
-  // Story #4620: swap the git-touching provisioning steps so the
-  // early-flip-then-rollback ordering is unit-testable without a real worktree.
   injectedMaterialize = materializeBaseBranch,
   injectedSeedBranch = seedStoryBranch,
   injectedProvisionWorktree = provisionWorktree,
@@ -607,10 +478,8 @@ export async function runSingleStoryInit({
       : parseSprintArgs();
   const { storyId, dryRun } = parsed;
   const cwd = path.resolve(cwdParam ?? parsed.cwd ?? PROJECT_ROOT);
-  // `--steal` is not part of the shared parseSprintArgs surface; read it from
-  // argv on the CLI path (the explicit `steal` param wins for programmatic /
-  // test callers). The standalone lease fails closed on a foreign assignee
-  // (audit #3513), so `--steal` is the operator's forcible-transfer override.
+  // `--steal` is outside parseSprintArgs; the lease fails closed on a foreign
+  // assignee, so this is the operator's forcible-transfer override.
   const stealRequested =
     steal || (storyIdParam === undefined && process.argv.includes('--steal'));
 
@@ -635,12 +504,9 @@ export async function runSingleStoryInit({
   );
   progress('INIT', `Initializing standalone Story #${storyId}...`);
 
-  // Issue #4483 — deterministic remote evidence at the v2 `/mandrel-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
-  // sanctioned fallback.
+  // Read-only, so it runs under --dry-run too. The workflow owns the
+  // `agent::blocked` transition on `remoteVerified: false`; inline delivery to
+  // local `main` is never a fallback.
   const remote = (injectedVerifyRemote ?? verifyRemote)({ cwd });
   progress(
     'REMOTE',
@@ -663,12 +529,7 @@ export async function runSingleStoryInit({
     `Standalone Story: "${story.title}" → branch ${storyBranch} from ${baseBranch}.`,
   );
 
-  // Story #3483 — lease preflight. Take an exclusive claim on the Story
-  // ticket before any git mutation so two concurrent standalone runs cannot
-  // both drive the same Story. The guard fails closed (audit #3513): a
-  // foreign assignee aborts init (naming the current owner) unless --steal
-  // forcibly transfers it. Unclaimed / self-held claims proceed. Skipped
-  // under --dry-run (no assignee mutation).
+  // Lease before any git mutation so two runs cannot drive one Story.
   let workCwd = cwd;
   let worktreeCreated = false;
   let installStatus = { status: 'skipped', reason: 'dry-run' };
@@ -686,9 +547,6 @@ export async function runSingleStoryInit({
       `🔒 Story #${storyId} lease ${lease.reason} (owner=@${lease.owner}).`,
     );
 
-    // Defense in depth: refuse a Story already labelled agent::executing that
-    // this run does not hold (label/assignee drift the lease alone misses).
-    // Runs before any git mutation; releases the just-taken lease on refusal.
     await assertNotForeignExecuting({
       story,
       lease,
@@ -698,20 +556,12 @@ export async function runSingleStoryInit({
       config,
     });
 
-    // Publish the claim as agent::executing BEFORE the multi-minute worktree
-    // install (not after), so a concurrent operator's probe sees it during the
-    // install window instead of reading agent::ready and double-dispatching.
+    // Before the install, so a concurrent probe cannot double-dispatch.
     await flipStoryToExecuting(provider, storyId, story);
 
-    // Story #5205 — the child is now in flight, so any container Epic listing
-    // it is too. Fired here rather than after provisioning so the board shows
-    // In Progress for the whole install window, and after the flip so the
-    // rollup reads the state it derives from.
+    // After the flip (the rollup reads it), before the install window.
     await rollUpContainerEpic(provider, storyId, config);
 
-    // Any failure from here on leaves a claimed, executing-labelled Story with
-    // no live run behind it — revert the label and release the lease so the
-    // Story is not stranded as phantom-executing.
     try {
       await injectedMaterialize({
         cwd,
@@ -751,10 +601,7 @@ export async function runSingleStoryInit({
     standalone: true,
     storyBranch,
     baseBranch,
-    // The write half of the run-scoped config pin. `baseBranch` above is the
-    // legacy field close still reads as a fallback; this block is the
-    // registry-driven form a second run-scoped key joins without a second
-    // mechanism (`lib/orchestration/run-scoped-config.js`).
+    // Write half of the run-scoped config pin; `baseBranch` is close's fallback.
     runScopedConfig: pinRunScopedConfig(config),
     storyTitle: story.title,
     worktreeEnabled: runtime.worktreeEnabled,
@@ -764,21 +611,12 @@ export async function runSingleStoryInit({
     dependenciesInstalled,
     installFailed: installStatus.status === 'failed',
     dryRun,
-    // Issue #4483 — verified remote evidence for the orchestrating agent.
     remoteVerified: remote.remoteVerified,
     remoteProbe: { remoteUrl: remote.remoteUrl, detail: remote.detail },
   };
 
-  // Story #5343 — init posts no `story-init` comment. It was one GitHub write
-  // per Story restating what its own envelope already carries; the envelope is
-  // on stdout and on disk (below), `deliver-recover.js` classifies state from
-  // labels, the PR probe and disk artifacts, and `run-scoped-config.js` reads
-  // the base-branch pin off that same envelope. The `agent::executing` flip
-  // above is what makes the claim visible during the install window.
-  //
-  // Story #4685 — route the full result to a temp log and emit a single-line
-  // summary carrying the fields the orchestrating agent acts on (workCwd,
-  // remoteVerified). The `## Spec` names this the hot-path stdout to quiet.
+  // The envelope (stdout + disk) is the only record; no ticket comment. Full
+  // result goes to a temp log, stdout gets the fields the caller acts on.
   emitTerseResult({
     label: 'STORY INIT RESULT',
     result,