mandrel 2.16.0 → 2.18.0

package/.agents/scripts/lib/observability/terse-result.js

@@ -1,6 +1,7 @@
 import nodeFs from 'node:fs';
 import path from 'node:path';
 
+import { orchestrationLogDir } from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
 
 /**
@@ -69,8 +70,10 @@ function detailBlock(label, result) {
  *   on; serialized compactly onto the single summary line.
  * @param {string|number} [args.scope] Disambiguating suffix for the log name
  *   (typically the Story id) so concurrent deliveries don't clobber one file.
- * @param {string} [args.logDir] Directory for the detail log. Defaults to
- *   `<cwd>/temp/orchestration`.
+ * @param {string} [args.logDir] Directory for the detail log. Defaults to the
+ *   configured `<tempRoot>/orchestration` (Story #4794 — was a hardcoded
+ *   `<cwd>/temp/orchestration`, which ignored `project.paths.tempRoot`).
+ * @param {object} [args.config] Resolved config bag, for the default `logDir`.
  * @param {typeof nodeFs} [args.fs] Filesystem seam (tests).
  * @param {{ info: (m: string) => void }} [args.log] Logger seam (tests).
  * @param {NodeJS.ProcessEnv} [args.env] Environment seam (tests).
@@ -82,6 +85,7 @@ export function emitTerseResult({
   summary = {},
   scope,
   logDir,
+  config,
   fs = nodeFs,
   log = Logger,
   env = process.env,
@@ -94,7 +98,7 @@ export function emitTerseResult({
     return { logPath: null, inline: true };
   }
 
-  const dir = logDir ?? path.join(process.cwd(), 'temp', 'orchestration');
+  const dir = logDir ?? orchestrationLogDir(config);
   const name = `${slugify(label)}${scope ? `-${scope}` : ''}.log`;
 
   try {

package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js

@@ -12,6 +12,7 @@
 import { readBaseFromGit } from '../../../baselines/git-base.js';
 import { getKindModule } from '../../../baselines/kernel.js';
 import { resolveScope } from '../../../baselines/scope.js';
+import { Logger } from '../../../Logger.js';
 import { DEFAULT_BASELINE_PATHS } from './parse-args.js';
 
 function baselineRelativePath(kind, gateBlock) {
@@ -67,6 +68,29 @@ export async function evaluateCompare({ kind, gateBlock, scope, cwd }) {
   return { baseRef: scope.ref, baseRead: true, basePayload, kindModule };
 }
 
+/**
+ * Is the base baseline comparable to the head baseline (Story #4775)?
+ *
+ * A kind can change its SCORING SEMANTICS — how it derives a row's metric —
+ * without moving `kernelVersion`. Across that boundary the same row can carry
+ * a different score for reasons that have nothing to do with the branch's
+ * changes, so a head-vs-base diff manufactures phantom regressions (and can
+ * hide real ones behind them).
+ *
+ * The head-side stamp is already a fail-closed gate: a stale HEAD baseline
+ * never reaches this point. What reaches here is the opposite and legitimate
+ * case — a branch that DOES carry a re-derived baseline, compared against a
+ * base that predates the change. The only honest verdict is "no comparison";
+ * floors still run, so a genuine ceiling breach is still caught, and once the
+ * refreshed baseline is the base the ratchet returns to full strength on the
+ * very next run without anything to remember to reset.
+ */
+function baseIsComparable(headBaseline, basePayload) {
+  const head = headBaseline?.scoringSemantics ?? null;
+  const base = basePayload?.scoringSemantics ?? null;
+  return head === base;
+}
+
 export function runCompareStage(headBaseline, cmp) {
   const empty = {
     regressions: [],
@@ -75,6 +99,17 @@ export function runCompareStage(headBaseline, cmp) {
     additions: [],
   };
   if (!cmp.baseRead || !cmp.basePayload || !cmp.kindModule) return empty;
+  if (!baseIsComparable(headBaseline, cmp.basePayload)) {
+    Logger.warn(
+      `[${cmp.kindModule.name}] ⚠ base baseline was scored under different ` +
+        `semantics (base=${cmp.basePayload.scoringSemantics ?? '<unstamped>'} ` +
+        `head=${headBaseline?.scoringSemantics ?? '<unstamped>'}); its rows are ` +
+        'not comparable, so the head-vs-base compare is skipped for this run. ' +
+        'Floors still enforced. The ratchet resumes once the re-derived ' +
+        'baseline is the base.',
+    );
+    return empty;
+  }
   try {
     const baseRows = Array.isArray(cmp.basePayload.rows)
       ? cmp.basePayload.rows

package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js

@@ -13,6 +13,7 @@ import {
 } from '../../../baselines/env-overrides.js';
 import { readRangeSubjectsTouchingFile } from '../../../baselines/git-base.js';
 import {
+  checkBaselineSemantics,
   checkKernelVersion,
   getKindModule,
 } from '../../../baselines/kernel.js';
@@ -247,6 +248,18 @@ export async function evaluateKind({
   const headLoad = loadHeadBaseline(kind, cwd, configPath);
   if (headLoad.schemaError) return { kind, schemaError: headLoad.schemaError };
   const baseline = headLoad.baseline;
+  // Story #4775 — scoring-semantics gate. A baseline whose rows were produced
+  // by superseded scoring semantics is structurally valid but semantically
+  // incomparable, so schema validation alone would wave it through. Fail
+  // closed on the `semantics` tag rather than compare across the boundary;
+  // the message names the exact re-baseline command.
+  const semanticsError = checkBaselineSemantics(kind, baseline);
+  if (semanticsError) {
+    return {
+      kind,
+      schemaError: { tag: 'semantics', message: semanticsError },
+    };
+  }
   const floorRollup = rollupExcludingIgnored({
     kind,
     baseline,

package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js

@@ -152,9 +152,24 @@ export function removeWorktree(worktreePath, cwd) {
   };
 }
 
+/**
+ * Prune the clone's stale remote-tracking refs and report which ones went.
+ *
+ * The fetch MUST NOT be `--quiet` (Story #4772). `--quiet` still prunes, but
+ * suppresses the `- [deleted] (none) -> <remote>/<ref>` progress lines that
+ * are the *only* record of what was dropped — `parsePruneFn` then reports an
+ * empty list for work that really happened, and `computeExitCode` reads the
+ * run as "nothing to do" (exit 2). The output is captured, not shown, so
+ * `--quiet` bought nothing to begin with.
+ *
+ * @param {string} cwd
+ * @param {string} remoteName
+ * @param {(output: string, remoteName: string) => string[]} parsePruneFn
+ * @returns {{ ok: boolean, pruned: string[], stderr?: string }}
+ */
 /* node:coverage ignore next */
 export function pruneRemoteTracking(cwd, remoteName, parsePruneFn) {
-  const res = gitSpawn(cwd, 'fetch', '--prune', '--quiet', remoteName);
+  const res = gitSpawn(cwd, 'fetch', '--prune', remoteName);
   if (res.status !== 0) return { ok: false, pruned: [], stderr: res.stderr };
   return { ok: true, pruned: parsePruneFn(res.stderr, remoteName) };
 }

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -37,13 +37,12 @@
  * @module lib/orchestration/plan-persist/run-plan-persist
  */
 
-import { readdir, rm, stat } from 'node:fs/promises';
+import { rm } from 'node:fs/promises';
 import path from 'node:path';
-
-import { anchorTempRoot, tempRootFrom } from '../../config/temp-paths.js';
 import { getLimits, PROJECT_ROOT } from '../../config-resolver.js';
 import { gitSpawn } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
+import { sweepTempRetention } from '../../temp-retention.js';
 import {
   deriveStoryShape,
   LITE_ROUTE_LABEL,
@@ -374,13 +373,6 @@ function resolveEffectiveRoute({
   };
 }
 
-/**
- * Age after which an abandoned `temp/plan-*` directory is reaped. A plan run
- * that is still being authored is minutes-to-hours old; a week is far past
- * any live run and comfortably past an operator returning to a paused one.
- */
-const STALE_PLAN_DIR_MS = 7 * 24 * 60 * 60 * 1000;
-
 /**
  * Reap abandoned `plan-*` directories under the temp root (Story #4541).
  *
@@ -389,9 +381,16 @@ const STALE_PLAN_DIR_MS = 7 * 24 * 60 * 60 * 1000;
  * `--dry-run` left its directory behind forever. This sweeps the stragglers
  * on each persist.
  *
+ * Story #4794 folded the age-floored reap into the shared temp-retention
+ * engine — `planDirs` is one of its declared classes, so the plan path and
+ * the delivery path now converge on one classifier and one staleness floor
+ * (`delivery.tempRetention.staleDays`, still 7 days by default) instead of
+ * this module owning a private constant. Behaviour is unchanged: only
+ * `plan-*` directories are considered, the age test is the directory's own
+ * mtime, and the current run's `planDir` is excluded.
+ *
  * Best-effort throughout: this is hygiene, never a reason to fail a run that
- * has already created Stories. The current run's own `planDir` is always
- * excluded — its cleanup is the caller's decision.
+ * has already created Stories.
  *
  * @param {{ config?: object, keepDir?: string|null, now?: number }} args
  * @returns {Promise<{ reaped: string[] }>}
@@ -401,35 +400,14 @@ export async function reapStalePlanDirs({
   keepDir = null,
   now = Date.now(),
 } = {}) {
-  const reaped = [];
-  const tempRoot = anchorTempRoot(tempRootFrom(config));
-  let entries;
-  try {
-    entries = await readdir(tempRoot, { withFileTypes: true });
-  } catch {
-    return { reaped }; // No temp root yet — nothing to reap.
-  }
-  const keep = keepDir ? path.resolve(keepDir) : null;
-  for (const entry of entries) {
-    if (!entry.isDirectory() || !entry.name.startsWith('plan-')) continue;
-    const dir = path.resolve(tempRoot, entry.name);
-    if (keep !== null && dir === keep) continue;
-    try {
-      const { mtimeMs } = await stat(dir);
-      if (now - mtimeMs < STALE_PLAN_DIR_MS) continue;
-      await rm(dir, { recursive: true, force: true });
-      reaped.push(dir);
-    } catch {
-      // A racing writer or a permission error: leave it for the next run.
-    }
-  }
-  if (reaped.length > 0) {
-    Logger.info(
-      `[plan-persist] reaped ${reaped.length} abandoned plan director(ies) ` +
-        `older than 7d under ${tempRoot}.`,
-    );
-  }
-  return { reaped };
+  const result = await sweepTempRetention({
+    config,
+    only: ['planDirs'],
+    excludePaths: keepDir ? [keepDir] : [],
+    now,
+    label: 'plan-persist',
+  });
+  return { reaped: result.purged.map((entry) => entry.path) };
 }
 
 /**

package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js

@@ -0,0 +1,122 @@
+/**
+ * single-story-close/failed-terminal.js — the `failed` terminal a close
+ * emits when a phase crashes, and the gate reconstruction it carries.
+ *
+ * Split out of `single-story-close.js` so the CLI entry stays an entry: it
+ * parses args, dispatches the runner, and maps a terminal onto an exit code.
+ * The reasoning about which gates had run by the time a phase died belongs
+ * with the envelope it feeds, not in the file that owns process lifetime.
+ *
+ * The runner deliberately throws rather than returning a failure (a red gate
+ * must not look like a return value), so without this the most common
+ * non-happy ending — a failing close-validation gate — would emit **no
+ * envelope at all**, exiting 1 with only a stderr line while the workflow
+ * docs promise the agent a `failed` envelope naming the phase.
+ */
+
+import { Logger } from '../../Logger.js';
+import {
+  buildTerminalEnvelope,
+  NEXT_COMMANDS,
+} from '../story-deliver-terminal.js';
+
+/**
+ * The close pipeline's phase order, as `setPhase` walks it. Only used to
+ * decide whether a gate had already run when a later phase died.
+ */
+const PHASE_ORDER = Object.freeze([
+  'init',
+  'wrong-tree-guard',
+  'close-validation',
+  'base-sync',
+  'push',
+  'pull-request',
+  'code-review',
+  'auto-merge',
+  'confirm-merge',
+  'post-land',
+  'done',
+]);
+
+/** Each reported gate and the pipeline phase that decides it. */
+const GATE_PHASES = Object.freeze([
+  ['validation', 'close-validation'],
+  ['baseSync', 'base-sync'],
+  ['codeReview', 'code-review'],
+]);
+
+/**
+ * Report every gate's outcome for a run that died at `phase`.
+ *
+ * The schema's contract: "A gate the run skipped … reports `skipped` rather
+ * than being omitted, so a missing gate is never mistaken for a passing one."
+ * The previous shape named only the gate that died and omitted the rest
+ * entirely — exactly the ambiguity the contract forbids.
+ *
+ * Reconstructed from the phase order, which is sound because the pipeline is
+ * strictly sequential: reaching phase N means every gate before it completed.
+ * A gate whose phase the run never reached is `skipped`; one the operator
+ * turned off via `--skip-validation` / `--skip-sync` is `skipped` too (it did
+ * not pass — it never ran).
+ *
+ * @param {string} phase The phase the run died in.
+ * @param {{ skipValidation?: boolean, skipSync?: boolean }} args Parsed CLI args.
+ * @returns {Record<string, 'passed'|'failed'|'skipped'>}
+ */
+export function gatesForFailedPhase(phase, args = {}) {
+  const skipped = { validation: args.skipValidation, baseSync: args.skipSync };
+  const failedAt = PHASE_ORDER.indexOf(phase);
+  const gates = {};
+  for (const [gate, gatePhase] of GATE_PHASES) {
+    const at = PHASE_ORDER.indexOf(gatePhase);
+    if (gatePhase === phase) gates[gate] = 'failed';
+    else if (failedAt < 0 || at > failedAt) gates[gate] = 'skipped';
+    else gates[gate] = skipped[gate] ? 'skipped' : 'passed';
+  }
+  return gates;
+}
+
+/**
+ * Build the `failed` terminal for a phase that crashed. Every close
+ * invocation emits exactly one envelope; this is the path that keeps that
+ * true when a phase dies.
+ *
+ * `err.closePhase` is tagged by the runner's phase tracker.
+ *
+ * **Never throws.** This runs on the path that already has one failure in
+ * hand, so a second failure here must not REPLACE the first: an
+ * envelope-build error surfacing as the run's cause sends the operator to
+ * diagnose the wrong thing entirely — a close whose PR had already merged
+ * once reported a schema `ENOENT` as its fatal error, because the worktree
+ * holding the script had been reaped mid-run. On failure this returns null
+ * and the caller rethrows the original.
+ *
+ * @param {unknown} err
+ * @param {{ storyId?: string|number, skipValidation?: boolean, skipSync?: boolean }} args
+ *   Parsed CLI args — the story id the envelope reports on, plus the skip
+ *   flags `gatesForFailedPhase` needs.
+ * @returns {object|null} A validated envelope, or null when even the story id
+ *   is unknown (a usage error — there is nothing to report an envelope about)
+ *   or the envelope itself could not be assembled.
+ */
+export function failedTerminalFor(err, args = {}) {
+  const phase = err?.closePhase ?? 'init';
+  const storyId = Number(args.storyId);
+  if (!Number.isInteger(storyId) || storyId <= 0) return null;
+  try {
+    return buildTerminalEnvelope({
+      storyId,
+      status: 'failed',
+      phase,
+      gates: gatesForFailedPhase(phase, args),
+      failure: { reason: String(err?.message ?? err) },
+      nextCommand: NEXT_COMMANDS.recover(storyId),
+      elapsedSeconds: 0,
+    });
+  } catch (buildErr) {
+    Logger.error(
+      `[single-story-close] ⚠️ Could not assemble the failed terminal envelope: ${buildErr?.message ?? buildErr}. Reporting the original failure instead.`,
+    );
+    return null;
+  }
+}

package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js

@@ -59,6 +59,7 @@
 import nodeFs from 'node:fs';
 import path from 'node:path';
 
+import { orchestrationLogDir } from '../../config/temp-paths.js';
 import { Logger, resolveLevel } from '../../Logger.js';
 
 /**
@@ -210,26 +211,29 @@ function createArtifactWriter(fs, logPath, handle) {
  *
  * @param {{
  *   storyId: number|null,
- *   cwd?: string,
  *   logDir?: string,
  *   fs?: typeof nodeFs,
  *   logger?: { info: (m: string) => void },
  *   level?: string,
- * }} [args] `logDir` defaults to `<cwd>/temp/orchestration`; `level` defaults
- *   to the live Logger level so `AGENT_LOG_LEVEL=verbose` restores streaming.
+ *   config?: object,
+ * }} [args] `logDir` defaults to the configured `<tempRoot>/orchestration`
+ *   (Story #4794 — was a hardcoded `<cwd>/temp/orchestration`, which ignored
+ *   `project.paths.tempRoot` and hid the artifact from the retention purge);
+ *   `level` defaults to the live Logger level so `AGENT_LOG_LEVEL=verbose`
+ *   restores streaming.
  * @returns {GateLogSink}
  */
 export function createGateLogSink({
   storyId = null,
-  cwd = process.cwd(),
   logDir,
   fs = nodeFs,
   logger = Logger,
   level,
+  config,
 } = {}) {
   const emit = (line) => logger.info?.(line);
   const verbose = (level ?? resolveLevel()) === 'verbose';
-  const dir = logDir ?? path.join(cwd, 'temp', 'orchestration');
+  const dir = logDir ?? orchestrationLogDir(config);
 
   let writer = null;
   let logPath = null;

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

@@ -33,6 +33,13 @@
  * 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 `runScopedFormatAutofix`
  * are accepted as injected dependencies so the parent CLI's cache-busted
  * bindings win in tests that mock the upstream module URLs.
@@ -136,7 +143,7 @@ export async function runCloseValidationPhase({
   );
   // Story #4736 — one sink for both `log` seams (gate construction and gate
   // execution), so nothing in the chain can route around the artifact.
-  const gateLog = createGateLogSink({ storyId, cwd });
+  const gateLog = createGateLogSink({ storyId, config });
   let validation;
   try {
     validation = await runCloseValidation({
@@ -154,6 +161,13 @@ export async function runCloseValidationPhase({
       // epicId; the standalone flag routes the cache to
       // temp/standalone/stories/story-<id>/validation-evidence.json.
       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.
+      baseBranch,
+      storyBranch,
+      config,
     });
   } finally {
     // Story #4766 — gate lines are buffered to an async stream so the drain

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

@@ -39,6 +39,7 @@ import {
   RUNTIME_FRICTION_CATEGORIES,
 } from '../../../observability/runtime-friction.js';
 import { acquireLockWithWait as defaultAcquireLockWithWait } from '../../../single-story-sweep/sweep-lock.js';
+import { purgeStoryTempArtifacts as defaultPurgeStoryTempArtifacts } from '../../../temp-retention.js';
 import {
   executeFastForward as defaultExecuteFastForward,
   planFastForward as defaultPlanFastForward,
@@ -224,6 +225,22 @@ async function stepBaseFastForward({
   };
 }
 
+/**
+ * Purge this Story's spent temp artifacts now that its merge is confirmed
+ * (Story #4794).
+ *
+ * The engine already emits its own one-line summary and returns a disabled
+ * policy as `skipped` with no errors, so this step needs no branching of its
+ * own: errors degrade it, everything else — including a deliberate
+ * config-disabled no-op — is a success. Reporting a disabled purge as a failed
+ * step would train readers to ignore the field.
+ */
+async function stepTempPurge({ storyId, config, purgeStoryTempArtifactsFn }) {
+  const result = await purgeStoryTempArtifactsFn({ storyId, config });
+  const errors = result?.errors ?? [];
+  return { ok: errors.length === 0, detail: errors.join('; ') || null };
+}
+
 /**
  * Run the whole post-land tail. Never throws.
  *
@@ -262,7 +279,8 @@ async function stepBaseFastForward({
  * @param {Function} [args.planFastForwardFn]       Test seam.
  * @param {Function} [args.executeFastForwardFn]    Test seam.
  * @param {Function} [args.acquireLockWithWaitFn]   Test seam.
- * @returns {Promise<{ followUps: boolean, statusResync: boolean, refCleanup: boolean, baseFastForward: boolean, details: Record<string, string|null> }>}
+ * @param {Function} [args.purgeStoryTempArtifactsFn] Test seam.
+ * @returns {Promise<{ followUps: boolean, statusResync: boolean, refCleanup: boolean, baseFastForward: boolean, tempPurge: boolean, details: Record<string, string|null> }>}
  */
 export async function runPostLandTail({
   storyId,
@@ -280,6 +298,7 @@ export async function runPostLandTail({
   planFastForwardFn = defaultPlanFastForward,
   executeFastForwardFn = defaultExecuteFastForward,
   acquireLockWithWaitFn = defaultAcquireLockWithWait,
+  purgeStoryTempArtifactsFn = defaultPurgeStoryTempArtifacts,
 }) {
   progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
 
@@ -373,16 +392,27 @@ export async function runPostLandTail({
     if (lock.acquired) lock.release();
   }
 
+  // Story #4794 — the merge is confirmed, so this Story's gate transcripts and
+  // validation evidence are spent. Runs LAST so a purge can never race a step
+  // that still reads them, and outside the checkout lock because it touches
+  // only the temp tree. Its `signals.ndjson` survives by construction.
+  const tempPurge = await step(
+    () => stepTempPurge({ storyId, config, purgeStoryTempArtifactsFn }),
+    { name: 'temp purge', progress },
+  );
+
   const tail = {
     followUps: followUps.ok,
     statusResync: statusResync.ok,
     refCleanup: refCleanup.ok,
     baseFastForward: baseFastForward.ok,
+    tempPurge: tempPurge.ok,
     details: {
       followUps: followUps.detail,
       statusResync: statusResync.detail,
       refCleanup: refCleanup.detail,
       baseFastForward: baseFastForward.detail,
+      tempPurge: tempPurge.detail,
     },
   };
   const degraded = Object.entries(tail)