mandrel 1.57.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js

@@ -0,0 +1,106 @@
+/**
+ * phases/pull-request.js — open or reuse the PR for a standalone Story.
+ *
+ * Probes for an existing open PR with `head = storyBranch`; creates one if
+ * none exists. Returns the PR URL.
+ *
+ * `gh pr view --head` is not available on all `gh` versions, so we probe
+ * with `gh pr list --head <branch>` and fall back to `gh pr create`.
+ *
+ * Story #2990 routed the underlying `gh pr list` / `gh pr create` calls
+ * through the `lib/gh-exec.js` facade (the same shim the
+ * `providers/github/` gateways use) so this phase inherits the typed
+ * error classification, timeout handling, and JSON parsing surface
+ * instead of carrying its own `execFileSync('gh', …)` plumbing.
+ *
+ * The function still accepts an injected `gh` facade so tests can wire
+ * a fake without spawning real children.
+ */
+
+import { gh as defaultGh } from '../../../gh-exec.js';
+import { Logger } from '../../../Logger.js';
+
+/**
+ * Probe for an existing open PR with `head = storyBranch`; create one if
+ * none exists. Returns the PR URL. Exported for testing.
+ *
+ * @param {{
+ *   cwd: string,
+ *   storyId: number,
+ *   storyTitle: string,
+ *   storyBranch: string,
+ *   baseBranch: string,
+ *   gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
+ *   progress?: (tag: string, msg: string) => void,
+ * }} args
+ * @returns {Promise<string>}
+ */
+export async function ensurePullRequestWith({
+  cwd: _cwd,
+  storyId,
+  storyTitle,
+  storyBranch,
+  baseBranch,
+  gh = defaultGh,
+  progress = () => {},
+}) {
+  // `cwd` is preserved on the call signature for backwards compatibility
+  // with the SUT's thin wrapper, but `gh-exec` spawns `gh` against the
+  // current process cwd. `single-story-close.js` chdirs into the worktree
+  // before invoking the phase, so the effective cwd matches the legacy
+  // `execFileSync('gh', …, { cwd })` shape.
+  try {
+    // `gh pr list --head <branch> --state open --json url` returns a
+    // JSON array of `{ url }` rows; an empty array means no open PR on
+    // this head. We pick the first entry's URL (matching the legacy
+    // `-q '.[0].url // empty'` projection on our side) so the typed
+    // `gh.pr.list` facade can stay generic.
+    const rows = await gh.pr.list(
+      ['--head', storyBranch, '--state', 'open'],
+      ['url'],
+    );
+    const existing =
+      Array.isArray(rows) && rows.length > 0
+        ? String(rows[0]?.url ?? '').trim()
+        : '';
+    if (existing) {
+      progress('PR', `Reusing existing PR: ${existing}`);
+      return existing;
+    }
+  } catch (err) {
+    // `gh pr list` failure is recoverable — fall through to create. Log
+    // the error so an auth issue surfaces visibly.
+    Logger.warn?.(
+      `[single-story-close] ⚠️ \`gh pr list\` probe failed (continuing to create): ${err?.message ?? err}`,
+    );
+  }
+
+  progress('PR', `Opening PR for ${storyBranch} → ${baseBranch}...`);
+  const title = storyTitle?.trim()
+    ? `${storyTitle} (#${storyId})`
+    : `Story #${storyId}`;
+  const body = [
+    `Closes #${storyId}`,
+    '',
+    `_Auto-opened by \`/single-story-deliver\`._`,
+  ].join('\n');
+  try {
+    const createResult = await gh.pr.create([
+      '--base',
+      baseBranch,
+      '--head',
+      storyBranch,
+      '--title',
+      title,
+      '--body',
+      body,
+    ]);
+    const url = (createResult?.stdout ?? '').trim();
+    progress('PR', `✅ Opened: ${url}`);
+    return url;
+  } catch (err) {
+    throw new Error(
+      `[single-story-close] \`gh pr create\` failed: ${err?.message ?? err}`,
+    );
+  }
+}

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

@@ -0,0 +1,42 @@
+/**
+ * phases/push.js — push the Story branch to origin.
+ *
+ * `git push -u` makes the local branch track origin/story-<id> so
+ * subsequent fetches are cheap. A push failure raises so the caller
+ * fails non-zero — the operator must resolve before retrying.
+ *
+ * `gitSync` is accepted as an injected dependency rather than statically
+ * imported so the caller's (cache-busted) binding wins. The
+ * `single-story-close.js` orchestrator owns the static import; test
+ * suites mock the git-utils module URL and re-import the SUT to refresh
+ * the binding it passes in.
+ */
+
+import { gitSync as defaultGitSync } from '../../../git-utils.js';
+
+/**
+ * Push the Story branch with `-u` so the upstream is set.
+ *
+ * @param {{
+ *   cwd: string,
+ *   storyBranch: string,
+ *   gitSync?: typeof defaultGitSync,
+ *   progress: (tag: string, msg: string) => void,
+ * }} args
+ */
+export function pushStoryBranch({
+  cwd,
+  storyBranch,
+  gitSync = defaultGitSync,
+  progress,
+}) {
+  progress('GIT', `Pushing ${storyBranch} to origin...`);
+  try {
+    gitSync(cwd, 'push', '--no-verify', '-u', 'origin', storyBranch);
+    progress('GIT', `✅ Pushed ${storyBranch}.`);
+  } catch (err) {
+    throw new Error(
+      `[single-story-close] git push failed for ${storyBranch}: ${err?.message ?? err}`,
+    );
+  }
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-reap.js

@@ -0,0 +1,73 @@
+/**
+ * phases/worktree-reap.js — reap the per-Story worktree after close.
+ *
+ * The Story branch is still alive on `origin` so the PR can land; the
+ * local worktree is no longer needed once the PR is open. Reap is
+ * best-effort: any failure is logged loudly and the close result still
+ * reports success because the operator can clean stale worktrees out of
+ * band.
+ *
+ * Also clears the trace-hook env vars so subsequent tooling falls back to
+ * the no-op branch instead of pointing at a (now-reaped) worktree.
+ */
+
+import { Logger } from '../../../Logger.js';
+import { clearActiveStoryEnv } from '../../../observability/active-story-env.js';
+import { WorktreeManager as DefaultWorktreeManager } from '../../../worktree-manager.js';
+
+/**
+ * Reap the worktree for a standalone Story when isolation is enabled and
+ * `reapOnSuccess` is not explicitly disabled.
+ *
+ * @param {{
+ *   cwd: string,
+ *   storyId: number,
+ *   worktreePath: string|null,
+ *   wtIsolation: object|undefined,
+ *   progress: (tag: string, msg: string) => void,
+ * }} args
+ * @returns {Promise<boolean>} true when reap completed
+ */
+export async function reapWorktreePhase({
+  cwd,
+  storyId,
+  worktreePath,
+  wtIsolation,
+  progress,
+  WorktreeManager = DefaultWorktreeManager,
+}) {
+  let worktreeReaped = false;
+  const reapEnabled = wtIsolation?.reapOnSuccess !== false;
+  if (worktreePath && reapEnabled) {
+    try {
+      const wm = new WorktreeManager({
+        repoRoot: cwd,
+        config: wtIsolation,
+        logger: {
+          info: (m) => progress('WORKTREE', m),
+          warn: (m) => progress('WORKTREE', `⚠️ ${m}`),
+          error: (m) => Logger.error(`[single-story-close] ${m}`),
+        },
+      });
+      await wm.reap(storyId);
+      worktreeReaped = true;
+      progress('WORKTREE', `🧹 Reaped worktree for story-${storyId}.`);
+    } catch (err) {
+      Logger.error(
+        `[single-story-close] ⚠️ Failed to reap worktree: ${err?.message ?? err}`,
+      );
+    }
+  }
+
+  // Clear the trace-hook env vars so subsequent tooling falls back to the
+  // no-op branch instead of pointing at a (now-reaped) worktree.
+  try {
+    clearActiveStoryEnv({
+      logger: { warn: (m) => progress('ENV', `⚠️ ${m}`) },
+    });
+  } catch {
+    // Non-fatal.
+  }
+
+  return worktreeReaped;
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/wrong-tree-guard.js

@@ -0,0 +1,225 @@
+/**
+ * phases/wrong-tree-guard.js — detect worktree/main-checkout edit divergence.
+ *
+ * Story #3364 — `/single-story-deliver` (and `/story-deliver`) materializes a
+ * per-Story worktree and instructs the agent to `cd` into it before editing.
+ * On Windows that guidance is silently insufficient: `cd <workCwd>` steers the
+ * Bash tool's working directory, but the path-based Edit/Write tools operate on
+ * absolute paths and ignore cwd. An agent whose shell is correctly inside the
+ * worktree can still resolve a main-checkout absolute path and edit the wrong
+ * tree — the two surfaces disagree and nothing detects it.
+ *
+ * Failure mode this guards: the worktree is the intended work tree, but the
+ * agent's edits landed under the main checkout instead. `single-story-close.js`
+ * runs its gates against the worktree only, so it would commit an unchanged /
+ * partial worktree (gates pass on the clean tree) while leaving the main
+ * checkout dirty — a silent empty-diff PR.
+ *
+ * Detection: when a worktree is the active work tree (it exists on disk and is
+ * distinct from `cwd`), inspect `git -C <mainCheckout> status --porcelain`. Any
+ * **tracked-path** change (modified, staged, deleted, renamed) in the main
+ * checkout is the wrong-tree signal. Untracked files (`??`) are ignored — they
+ * are scratch artifacts, not relocated Story work, and flagging them would
+ * produce false positives on every run.
+ *
+ * The guard runs before the gate chain. On detection it posts a `friction`
+ * structured comment naming the stray files and throws, so the operator/agent
+ * relocates the edits into the worktree before close proceeds. This is the
+ * load-bearing, detection-based fix: it fires regardless of whether the agent
+ * ever realized it edited the wrong tree.
+ */
+
+import path from 'node:path';
+import { postStructuredComment } from '../../ticketing/state.js';
+
+/**
+ * Parse `git status --porcelain` output into structured status entries.
+ *
+ * Porcelain v1 format: a two-character status field, a space, then the path
+ * (renames use `orig -> dest`, which we collapse to the destination path).
+ * Untracked entries carry the `??` status field.
+ *
+ * @param {string} raw - Raw `git status --porcelain` stdout (may be empty).
+ * @returns {Array<{ status: string, path: string, untracked: boolean }>}
+ */
+export function parsePorcelainStatus(raw) {
+  if (typeof raw !== 'string' || raw.trim() === '') return [];
+  return raw
+    .split('\n')
+    .map((line) => line.replace(/\r$/, ''))
+    .filter((line) => line.length > 0)
+    .map((line) => {
+      // First two chars are the status code; path begins at column 3.
+      const status = line.slice(0, 2);
+      let filePath = line.slice(3).trim();
+      // Renames/copies render as "orig -> dest"; keep the destination.
+      const arrowIdx = filePath.indexOf(' -> ');
+      if (arrowIdx !== -1) {
+        filePath = filePath.slice(arrowIdx + 4).trim();
+      }
+      // Porcelain may quote paths containing special chars; strip the quotes.
+      if (filePath.startsWith('"') && filePath.endsWith('"')) {
+        filePath = filePath.slice(1, -1);
+      }
+      return { status, path: filePath, untracked: status === '??' };
+    });
+}
+
+/**
+ * Filter porcelain status entries down to the tracked-path changes that
+ * indicate stray Story work landed in the main checkout.
+ *
+ * Untracked files (`??`) are excluded — they are scratch artifacts, not
+ * relocated tracked-file edits, and the issue's contract scopes the signal to
+ * "uncommitted changes under tracked paths".
+ *
+ * @param {Array<{ status: string, path: string, untracked: boolean }>} entries
+ * @returns {string[]} sorted list of stray tracked-file paths.
+ */
+export function collectStrayTrackedPaths(entries) {
+  return entries
+    .filter((e) => !e.untracked)
+    .map((e) => e.path)
+    .filter(Boolean)
+    .sort();
+}
+
+/**
+ * Decide whether the wrong-tree guard applies for this close.
+ *
+ * The guard only makes sense when a worktree is the active work tree: it must
+ * exist on disk (`worktreePath` is non-null) and be a distinct directory from
+ * the main checkout (`cwd`). In single-tree mode the worktree IS the main
+ * checkout, so there is no divergence to detect.
+ *
+ * @param {{ cwd: string, worktreePath: string|null }} opts
+ * @returns {boolean}
+ */
+export function guardApplies({ cwd, worktreePath }) {
+  if (!worktreePath) return false;
+  return path.resolve(cwd) !== path.resolve(worktreePath);
+}
+
+/**
+ * Format the `friction` finding body naming the stray files.
+ *
+ * @param {{ storyId: number, strayFiles: string[], worktreePath: string }} opts
+ * @returns {string}
+ */
+export function formatWrongTreeFinding({ storyId, strayFiles, worktreePath }) {
+  const list = strayFiles.map((f) => `- \`${f}\``).join('\n');
+  return (
+    `### wrong-tree edit detected (close aborted)\n\n` +
+    `Story #${storyId}: the main checkout has uncommitted changes under ` +
+    `tracked paths while the active work tree is the per-Story worktree:\n\n` +
+    `\`${worktreePath}\`\n\n` +
+    `This is the wrong-tree failure mode: edits intended for the worktree ` +
+    `landed in the main checkout instead (on Windows, \`cd\` steers the Bash ` +
+    `cwd but path-based Edit/Write tools resolve absolute paths and ignore ` +
+    `it). Close was **aborted** to prevent committing an unchanged worktree ` +
+    `and opening an empty-diff PR.\n\n` +
+    `**Stray files in the main checkout:**\n\n${list}\n\n` +
+    `**Recovery:** relocate these edits into the worktree (re-apply them under ` +
+    `\`${worktreePath}\`), restore the main checkout ` +
+    `(\`git -C <main-repo> checkout -- <files>\`), then re-run ` +
+    `\`/single-story-deliver\`.`
+  );
+}
+
+/**
+ * Run the wrong-tree detection guard for `single-story-close`.
+ *
+ * When a worktree is the active work tree and the main checkout has uncommitted
+ * tracked-path changes, posts a `friction` comment naming the stray files and
+ * throws to abort close. Otherwise returns a clean result.
+ *
+ * Unlike the soft drift-detection phase, this guard is **load-bearing**: a
+ * positive detection aborts close (throws). Failures to run git, however, are
+ * swallowed as warnings — a probe failure must not block an otherwise valid
+ * close (fail-open on the probe, fail-closed on a confirmed positive).
+ *
+ * @param {{
+ *   cwd: string,
+ *   worktreePath: string|null,
+ *   storyId: number,
+ *   provider: object,
+ *   progress: (tag: string, msg: string) => void,
+ *   gitSpawn?: Function,
+ * }} args
+ * @returns {Promise<{ applied: boolean, strayFiles: string[] }>}
+ * @throws {Error} when stray tracked-path edits are detected in the main checkout.
+ */
+export async function runWrongTreeGuardPhase({
+  cwd,
+  worktreePath,
+  storyId,
+  provider,
+  progress,
+  gitSpawn: injectedGitSpawn,
+}) {
+  if (!guardApplies({ cwd, worktreePath })) {
+    return { applied: false, strayFiles: [] };
+  }
+
+  // Dynamic import keeps the default git binding out of the module top-level so
+  // unit tests can inject a fake without module-URL mocking.
+  const { gitSpawn: defaultGitSpawn } = await import('../../../git-utils.js');
+  const gitSpawnFn = injectedGitSpawn ?? defaultGitSpawn;
+
+  progress(
+    'WRONG-TREE',
+    `Checking main checkout for stray edits (worktree-isolated Story #${storyId})...`,
+  );
+
+  let result;
+  try {
+    result = gitSpawnFn(cwd, 'status', '--porcelain');
+  } catch (err) {
+    // Probe failure is non-fatal — never block a valid close on a git hiccup.
+    progress(
+      'WRONG-TREE',
+      `⚠️ Could not probe main checkout status: ${err?.message ?? err}. Skipping guard.`,
+    );
+    return { applied: false, strayFiles: [] };
+  }
+
+  if (!result || result.status !== 0) {
+    progress(
+      'WRONG-TREE',
+      `⚠️ git status probe exited non-zero: ${result?.stderr || '(no stderr)'}. Skipping guard.`,
+    );
+    return { applied: false, strayFiles: [] };
+  }
+
+  const strayFiles = collectStrayTrackedPaths(
+    parsePorcelainStatus(result.stdout ?? ''),
+  );
+
+  if (strayFiles.length === 0) {
+    progress('WRONG-TREE', '✅ Main checkout clean — no wrong-tree edits.');
+    return { applied: true, strayFiles: [] };
+  }
+
+  // Confirmed positive: post a friction comment and abort close.
+  const body = formatWrongTreeFinding({ storyId, strayFiles, worktreePath });
+  try {
+    await postStructuredComment(provider, storyId, 'friction', body);
+    progress(
+      'WRONG-TREE',
+      `🛑 Wrong-tree edits detected: ${strayFiles.length} stray file(s). Posted friction comment to Story #${storyId}.`,
+    );
+  } catch (err) {
+    progress(
+      'WRONG-TREE',
+      `⚠️ Failed to post wrong-tree friction comment: ${err?.message ?? err}`,
+    );
+  }
+
+  throw new Error(
+    `[single-story-close] Wrong-tree edits detected: the main checkout has ` +
+      `uncommitted tracked-path changes while the worktree (${worktreePath}) is ` +
+      `the active work tree. Close aborted to avoid an empty-diff PR. Stray ` +
+      `files: ${strayFiles.join(', ')}. Relocate the edits into the worktree, ` +
+      `restore the main checkout, then re-run /single-story-deliver.`,
+  );
+}