forgedock 1.43.1 → 1.45.0

package/bin/lean/conformance.mjs

@@ -32,7 +32,7 @@ export const MIN_QUOTE_CHARS = 12;
 /** A contract larger than this cannot be posted whole in one comment (the comment cap is 60k). */
 export const MAX_CONTRACT_CHARS = 40000;
 import { CHECK_ID_RE } from "./postdeploy-check.mjs";
-import { normaliseDecision, deadAnchors } from "./decisions.mjs";
+import { normaliseDecision, deadAnchors, anchorMatches } from "./decisions.mjs";
 const C = OUTCOME_CODES;
 
 /** #4789: folds what a builder retyping a quote changes: unicode punctuation, markdown links/markup, escapes, invisible chars. */
@@ -325,10 +325,14 @@ export function validateContract(c, issueText, { repro = false } = {}) {
 /** forge#4519: a shell pattern as in scripts/hotspots.sh `case` (`*` crosses `/`, `?` one character), anchored. */
 const shellGlobRe = (g) => new RegExp(`^${String(g).replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
 
-const AMEND_KINDS = ["add-deliverable", "add-requirement", ...TRACKED, "amend-requirement", "supersedes", "decision", "substitute-validate"];
+const AMEND_KINDS = ["add-deliverable", "add-requirement", ...TRACKED, "amend-requirement", "supersedes", "decision", "substitute-validate", "out-of-band"];
 const UNRELATED_CI_KIND = "unrelated-ci-failure";
 const GUARD_ID_RE = /^#?\d+$/;
-const AMEND_SLIPS = { "amend-requirement": "defer", limitation: "defer", deferred: "defer", deferral: "defer", "scope-deferral": "defer" };
+const AMEND_SLIPS = { "amend-requirement": "defer", limitation: "defer", deferred: "defer", deferral: "defer", "scope-deferral": "defer", "verification-substitution": "substitute-validate", "out-of-band-verification": "out-of-band" };
+// #5036: annotation-only kinds change no requirement: recorded for the reviewer, never a problem (like UNRELATED_CI_KIND)
+const INFO_KINDS = ["scope-note", "scope", "scope-clarification", "interpretation", "environment", "validation-unavailable"];
+// #5036: deferral-shaped kinds (scope narrowing/reduction, defer-*, deferred-*) are `defer` once they name a requirement
+const DEFER_FAMILY_RE = /^(?:scope-(?:narrowing|reduction)|defer-.+|deferred-.+)$/;
 // #4916: near-synonyms builders emit for the per-guard `supersedes` amendment
 const SUPERSEDES_SYNONYMS = ["supersede-guard", "supersede", "supersedes-guard"];
 
@@ -341,7 +345,8 @@ function normalizeAmendment(a) {
   // #4856: kinds compare case-insensitively with `_` as `-`; only a recognised kind or alias is rewritten, so unknown kinds keep their spelling in the error
   if (typeof n.kind === "string") {
     const k = n.kind.trim().toLowerCase().replace(/_/g, "-");
-    if (AMEND_KINDS.includes(k) || Object.hasOwn(AMEND_SLIPS, k)) n.kind = k;
+    if (AMEND_KINDS.includes(k) || Object.hasOwn(AMEND_SLIPS, k) || INFO_KINDS.includes(k)) n.kind = k;
+    else if (DEFER_FAMILY_RE.test(k) && (!blank(n.requirement) || /^R\d+$/.test(String(n.id ?? "")))) n.kind = "defer";
   }
   if (Object.hasOwn(AMEND_SLIPS, n.kind) && !(n.kind === "amend-requirement" && !blank(n.text))) n.kind = AMEND_SLIPS[n.kind];
   if (SUPERSEDES_SYNONYMS.includes(n.kind)) n.kind = "supersedes";
@@ -368,6 +373,7 @@ function amendmentProblem(a, tag) {
   const kind = a?.kind;
   const need = kind === "add-deliverable" ? "needs a path" : kind === "add-requirement" ? "needs requirement {id, quote}"
     : kind === "supersedes" ? "needs guard: \"#N\" (the guarded issue)" : TRACKED.includes(kind) ? "needs requirement: \"R#\"" : kind === "amend-requirement" ? "needs requirement: \"R#\" and text (the revised wording)"
+      : kind === "substitute-validate" ? "needs validate: \"V#\" and command" : kind === "out-of-band" ? "needs requirement: \"R#\" and evidence (the job or workflow that measures it)"
       : kind === "decision" ? "needs decision {choice, anchors: [paths or globs], symbols?, supersedes?: decision id}" : null;
   const why = need ? `amendment kind '${kind}' ${need}` : `unknown kind '${kind ?? ""}'; valid kinds are ${AMEND_KINDS.join(", ")}`;
   return `unknown or incomplete amendment: ${why}: ${tag}`;
@@ -407,6 +413,7 @@ export function applyAmendments(frozen, amendments, issueText = null, { generate
   for (let { a, raw } of rows) {
     // an unrelated out-of-diff CI failure is not a contract change: informational, never a problem
     if (a?.kind === UNRELATED_CI_KIND) { applied.push({ kind: a.kind, target: String(a.target ?? "unrelated check"), why: String(a.why ?? "").trim() || "unrelated to the diff" }); continue; }
+    if (INFO_KINDS.includes(a?.kind)) { applied.push({ kind: a.kind, target: String(a.target ?? a.requirement ?? a.id ?? "note").slice(0, 60), why: String(a.why ?? a.text ?? a.note ?? "").trim() || "informational" }); continue; }
     const tag = JSON.stringify(raw ?? null).slice(0, 400);
     if (a && blank(a.why) && !blank(defaultWhy)) a = { ...a, why: String(defaultWhy) }; // the engine demanded the change: its reason is the why
     if (blank(a?.why)) { problems.push(`amendment without why: ${tag}`); continue; }
@@ -424,12 +431,20 @@ export function applyAmendments(frozen, amendments, issueText = null, { generate
       // #4857: a runnable equivalent of an unrunnable frozen validate command; same id, same checks as a planned command
       const v = (c.validate ?? []).find((x) => x.id === a.validate);
       if (!v) { problems.push(`substitute-validate names unknown validate ${a.validate}`); continue; }
-      const bad = blank(a.command) ? "no command" : shellSyntaxError(a.command) ? "not valid shell (bash -n)" : noopCommand(a.command) ? "runs no check (true, :, exit 0, echo)" : movingBaseDiff(a.command) ? "diffs against a moving base tip" : tmpdirInputs(a.command).length ? "reads a $TMPDIR file it did not create" : null;
+      const bad = blank(a.command) ? "no command" : substituteShellProblem(a.command) ? "not valid shell (bash -n)" : noopCommand(a.command) ? "runs no check (true, :, exit 0, echo)" : movingBaseDiff(a.command) ? "diffs against a moving base tip" : tmpdirInputs(a.command).length ? "reads a $TMPDIR file it did not create" : null;
       if (bad) { problems.push(`substitute-validate ${a.validate}: ${bad}`); continue; }
       // SEC-11: a second substitute of the same id keeps the frozen command as `from`, so the engine always reruns the original
       v.substituted = { from: v.substituted?.from ?? v.command, why: String(a.why).trim() }; v.command = String(a.command).trim();
       applied.push({ kind: a.kind, target: a.validate, why: String(a.why).trim() });
       continue;
+    } else if (a.kind === "out-of-band" && !blank(a.requirement) && !blank(a.evidence ?? a.job)) {
+      // #5036: the existing out_of_band path for a deliver requirement; evidence names the job that measures it
+      const r = c.requirements.find((x) => x.id === a.requirement);
+      if (!r) { problems.push(`amendment names unknown requirement ${a.requirement}`); continue; }
+      if (r.disposition !== "deliver") { problems.push(`out-of-band ${r.id}: applies only to a deliver requirement`); continue; }
+      r.verify = "out_of_band"; r.evidence = String(a.evidence ?? a.job).trim(); r.amended = true;
+      applied.push({ kind: a.kind, target: r.id, why: String(a.why).trim() });
+      continue;
     } else if (a.kind === "add-requirement" && a.requirement?.id && !blank(a.requirement?.quote)) {
       if (c.requirements.some((r) => r.id === a.requirement.id)) { problems.push(`add-requirement reuses id ${a.requirement.id}`); continue; }
       if (issueText != null && !inIssue(a.requirement.quote, issueText)) { problems.push(`add-requirement ${a.requirement.id}: quote is not verbatim from the issue`); continue; }
@@ -465,18 +480,24 @@ export function applyAmendments(frozen, amendments, issueText = null, { generate
       if (!r) { problems.push(`amendment names unknown requirement ${a.requirement}`); continue; }
       if (!TRACKED.includes(r.disposition)) {
         if (a.bucket != null) r.bucket = a.bucket; // #4724
-        if (a.kind === "post-deploy" && !CHECK_ID_RE.test(String(a.check ?? r.check ?? ""))) { problems.push(`amendment post-deploy ${a.requirement} needs a check id (check)`); continue; }
+        if (a.kind === "post-deploy" && !CHECK_ID_RE.test(String(a.check ?? r.check ?? ""))) { // #5020: no runnable check: a manual or credentialed action is deferred to the orchestrator, never a conformance failure
+          r.disposition = "defer"; r.why = a.why; r.amended = true; r.bucket = String(a.bucket ?? "").startsWith("owner:") ? a.bucket : ORCHESTRATOR_BUCKET; toTrack.push(r); continue;
+        }
         r.disposition = a.kind; r.why = a.why; r.amended = true; r.bucket ??= "post-deploy"; toTrack.push(r); // #4724: an amendment without a bucket defaults to post-deploy
         if (a.kind === "post-deploy") r.check = a.check ?? r.check; // #4626
       }
     } else if (a.kind === "decision") {
       const d = normaliseDecision({ ...a.decision, why: a.decision?.why ?? a.why });
       if (!d) { problems.push(amendmentProblem(a, tag)); continue; }
-      // a file the lane adds and the contract lists as a deliverable is a new file the issue declared: a valid anchor
+      // #5036: any file the lane adds is a valid anchor; one the contract does not list becomes a deliverable
       const listed = new Set(c.deliverables.map((x) => x.path));
-      const added = (Array.isArray(addedPaths) ? addedPaths : []).filter((x) => listed.has(x));
+      const added = Array.isArray(addedPaths) ? addedPaths : [];
       const dead = Array.isArray(baseFiles) ? deadAnchors(d.anchors, [...baseFiles, ...added]) : [];
       if (dead.length) { problems.push(`decision anchor(s) ${dead.join(", ")} match no file on the base; anchor a path that exists there`); continue; }
+      for (const f of added) {
+        if (listed.has(f) || (Array.isArray(baseFiles) && baseFiles.includes(f)) || !d.anchors.some((x) => anchorMatches(x, f))) continue;
+        c.deliverables.push({ id: `A${c.deliverables.length + 1}`, path: f, change: `new file anchoring decision: ${d.choice.slice(0, 80)}`, amended: true }); listed.add(f);
+      }
       if (!blank(a.decision?.supersedes)) c.preserve = (c.preserve ?? []).filter((p) => p.decision !== a.decision.supersedes && p.id !== a.decision.supersedes);
       decisions.push(a.decision?.supersedes ? { ...d, supersedes: String(a.decision.supersedes) } : d);
       applied.push({ kind: a.kind, target: d.choice.slice(0, 60), why: String(a.why).trim() });
@@ -489,6 +510,7 @@ export function applyAmendments(frozen, amendments, issueText = null, { generate
 
 const PY_MISSING_RE = /ModuleNotFoundError: No module named '([^']+)'|ImportError: No module named '?([\w.]+)'?/;
 const NODE_MISSING_RE = /Cannot find (?:module|package) '([^']+)'/;
+const POETRY_NOT_FOUND_RE = /^\s*Command not found: (\S+)/m;
 const CMD_NOT_FOUND_RE = /([^\s:'"`]+): command not found/, SH_NOT_FOUND_RE = /([^\s:'"`]+): not found\b/;
 /** #4857: why a command is not valid bash (`bash -n`), or null when it parses (or bash is unavailable). Catches prose left on a command. */
 export function shellSyntaxError(command) {
@@ -496,6 +518,49 @@ export function shellSyntaxError(command) {
   if (r.error || r.status === 0 || r.status == null) return null;
   return String(r.stderr || "syntax error").trim().split("\n")[0].replace(/^bash: (?:line \d+: )?/, "").slice(0, 160);
 }
+/** #5020: like shellSyntaxError, but fails closed: when bash cannot run the check the command is not shown to parse. */
+export function substituteShellProblem(command) {
+  const r = spawnSync("bash", ["-n", "-c", String(command ?? "")], { encoding: "utf8", timeout: 5000 });
+  if (r.error || r.status == null) return "bash -n could not run, so the command is unverified";
+  return r.status === 0 ? null : shellSyntaxError(command) ?? "syntax error";
+}
+export const ORCHESTRATOR_BUCKET = "owner:orchestrator";
+/**
+ * #5020: a post-deploy requirement that names no check id (a manual or production-credential action) becomes a `defer` with an
+ * `owner:orchestrator` bucket, the legal disposition the engine files as a follow-up. Pure; returns {contract, converted[]}.
+ */
+export function deferChecklessPostDeploy(contract) {
+  const converted = [];
+  const requirements = (Array.isArray(contract?.requirements) ? contract.requirements : []).map((r) => {
+    if (r?.disposition !== "post-deploy" || CHECK_ID_RE.test(String(r?.check ?? ""))) return r;
+    converted.push(r.id);
+    return { ...r, disposition: "defer", bucket: String(r.bucket ?? "").startsWith("owner:") ? r.bucket : ORCHESTRATOR_BUCKET, why: r.why ?? "post-deploy action with no registered check: deferred to the orchestrator" };
+  });
+  return { contract: converted.length ? { ...contract, requirements } : contract, converted };
+}
+/**
+ * #5020: apply forge.yaml `validate.recipes` ([{match, replace}], match a regex source) to each validate command and the
+ * repro_test command at freeze, first matching recipe per command. Pure; returns {contract, applied[{id, from, to}]}.
+ */
+export function applyValidateRecipes(contract, recipes) {
+  const list = (Array.isArray(recipes) ? recipes : []).map((r) => { try { return typeof r?.replace === "string" && r?.match ? { re: new RegExp(String(r.match)), replace: r.replace } : null; } catch { return null; } }).filter(Boolean);
+  if (!list.length || !contract || typeof contract !== "object") return { contract, applied: [] };
+  const applied = [];
+  const rewrite = (id, cmd) => {
+    if (typeof cmd !== "string") return cmd;
+    for (const { re, replace } of list) if (re.test(cmd)) { const to = cmd.replace(re, replace); if (to !== cmd) applied.push({ id, from: cmd, to }); return to; }
+    return cmd;
+  };
+  const out = { ...contract };
+  if (Array.isArray(contract.validate)) out.validate = contract.validate.map((v) => (v && typeof v === "object" ? { ...v, command: rewrite(v.id, v.command) } : v));
+  const t = contract.repro_test;
+  if (t && typeof t === "object" && !Array.isArray(t)) out.repro_test = { ...t, command: rewrite("repro_test", t.command) };
+  return { contract: applied.length ? out : contract, applied };
+}
+/** #5020: the env.* verdict for a repro command that failed on head because a tool is missing (e.g. an uninstalled Poetry env); null when the failure is the test's own. */
+export function reproEnvMiss(run, opts) {
+  return run && run.rc !== 0 && run.rc !== 124 ? missingTool(run, opts) : null;
+}
 const NOOP_SEGMENT_RE = /^(?:true|false|:|exit(?:\s+\d+)?|echo(?:\s.*)?|printf(?:\s.*)?|sleep(?:\s+[\d.]+)?|test\s+-?\w+|\[\s+-?\w+\s+\]|fi|done|node\s+-e\s+['"]?[\d;\s]*['"]?|python3?\s+-c\s+['"]?(?:pass|0|None)?['"]?)$/;
 const KEYWORD_RE = /^(if|then|else|elif|do|while|until)(?:\s+|$)/;
 const CONST_FALSE_RE = /^(?:false|\[\s+0\s+=\s+1\s+\]|\[\s+1\s+=\s+0\s+\]|test\s+0\s+=\s+1|test\s+-n\s+(?:""|'')|\[\s+-n\s+(?:""|'')\s+\])$/;
@@ -537,14 +602,35 @@ export function substituteVerdict(run, { repoHas = () => false, command = "" } =
  * a whitespace token equal to the path, or a directory token above it. A builder that removes the target of its frozen
  * validate makes the engine's rerun read "unrunnable", so the substitute is judged on the diff instead.
  */
-export function removedNamedPaths(command, removed = []) {
-  const toks = String(command ?? "").split(/\s+/).map((t) => t.replace(/^['"`(]+|['"`);]+$/g, "").replace(/^\.\//, "").replace(/\/+$/, "")).filter((t) => t && t !== ".");
-  return removed.filter((p) => toks.some((t) => p === t || p.startsWith(`${t}/`)));
+const TEST_FILE_RE = /\.(?:test|spec)\.[a-z0-9]+$|^test_[^/]+\.[a-z0-9]+$|_test\.[a-z0-9]+$|Tests?\.(?:java|kt|kts|cs|php|scala|swift)$|_spec\.rb$|^tests\.rs$|^conftest\.py$|\.bats$/;
+/** #5003: a runnable test FILE (by basename), unlike `isTestPath`, which also matches fixtures under tests/. */
+const isTestFile = (p) => TEST_FILE_RE.test(String(p).split("/").pop());
+/**
+ * #4990 SEC-13: the paths of `removed` (deleted, or the old side of a rename, in the diff) that a frozen command names.
+ * #5003: a token is stripped of quotes, a `--flag=` prefix and a pytest `::node` suffix; a glob is expanded against
+ * `baseFiles`; an exact path matches itself; a directory or bare-word token matches only a removed test file under it.
+ */
+export function removedNamedPaths(command, removed = [], baseFiles = []) {
+  const toks = String(command ?? "").split(/\s+/).map((t) => t.replace(/^['"`(]+|['"`);]+$/g, "").replace(/^-[^=\/]*=/, "").replace(/::.*$/, "").replace(/^['"`]+|['"`]+$/g, "").replace(/^\.\//, "").replace(/\/+$/, "")).filter((t) => t && t !== ".");
+  const files = new Set(baseFiles);
+  return removed.filter((p) => toks.some((t) => {
+    if (/[*?]/.test(t)) return globRe(t).test(p) && (files.size === 0 || files.has(p));
+    return p === t || (p.startsWith(`${t}/`) && isTestFile(p));
+  }));
 }
-/** #4990: paths the lane's diff deletes or renames away from (the old side), per `git diff --name-status -M`. */
+/** #4990: paths the lane's diff deletes or renames away from (the old side). #5003: `-z` (unquoted), null on a git error (fail closed). */
 export async function removedPathsOf(git, base) {
-  const rows = String(await git(["diff", "--name-status", "-M", `${base}...HEAD`]).catch(() => "")).split("\n").map((l) => l.split("\t"));
-  return rows.filter((r) => /^[DR]/.test(r[0] ?? "") && r[1]).map((r) => r[1]);
+  let out;
+  try { out = String(await git(["diff", "--name-status", "-z", "-M", `${base}...HEAD`])); } catch { return null; }
+  const f = out.split("\0"), gone = [];
+  for (let i = 0; i < f.length; i++) {
+    const st = f[i];
+    if (!/^[A-Z]/.test(st)) continue;
+    const two = /^[RC]/.test(st);
+    if (/^[DR]/.test(st) && f[i + 1]) gone.push(f[i + 1]);
+    i += two ? 2 : 1;
+  }
+  return gone;
 }
 const UNRUNNABLE_RE = /no tests ran|collected 0 items|no tests found|could not find (?:the )?pyproject|poetry could not find|syntax error near|unexpected EOF while looking/i;
 /** #4857: a failed rerun that died before any test ran (no tests selected, no project at the cwd, invalid shell): a defect of the frozen command. */
@@ -605,6 +691,8 @@ export function missingTool({ rc, output } = {}, { repoHas = () => false, comman
     const tool = scoped ? spec.split("/").slice(0, 2).join("/") : spec;
     return local(tool) || (scoped && !tool.includes("/")) ? null : { tool, kind: "node-module" };
   }
+  const po = POETRY_NOT_FOUND_RE.exec(out)?.[1]; // #5020: `poetry run pytest` in an env that was never installed
+  if (po) return local(po) ? null : { tool: po, kind: "command" };
   const cmd = CMD_NOT_FOUND_RE.exec(out)?.[1] ?? (rc === 127 ? SH_NOT_FOUND_RE.exec(out)?.[1] ?? String(command).trim().split(/\s+/)[0] : null);
   if (!cmd || cmd.includes("/") || local(cmd)) return null;
   return { tool: cmd, kind: "command" };
@@ -632,7 +720,7 @@ export function repoTracks(paths) {
  * `ciCovered` (#4527): the validate ids accepted only because the head is CI-verified (no local result, or a missing host
  * tool), for the trajectory; always an array.
  */
-export function precheck({ contract, result, changedFiles, ignore = [], ciVerified = false, hotspots = null, repro = null, validateRuns = null, repoHas = () => false, frozen = null, checkIds = null, guardFailures = null, newOffKeys = null, substitutedRuns = null, removedPaths = [] }) {
+export function precheck({ contract, result, changedFiles, ignore = [], ciVerified = false, hotspots = null, repro = null, validateRuns = null, repoHas = () => false, frozen = null, checkIds = null, guardFailures = null, newOffKeys = null, substitutedRuns = null, removedPaths = [], baseFiles = [] }) {
   const failures = [], superseded = [], ciCovered = [];
   // #4626: a post-deploy check id must be on the default branch or added by this PR (`checkIds`: ids of both checks files; null = not resolved)
   if (checkIds) for (const r of contract.requirements ?? []) {
@@ -648,7 +736,10 @@ export function precheck({ contract, result, changedFiles, ignore = [], ciVerifi
   for (const v of contract.validate ?? []) {
     // #4979 SPEC-2: a substitute counts only when the frozen command it replaced cannot run (or passes); checked first, never CI-covered
     if (v.substituted) {
-      const gone = removedNamedPaths(v.substituted.from, removedPaths);
+      const shellBad = substituteShellProblem(v.command); // #5020: re-checked before the substitute is used
+      if (shellBad) { failures.push({ code: C.CONTRACT_INVALID_COMMAND, kind: "validate_command_invalid", detail: `validate ${v.id} substitute \`${v.command}\` is not valid shell (bash -n: ${shellBad})` }); continue; }
+      if (removedPaths === null) { failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, kind: "substitute_unverified", detail: `validate ${v.id} substituted \`${v.command}\` for the frozen \`${v.substituted.from}\`, but the engine could not read the diff's removed paths to show the frozen command's target survives` }); continue; }
+      const gone = removedNamedPaths(v.substituted.from, removedPaths, baseFiles);
       if (gone.length) { failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, kind: "substitute_removed_path", detail: `validate ${v.id} substituted \`${v.command}\` for the frozen \`${v.substituted.from}\`, but the diff removes ${gone.map((x) => `\`${x}\``).join(", ")} that the frozen command names: a substitute may not replace a check by deleting its target` }); continue; }
       const verdict = substituteVerdict(substitutedRuns?.[v.id], { repoHas, command: v.substituted.from });
       const from = `validate ${v.id} substituted \`${v.command}\` for the frozen \`${v.substituted.from}\``;

package/bin/lean/conformance.test.mjs

@@ -3,7 +3,7 @@
 import { readFileSync } from "node:fs";
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { removedNamedPaths, removedPathsOf, shellSyntaxError, unrunnableValidate, noopCommand, substituteVerdict, describesUnrunnableCommand, vitestQuietFlag, normalizeRunnerCommand, cliUsageError, validateContract, applyAmendments, precheck, hotspotGrowth, reproFailures, isBugIssue, parseReview, checkCompleteness, decide, closePlan, isInvestigation, formatShadowSummary, followupItems, inIssue, isTestPath, normalizeEvidencePath, mergeReviewRows, reviewSkeleton, missingIds, resolveEvidencePath, movingBaseDiff, scopeText, evidencePathLine, evidencePathOnly, explainFailures, resolveForgedockPaths, missingTool, repoTracks, tmpdirInputs, isScopeCheck, isPureScopeCheck, dropScopeValidates, tagOutOfBand, outOfBandRequirements, isOutOfBand, followupMap, VERIFY_MODES, OUT_OF_BAND_RE, FOLLOWUP_CLASSES, followupClass, BUCKETS, bucketKind, bucketProblems, bucketTally, isE2eCommand, e2eVerified, impliedDocDeliverables } from "./conformance.mjs";
+import { removedNamedPaths, removedPathsOf, shellSyntaxError, unrunnableValidate, noopCommand, substituteVerdict, describesUnrunnableCommand, vitestQuietFlag, normalizeRunnerCommand, cliUsageError, validateContract, applyAmendments, precheck, hotspotGrowth, reproFailures, isBugIssue, parseReview, checkCompleteness, decide, closePlan, isInvestigation, formatShadowSummary, followupItems, inIssue, isTestPath, normalizeEvidencePath, mergeReviewRows, reviewSkeleton, missingIds, resolveEvidencePath, movingBaseDiff, scopeText, evidencePathLine, evidencePathOnly, explainFailures, resolveForgedockPaths, missingTool, repoTracks, tmpdirInputs, isScopeCheck, isPureScopeCheck, dropScopeValidates, tagOutOfBand, outOfBandRequirements, isOutOfBand, followupMap, VERIFY_MODES, OUT_OF_BAND_RE, FOLLOWUP_CLASSES, followupClass, BUCKETS, bucketKind, bucketProblems, bucketTally, isE2eCommand, e2eVerified, impliedDocDeliverables, applyValidateRecipes, deferChecklessPostDeploy, substituteShellProblem, reproEnvMiss, ORCHESTRATOR_BUCKET } from "./conformance.mjs";
 
 const ISSUE = "## Requirements\n1. The scrape route must release the spend reservation on 429.\n2. The search route must release the spend reservation on 429.\n\n- [ ] Billing pricing is unchanged.";
 const Q1 = "The scrape route must release the spend reservation on 429.";
@@ -78,8 +78,8 @@ describe("amendment kind aliases (#4856)", () => {
       assert.deepEqual(a.toTrack.map((r) => r.id), ["R1"], kind);
     }
   });
-  it("scope-note and other unlisted kinds stay unknown and list the valid kinds", () => {
-    for (const kind of ["scope-note", "Scope_Note", "flaky-note"]) {
+  it("unlisted kinds stay unknown and list the valid kinds (scope-note is informational since #5036)", () => {
+    for (const kind of ["scope-creep", "Scope_Creep", "flaky-note"]) {
       assert.match(applyAmendments(C, [{ kind, requirement: "R1", why: "w" }]).problems[0], new RegExp(`unknown kind '${kind}'; valid kinds are add-deliverable`));
     }
   });
@@ -94,9 +94,9 @@ describe("#4655 multi-requirement amendment references", () => {
       assert.deepEqual(a.applied.map((x) => x.target), ["R1", "R2"], requirement);
     }
   });
-  it("an unknown id inside a list is still a problem; scope-note stays an unknown kind", () => {
+  it("an unknown id inside a list is still a problem; an unknown kind with a requirement is still unknown", () => {
     assert.match(applyAmendments(C, [{ kind: "defer", requirement: "R1/R9", why: "w" }]).problems[0], /unknown requirement R9/);
-    assert.match(applyAmendments(C, [{ kind: "scope-note", requirement: "R1", why: "w" }]).problems[0], /unknown kind 'scope-note'; valid kinds are/);
+    assert.match(applyAmendments(C, [{ kind: "scope-creep", requirement: "R1", why: "w" }]).problems[0], /unknown kind 'scope-creep'; valid kinds are/);
   });
   it("an unrelated-ci-failure amendment (kind or type) is an informational no-op; other unknown kinds still fail", () => {
     for (const a of [{ kind: "unrelated-ci-failure", target: "core rate-limit test", why: "diff touches no core file" }, { type: "unrelated-ci-failure", target: "t", why: "w" }]) {
@@ -232,9 +232,25 @@ describe("precheck (deterministic, no reviewer)", () => {
     assert.match(gone.failures[0].detail, /test\/leak\.test\.js/);
     const env = precheck({ contract: sub, result: res, changedFiles: files, substitutedRuns: { V1: { rc: 1, output: "Unknown option `-q`" } }, removedPaths: ["docs/other.md"] });
     assert.deepEqual(env.failures, [], "intact named files: env-unrunnable substitute stands");
-    assert.deepEqual(removedNamedPaths("node --test ./test/a.js 'b/c.js' tests/", ["test/a.js", "b/c.js", "tests/x.js", "z.js"]), ["test/a.js", "b/c.js", "tests/x.js"]);
+    assert.deepEqual(removedNamedPaths("node --test ./test/a.js 'b/c.js' z.js", ["test/a.js", "b/c.js", "tests/x.js", "z.js"]), ["test/a.js", "b/c.js", "z.js"]);
     assert.deepEqual(removedNamedPaths("pytest -k leak", ["leak.py"]), []);
-    assert.deepEqual(await removedPathsOf(async () => "D\ta.js\nR100\told.js\tnew.js\nM\tm.js\nA\tn.js", "b"), ["a.js", "old.js"]);
+    assert.deepEqual(await removedPathsOf(async () => "D\0a.js\0R100\0old.js\0new.js\0M\0m.js\0A\0n.js\0", "b"), ["a.js", "old.js"]);
+  });
+  it("#5003 removed-path matching: node ids, globs, flag paths, directory tokens, -z, fail closed", async () => {
+    assert.deepEqual(removedNamedPaths("pytest tests/a.py::test_x", ["tests/a.py"]), ["tests/a.py"]);
+    assert.deepEqual(removedNamedPaths("pytest --junit=tests/a.py", ["tests/a.py"]), ["tests/a.py"]);
+    assert.deepEqual(removedNamedPaths('pytest "tests/a.py::T::t"', ["tests/a.py"]), ["tests/a.py"]);
+    const base = ["tests/test_a.py", "tests/test_b.py", "tests/fixtures/d.json", "src/x.py"];
+    assert.deepEqual(removedNamedPaths("pytest tests/test_*.py", ["tests/test_a.py", "tests/fixtures/d.json", "src/x.py"], base), ["tests/test_a.py"]);
+    assert.deepEqual(removedNamedPaths("pytest tests/", ["tests/fixtures/d.json"]), []);
+    assert.deepEqual(removedNamedPaths("pytest tests/", ["tests/test_a.py"]), ["tests/test_a.py"]);
+    assert.deepEqual(removedNamedPaths("npm test", ["test/fixtures/d.json"]), []);
+    assert.deepEqual(removedNamedPaths("npm test", ["test/a.test.js"]), ["test/a.test.js"]);
+    assert.deepEqual(await removedPathsOf(async (a) => (a.includes("-z") ? "D\0tests/é.py\0" : '"tests/\\303\\251.py"'), "b"), ["tests/é.py"]);
+    assert.equal(await removedPathsOf(async () => { throw new Error("git"); }, "b"), null);
+    const sub = applyAmendments({ ...C, validate: [{ id: "V1", command: "node --test test/leak.test.js" }] }, [{ kind: "substitute-validate", validate: "V1", command: "node --test test/weak.test.js", why: "w" }]).contract;
+    const res = { requirements: [{ id: "R1", status: "implemented" }, { id: "R2", status: "implemented" }], validation: [{ id: "V1", exit: 0 }] };
+    assert.deepEqual(precheck({ contract: sub, result: res, changedFiles: files, substitutedRuns: { V1: { rc: 1, output: "no tests found" } }, removedPaths: null }).failures.map((f) => f.kind), ["substitute_unverified"]);
   });
   it("#4857 describesUnrunnableCommand reads a blocked summary", () => {
     assert.ok(describesUnrunnableCommand("V2 is unrunnable: poetry found no pyproject at the repo root"));
@@ -894,9 +910,10 @@ describe("post-deploy check ids (#4626)", () => {
     assert.ok(validateContract(pd({ check: "Bad Id" }), ISSUE).problems.some((p) => /post-deploy needs a check id/.test(p)));
     assert.ok(!validateContract(pd({ check: "login-smoke" }), ISSUE).problems.some((p) => /check id/.test(p)));
   });
-  it("applyAmendments: a post-deploy amendment needs a check id", () => {
+  it("applyAmendments: a post-deploy amendment without a check id is deferred to the orchestrator (#5020)", () => {
     const bad = applyAmendments(C, [{ kind: "post-deploy", requirement: "R1", why: "w" }], ISSUE);
-    assert.ok(bad.problems.some((p) => /needs a check id/.test(p)));
+    assert.deepEqual(bad.problems, []);
+    assert.equal(bad.contract.requirements[0].disposition, "defer");
     const ok = applyAmendments(C, [{ kind: "post-deploy", requirement: "R1", why: "w", check: "login-smoke" }], ISSUE);
     assert.equal(ok.contract.requirements[0].check, "login-smoke");
   });
@@ -1005,10 +1022,12 @@ describe("decision amendments (#4695)", () => {
     assert.match(a.problems[0], /match no file on the base/);
     assert.equal(a.decisions.length, 0);
   });
-  it("an anchor on a lane-added file the contract lists as a deliverable conforms; an unlisted added file does not", () => {
-    const withNew = { ...withRow, deliverables: [...withRow.deliverables, { id: "D3", path: "scripts/seed.py" }] };
-    const go = (added) => applyAmendments(withNew, [{ kind: "decision", why: "w", decision: { choice: "use B", anchors: ["scripts/seed.py"] } }], null, { baseFiles: ["src/scrape.js"], addedPaths: added });
-    assert.deepEqual(go(["scripts/seed.py"]).problems, []);
+  it("an anchor on a lane-added file conforms and the unlisted file becomes a deliverable; an anchor matching neither base nor an added file is rejected", () => {
+    const go = (added, anchor = "scripts/seed.py") => applyAmendments(withRow, [{ kind: "decision", why: "w", decision: { choice: "use B", anchors: [anchor] } }], null, { baseFiles: ["src/scrape.js"], addedPaths: added });
+    const ok = go(["scripts/seed.py"]);
+    assert.deepEqual(ok.problems, []);
+    assert.ok(ok.contract.deliverables.some((d) => d.path === "scripts/seed.py" && d.amended));
+    assert.equal(ok.contract.deliverables.filter((d) => d.path === "scripts/seed.py").length, 1);
     assert.match(go(["scripts/other.py"]).problems[0], /match no file on the base/);
   });
   it("a blank-why amendment takes the engine's defaultWhy; without one it is still rejected", () => {
@@ -1154,3 +1173,97 @@ describe("mutation check (#4913)", () => {
     assert.equal(g("status", "--porcelain").trim(), "");
   });
 });
+
+describe("builder amendment slips (#5036)", () => {
+  it("deferral-shaped kinds naming a requirement apply as a tracked defer", () => {
+    for (const kind of ["scope_narrowing", "scope_reduction", "defer-verification", "deferred_measurement", "Scope-Narrowing"]) {
+      const a = applyAmendments(C, [{ kind, requirement: "R1", why: "w" }]);
+      assert.deepEqual(a.problems, [], kind);
+      assert.equal(a.contract.requirements.find((r) => r.id === "R1").disposition, "defer", kind);
+      assert.deepEqual(a.toTrack.map((r) => r.id), ["R1"], kind);
+    }
+    assert.match(applyAmendments(C, [{ kind: "scope_narrowing", why: "w" }]).problems[0], /unknown kind 'scope_narrowing'; valid kinds are/);
+  });
+  it("verification_substitution applies as substitute-validate with the same checks", () => {
+    const base = { requirements: [], validate: [{ id: "V2", command: "poetry run pytest" }] };
+    const ok = applyAmendments(base, [{ kind: "verification_substitution", validate: "V2", command: "node --test t.mjs", why: "no poetry" }]);
+    assert.deepEqual(ok.problems, []);
+    assert.equal(ok.contract.validate[0].command, "node --test t.mjs");
+    assert.equal(ok.contract.validate[0].substituted.from, "poetry run pytest");
+    for (const command of ["echo (oops", "true", "git diff origin/main"]) {
+      assert.equal(applyAmendments(base, [{ kind: "verification_substitution", validate: "V2", command, why: "w" }]).problems.length, 1, command);
+    }
+    assert.match(applyAmendments(base, [{ kind: "verification_substitution", why: "w" }]).problems[0], /needs validate/);
+  });
+  it("out_of_band_verification marks a deliver requirement out_of_band with its evidence", () => {
+    const ok = applyAmendments(C, [{ kind: "out_of_band_verification", requirement: "R1", evidence: ".github/workflows/perf.yml", why: "field metric" }]);
+    assert.deepEqual(ok.problems, []);
+    const r = ok.contract.requirements.find((x) => x.id === "R1");
+    assert.equal(r.verify, "out_of_band"); assert.equal(r.evidence, ".github/workflows/perf.yml");
+    assert.equal(applyAmendments(C, [{ kind: "out_of_band_verification", requirement: "R1", why: "w" }]).problems.length, 1);
+  });
+  it("annotation-only kinds are informational: recorded, no problem, no contract change", () => {
+    for (const kind of ["scope-note", "scope_clarification", "interpretation", "environment", "scope", "validation_unavailable"]) {
+      const a = applyAmendments(C, [{ kind, note: "n" }, { kind, why: "w" }]);
+      assert.deepEqual(a.problems, [], kind);
+      assert.deepEqual(a.contract, C, kind);
+      assert.equal(a.applied.length, 2, kind);
+    }
+  });
+  it("a truly unknown kind is still rejected with the valid kinds", () => {
+    assert.match(applyAmendments(C, [{ kind: "flaky-note", why: "w" }]).problems[0], /unknown kind 'flaky-note'; valid kinds are .*substitute-validate/);
+  });
+});
+
+describe("#5020 freeze-time environment defects", () => {
+  const base = { requirements: [{ id: "R1", quote: "q", disposition: "deliver" }], validate: [{ id: "V1", command: "cd services/api && poetry run pytest tests/x.py" }, { id: "V2", command: "node --test a.test.mjs" }], repro_test: { path: "t.py", id: "t", command: "cd services/api && poetry run pytest t.py" } };
+  const recipes = [{ match: "poetry run pytest", replace: "uv run --with-requirements r.txt pytest" }];
+
+  it("applyValidateRecipes rewrites matching validate and repro commands and leaves the rest", () => {
+    const { contract, applied } = applyValidateRecipes(base, recipes);
+    assert.equal(contract.validate[0].command, "cd services/api && uv run --with-requirements r.txt pytest tests/x.py");
+    assert.equal(contract.validate[1].command, "node --test a.test.mjs");
+    assert.match(contract.repro_test.command, /uv run --with-requirements r\.txt pytest t\.py/);
+    assert.deepEqual(applied.map((a) => a.id), ["V1", "repro_test"]);
+    assert.equal(base.validate[0].command.includes("poetry"), true, "input is not mutated");
+  });
+  it("applyValidateRecipes ignores no recipes and invalid regexes", () => {
+    assert.equal(applyValidateRecipes(base, null).contract, base);
+    assert.equal(applyValidateRecipes(base, [{ match: "(", replace: "x" }]).applied.length, 0);
+  });
+  it("Poetry's missing-env output is env.tool_missing material, and a repro head that dies on it is an env miss", () => {
+    const run = { rc: 1, output: "Creating virtualenv api-py3.12\n\nCommand not found: pytest\n" };
+    assert.deepEqual(missingTool(run), { tool: "pytest", kind: "command" });
+    assert.deepEqual(reproEnvMiss(run), { tool: "pytest", kind: "command" });
+    assert.equal(reproEnvMiss({ rc: 1, output: "1 failed" }), null);
+    // release review BUG-1: a module the repo tracks is a real failure of the change, not an env miss
+    const mod = { rc: 1, output: "ModuleNotFoundError: No module named 'mypkg'" };
+    assert.deepEqual(reproEnvMiss(mod, { command: "pytest t.py" }), { tool: "mypkg", kind: "python-module" });
+    assert.equal(reproEnvMiss(mod, { command: "pytest t.py", repoHas: repoTracks(["src/mypkg/__init__.py"]) }), null);
+    assert.equal(reproEnvMiss({ rc: 0, output: "" }), null);
+  });
+  it("a post-deploy requirement with no check id is deferred to the orchestrator; one with a check is untouched", () => {
+    const c = { requirements: [{ id: "R1", quote: "q", disposition: "post-deploy", why: "needs prod creds" }, { id: "R2", quote: "q", disposition: "post-deploy", check: "login-smoke", why: "w" }] };
+    const { contract, converted } = deferChecklessPostDeploy(c);
+    assert.deepEqual(converted, ["R1"]);
+    assert.equal(contract.requirements[0].disposition, "defer");
+    assert.equal(contract.requirements[0].bucket, ORCHESTRATOR_BUCKET);
+    assert.equal(contract.requirements[1].disposition, "post-deploy");
+    assert.deepEqual(bucketProblems(contract.requirements[0]), []);
+  });
+  it("a post-deploy amendment with no check becomes a tracked defer instead of a problem", () => {
+    const c = { requirements: [{ id: "R1", quote: "q", disposition: "deliver" }], deliverables: [], validate: [] };
+    const r = applyAmendments(c, [{ kind: "post-deploy", requirement: "R1", why: "manual prod action" }], "q");
+    assert.deepEqual(r.problems, []);
+    assert.equal(r.contract.requirements[0].disposition, "defer");
+    assert.equal(r.contract.requirements[0].bucket, ORCHESTRATOR_BUCKET);
+  });
+  it("a substitute-validate that is not valid shell is rejected", () => {
+    assert.match(substituteShellProblem("pytest tests/ && ("), /./);
+    assert.equal(substituteShellProblem("pytest tests/"), null);
+    const c = { requirements: [{ id: "R1", quote: "q", disposition: "deliver" }], deliverables: [], validate: [{ id: "V1", command: "poetry run pytest" }] };
+    const r = applyAmendments(c, [{ kind: "substitute-validate", validate: "V1", command: "uv run pytest tests/ && (", why: "poetry env missing" }], "q");
+    assert.ok(r.problems.some((p) => /not valid shell/.test(p)));
+    assert.equal(r.contract.validate[0].command, "poetry run pytest");
+  });
+});

package/bin/lean/decision-engine.mjs

@@ -10,7 +10,7 @@
  * analysis attached, never a guess. Shadow mode (the default) posts `FORGE:DECISION (shadow)` and keeps the label; live mode
  * records the decision, clears needs-human and requeues. A veto (`forge:decision-veto` label, or a reply within
  * `veto_hours`) reverts it; a reversal rate above `reversal_max` forces shadow. Never throws: an error is an `error` row.
- * The issue-watch stage (#4765) calls `settle` once per escalation (key: the escalation comment id).
+ * Not yet called in production: the issue-watch stage (#4765) is meant to call `settle` once per escalation (key: the escalation comment id).
  */
 import { parseForgeYaml } from "../forge-utils.mjs";
 import { foldDecisions, recordDecisions as recordToRegister } from "./decisions.mjs";

package/bin/lean/decision-engine.test.mjs

@@ -157,3 +157,14 @@ test("#4766 tally, telemetry mapping and the batch report 'decided' section", ()
   assert.match(lines.join("\n"), /decided .*\n- #7: use option A/);
   assert.deepEqual(formatOutcomeLists([{ issue: 7, outcome: "merged" }]), []);
 });
+
+test("#4826 docs say 'not yet wired' exactly while no production module calls settle", async () => {
+  const { readFileSync, readdirSync } = await import("node:fs");
+  const dir = new URL(".", import.meta.url);
+  const callers = readdirSync(dir).filter((f) => f.endsWith(".mjs") && !f.endsWith(".test.mjs") && f !== "decision-engine.mjs")
+    .filter((f) => /\b(settle|revertVeto)\b[^;]*from "\.\/decision-engine\.mjs"/.test(readFileSync(new URL(f, dir), "utf8")));
+  const wired = callers.length > 0;
+  for (const p of ["../../docs/DECISIONS.md", "../../docs/CONFIG.md"]) {
+    assert.equal(/not yet wired/i.test(readFileSync(new URL(p, import.meta.url), "utf8")), !wired, `${p}: banner must match wiring state (${callers.join(",") || "no callers"})`);
+  }
+});

package/bin/lean/execution.mjs

@@ -562,15 +562,18 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
     for (;;) {
       try { const v = await fn(); st.waited = 0; st.tries = 0; return v; } catch (e) {
         if (!isTransportError(e)) throw e;
-        if (st.waited >= unreachableWindowMs) throw Object.assign(new Error(`unreachable for ${Math.round(st.waited / 1000)}s: ${errText(e)}`), { unreachable: true });
+        // release review BUG-6: a 401 that outlasts the window is an auth failure (capped sandbox.auth), not an uncapped unreachable pool
+        if (st.waited >= unreachableWindowMs) throw Object.assign(new Error(`unreachable for ${Math.round(st.waited / 1000)}s: ${errText(e)}`), { unreachable: true, ...(e?.status === 401 ? { auth: true, hop: e.hop } : {}) });
         const d = Math.min(pollMs * 2 ** Math.min(st.tries++, 10), 30000, Math.max(1, unreachableWindowMs - st.waited));
         st.waited += d;
         await sleep(d);
       }
     }
   };
-  const unreachable = (h, e) => ({ terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_UNREACHABLE, retryInSeconds: 60,
-    detail: `sandbox ${h.id} ${errText(e)}; kept for adopt on resume` });
+  const unreachable = (h, e) => (e?.auth
+    ? { terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_AUTH, retryInSeconds: 300, detail: `sandbox ${h.id} kept answering 401 (${e.hop === "agent" ? "the pool agent refused the router" : "check the pool token"}): ${errText(e)}; kept for adopt on resume` }
+    : { terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_UNREACHABLE, retryInSeconds: 60,
+      detail: `sandbox ${h.id} ${errText(e)}; kept for adopt on resume` });
   const tailOf = async (h) => { try { return typeof logTail === "function" ? String(await logTail(h) ?? "") : ""; } catch { return ""; } };
   const settleClone = (r, id) => (r?.terminalReason === "engine-error" && r.code === undefined && isCloneFailure(r.detail) ? cloneDeferred(id, errLine(r.detail)) : r);
   const wait = async (h, g = guard({ waited: 0, tries: 0 })) => {
@@ -590,7 +593,7 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
   // A start failure repeats on a relaunch: typed, never engine-error (#4254). Retryable (capacity) defers with backoff.
   // #4685: a refused or missing credential defers with its own code (a fixed token is picked up on the retry), never needs-human.
   const startFailed = (id, e) => ([401, 403].includes(e?.status)
-    ? { terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_AUTH, retryInSeconds: 300, detail: `sandbox ${id} could not start (auth): ${errText(e)}; check the pool token (COMPUTESHARE_TOKEN or ~/.config/computeshare/forgedock.token)` }
+    ? { terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_AUTH, retryInSeconds: 300, detail: `sandbox ${id} could not start (auth): ${errText(e)}; ${e?.hop === "agent" ? "the pool agent refused the router (re-enroll or fix the agent token)" : "check the pool token (COMPUTESHARE_TOKEN or ~/.config/computeshare/forgedock.token)"}` }
     : e?.retryable === true
     ? { terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_CAPACITY, detail: `sandbox ${id} could not start (capacity): ${errText(e)}`, ...(Number(e.retryInSeconds) > 0 ? { retryInSeconds: Number(e.retryInSeconds) } : {}) }
     : isCloneFailure(errText(e)) ? cloneDeferred(id, errText(e))

package/bin/lean/execution.test.mjs

@@ -116,6 +116,27 @@ describe("providerLanes: an unreachable provider is retried, then deferred witho
     assert.deepEqual(ledgerFor(7).entries("sandbox").map((e) => e.value), ["fake-7"]);
   });
 
+  it("#5053 a 401 on status/result of a launched sandbox is retried, then ends sandbox.auth (capped), never engine-error", async () => {
+    const e401 = () => Object.assign(new Error("sandbox status: HTTP 401 (agent a1 auth)"), { status: 401, hop: "agent", transient: true });
+    const mk = (failPolls) => { const prov = flaky(0); let polls = 0; prov.start = async () => ({ provider: "fake", id: "fake-7", issue: 7 });
+      prov.status = async (h) => { if (polls++ < failPolls) throw e401(); return prov.live.has(h.issue) ? "running" : "exited"; }; return prov; };
+    const ok = mk(2); ok.results[7] = { terminalReason: "merged", pr: 1 }; ok.live.delete(7);
+    assert.equal((await lanes(ok).l.runOne(7, "staging")).terminalReason, "merged");
+    const down = mk(1e9);
+    const r = await lanes(down, { unreachableWindowMs: 5000 }).l.runOne(7, "staging");
+    // release review BUG-6: a persistent 401 is sandbox.auth (capped by max_deferrals), not the uncapped sandbox.unreachable
+    assert.deepEqual([r.terminalReason, r.code, r.retryInSeconds], ["deferred", "sandbox.auth", 300]);
+    assert.match(r.detail, /agent a1 auth/);
+    assert.match(r.detail, /pool agent refused the router/);
+  });
+
+  it("#5053 launch 401 from the agent hop says the agent refused, not the forgedock token", async () => {
+    const prov = fakeProvider(); prov.start = async () => { throw Object.assign(new Error("sandbox launch: HTTP 401 (agent a1 auth)"), { status: 401, hop: "agent" }); };
+    const r = await lanes(prov).l.runOne(7, "staging");
+    assert.equal(r.code, "sandbox.auth");
+    assert.match(r.detail, /agent a1 auth.*pool agent refused the router/);
+  });
+
   it("unreachable: adopt applies the same tolerance, and a non-transport error is still engine-error", async () => {
     const down = flaky(1e9);
     const { l } = lanes(down, { unreachableWindowMs: 3000 });

package/bin/lean/gatewatch.test.mjs

@@ -17,7 +17,7 @@ describe("#4656 gate watchdog", () => {
   it("the batch runner reports GATE_DEADLOCK once per (gate, issue) for a parked issue on the gate, instead of waiting", async () => {
     const rows = [], decisions = [];
     const runOne = async (n) => n === 1
-      ? { terminalReason: "needs-human", code: "conformance.unimplemented", detail: "unknown requirement", pr: 9 }
+      ? { terminalReason: "needs-human", code: "conformance.regression", detail: "unknown requirement", pr: 9 }
       : { terminalReason: "merged", pr: 10 };
     const _unused = async (n) => n === 1
       ? { terminalReason: "needs-human", code: "ci.red", detail: "lint failed", pr: 9 }
@@ -29,13 +29,13 @@ describe("#4656 gate watchdog", () => {
     assert.equal(dl.length, 1);
     assert.match(dl[0].detail, /GATE_DEADLOCK issue=#1 gate=ship/);
     assert.ok(Array.isArray(res));
-    assert.deepEqual(relabels.map((r) => r.parked?.code), ["conformance.unimplemented"]);
+    assert.deepEqual(relabels.map((r) => r.parked?.code), ["conformance.regression"]);
   });
 });
 
 describe("#4656 parked class and migration", () => {
   it("parked is opt-in and leaves the default classes untouched", () => {
-    const row = { outcome: "needs-human", code: "conformance.unimplemented" };
+    const row = { outcome: "needs-human", code: "conformance.regression" };
     assert.equal(classifyNeedsHuman(row), "terminal");
     assert.equal(classifyNeedsHuman(row, { parked: true }), "parked");
     assert.equal(classifyNeedsHuman({ outcome: "needs-human", code: "builder.blocked" }, { parked: true }), "human");
@@ -53,7 +53,7 @@ describe("#4656 parked class and migration", () => {
 describe("#4656 report routing", () => {
   it("a parked row past recovery is listed on the remediation queue line, not unrecovered or escalations", async () => {
     const { formatOutcomeLists } = await import("./orchestrate.mjs");
-    const lines = formatOutcomeLists([{ issue: 1, outcome: "needs-human", code: "conformance.unimplemented", pr: 9, parkedQueued: true }]);
-    assert.deepEqual(lines, ["remediation queue (/work-on:remediate): #1 (parked:conformance.unimplemented PR #9)"]);
+    const lines = formatOutcomeLists([{ issue: 1, outcome: "needs-human", code: "conformance.regression", pr: 9, parkedQueued: true }]);
+    assert.deepEqual(lines, ["remediation queue (/work-on:remediate): #1 (parked:conformance.regression PR #9)"]);
   });
 });