mandrel 2.60.0 → 2.61.0

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

@@ -1,69 +1,23 @@
 /**
- * phases/close-validation.js — run the canonical close-validation gate
- * chain for a standalone Story.
+ * phases/close-validation.js — the close-validation gate chain for a Story.
  *
- * The standalone path uses the same `runCloseValidation` chain as
- * Epic-attached Stories so the experience matches — only the baseline
- * ref changes (`main`, not `epic/<id>`).
- *
- * Standalone evidence keyspace (Story #4250). Standalone Stories have no
- * parent Epic, so they cannot scope a `validation-evidence.json` under a
- * `temp/run-<id>/` tree. Rather than feed a null `epicId` into the
- * Epic-keyed path (which structurally disabled the evidence cache and
- * forced every re-run — base-sync conflict, review remediation, baseline
- * absorb — to re-execute ALL gates including the coverage suite), the
- * standalone close now passes `standalone: true`. `runCloseValidation`
- * then anchors the cache on the Story id alone at
- * `temp/standalone/stories/story-<id>/validation-evidence.json`, so a
- * second close at unchanged HEAD short-circuits the already-passed gates.
- *
- * Pre-gate self-heal (Stories #4250, #5224). Two best-effort steps run on the
- * Story branch before the check-only gates score it — the scoped format
- * autofix and the upward maintainability write-back — so whatever they commit
- * is part of what the gates see and part of the branch's own PR. Both live in
- * [`pre-gate-steps.js`](pre-gate-steps.js); neither can fail a close, because
- * an authoritative gate for each runs immediately below.
- *
- * Bounded gate output (Story #4736). Every gate line goes to the run's
- * `gate-log.js` sink — an artifact under the gitignored temp tree — instead
- * of straight to the agent's stdout, where a passing `npm test` alone once
- * pushed a successful close past the host's inline tool-result ceiling. A
- * clean run reports one digest line naming the artifact; a failing gate
- * replays its captured tail inline, because that is exactly when the caller
- * needs the evidence in front of them. `AGENT_LOG_LEVEL=verbose` restores
- * live streaming.
- *
- * Projection advisories (Story #4776). `baseBranch`, `storyBranch` and the
- * resolved `config` are forwarded to `runCloseValidation` so its projection
- * phase can run. They surface, after the gates pass, which committed
- * baseline rows the post-merge tree would breach and the exact
- * `*:update` + `baseline-refresh:` remedy — advisory only, so the close
- * verdict is unchanged.
- *
- * `runCloseValidation`, `buildDefaultGates` and the pre-gate steps (whole, or
- * their two individual collaborators) are accepted as injected dependencies so
- * the parent CLI's cache-busted bindings win in tests that mock the upstream
- * module URLs.
+ * Gate output goes to an artifact sink (inline output once overflowed the
+ * host's tool-result ceiling): a pass reports one digest line, a failure
+ * replays its tail inline. Full-suite lock-wait lines are also teed to
+ * `progress()` so a long wait doesn't read as a hang, and an expired wait
+ * defers to `pending` rather than failing.
  */
 
 import { buildDefaultGates as defaultBuildDefaultGates } from '../../../close-validation/gates.js';
 import { runCloseValidation as defaultRunCloseValidation } from '../../../close-validation/runner.js';
+import { LOCK_WAIT_EXPIRED_EXIT_CODE } from '../../../full-suite-lock.js';
+import { parseLockWaitOutcome } from '../../../full-suite-queue.js';
 import { createGateLogSink as defaultCreateGateLogSink } from '../gate-log.js';
 import { runPreGateSteps as defaultRunPreGateSteps } from './pre-gate-steps.js';
 
 /**
- * Run the close-validation gate chain. Throws on first gate failure.
- *
- * Order: pre-gate self-heal steps → close-validation gates. The steps scope
- * to the `baseBranch...storyBranch` diff, commit inside the Story worktree,
- * and are best-effort — a missing `storyBranch` (resume/legacy callers) skips
- * them with a log line rather than failing.
- *
- * Gates are built from the canonical resolved config (`buildDefaultGates`
- * reads `project.commands` and `delivery.quality.gates.crap.enabled`); the
- * `baseBranch` is forwarded as the gate `baseBranch` so the format gate's
- * changed-file scope anchors on it. `standalone: true` routes the evidence
- * cache to the storyId-anchored keyspace.
+ * Pre-gate self-heal steps, then the gates (throws on first failure). The
+ * steps commit in the worktree before scoring, so the gates see their output.
  *
  * @param {{
  *   cwd: string,
@@ -81,10 +35,12 @@ import { runPreGateSteps as defaultRunPreGateSteps } from './pre-gate-steps.js';
  *   runContextBudgetWriteback?: Function,
  *   createGateLogSink?: typeof defaultCreateGateLogSink,
  * }} args
- * @returns {Promise<{ gates: Record<string, 'passed'|'skipped'> }>} Per-gate
- *   outcomes keyed by gate name — the terminal envelope reports the split
- *   baselines entries from this (Story #5172). A failure throws instead, with
- *   `err.closeGate` naming the gate that died.
+ * @returns {Promise<{
+ *   gates: Record<string, 'passed'|'skipped'>|null,
+ *   lockWait: { waitedSeconds: number, expired: boolean }|null,
+ *   pending: boolean,
+ * }>} `pending` (with `gates: null`) when a lock wait expired; any other
+ *   failure throws with `err.closeGate` naming the gate.
  */
 export async function runCloseValidationPhase({
   cwd,
@@ -119,15 +75,15 @@ export async function runCloseValidationPhase({
     'VALIDATE',
     `Running close-validation gates against baseline ${baseBranch}${worktreePath ? ` in ${worktreePath}` : ''}...`,
   );
-  // Story #4736 — one sink for both `log` seams (gate construction and gate
-  // execution), so nothing in the chain can route around the artifact.
+  // One sink for both `log` seams so nothing routes around the artifact.
   const gateLog = createGateLogSink({ storyId, config });
+  const lockWaits = trackLockWaits({ sink: gateLog.log, progress });
   const gateList = buildDefaultGates({
     config,
     baseBranch,
     cwd: worktreePath || cwd,
     log: gateLog.log,
-    storyId, // Story #5313 — a credited bare `npm test` registers `test`.
+    storyId,
     evidenceCwd: cwd,
   });
   let validation;
@@ -136,57 +92,107 @@ export async function runCloseValidationPhase({
       cwd,
       worktreePath,
       gates: gateList,
-      log: gateLog.log,
+      log: lockWaits.log,
       storyId,
-      // Story #4250 — standalone storyId-anchored evidence keyspace. No
-      // epicId; the standalone flag routes the cache to
-      // temp/standalone/stories/story-<id>/validation-evidence.json.
+      // Anchors the evidence cache on the Story id, so a re-close at an
+      // unchanged HEAD skips already-passed gates.
       standalone: true,
-      // Story #4776 — the branch pair and resolved config the advisory
-      // projections need. Without them the runner skips the projection
-      // phase entirely, which is the correct behaviour for resume/legacy
-      // callers that have no story branch to diff.
+      // Needed for the advisory baseline projections; absent, they're skipped.
       baseBranch,
       storyBranch,
       config,
+      deferOnLockExpiry: true,
     });
   } finally {
-    // Story #4766 — gate lines are buffered to an async stream so the drain
-    // never blocks a gate child's pipe. Settle the artifact before anything
-    // reads it, replays from it, or reports its path — including on the throw
-    // path, where the artifact is the only surviving record.
+    // The sink is async-buffered; settle it before anything reads it, on
+    // the throw path too.
     await gateLog.flush();
   }
+  const lockWait = lockWaits.summary();
   if (!validation.ok) {
-    const [first] = validation.failed;
-    const { gate, status, cwd: gateCwd } = first;
-    // The evidence is the point on this path: replay the captured tail inline
-    // rather than making the caller open a file to learn why close stopped.
-    gateLog.replay();
-    const err = new Error(
-      `[single-story-close] Gate failed: ${gate.name} (exit ${status})${gateCwd ? ` in ${gateCwd}` : ''}.` +
-        (gate.hint ? ` ${gate.hint}` : ''),
-    );
-    // Story #5172 — the phase tracker tags `closePhase`; this tags WHICH gate
-    // inside the phase died, so the failed terminal can name the split
-    // baselines entry rather than reporting a generic validation failure.
-    err.closeGate = gate.name;
-    throw err;
+    return settleFailedValidation({ validation, lockWait, gateLog, progress });
   }
   progress('VALIDATE', `✅ All gates passed. ${gateLog.digest()}`);
-  return { gates: gateOutcomes(gateList, validation) };
+  return {
+    gates: gateOutcomes(gateList, validation),
+    lockWait,
+    pending: false,
+  };
+}
+
+/**
+ * Deferred on an expired lock wait → `pending`; otherwise throws.
+ *
+ * @param {{
+ *   validation: { failed: Array<{ gate: { name: string, hint?: string }, status: number, cwd?: string }> },
+ *   lockWait: { waitedSeconds: number, expired: boolean }|null,
+ *   gateLog: { replay: () => void },
+ *   progress: (tag: string, msg: string) => void,
+ * }} args
+ * @returns {{ gates: null, lockWait: object, pending: true }}
+ */
+function settleFailedValidation({ validation, lockWait, gateLog, progress }) {
+  const [first] = validation.failed;
+  const { gate, status, cwd: gateCwd } = first;
+  if (isDeferredLockWait(first, lockWait)) {
+    progress(
+      'VALIDATE',
+      `⏸ ${gate.name} deferred: the full-suite lock wait expired after ${lockWait.waitedSeconds}s. Nothing was spawned; close will report pending.`,
+    );
+    return { gates: null, lockWait, pending: true };
+  }
+  gateLog.replay();
+  const err = new Error(
+    `[single-story-close] Gate failed: ${gate.name} (exit ${status})${gateCwd ? ` in ${gateCwd}` : ''}.` +
+      (gate.hint ? ` ${gate.hint}` : ''),
+  );
+  err.closeGate = gate.name;
+  throw err;
 }
 
 /**
- * Per-gate outcomes for a validation run that passed (Story #5172).
+ * Parsed from the gate log because it is the one place that sees waits both
+ * in-process and in gate children.
  *
- * Every registered gate passed unless the runner reported it skipped — an
- * evidence short-circuit at unchanged HEAD, or a changed-file scope that
- * matched nothing. `skipped` is the honest verdict for both: the gate did not
- * run in THIS invocation, and the terminal schema's own contract is that a
- * skipped gate is reported as skipped rather than quietly counted as a pass.
+ * @param {{ sink: (m: string) => void, progress: (tag: string, msg: string) => void }} args
+ * @returns {{ log: (m: string) => void, summary: () => { waitedSeconds: number, expired: boolean }|null }}
+ */
+function trackLockWaits({ sink, progress }) {
+  let tally = null;
+  return {
+    log(line) {
+      sink(line);
+      if (!String(line).includes('[full-suite-lock]')) return;
+      progress('LOCK', line);
+      const outcome = parseLockWaitOutcome(line);
+      if (!outcome) return;
+      tally = {
+        waitedSeconds: (tally?.waitedSeconds ?? 0) + outcome.waitedSeconds,
+        expired: Boolean(tally?.expired) || outcome.expired,
+      };
+    },
+    summary: () => tally,
+  };
+}
+
+/**
+ * Needs both the exit code and a recorded expiry — either alone is ambiguous.
+ *
+ * @param {{ status: number }|undefined} failure
+ * @param {{ expired: boolean }|null} lockWait
+ * @returns {boolean}
+ */
+function isDeferredLockWait(failure, lockWait) {
+  return (
+    failure?.status === LOCK_WAIT_EXPIRED_EXIT_CODE &&
+    lockWait?.expired === true
+  );
+}
+
+/**
+ * A gate that did not run this invocation reports `skipped`, never `passed`.
  *
- * @param {Array<{ name: string }>} gateList The gates this run registered.
+ * @param {Array<{ name: string }>} gateList
  * @param {{ skipped?: Array<{ gate: { name: string } }> }} validation
  * @returns {Record<string, 'passed'|'skipped'>}
  */

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

@@ -1,38 +1,11 @@
 /**
- * phases/code-review.js — Story-scope code review phase for
- * `single-story-close`.
+ * phases/code-review.js — Story-scope code review: findings post to the PR,
+ * with a cross-reference on the Story issue. Critical findings return
+ * `halted: true` so the caller never arms auto-merge.
  *
- * Runs the Story-scope code review against `main`, posts the structured
- * findings comment to the PR (not the Story issue), and adds a one-line
- * cross-reference comment on the Story issue linking back to the PR
- * review comment. The render header still labels the comment "Story #N"
- * even though the post target is the PR — the PR is the comment surface,
- * the Story is the ticket the findings *describe*.
- *
- * Cross-reference URL shape: GitHub serves issue comments at
- * `<prUrl>#issuecomment-<commentId>` — the same URL pattern for PR
- * conversation comments and issue comments, because PRs are issues at
- * the API level.
- *
- * Re-exports `parsePrNumber` (delegates to `lib/github-url.js`) so
- * existing call sites need not change. Story #3649.
- *
- * Critical findings cause `runStoryScopeReview` to return `halted: true`;
- * the caller raises that to a thrown error so auto-merge is not enabled.
- *
- * Delegates the `runCodeReview` invocation to `runStoryReviewCore`
- * (exported from `story-close/phases/review-core.js`) so the close path
- * shares a single invocation pattern (Story #3653). Review depth needs no
- * input here: it is derived from this Story's own diff inside `runCodeReview`
- * (Story #4542).
- *
- * Story #5325 — this phase boundary is where the base ref is resolved, once.
- * The resolved ref threads into `runStoryReviewCore`, which hands it to both
- * the change-set enumeration (and through it the provider review) and the
- * local lens pass, so one resolution corrects both arms. It resolves to
- * `origin/<baseBranch>` — the ref base-sync merged from — rather than the bare
- * branch name git would resolve to the local `refs/heads/<baseBranch>`, whose
- * drift would otherwise be scored as this Story's own change.
+ * The base ref is resolved once, here, to `origin/<baseBranch>` (what
+ * base-sync merged from) — the local branch's drift would otherwise be
+ * scored as this Story's change.
  */
 
 import { parsePrNumberFromUrl } from '../../../github-url.js';
@@ -49,23 +22,12 @@ import {
 } from './review-outcome.js';
 
 /**
- * Extract the numeric PR ID from a `gh pr create` URL. The CLI returns a
- * URL like `https://github.com/<owner>/<repo>/pull/<n>`; we want `<n>`.
- * Returns `null` when the URL doesn't match. Exported for testing.
- *
- * Delegates to `parsePrNumberFromUrl` in `lib/github-url.js`.
- * Re-exported under the original name so existing call sites and tests
- * do not need to change. Story #3649.
- *
  * @param {string|null|undefined} prUrl
  * @returns {number|null}
  */
 export const parsePrNumber = parsePrNumberFromUrl;
 
 /**
- * Build the cross-reference comment body posted on the Story issue when
- * the PR-side review comment lands. Pure; exported for testing.
- *
  * @param {{
  *   prUrl: string,
  *   prNumber: number,
@@ -109,9 +71,6 @@ async function invokeStoryReviewCore({
     progressTag: 'REVIEW',
     runCodeReviewFn,
     gitSpawnFn,
-    // Forward the seams only when the caller injects them; otherwise
-    // `runStoryReviewCore` uses its defaults. `undefined` deep-merges to
-    // the default via the destructuring default there.
     ...(runLocalLensReviewFn ? { runLocalLensReviewFn } : {}),
     ...(appendFindingsYieldFn ? { appendFindingsYieldFn } : {}),
   });
@@ -160,21 +119,8 @@ async function postStoryReviewCrossRef({
 }
 
 /**
- * Run the Story-scope code review against `main`, post the structured
- * findings comment to the PR, and add a one-line cross-reference comment
- * on the Story issue linking back to the PR review comment.
- *
- * Failure modes:
- *   - When `prNumber` is null (couldn't parse), the review is skipped
- *     and the function returns `{ halted: false, skipped: true }`.
- *   - When `origin/<baseBranch>` cannot be resolved, the review is skipped,
- *     a `base-ref-resolution` degradation is recorded on the returned
- *     envelope, and no findings are raised (Story #5325).
- *   - When the runner throws, the close fails non-zero (the throw
- *     propagates) — a Story-scope review failure is not silently
- *     ignored.
- *
- * Exported for testing.
+ * Skips on an unparseable PR number or an unresolvable base (recording a
+ * degradation); a runner throw propagates and fails the close.
  *
  * @param {{
  *   cwd: string,
@@ -224,8 +170,6 @@ export async function runStoryScopeReview({
     return { halted: false, skipped: true };
   }
 
-  // One resolution per close, at the phase boundary: `baseRef` threads from
-  // here into the change set, the provider review and the local lens pass.
   const base = resolveSharedBaseRef({ baseBranch, cwd, gitSpawnFn });
   if (!base.resolved) {
     return unresolvedBaseReviewOutcome({