forgedock 1.33.0 → 1.35.0

package/bin/lean/conflictres.test.mjs

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4588: deterministic base-merge conflict resolution, on real temp git repos.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { readBaseMerge } from "../engine-cli.mjs";
+import { resolveBaseConflicts, jsonUnionText } from "./conflictres.mjs";
+
+const sh = (cwd, ...a) => execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", ...a], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+const put = (root, files) => { for (const [p, t] of Object.entries(files)) { mkdirSync(dirname(join(root, p)), { recursive: true }); writeFileSync(join(root, p), t); } };
+const commit = (d, m) => { sh(d, "add", "-A"); sh(d, "commit", "-qm", m); };
+
+/** A repo whose lane and main both edited `files`; the merge of main into the lane is left in progress. */
+function conflicted(root, start, lane, main) {
+  sh(root, "init", "-q", "-b", "main"); put(root, start); commit(root, "base");
+  sh(root, "checkout", "-qb", "lane"); put(root, lane); commit(root, "lane");
+  sh(root, "checkout", "-q", "main"); put(root, main); commit(root, "main");
+  sh(root, "checkout", "-q", "lane");
+  try { sh(root, "merge", "--no-edit", "main"); } catch { /* conflicts */ }
+  return Object.keys(start).filter((f) => sh(root, "diff", "--name-only", "--diff-filter=U").split("\n").includes(f));
+}
+const env = (root) => ({ git: async (a) => sh(root, ...a), cwd: root });
+
+describe("resolveBaseConflicts (#4588)", () => {
+  it("union: two lanes appending to one barrel keep both lines", async () => {
+    const root = tmpDir("cr-union"); const files = conflicted(root, { "index.ts": "a\n" }, { "index.ts": "a\nlane\n" }, { "index.ts": "a\nmain\n" });
+    const r = await resolveBaseConflicts({ ...env(root), files, cfg: { unionGlobs: ["index.ts"] } });
+    assert.deepEqual(r, { resolved: ["index.ts"], remaining: [] });
+    assert.equal(readFileSync(join(root, "index.ts"), "utf8"), "a\nlane\nmain\n");
+    sh(root, "commit", "--no-edit"); // all staged: the merge commits
+  });
+
+  it("union: a hunk that edits a base line is refused and stays conflicted", async () => {
+    const root = tmpDir("cr-union-edit"); const files = conflicted(root, { "index.ts": "a\n" }, { "index.ts": "x\n" }, { "index.ts": "y\n" });
+    assert.deepEqual(await resolveBaseConflicts({ ...env(root), files, cfg: { unionGlobs: ["index.ts"] } }), { resolved: [], remaining: ["index.ts"] });
+  });
+
+  it("json: key union of a status map; the lane's indent is kept", async () => {
+    const root = tmpDir("cr-json");
+    const files = conflicted(root, { "status.json": '{\n    "a": 1\n}\n' }, { "status.json": '{\n    "a": 1,\n    "lane": 2\n}\n' }, { "status.json": '{\n    "a": 1,\n    "main": 3\n}\n' });
+    const r = await resolveBaseConflicts({ ...env(root), files, cfg: { jsonGlobs: ["status.json"] } });
+    assert.deepEqual(r.resolved, ["status.json"]);
+    assert.equal(readFileSync(join(root, "status.json"), "utf8"), '{\n    "a": 1,\n    "lane": 2,\n    "main": 3\n}\n');
+  });
+
+  it("json: the same key changed differently on both sides is refused", async () => {
+    const root = tmpDir("cr-json-clash");
+    const files = conflicted(root, { "status.json": '{"a":1}\n' }, { "status.json": '{"a":2}\n' }, { "status.json": '{"a":3}\n' });
+    assert.deepEqual(await resolveBaseConflicts({ ...env(root), files, cfg: { jsonGlobs: ["status.json"] } }), { resolved: [], remaining: ["status.json"] });
+    assert.throws(() => jsonUnionText('[1]', '[2]', '[3]'));
+  });
+
+  it("generated: the base side is taken and the command regenerates the file", async () => {
+    const root = tmpDir("cr-gen");
+    const files = conflicted(root, { "gen/out.txt": "v0\n", "src.txt": "s\n" }, { "gen/out.txt": "lane\n" }, { "gen/out.txt": "main\n" });
+    const r = await resolveBaseConflicts({ ...env(root), files, cfg: { generatedGlobs: ["gen/*"], generatedCommand: "echo regenerated > gen/out.txt" } });
+    assert.deepEqual(r, { resolved: ["gen/out.txt"], remaining: [] });
+    assert.equal(readFileSync(join(root, "gen/out.txt"), "utf8"), "regenerated\n");
+    assert.equal(sh(root, "diff", "--name-only", "--diff-filter=U"), "");
+  });
+
+  it("generated: a failing command leaves the file conflicted", async () => {
+    const root = tmpDir("cr-gen-fail");
+    const files = conflicted(root, { "gen/out.txt": "v0\n" }, { "gen/out.txt": "lane\n" }, { "gen/out.txt": "main\n" });
+    const r = await resolveBaseConflicts({ ...env(root), files, cfg: { generatedGlobs: ["gen/*"], generatedCommand: "exit 3" } });
+    assert.deepEqual(r.resolved, []);
+    assert.deepEqual(r.remaining, ["gen/out.txt"]);
+    assert.match(r.note, /generated command failed/);
+    assert.match(readFileSync(join(root, "gen/out.txt"), "utf8"), /<<<<<<</);
+  });
+
+  it("sequence files and unconfigured files are left alone", async () => {
+    const root = tmpDir("cr-skip");
+    const files = conflicted(root, { "db/meta/_journal.json": '{"a":1}\n', "x.ts": "a\n" }, { "db/meta/_journal.json": '{"a":1,"l":1}\n', "x.ts": "a\nl\n" }, { "db/meta/_journal.json": '{"a":1,"m":1}\n', "x.ts": "a\nm\n" });
+    const r = await resolveBaseConflicts({ ...env(root), files, cfg: { jsonGlobs: ["*.json"] } });
+    assert.deepEqual(r.resolved, []);
+    assert.deepEqual(r.remaining.sort(), ["db/meta/_journal.json", "x.ts"]);
+    assert.deepEqual(await resolveBaseConflicts({ ...env(root), files, cfg: {} }), { resolved: [], remaining: files });
+  });
+});
+
+describe("readBaseMerge (#4588)", () => {
+  it("reads lean.base_merge_* and is undefined when no glob is set", () => {
+    const root = tmpDir("cr-cfg");
+    assert.equal(readBaseMerge(root), undefined);
+    writeFileSync(join(root, "forge.yaml"), 'lean:\n  base_merge_union_globs: "index.ts, **/messages.ts"\n  base_merge_json_globs: "status.json"\n  base_merge_generated_globs: "gen/**"\n  base_merge_generated_command: "pnpm gen"\n');
+    assert.deepEqual(readBaseMerge(root), { unionGlobs: ["index.ts", "**/messages.ts"], jsonGlobs: ["status.json"], generatedGlobs: ["gen/**"], generatedCommand: "pnpm gen" });
+  });
+});

package/bin/lean/conformance.mjs

@@ -57,11 +57,13 @@ export function scopeText(iss, trustedComments = []) {
 /** #4265: failures whose detail starts with a contract requirement id also quote that requirement, so a needs-human names what is unmet. */
 export function explainFailures(failures, contract) {
   const reqs = new Map((contract?.requirements ?? []).map((r) => [String(r?.id ?? ""), String(r?.quote ?? "")]));
+  const amended = new Map((contract?.requirements ?? []).filter((r) => r?.amendment?.text).map((r) => [String(r.id), String(r.amendment.text)]));
   return (failures ?? []).map((f) => {
     const id = /^([A-Za-z][\w-]*)\b/.exec(String(f?.detail ?? ""))?.[1];
     const q = id && reqs.get(id);
     if (!q) return f;
-    return { ...f, detail: `${f.detail} ("${q.length > 160 ? `${q.slice(0, 157)}...` : q}")` };
+    const am = amended.get(id);
+    return { ...f, detail: `${f.detail} ("${q.length > 160 ? `${q.slice(0, 157)}...` : q}"${am ? `, amended to "${am.length > 160 ? `${am.slice(0, 157)}...` : am}"` : ""})` };
   });
 }
 export const isTestPath = (p) => TEST_RE.test(String(p));
@@ -264,6 +266,29 @@ 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"];
+const AMEND_SLIPS = { "amend-requirement": "defer", limitation: "defer" };
+
+/** forge#4574: common builder slips: `type` for `kind`, amend-requirement/limitation as defer, an `R#` in `id` as the requirement. */
+function normalizeAmendment(a) {
+  if (!a || typeof a !== "object" || Array.isArray(a)) return a;
+  const n = { ...a };
+  if (blank(n.kind) && !blank(n.type)) n.kind = n.type;
+  // #4594: amend-requirement with a revised `text` is a real amendment; without one it stays the slip for defer
+  if (Object.hasOwn(AMEND_SLIPS, n.kind) && !(n.kind === "amend-requirement" && !blank(n.text))) n.kind = AMEND_SLIPS[n.kind];
+  if (TRACKED.includes(n.kind) && blank(n.requirement) && /^R\d+$/.test(String(n.id ?? ""))) n.requirement = n.id;
+  return n;
+}
+
+/** The rejection reason, naming the valid kinds or the missing field so the builder's correction round can fix it. */
+function amendmentProblem(a, tag) {
+  const kind = a?.kind;
+  const need = kind === "add-deliverable" ? "needs a path" : kind === "add-requirement" ? "needs requirement {id, quote}"
+    : TRACKED.includes(kind) ? "needs requirement: \"R#\"" : kind === "amend-requirement" ? "needs requirement: \"R#\" and text (the revised wording)" : null;
+  const why = need ? `amendment kind '${kind}' ${need}` : `unknown kind '${kind ?? ""}'; valid kinds are ${AMEND_KINDS.join(", ")}`;
+  return `unknown or incomplete amendment: ${why}: ${tag}`;
+}
+
 /**
  * Apply result.json amendments to the frozen contract. Kinds: add-deliverable {path}, add-requirement {requirement},
  * defer|post-deploy {requirement: id}. Every amendment needs a why. Returns {contract, applied[], toTrack[], problems[]}.
@@ -275,8 +300,9 @@ export function applyAmendments(frozen, amendments, issueText = null, { generate
   c.deliverables = c.deliverables ?? [];
   const applied = [], toTrack = [], problems = [];
   const genRes = (Array.isArray(generatedPaths) ? generatedPaths : []).filter((g) => typeof g === "string" && g).map(shellGlobRe);
-  for (const a of Array.isArray(amendments) ? amendments : []) {
-    const tag = JSON.stringify(a ?? null).slice(0, 100);
+  for (const raw of Array.isArray(amendments) ? amendments : []) {
+    const a = normalizeAmendment(raw);
+    const tag = JSON.stringify(raw ?? null).slice(0, 400);
     if (blank(a?.why)) { problems.push(`amendment without why: ${tag}`); continue; }
     if (a.kind === "add-deliverable" && !blank(a.path)) {
       if (genRes.some((re) => re.test(cleanPath(a.path)))) {
@@ -297,11 +323,16 @@ export function applyAmendments(frozen, amendments, issueText = null, { generate
       if (tagsOutOfBand(r)) r.verify = "out_of_band"; // #4404: same freeze-time tag as the planned requirements
       c.requirements.push(r);
       if (TRACKED.includes(r.disposition)) toTrack.push(r);
+    } else if (a.kind === "amend-requirement" && !blank(a.requirement)) {
+      // #4594: the requirement stays deliver and keeps its verbatim quote; the reviewer judges it against amendment.text
+      const r = c.requirements.find((x) => x.id === a.requirement);
+      if (!r) { problems.push(`amendment names unknown requirement ${a.requirement}`); continue; }
+      r.amendment = { text: String(a.text).trim(), why: String(a.why).trim() }; r.amended = true;
     } else if (TRACKED.includes(a.kind) && a.requirement) {
       const r = c.requirements.find((x) => x.id === a.requirement);
       if (!r) { problems.push(`amendment names unknown requirement ${a.requirement}`); continue; }
       if (!TRACKED.includes(r.disposition)) { r.disposition = a.kind; r.why = a.why; r.amended = true; toTrack.push(r); }
-    } else { problems.push(`unknown or incomplete amendment: ${tag}`); continue; }
+    } else { problems.push(amendmentProblem(a, tag)); continue; }
     applied.push({ kind: a.kind, target: a.path ?? a.requirement?.id ?? a.requirement, why: String(a.why).trim() });
   }
   return { contract: c, applied, toTrack, problems };
@@ -602,14 +633,16 @@ export function decide(raw, ctx) {
   const comp = checkCompleteness(rv, ctx);
   if (!comp.complete) return { state: "review.incomplete", failures: comp.problems.map((d) => ({ code: C.REVIEW_INCOMPLETE, detail: d })), missing: comp.missing, review: rv };
   const f = [];
-  for (const c of rv.issue_coverage) if (c.status !== "covered") f.push({ code: C.CONFORMANCE_OMISSION, detail: `issue requirement ${c.status}: "${c.quote}"${c.note ? ` (${c.note})` : ""}` });
+  const amendedOf = (ids) => (ctx.contract.requirements ?? []).find((r) => r.amendment?.text && (ids ?? []).includes(r.id));
+  const notAccepted = (r) => (r ? `amendment not accepted (${r.id} amended to "${String(r.amendment.text).slice(0, 200)}"): ` : "");
+  for (const c of rv.issue_coverage) if (c.status !== "covered") f.push({ code: C.CONFORMANCE_OMISSION, detail: `${notAccepted(amendedOf(c.contract_ids))}issue requirement ${c.status}: "${c.quote}"${c.note ? ` (${c.note})` : ""}` });
   for (const r of ctx.contract.requirements) {
     const row = rv.requirements.find((x) => x.id === r.id);
     if (r.disposition === "deliver" && isOutOfBand(r)) {
       // #4404: the measured result lives in the named job; only the instrumentation is judged here
       if (row.instrumented !== true) f.push({ code: C.CONFORMANCE_UNIMPLEMENTED, detail: `${r.id} verified out of band${r.evidence ? ` by ${r.evidence}` : ""}: instrumentation missing${row.note ? `: ${row.note}` : ""}${row.evidence ? ` (${row.evidence})` : ""}` });
     } else if (r.disposition === "deliver" && row.status !== "implemented") {
-      f.push({ code: ["deferred", "post-deploy"].includes(row.status) ? C.CONFORMANCE_UNTRACKED_DEFERRAL : C.CONFORMANCE_UNIMPLEMENTED, detail: `${r.id} ${row.status}${row.note ? `: ${row.note}` : ""}${row.evidence ? ` (${row.evidence})` : ""}` });
+      f.push({ code: ["deferred", "post-deploy"].includes(row.status) ? C.CONFORMANCE_UNTRACKED_DEFERRAL : C.CONFORMANCE_UNIMPLEMENTED, detail: `${r.amendment?.text ? `${r.id} amendment not accepted (amended to "${String(r.amendment.text).slice(0, 200)}"): ` : `${r.id} `}${row.status}${row.note ? `: ${row.note}` : ""}${row.evidence ? ` (${row.evidence})` : ""}` });
     }
     if (TRACKED.includes(r.disposition) && row.deferral_ok === false) f.push({ code: C.CONFORMANCE_UNJUSTIFIED_DEFERRAL, detail: `${r.id} ${r.disposition} is not justified${row.note ? `: ${row.note}` : ""}; implement it` });
   }

package/bin/lean/conformance.test.mjs

@@ -60,6 +60,27 @@ describe("amendments", () => {
   });
 });
 
+describe("#4574 amendment slips", () => {
+  it("type for kind, amend-requirement and limitation apply as defer; an R# id fills requirement", () => {
+    const a = applyAmendments(C, [{ kind: "amend-requirement", id: "R2", why: "stored hashed" }, { id: "A1", requirement: "R1", type: "limitation", why: "plugin limit" }]);
+    assert.deepEqual(a.problems, []);
+    assert.deepEqual(a.toTrack.map((r) => r.id).sort(), ["R1", "R2"]);
+    assert.ok(a.contract.requirements.every((r) => r.disposition === "defer"));
+  });
+  it("an unknown kind names the valid kinds and shows the full amendment", () => {
+    const why = "x".repeat(300);
+    const a = applyAmendments(C, [{ kind: "rewrite", why }]);
+    assert.match(a.problems[0], /unknown kind 'rewrite'; valid kinds are add-deliverable, add-requirement, defer, post-deploy/);
+    assert.ok(a.problems[0].includes(why));
+  });
+  it("an Object.prototype key as kind is an unknown kind, not a slip", () => {
+    assert.match(applyAmendments(C, [{ kind: "constructor", why: "w" }]).problems[0], /unknown kind 'constructor'; valid kinds are add-deliverable/);
+  });
+  it("an incomplete known kind names the missing field", () => {
+    assert.match(applyAmendments(C, [{ kind: "defer", why: "w" }]).problems[0], /'defer' needs requirement/);
+  });
+});
+
 describe("precheck (deterministic, no reviewer)", () => {
   const res = { requirements: [{ id: "R1", status: "implemented" }, { id: "R2", status: "implemented" }], validation: [{ id: "V1", exit: 0 }] };
   it("passes a complete, validated, in-scope change", () => assert.deepEqual(precheck({ contract: C, result: res, changedFiles: files }), { ok: true, failures: [], superseded: [], ciCovered: [] }));
@@ -624,3 +645,28 @@ describe("#4404 verified out of band: a requirement measured outside the lane is
     assert.deepEqual(outOfBandRequirements(tagged), [{ id: "R3", quote: LH, job: "lighthouse-nightly" }]);
   });
 });
+
+describe("#4594 amend-requirement", () => {
+  const am = { kind: "amend-requirement", requirement: "R1", text: "regenerate and reveal the feed URL once", why: "token stored hash-only" };
+  it("with text it keeps deliver, tracks nothing and records the amendment", () => {
+    const a = applyAmendments(C, [am]);
+    assert.deepEqual(a.problems, []); assert.deepEqual(a.toTrack, []);
+    const r = a.contract.requirements.find((x) => x.id === "R1");
+    assert.equal(r.disposition, "deliver"); assert.equal(r.amendment.text, am.text); assert.equal(r.amendment.why, am.why); assert.equal(r.quote, C.requirements[0].quote);
+  });
+  it("an unknown requirement is a problem; the frozen contract is untouched", () => {
+    assert.match(applyAmendments(C, [{ ...am, requirement: "R9" }]).problems[0], /unknown requirement R9/);
+    assert.equal(C.requirements[0].amendment, undefined);
+  });
+  it("decide: an amended requirement the reviewer rejects fails as 'amendment not accepted'; accepted conforms", () => {
+    const k = { ...ctx, contract: applyAmendments(C, [am]).contract };
+    assert.equal(decide(good, k).state, "conforms");
+    const d = decide({ ...row("R1", { status: "partial", note: "amendment: still never shows the URL" }), issue_coverage: good.issue_coverage.map((c) => (c.quote === Q1 ? { ...c, contract_ids: ["R1"], status: "narrowed" } : c)) }, k);
+    assert.equal(d.state, "nonconforming");
+    assert.ok(d.failures.length >= 2 && d.failures.every((f) => /amendment not accepted \(.*amended to "regenerate/.test(f.detail)));
+  });
+  it("explainFailures shows the amended text", () => {
+    const c = applyAmendments(C, [am]).contract;
+    assert.match(explainFailures([{ code: "x", detail: "R1 partial" }], c)[0].detail, /amended to "regenerate and reveal/);
+  });
+});

package/bin/lean/effects.mjs

@@ -17,7 +17,8 @@ import { makeHeavyIo } from "./heavy.mjs";
 import { gatherContextFacts } from "./context.mjs";
 import { makePitfallStore } from "./pitfalls.mjs";
 import { enumeratingTests, missingEntries } from "./enumerating.mjs";
-import { sequenceCollisions, snapshotLane, verifyRenumber, renumberLane, resolveSequenceConflicts } from "./sequence.mjs";
+import { resolveBaseConflicts } from "./conflictres.mjs";
+import { sequenceCollisions, snapshotLane, verifyRenumber, renumberLane, resolveSequenceConflicts, generatorProblems } from "./sequence.mjs";
 import { duplicateExports } from "./postmerge.mjs";
 import { scopedChecks } from "./checks.mjs";
 import { makeSequenceLeaseIo } from "./seqlease.mjs";
@@ -63,8 +64,11 @@ export const noToolFlags = (caps) => (caps?.strictMcp ? ["--tools", ""]
 
 /** #4456: `--settings` registering the re-read nudge (bin/hooks/reread-nudge.mjs) as a PostToolUse hook on Read and Bash. */
 export const REREAD_HOOK = fileURLToPath(new URL("../hooks/reread-nudge.mjs", import.meta.url));
-export const rereadNudgeFlags = (node = process.execPath, hook = REREAD_HOOK) => ["--settings", JSON.stringify({ hooks: { PostToolUse: [{ matcher: "Read|Bash",
-  hooks: [{ type: "command", command: `${JSON.stringify(node)} ${JSON.stringify(hook)}` }] }] } })];
+export const rereadNudgeFlags = (node = process.execPath, hook = REREAD_HOOK) => {
+  const hooks = [{ type: "command", command: `${JSON.stringify(node)} ${JSON.stringify(hook)}` }];
+  // #4580: the same script denies a full-file Read of an unchanged path already read twice (PreToolUse)
+  return ["--settings", JSON.stringify({ hooks: { PostToolUse: [{ matcher: "Read|Bash", hooks }], PreToolUse: [{ matcher: "Read", hooks }] } })];
+};
 
 export function makeLeanRunner({ runCli = runCliBackendAsync, probe = systemdRunAvailable } = {}) {
   return async ({ role, issue, cwd, model, resume, system, prompt, readOnly = false, noTools = false, rereadNudge = false, maxTurns = null, agents = null, env = null, idleMs = 0, maxMs = 0, laneLimits = null, control = null, onSpawn = null, contextMax = 0, turnMax = 0, busy = null, busyMs = 0, onIdleExtend = null }) => {
@@ -372,7 +376,11 @@ export function makeLeanIo({ repo }) {
     /** #4386: the deterministic renumber, sequence-only base-sync resolution, and the host sequence lease at the merge gate. */
     sequenceRenumber: ({ cwd, base, laneRef, regenerate, reserve }) => renumberLane({ git: (a) => run("git")(a, { cwd }), base, cwd, laneRef, regenerate, reserve }),
     sequenceResolve: ({ cwd, files }) => resolveSequenceConflicts({ git: (a) => run("git")(a, { cwd }), files }),
+    /** #4588: deterministic base-merge resolution of union / JSON-map / generated files (bin/lean/conflictres.mjs). */
+    conflictResolve: ({ cwd, files, cfg }) => resolveBaseConflicts({ git: (a) => run("git")(a, { cwd }), cwd, files, cfg }),
     sequenceLease: makeSequenceLeaseIo(),
+    /** #4591: lane-added migrations the repo's generator did not produce (no journal entry or snapshot); [] on failure. */
+    migrationGenerator: ({ cwd, base }) => generatorProblems({ git: (a) => run("git")(a, { cwd }), base }),
     /** #4406: the lane's scoped checks after a base merge (bin/lean/checks.mjs; [] on failure), and same-app duplicate exports (bin/lean/postmerge.mjs). */
     postMergeChecks: async ({ cwd, base }) => { try { return scopedChecks({ repo: cwd, base }); } catch { return []; } },
     duplicateExports: ({ cwd, base }) => duplicateExports({ git: (a) => run("git")(a, { cwd }), cwd, base }),

package/bin/lean/lane.mjs

@@ -83,3 +83,16 @@ export async function resolveLane({ issue, repo, io, cwd, branches = {}, request
   if (!out.trim()) return refuse(OUTCOME_CODES.LANE_BRANCH_MISSING, `lane branch ${lane} (${why}) does not exist on origin; create it first (e.g. /milestone start) or fix the milestone title`);
   return { ok: true, lane, expected, milestone, overridden, defaults };
 }
+
+/**
+ * #4593: true when `lane` is a non-staging branch fully merged into `staging` (a shipped milestone branch).
+ * Fail closed: any git error (no such ref, offline) is "not shipped".
+ */
+export async function isShippedLane({ lane, staging = DEFAULT_STAGING_BRANCH, io, cwd }) {
+  if (!lane || lane === staging) return false;
+  try {
+    try { await io.git(["fetch", "origin", lane, staging], { cwd }); } catch { /* offline: use the local refs */ }
+    await io.git(["merge-base", "--is-ancestor", `origin/${lane}`, `origin/${staging}`], { cwd });
+    return true;
+  } catch { return false; }
+}