mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/story-close/cd-out-guard.js

@@ -1,86 +0,0 @@
-/**
- * cd-out-guard.js — pre-flight check that refuses to close while the
- * operator's shell is still cd'd into the per-story worktree being reaped.
- *
- * Extracted from story-close.js (Story #956, Theme A finishing touch) so the
- * close orchestrator becomes a thin CLI shell.
- *
- * On Windows this surfaces as `EBUSY: resource busy or locked, rmdir`
- * during reap; cross-platform it makes `--cwd` semantics impossible to
- * honour because git operations target the main repo while the filesystem
- * mutation targets the worktree the caller is sitting inside.
- *
- * Fires only when `--cwd` is set explicitly. Single-tree closures resolve
- * `workCwd` to the main repo, so the equality check is a tautology there
- * and we don't reject those.
- *
- * Both operands are canonicalized through `fs.realpathSync` before the
- * equality check (Story #3672). `path.resolve` normalizes `.`/`..` and makes
- * a path absolute but does NOT resolve symlinks, while `process.cwd()` is
- * returned fully canonicalized by the OS. On hosts where the working path
- * contains a symlinked component — most notably macOS, where `/tmp` →
- * `/private/tmp` and `/var` → `/private/var` — the two strings would never
- * match, so the guard silently no-opped and failed to fire. Realpath'ing
- * both sides closes that false-negative.
- *
- * Pure: takes inputs, returns a verdict. Exported so the rejection path is
- * unit-testable without spawning the script. The `realpath` seam is injected
- * (default `fs.realpathSync`) so tests can drive the symlinked and
- * non-symlinked cases without touching the filesystem.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-/**
- * Canonicalize a path: resolve symlinks via `realpath`, falling back to
- * `path.resolve` when the path does not exist yet (`realpathSync` throws on
- * missing paths). The fallback keeps the comparison correct for
- * not-yet-created worktree directories.
- *
- * @param {string} p
- * @param {(p: string) => string} realpath
- * @returns {string}
- */
-function canonical(p, realpath) {
-  try {
-    return realpath(p);
-  } catch {
-    return path.resolve(p);
-  }
-}
-
-/**
- * @param {object} opts
- * @param {boolean} opts.cwdExplicit       True when `--cwd` (or AGENT_WORKTREE_ROOT) was set.
- * @param {string} opts.mainCwd            Resolved main repo path.
- * @param {number|string} opts.storyId
- * @param {string} [opts.worktreeRoot]     `delivery.worktreeIsolation.root` (defaults to `.worktrees`).
- * @param {string} [opts.currentCwd]       Defaults to `process.cwd()`.
- * @param {(p: string) => string} [opts.realpath]  Symlink-resolution seam (defaults to `fs.realpathSync`).
- * @returns {{ ok: true } | { ok: false, message: string }}
- */
-export function checkCdOutGuard({
-  cwdExplicit,
-  mainCwd,
-  storyId,
-  worktreeRoot = '.worktrees',
-  currentCwd = process.cwd(),
-  realpath = fs.realpathSync,
-}) {
-  if (!cwdExplicit) return { ok: true };
-  const workCwd = canonical(
-    path.resolve(mainCwd, worktreeRoot, `story-${storyId}`),
-    realpath,
-  );
-  const cwd = canonical(currentCwd, realpath);
-  if (cwd !== workCwd) return { ok: true };
-  return {
-    ok: false,
-    message:
-      `Refusing to close while CWD is the worktree being reaped.\n` +
-      `   Current cwd:  ${cwd}\n` +
-      `   Main repo:    ${mainCwd}\n` +
-      `   Run instead:  cd "${mainCwd}" && node .agents/scripts/story-close.js --story ${storyId}`,
-  };
-}

package/.agents/scripts/lib/orchestration/story-close/cleanup-reconciler.js

@@ -1,147 +0,0 @@
-/**
- * cleanup-reconciler.js — post-merge worktree-cleanup drain + reconciliation.
- *
- * Extracted from story-close.js (Story #955, Theme A part 2) so the close
- * orchestrator becomes a thin CLI shell. This module owns the three
- * worktree-cleanup helpers that previously lived inline in `runStoryClose`:
- *
- *   - drainPendingCleanupAfterClose — drives the `forceDrainPendingCleanup`
- *     pass that runs after the post-merge pipeline reaps the per-story
- *     worktree. Logs the drain summary via the supplied progress sink.
- *   - reconcileCleanupState         — pure helper that folds the drain
- *     outcome back into the pipeline's `worktreeReap` + `branchCleanup`
- *     state, lifting `localDeleted` / `remoteDeleted` flags and the
- *     `closeDrainStatus` enum.
- *   - getCloseDrainStatus           — names the three deferred-to-sweep
- *     outcomes (persistent / still-pending / not-found) so callers don't
- *     have to read a nested ternary.
- *
- * No close-time control flow lives here — the helpers are pure functions
- * (or thin wrappers around an injected `drainFn`) and exercise nothing
- * outside the worktree-isolation surface.
- */
-
-import path from 'node:path';
-import { gitSpawn } from '../../git-utils.js';
-import { Logger } from '../../Logger.js';
-import { forceDrainPendingCleanup } from '../../worktree/lifecycle/force-drain.js';
-
-function resolveWorktreeRoot(repoRoot, delivery) {
-  const configuredRoot = delivery?.worktreeIsolation?.root ?? '.worktrees';
-  return path.join(repoRoot, configuredRoot);
-}
-
-export async function drainPendingCleanupAfterClose({
-  repoRoot,
-  delivery,
-  progress: progressFn,
-  logger = Logger,
-  git = { gitSpawn },
-  drainFn = forceDrainPendingCleanup,
-} = {}) {
-  const wtConfig = delivery?.worktreeIsolation;
-  if (!wtConfig?.enabled) return null;
-  const worktreeRoot = resolveWorktreeRoot(repoRoot, delivery);
-  const result = await drainFn({
-    repoRoot,
-    worktreeRoot,
-    git,
-    logger,
-  });
-  const totalResolved =
-    (result.drained?.length ?? 0) +
-    (result.persistent?.length ?? 0) +
-    (result.stillPending?.length ?? 0);
-  if (totalResolved > 0 && typeof progressFn === 'function') {
-    progressFn(
-      'WORKTREE',
-      `Pending cleanup drain: drained=${result.drained.length}, persistent=${result.persistent.length}, stillPending=${result.stillPending.length}`,
-    );
-  }
-  return { worktreeRoot, ...result };
-}
-
-const REAP_STATUSES_DRAIN_FLIPS = new Set([
-  'deferred-to-sweep',
-  'stale-registry-entry',
-]);
-
-function applyDrainedEntry(nextWorktreeReap, nextBranchCleanup, drainedEntry) {
-  if (drainedEntry.localBranchDeleted !== null) {
-    nextBranchCleanup.localDeleted =
-      nextBranchCleanup.localDeleted || !!drainedEntry.localBranchDeleted;
-  }
-  if (drainedEntry.remoteBranchDeleted !== null) {
-    nextBranchCleanup.remoteDeleted =
-      nextBranchCleanup.remoteDeleted || !!drainedEntry.remoteBranchDeleted;
-  }
-  if (REAP_STATUSES_DRAIN_FLIPS.has(nextWorktreeReap.status)) {
-    nextWorktreeReap.status = 'removed-after-drain';
-  }
-  nextWorktreeReap.pendingCleanup = null;
-  nextWorktreeReap.closeDrainStatus = 'drained';
-}
-
-export function reconcileCleanupState({
-  storyId,
-  worktreeReap,
-  branchCleanup,
-  pendingCleanupDrain,
-}) {
-  const normalizedStoryId = Number(storyId);
-  const nextWorktreeReap = worktreeReap ? { ...worktreeReap } : null;
-  const nextBranchCleanup = branchCleanup ? { ...branchCleanup } : null;
-  if (!pendingCleanupDrain || !nextWorktreeReap || !nextBranchCleanup) {
-    return { worktreeReap: nextWorktreeReap, branchCleanup: nextBranchCleanup };
-  }
-
-  const drainedEntry =
-    pendingCleanupDrain.drainedDetails?.find(
-      (entry) => Number(entry.storyId) === normalizedStoryId,
-    ) ?? null;
-
-  if (drainedEntry) {
-    applyDrainedEntry(nextWorktreeReap, nextBranchCleanup, drainedEntry);
-    return { worktreeReap: nextWorktreeReap, branchCleanup: nextBranchCleanup };
-  }
-
-  if (REAP_STATUSES_DRAIN_FLIPS.has(nextWorktreeReap.status)) {
-    nextWorktreeReap.closeDrainStatus = getCloseDrainStatus({
-      isPersistent:
-        pendingCleanupDrain.persistent?.includes(normalizedStoryId) ?? false,
-      isStillPending:
-        pendingCleanupDrain.stillPending?.includes(normalizedStoryId) ?? false,
-    });
-  }
-
-  return { worktreeReap: nextWorktreeReap, branchCleanup: nextBranchCleanup };
-}
-
-/**
- * Resolve the deferred-to-sweep close-drain status when the current Story's
- * pending-cleanup entry was *not* drained on this close. Three outcomes:
- *
- *   - `'persistent'`   — the entry has hit the persistent-lock threshold
- *                        (`MAX_SWEEP_ATTEMPTS` reached). `isPersistent` wins
- *                        regardless of whether the entry is also still in
- *                        the live pending list, because operator-action is
- *                        the authoritative outcome.
- *   - `'still-pending'`— the entry is in the pending list but has not yet
- *                        crossed the persistent threshold. The next sweep
- *                        run will retry.
- *   - `'not-found'`    — the entry is in neither list. Either the drain
- *                        cleared it before this reconcile saw it, or this
- *                        Story never had a pending entry. Treated as a
- *                        clean state for downstream callers.
- *
- * Extracted from a nested ternary so the truth table is greppable and each
- * branch carries an explicit name.
- *
- * @param {{ isPersistent: boolean, isStillPending: boolean }} flags
- * @returns {'persistent' | 'still-pending' | 'not-found'}
- */
-export function getCloseDrainStatus({ isPersistent, isStillPending }) {
-  if (isPersistent) return 'persistent';
-  if (isStillPending) return 'still-pending';
-  return 'not-found';
-}

package/.agents/scripts/lib/orchestration/story-close/close-inputs.js

@@ -1,142 +0,0 @@
-/**
- * close-inputs.js — argument parsing + cwd / epic / branch resolution for
- * the story-close CLI. Extracted from story-close.js (Story #956, Theme A
- * finishing touch) so the close orchestrator becomes a thin CLI shell.
- *
- * `resolveCloseInputs` folds the three pre-merge resolutions that
- * `runStoryClose` does up-front into a single helper:
- *
- *   - parse the CLI argv (or normalize the parameter object passed to
- *     `runStoryClose(...)` from a test/programmatic caller),
- *   - resolve the main-repo cwd (explicit param > --cwd flag > env >
- *     PROJECT_ROOT),
- *   - run the cd-out guard before any git/filesystem mutation,
- *   - fetch the Story ticket and resolve `epicId` from the body when not
- *     passed via --epic,
- *   - derive `epicBranch` + `storyBranch` from the canonical helpers.
- *
- * The helper does NOT touch the merge lock, the post-merge pipeline, or
- * the phase timer — those stay in the orchestrator.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { parseSprintArgs } from '../../cli-args.js';
-import { PROJECT_ROOT, resolveConfig } from '../../config-resolver.js';
-import { getEpicBranch, getStoryBranch } from '../../git-utils.js';
-import { createProvider as defaultCreateProvider } from '../../provider-factory.js';
-import { resolveStoryHierarchy } from '../../story-lifecycle.js';
-import { checkCdOutGuard } from './cd-out-guard.js';
-
-/**
- * Resolve the path of the Story's worktree given the resolved main `cwd` and
- * `storyId`. Returns the absolute worktree path when `<cwd>/<root>/story-<id>`
- * exists on disk; returns `null` otherwise (single-tree mode, or the worktree
- * was reaped earlier in the close flow). Used by `runStoryClose` to thread
- * the worktree directory into pre-merge gate spawns so close-validation runs
- * against the Story branch's post-rebase tree (Story #1120).
- *
- * Pure-ish (modulo `fs.existsSync`) — exported so tests can pin the
- * "what counts as a usable worktree" contract without mocking filesystem
- * state.
- */
-export function resolveWorktreePath({ cwd, storyId, worktreeRoot }) {
-  if (!cwd || !storyId) return null;
-  const root = worktreeRoot ?? '.worktrees';
-  const candidate = path.resolve(cwd, root, `story-${storyId}`);
-  try {
-    return fs.existsSync(candidate) ? candidate : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * @param {{
- *   storyIdParam?: number|string,
- *   epicIdParam?: number|string,
- *   skipDashboardParam?: boolean,
- *   skipValidationParam?: boolean,
- *   cwdParam?: string|null,
- *   resumeParam?: boolean,
- *   restartParam?: boolean,
- *   injectedProvider?: object,
- *   createProvider?: typeof defaultCreateProvider,
- * }} args
- */
-export async function resolveCloseInputs({
-  storyIdParam,
-  epicIdParam,
-  skipDashboardParam,
-  skipValidationParam,
-  cwdParam,
-  resumeParam,
-  restartParam,
-  injectedProvider,
-  createProvider = defaultCreateProvider,
-}) {
-  const parsed =
-    storyIdParam !== undefined
-      ? {
-          storyId: storyIdParam,
-          epicId: epicIdParam,
-          skipDashboard: !!skipDashboardParam,
-          skipValidation: !!skipValidationParam,
-          cwd: cwdParam ?? null,
-          resume: !!resumeParam,
-          restart: !!restartParam,
-        }
-      : parseSprintArgs();
-  const cwd = path.resolve(cwdParam ?? parsed.cwd ?? PROJECT_ROOT);
-
-  if (!parsed.storyId) {
-    throw new Error(
-      'Usage: node story-close.js --story <STORY_ID> [--epic <EPIC_ID>]',
-    );
-  }
-
-  const config = resolveConfig({ cwd });
-  const worktreeRoot = config.delivery?.worktreeIsolation?.root;
-
-  const guard = checkCdOutGuard({
-    cwdExplicit: parsed.cwd != null,
-    mainCwd: cwd,
-    storyId: parsed.storyId,
-    worktreeRoot,
-  });
-  if (!guard.ok) throw new Error(guard.message);
-
-  const provider = injectedProvider || createProvider(config);
-  const story = await provider.getTicket(parsed.storyId);
-  let epicId = parsed.epicId;
-  if (!epicId) {
-    const resolved = resolveStoryHierarchy(story.body);
-    if (!resolved.epicId) {
-      throw new Error(
-        `Story #${parsed.storyId} has no "Epic: #N" reference. Pass --epic <id> explicitly.`,
-      );
-    }
-    epicId = resolved.epicId;
-  }
-
-  return {
-    storyId: parsed.storyId,
-    epicId,
-    cwd,
-    worktreePath: resolveWorktreePath({
-      cwd,
-      storyId: parsed.storyId,
-      worktreeRoot,
-    }),
-    skipDashboard: parsed.skipDashboard,
-    skipValidation: !!parsed.skipValidation,
-    resumeFlag: parsed.resume,
-    restartFlag: parsed.restart,
-    noEvidenceFlag: parsed.noEvidence,
-    config,
-    provider,
-    story,
-    epicBranch: getEpicBranch(epicId),
-    storyBranch: getStoryBranch(epicId, parsed.storyId),
-  };
-}

package/.agents/scripts/lib/orchestration/story-close/comment-bodies.js

@@ -1,62 +0,0 @@
-import { buildMergeMessageWithCap } from './merge-subject.js';
-
-/**
- * comment-bodies.js — pure renderers for story-close GitHub comment payloads
- * and operator-facing fatal-message envelopes.
- *
- * Extracted from story-close.js (Story #955, Theme A part 3) so the close
- * orchestrator becomes a thin CLI shell. These helpers are stateless and
- * format-only:
- *
- *   - buildResumeMergeCommitMsg     — the conventional-commit subject the
- *     `--resume` partial-merge path uses to finalize the in-progress merge.
- *   - describeResumePushFailure     — classifies a `pushEpicWithRetry`
- *     outcome into the operator-facing fatal-error string (or returns null
- *     when the push was ok).
- *
- * Epic #1030 Story #1046 — `renderPhaseTimingsCommentBody` was removed; the
- * legacy `<!-- structured:phase-timings -->` post is now produced by
- * `analyze-execution.js` as the unified `<!-- structured:story-perf-summary -->`
- * comment. The `perf-summary` phase in post-merge-pipeline.js is the call
- * site.
- *
- * No I/O, no logging, no hidden globals. Tests import the same symbols and
- * pin behaviour without spawning the close script.
- */
-
-/**
- * Pure: build the conventional-commit subject the resume path uses to
- * finalize a partial-merge commit. When `headerMaxLength` is provided
- * and the assembled subject would exceed it, the title is truncated on
- * a word boundary (Conventional-Commits prefix and `(resolves #N)` suffix
- * preserved verbatim) and a `truncated-from: <original>` body trailer is
- * appended. Exported for tests.
- *
- * @param {string} storyTitle
- * @param {number|string} storyId
- * @param {{ headerMaxLength?: number, logger?: { warn?: Function } }} [opts]
- */
-export function buildResumeMergeCommitMsg(storyTitle, storyId, opts = {}) {
-  return buildMergeMessageWithCap({
-    type: 'feat',
-    title: storyTitle,
-    storyId,
-    headerMaxLength: opts.headerMaxLength,
-    logger: opts.logger,
-  }).message;
-}
-
-/**
- * Pure: classify a `pushEpicWithRetry` outcome into the operator-facing
- * fatal-error message. Returns `null` when the push was ok.
- */
-export function describeResumePushFailure(pushOutcome) {
-  if (pushOutcome.ok) return null;
-  const reasonLabel =
-    pushOutcome.reason === 'retry-exhausted'
-      ? `retries exhausted after ${pushOutcome.attempts} attempt(s)`
-      : pushOutcome.reason;
-  const detail =
-    pushOutcome.result?.stderr || pushOutcome.result?.stdout || 'unknown';
-  return `Push failed (${reasonLabel}): ${detail}`;
-}