forgedock 1.29.1 → 1.31.0

package/bin/lean/context.mjs

@@ -10,22 +10,28 @@
  */
 import { createHash } from "node:crypto";
 import { join } from "node:path";
-import { isTrustedComment, parseDependsOn } from "../engine/phases.mjs";
+import { parseDependsOn } from "../engine/phases.mjs";
 import { codeForTerminalReason } from "../engine/outcome-codes.mjs";
-import { namedPaths } from "./prefilter.mjs";
+import { runLogKey } from "../engine/runlog.mjs";
+import { namedPaths, isTrustedIssueComment as trusted } from "./prefilter.mjs";
 import { parseContractComment, noComments } from "./render.mjs";
 import { REPO_FACTS_FILE, TEST_MAP_FILE } from "./testmap.mjs";
+import { parseFactsComment, factsLines, FACTS_RANK } from "./facts.mjs";
 
 // noComments lives in render.mjs (#4298: one comment-strip helper for context, conformance and prefilter).
 export { noComments };
 
 export const CONTEXT_MODES = Object.freeze(["shadow", "on", "off"]);
-export const CONTEXT_SOURCES = Object.freeze(["graph", "attempts", "ledger", "facts"]);
+export const CONTEXT_SOURCES = Object.freeze(["graph", "attempts", "pitfalls", "ledger", "facts"]);
 export const DEFAULT_CONTEXT_BYTES = 6144;
 export const DEFAULT_LEDGER_DAYS = 30;
+/** #4375: a pitfall not seen in this many lanes of the repo ages out (forge.yaml engine.context_pack_pitfall_lanes). */
+export const DEFAULT_PITFALL_LANES = 50;
 /** Bounds on GitHub reads per pack: linked issues read, ledger PRs inspected. */
 export const MAX_LINKS = 20;
 export const MAX_LEDGER_PRS = 8;
+/** #4401: FORGE:FACTS records (earlier lanes) read into one pack: this issue's own attempts first, then the file-path ledger. */
+export const MAX_FACT_LANES = 6;
 export const REPO_FACT_FILES = Object.freeze([REPO_FACTS_FILE, TEST_MAP_FILE]);
 const ATTEMPT_MARKERS = ["NEEDS_HUMAN", "BASE_SYNC", "FIX_CI"];
 const LINE_MAX = 200;
@@ -38,13 +44,13 @@ const oneLine = (s, max = LINE_MAX) => {
 const stripComments = (s) => noComments(s).replace(/\r\n/g, "\n").trim();
 const byNum = (a, b) => a - b;
 
-/** forge.yaml engine.context_pack (+ _sources, _bytes, _days) normalised; invalid values fall back to the defaults. */
-export function parseContextPackConfig({ mode, sources, bytes, days } = {}) {
+/** forge.yaml engine.context_pack (+ _sources, _bytes, _days, _pitfall_lanes) normalised; invalid values fall back to the defaults. */
+export function parseContextPackConfig({ mode, sources, bytes, days, pitfallLanes } = {}) {
   const m = String(mode ?? "").trim().toLowerCase();
   const list = Array.isArray(sources) ? sources : typeof sources === "string" && sources.trim() ? sources.split(/[\s,]+/) : null;
   const picked = list ? CONTEXT_SOURCES.filter((s) => list.map((x) => String(x).trim().toLowerCase()).includes(s)) : [...CONTEXT_SOURCES];
   const pos = (v, d) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? Math.floor(n) : d; };
-  return { mode: CONTEXT_MODES.includes(m) ? m : "shadow", sources: picked, budgetBytes: pos(bytes, DEFAULT_CONTEXT_BYTES), days: pos(days, DEFAULT_LEDGER_DAYS) };
+  return { mode: CONTEXT_MODES.includes(m) ? m : "shadow", sources: picked, budgetBytes: pos(bytes, DEFAULT_CONTEXT_BYTES), days: pos(days, DEFAULT_LEDGER_DAYS), pitfallLanes: pos(pitfallLanes, DEFAULT_PITFALL_LANES) };
 }
 
 /** `**Parent**: #N` (decomposition sub-issue body line); null when absent. */
@@ -102,34 +108,40 @@ export function priorAttempts(body, comments = []) {
 }
 
 /**
- * Cache key for a compiled pack: issue + base head SHA, plus the config that shapes it and (#4298, #4304) the hash of the
+ * Cache key for a compiled pack: issue (with `repo`, #4432: repo-scoped) + base head SHA, plus the config that shapes it and (#4298, #4304) the hash of the
  * issue's human scope text (`scope`) and prior-attempt count, so an edit or a new attempt on the same base compiles a
  * fresh pack. Not `updatedAt`: the lane's own FORGE:STATE/CONTEXT posts and label edits bump it, so the cache never hit.
+ * #4375: `stamp.pitfalls` (the selected pitfall signatures) joins the key, so a newly learned pitfall is never served stale.
  */
-export const contextPackCacheKey = (issue, headSha, cfg = {}, stamp = {}) =>
-  `context-${issue}-${String(headSha ?? "").trim().slice(0, 40) || "nohead"}-${hash12(JSON.stringify([cfg.sources ?? [], cfg.budgetBytes ?? null, cfg.days ?? null,
+export const contextPackCacheKey = (issue, headSha, cfg = {}, stamp = {}, repo = null) =>
+  `context-${runLogKey(issue, repo)}-${String(headSha ?? "").trim().slice(0, 40) || "nohead"}-${hash12(JSON.stringify([cfg.sources ?? [], cfg.budgetBytes ?? null, cfg.days ?? null,
     ...(stamp?.scope != null || stamp?.attempts != null ? [String(stamp.scope ?? ""), Number(stamp.attempts) || 0] : []),
-    ...(stamp?.links ? [`links:${stamp.links}`] : [])]))}.json`;
+    ...(stamp?.links ? [`links:${stamp.links}`] : []), ...(stamp?.pitfalls?.length ? [`pitfalls:${stamp.pitfalls.join(",")}`] : [])]))}.json`;
 
-/** Max referenced issues whose state is read for the cache stamp (one REST call each). */
-export const LINK_STAMP_MAX = 20;
+/** Max referenced issues whose state is read for the cache stamp (#4318: one GraphQL call for all of them). */
+export const LINK_STAMP_MAX = 100;
 /**
  * #4316: the linked-issue part of the cache stamp: a hash of `n:STATE` for each issue the body references (parent, Depends
- * on, `#N` links), so a pack never shows a linked issue as open after it closed on the same base. Timeline cross-refs are
- * left to the gather. An unreadable issue counts as `n:?`; never throws; '' when the body references nothing.
+ * on, `#N` links), so a pack never shows a linked issue as open after it closed on the same base. #4318: one GraphQL call
+ * reads every state plus the issue's own cross-reference/connected timeline count (a new relation changes the stamp too);
+ * above LINK_STAMP_MAX the highest (most recent) numbers are kept. A failed call counts every number as `n:?`; never
+ * throws; '' (and no call) when the body references nothing.
  */
 export async function linkStateStamp({ gh, repo, issue, body }) {
   const parent = parentOf(body);
   const nums = [...new Set([...(parent ? [parent] : []), ...parseDependsOn(stripComments(body), issue), ...bodyLinks(body, repo, issue)])]
-    .filter((n) => Number.isSafeInteger(n) && n > 0 && n !== Number(issue)).sort(byNum).slice(0, LINK_STAMP_MAX);
+    .filter((n) => Number.isSafeInteger(n) && n > 0 && n !== Number(issue)).sort(byNum).slice(-LINK_STAMP_MAX);
   if (!nums.length) return "";
-  const states = [];
-  for (const n of nums) {
-    let st = "?";
-    try { st = String(await gh(["api", `repos/${repo}/issues/${n}`, "--jq", ".state"])).trim().toUpperCase() || "?"; } catch { /* unreadable: n:? */ }
-    states.push(`${n}:${st}`);
-  }
-  return hash12(states.join(","));
+  const [owner, name] = String(repo ?? "").split("/");
+  const self = Number(issue);
+  const q = `query($o:String!,$n:String!){repository(owner:$o,name:$n){${Number.isSafeInteger(self) && self > 0
+    ? `self:issueOrPullRequest(number:${self}){... on Issue{timelineItems(itemTypes:[CROSS_REFERENCED_EVENT,CONNECTED_EVENT,DISCONNECTED_EVENT]){totalCount}}}` : ""}${
+    nums.map((n) => `i${n}:issueOrPullRequest(number:${n}){... on Issue{state} ... on PullRequest{state}}`).join(" ")}}}`;
+  let r = null;
+  try { r = JSON.parse(String(await gh(["api", "graphql", "-f", `query=${q}`, "-f", `o=${owner ?? ""}`, "-f", `n=${name ?? ""}`])))?.data?.repository ?? null; } catch { r = null; }
+  const states = nums.map((n) => `${n}:${String(r?.[`i${n}`]?.state ?? "").toUpperCase() || "?"}`);
+  const rel = r?.self?.timelineItems?.totalCount;
+  return hash12([...states, `rel:${Number.isInteger(rel) ? rel : "?"}`].join(","));
 }
 
 // ---- gather (I/O) ----
@@ -151,10 +163,6 @@ const outcomeOf = (st) => {
   return codeOf(c) && c !== "unclassified" ? c : null;
 };
 const failuresOf = (st) => (Array.isArray(st?.failureClasses) ? [...new Set(st.failureClasses.map(codeOf).filter(Boolean))].sort().slice(0, 5) : []);
-const trusted = (c) => {
-  const login = String(c?.author?.login ?? c?.user?.login ?? "");
-  return isTrustedComment({ author_association: c?.authorAssociation ?? c?.author_association, user: { login, type: c?.user?.type ?? (/\[bot\]$|^app\//.test(login) ? "Bot" : "User") } });
-};
 /** First line of a FORGE record that is not a marker or a heading. */
 const recordLine = (body) => oneLine(noComments(body).split("\n").map((l) => l.trim()).find((l) => l && !/^#+\s/.test(l)) ?? "");
 const markerOf = (body) => /^\s*<!--\s*FORGE:([A-Z_]+)\s*-->/.exec(String(body ?? ""))?.[1] ?? null;
@@ -169,10 +177,11 @@ async function readComments(gh, repo, n) {
 
 /**
  * Collect the facts for one issue's pack. `io`: {gh, git, exists}; git runs in `cwd` (the lane worktree), base is the
- * base ref. Every source is independent and best effort: a failing source is listed in `errors` and contributes nothing.
+ * base ref; `checkout` (the main checkout, optional) is where repo-fact files absent from the worktree are looked up.
+ * Every source is independent and best effort: a failing source is listed in `errors` and contributes nothing.
  */
-export async function gatherContextFacts({ io, repo, issue, iss, comments = [], cwd, base, sources = CONTEXT_SOURCES, days = DEFAULT_LEDGER_DAYS, now = Date.now() }) {
-  const facts = { issue: Number(issue), links: [], attempts: [], ledger: [], facts: [], errors: [] };
+export async function gatherContextFacts({ io, repo, issue, iss, comments = [], cwd, checkout = null, base, sources = CONTEXT_SOURCES, days = DEFAULT_LEDGER_DAYS, now = Date.now(), pitfalls = [] }) {
+  const facts = { issue: Number(issue), links: [], attempts: [], pitfalls: [], ledger: [], facts: [], lanes: [], errors: [] };
   const body = String(iss?.body ?? "");
   const on = new Set(sources);
   const step = async (name, fn) => { if (!on.has(name)) return; try { await fn(); } catch (e) { facts.errors.push(`${name}: ${oneLine(e?.message ?? e, 120)}`); } };
@@ -225,30 +234,54 @@ export async function gatherContextFacts({ io, repo, issue, iss, comments = [],
     for (const l of refs) { const [ref, sha] = l.split(" "); facts.attempts.push({ kind: "salvage", ref, line: `salvaged uncommitted work at ${sha ?? "?"} (git diff HEAD ${ref} --stat)` }); }
   });
 
-  await step("ledger", async () => {
-    const paths = namedPaths(body);
-    const symbols = issueSymbols(body);
-    if (!paths.length || !base) return;
+  // #4375: already read and selected by the engine from the local ledger (pitfalls.mjs selectPitfalls); no I/O here
+  await step("pitfalls", async () => {
+    for (const p of Array.isArray(pitfalls) ? pitfalls : []) {
+      if (p && typeof p.sig === "string") facts.pitfalls.push({ sig: p.sig, trigger: String(p.trigger ?? ""), lesson: oneLine(p.lesson ?? "", 160), globs: (p.globs ?? []).slice(0, 5), count: Number(p.count) || 1, match: p.match === "files" ? "files" : "repo" });
+    }
+  });
+
+  // The file-path ledger walk (merged PRs on the issue's named paths) and each PR's trusted records, shared by the ledger
+  // and facts sources (#4401): run once per gather, and only when a source that needs them is on.
+  const paths = namedPaths(body);
+  let walked = null;
+  const walk = () => (walked ??= (async () => {
+    if (!paths.length || !base) return [];
     const since = new Date(now - days * 86400000).toISOString().slice(0, 10);
     const out = String(await git(["log", "--first-parent", `--since=${since}`, "--format=%x1e%H%x1f%s%x1f%b%x1f", "--name-only", base, "--", ...paths]));
-    const commits = out.split("\x1e").filter((x) => x.trim()).map((rec) => {
+    return out.split("\x1e").filter((x) => x.trim()).map((rec) => {
       const [sha, subject = "", msg = "", files = ""] = rec.split("\x1f");
       const pr = Number(/Merge pull request #(\d+)/.exec(subject)?.[1] ?? /\(#(\d+)\)\s*$/.exec(subject)?.[1]) || null;
       return { sha: sha.trim(), subject: subject.trim(), msg, pr, files: files.split("\n").map((f) => f.trim()).filter(Boolean),
         revert: /^Revert\b/.test(subject.trim()) || /\/revert-\d+-/.test(subject) || /^This reverts commit [0-9a-f]{7,40}/m.test(msg) };
     });
+  })());
+  const prReads = new Map();
+  const prInfo = (n) => {
+    if (!prReads.has(n)) prReads.set(n, (async () => {
+      const pr = JSON.parse(String(await io.gh(["api", `repos/${repo}/pulls/${n}`, "--jq", "{title, body, head: .head.ref}"])));
+      const linked = Number(/issue-(\d+)/.exec(String(pr.head ?? ""))?.[1] ?? /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/i.exec(String(pr.body ?? ""))?.[1]) || null;
+      const recs = [...(await readComments(io.gh, repo, n)), ...(linked ? await readComments(io.gh, repo, linked) : [])].filter(trusted);
+      return { title: pr.title, linked, recs };
+    })());
+    return prReads.get(n);
+  };
+  const ledgerPrs = async () => (await walk()).filter((x) => x.pr || x.revert).slice(0, MAX_LEDGER_PRS);
+
+  await step("ledger", async () => {
+    const symbols = issueSymbols(body);
+    const commits = await walk();
+    if (!commits.length) return;
     const reverts = commits.filter((c) => c.revert);
     const revertedBy = (c) => reverts.find((r) => r !== c && ((c.pr && (new RegExp(`#${c.pr}\\b`).test(`${r.subject}\n${r.msg}`) || new RegExp(`/revert-${c.pr}-`).test(r.subject))) || r.msg.includes(c.sha) || r.msg.includes(c.sha.slice(0, 12))));
-    for (const c of commits.filter((x) => x.pr || x.revert).slice(0, MAX_LEDGER_PRS)) {
+    for (const c of await ledgerPrs()) {
       let title = c.subject, notes = [];
       const reverted = c.revert ? null : revertedBy(c);
       if (c.pr) {
         try {
-          const pr = JSON.parse(String(await io.gh(["api", `repos/${repo}/pulls/${c.pr}`, "--jq", "{title, body, head: .head.ref}"])));
+          const pr = await prInfo(c.pr);
           title = oneLine(pr.title ?? title, 120);
-          const linked = Number(/issue-(\d+)/.exec(String(pr.head ?? ""))?.[1] ?? /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/i.exec(String(pr.body ?? ""))?.[1]) || null;
-          const recs = [...(await readComments(io.gh, repo, c.pr)), ...(linked ? await readComments(io.gh, repo, linked) : [])].filter(trusted);
-          for (const r of recs) {
+          for (const r of pr.recs) {
             const m = markerOf(r.body);
             if (m === "DECISION") notes.push(...String(r.body).split("\n").slice(1).map((l) => oneLine(l, 160)).filter((l) => l && !l.startsWith("#")).map((l) => `decision: ${l}`));
             if (m === "CONTRACT") for (const d of parseContractComment(r.body)?.contract?.decisions ?? []) notes.push(oneLine(`decision ${d?.id ?? ""}: ${d?.choice ?? ""}`, 160));
@@ -264,7 +297,32 @@ export async function gatherContextFacts({ io, repo, issue, iss, comments = [],
   });
 
   await step("facts", async () => {
-    for (const p of REPO_FACT_FILES) if (await io.exists(`${cwd}/${p}`)) facts.facts.push(p);
+    // #4401: FORGE:FACTS of earlier lanes: this issue's own attempts (newest first), then merged PRs on the issue's files
+    // whose record names an overlapping file. Only trusted comments; a malformed record contributes nothing.
+    const seen = new Set();
+    const add = (rec, ref, n, pr) => {
+      const key = JSON.stringify(rec);
+      if (!rec || seen.has(key) || facts.lanes.length >= MAX_FACT_LANES) return;
+      seen.add(key);
+      facts.lanes.push({ ref, issue: n, pr, ...rec });
+    };
+    for (const c of [...comments].reverse()) if (trusted(c)) add(parseFactsComment(c?.body), `#${issue} earlier attempt`, Number(issue), null);
+    const overlaps = (files) => files.some((f) => paths.some((p) => f === p || f.startsWith(`${p.replace(/\/+$/, "")}/`) || p.startsWith(`${f}/`)));
+    let prs = [];
+    try { prs = await ledgerPrs(); } catch (e) { facts.errors.push(`facts: ledger ${oneLine(e?.message ?? e, 80)}`); }
+    for (const c of prs) {
+      if (!c.pr || facts.lanes.length >= MAX_FACT_LANES) continue;
+      let pr;
+      try { pr = await prInfo(c.pr); } catch (e) { facts.errors.push(`facts: PR #${c.pr} ${oneLine(e?.message ?? e, 80)}`); continue; }
+      for (const r of [...pr.recs].reverse()) {
+        const rec = parseFactsComment(r.body);
+        if (rec && overlaps(rec.files)) add(rec, `${pr.linked ? `#${pr.linked}, ` : ""}PR #${c.pr}`, pr.linked, c.pr);
+      }
+    }
+    // #4400: the .forge/ caches are untracked, so a fresh lane worktree lacks them: the main checkout is the fallback
+    for (const p of REPO_FACT_FILES) {
+      for (const d of [...new Set([cwd, checkout].filter(Boolean))]) if (await io.exists(`${d}/${p}`)) { facts.facts.push(p); break; }
+    }
   });
   return facts;
 }
@@ -274,25 +332,33 @@ export async function gatherContextFacts({ io, repo, issue, iss, comments = [],
 // forge#4297: codes are re-checked here too, so facts read back from the cache get the same whitelist
 const linkLine = (l) => { const fails = (Array.isArray(l.failures) ? l.failures : []).map(codeOf).filter(Boolean), res = codeOf(l.result);
   return `- #${l.number} [${l.rel}${l.kind === "pr" ? ", PR" : ""}] ${l.state ?? "?"}${l.title ? ` "${l.title}"` : ""}${codeOf(l.code) ? `; outcome ${l.code}` : ""}${res ? `; ${res}` : ""}${fails.length ? `; failures ${fails.join(", ")}` : ""}`; };
+const pitfallLine = (p) => `- [${p.trigger}] ${oneLine(p.lesson, 160)}${p.globs?.length ? ` (${p.globs.join(", ")})` : ""}; seen ${p.count}×`;
 const ledgerLine = (p) => `- ${p.pr ? `PR #${p.pr}` : "commit"} ${p.sha}${p.revert ? " [revert]" : ""}${p.reverted ? ` [reverted by ${p.reverted}]` : ""} "${p.title}"${p.files?.length ? ` (${p.files.join(", ")})` : ""}${p.notes?.length ? ` — ${p.notes.join("; ")}` : ""}`;
 
 /**
  * The pack text for `facts`, ranked: explicit links (parent > Depends on > body links > cross-references > siblings),
- * prior attempts, the symbol ledger (newest first), repo-fact pointers. One line per item; a parent or dependency also
+ * prior attempts, recurring pitfalls of the repo (#4375, in the engine's selected order), the symbol ledger (newest first), repo-fact pointers. One line per item; a parent or dependency also
  * carries its full body when it fits. Items that do not fit `budgetBytes` are dropped whole and counted in `truncated`.
- * @returns {{text:string, bytes:number, items:number, truncated:number, sources:object, found:object, hash:string|null}}
+ * `pitfalls` lists the kept pitfalls ({sig, match}) for the run log (#4375).
+ * @returns {{text:string, bytes:number, items:number, truncated:number, sources:object, found:object, hash:string|null, pitfalls:object[]}}
  */
 export function compileContextPack(facts, { budgetBytes = DEFAULT_CONTEXT_BYTES, sources = CONTEXT_SOURCES } = {}) {
   const on = new Set(sources);
   const cand = [];
   if (on.has("graph")) for (const l of facts?.links ?? []) cand.push({ src: "graph", line: linkLine(l), full: l.body ? `${linkLine(l)}\n${l.body.split("\n").map((x) => `  > ${x}`).join("\n")}` : null });
   if (on.has("attempts")) for (const a of facts?.attempts ?? []) cand.push({ src: "attempts", line: `- ${a.ref}: ${oneLine(a.line)}` });
+  if (on.has("pitfalls")) for (const p of facts?.pitfalls ?? []) cand.push({ src: "pitfalls", line: pitfallLine(p), pit: { sig: p.sig, match: p.match } });
   if (on.has("ledger")) for (const p of facts?.ledger ?? []) cand.push({ src: "ledger", line: ledgerLine(p) });
-  if (on.has("facts")) for (const f of facts?.facts ?? []) cand.push({ src: "facts", line: `- ${f} (repo facts file; read it if relevant)` });
+  if (on.has("facts")) {
+    // #4401: earlier lanes' facts by kind (rejected approaches first, across lanes), then the repo-fact file pointers
+    const lanes = (facts?.lanes ?? []).map((l) => factsLines(l, l.ref));
+    for (const k of FACTS_RANK) for (const l of lanes) for (const line of l[k]) cand.push({ src: "facts", line: oneLine(line) });
+    for (const f of facts?.facts ?? []) cand.push({ src: "facts", line: `- ${f} (repo facts file; read it if relevant)` });
+  }
   const found = Object.fromEntries(CONTEXT_SOURCES.map((s) => [s, cand.filter((c) => c.src === s).length]));
-  const empty = { text: "", bytes: 0, items: 0, truncated: 0, sources: Object.fromEntries(CONTEXT_SOURCES.map((s) => [s, 0])), found, hash: null };
+  const empty = { text: "", bytes: 0, items: 0, truncated: 0, sources: Object.fromEntries(CONTEXT_SOURCES.map((s) => [s, 0])), found, hash: null, pitfalls: [] };
   if (!cand.length) return empty;
-  const titles = { graph: "Linked issues and PRs", attempts: "Prior attempts at this issue", ledger: "Merged PRs on the same symbols (reverts, decisions, findings)", facts: "Repo facts" };
+  const titles = { graph: "Linked issues and PRs", attempts: "Prior attempts at this issue", pitfalls: "Recurring pitfalls in this repo (past rework)", ledger: "Merged PRs on the same symbols (reverts, decisions, findings)", facts: "Facts from earlier lanes and repo facts" };
   const head = `Context pack for #${facts.issue}`;
   const size = (s) => Buffer.byteLength(s, "utf8");
   const kept = [];
@@ -301,7 +367,7 @@ export function compileContextPack(facts, { budgetBytes = DEFAULT_CONTEXT_BYTES,
     const secCost = kept.some((k) => k.src === c.src) ? 0 : size(`\n${titles[c.src]}:`) + 1;
     const pick = [c.full, c.line].find((t) => t && used + secCost + size(t) + 1 <= budgetBytes);
     if (!pick) { truncated++; continue; }
-    kept.push({ src: c.src, text: pick });
+    kept.push({ src: c.src, text: pick, pit: c.pit });
     used += secCost + size(pick) + 1;
   }
   if (!kept.length) return { ...empty, truncated };
@@ -311,13 +377,25 @@ export function compileContextPack(facts, { budgetBytes = DEFAULT_CONTEXT_BYTES,
     if (rows.length) parts.push(`\n${titles[s]}:`, ...rows.map((r) => r.text));
   }
   const text = parts.join("\n");
-  return { text, bytes: size(text), items: kept.length, truncated, sources: Object.fromEntries(CONTEXT_SOURCES.map((s) => [s, kept.filter((k) => k.src === s).length])), found, hash: hash12(text) };
+  return { text, bytes: size(text), items: kept.length, truncated, sources: Object.fromEntries(CONTEXT_SOURCES.map((s) => [s, kept.filter((k) => k.src === s).length])), found, hash: hash12(text), pitfalls: kept.filter((k) => k.pit).map((k) => k.pit) };
+}
+
+/** The pack text without its pitfalls section (#4375: pitfalls are local only and never posted). */
+export function publicPackText(text) {
+  const out = [];
+  let skip = false;
+  for (const l of String(text ?? "").split("\n")) {
+    if (/^[^\s-].*:$/.test(l)) skip = l === "Recurring pitfalls in this repo (past rework):";
+    else if (skip && l === "") skip = false;
+    if (!skip) out.push(l);
+  }
+  return out.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
 }
 
-/** The collapsed FORGE:CONTEXT issue record body (without the marker). */
+/** The collapsed FORGE:CONTEXT issue record body (without the marker); pitfalls show as a count only (#4375). */
 export function renderContextRecord(pack, { mode, laneType: lt }) {
-  const src = CONTEXT_SOURCES.map((s) => `${s} ${pack.sources[s]}/${pack.found[s]}`).join(", ");
-  return `<details><summary>Context pack: ${pack.items} item(s), ${pack.bytes} bytes, ${pack.truncated} dropped (mode ${mode}, lane ${lt}, hash ${pack.hash})</summary>\n\nSources (included/found): ${src}\n\n~~~~text\n${noComments(pack.text).replace(/~~~~/g, "~~~")}\n~~~~\n</details>`;
+  const src = CONTEXT_SOURCES.map((s) => `${s} ${pack.sources?.[s] ?? 0}/${pack.found?.[s] ?? 0}`).join(", ");
+  return `<details><summary>Context pack: ${pack.items} item(s), ${pack.bytes} bytes, ${pack.truncated} dropped (mode ${mode}, lane ${lt}, hash ${pack.hash})</summary>\n\nSources (included/found): ${src}${pack.sources?.pitfalls ? " (pitfalls are local only, not shown)" : ""}\n\n~~~~text\n${noComments(publicPackText(pack.text)).replace(/~~~~/g, "~~~")}\n~~~~\n</details>`;
 }
 
 /**
@@ -326,19 +404,19 @@ export function renderContextRecord(pack, { mode, laneType: lt }) {
  * reported source errors is not cached (#4298), the write goes through a temp file and a rename, and the issue's other
  * cached packs are pruned. A cache miss or any write/rename/prune failure is not an error.
  */
-export async function contextPackFor({ cfg, issue, headSha, cacheDir, fs, gather, stamp = {} }) {
-  const name = cacheDir && headSha ? contextPackCacheKey(issue, headSha, cfg, stamp) : null;
+export async function contextPackFor({ cfg, issue, repo = null, headSha, cacheDir, fs, gather, stamp = {} }) {
+  const name = cacheDir && headSha ? contextPackCacheKey(issue, headSha, cfg, stamp, repo) : null;
   const file = name ? join(cacheDir, name) : null;
   if (file && fs?.read) {
     try { const c = JSON.parse(await fs.read(file)); if (c?.pack && typeof c.pack.text === "string") return { ...c, cached: true }; } catch { /* miss */ }
   }
   const facts = await gather();
   const out = { pack: compileContextPack(facts, cfg), errors: facts?.errors ?? [] };
-  if (file && fs?.write && !out.errors.length) await cachePack(fs, cacheDir, file, name, issue, JSON.stringify(out));
+  if (file && fs?.write && !out.errors.length) await cachePack(fs, cacheDir, file, name, runLogKey(issue, repo), JSON.stringify(out));
   return { ...out, cached: false };
 }
 
-async function cachePack(fs, cacheDir, file, name, issue, text) {
+async function cachePack(fs, cacheDir, file, name, key, text) {
   try {
     if (typeof fs.rename === "function") {
       const tmp = `${file}.${process.pid}.tmp`;
@@ -348,7 +426,7 @@ async function cachePack(fs, cacheDir, file, name, issue, text) {
   } catch { return; /* cache is optional */ }
   if (typeof fs.list !== "function" || typeof fs.rm !== "function") return;
   try {
-    const prefix = `context-${issue}-`;
+    const prefix = `context-${key}-`;
     for (const f of await fs.list(cacheDir)) {
       if (f !== name && f.startsWith(prefix) && f.endsWith(".json")) { try { await fs.rm(join(cacheDir, f)); } catch { /* best effort */ } }
     }

package/bin/lean/context.test.mjs

@@ -2,7 +2,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { gatherContextFacts, compileContextPack, contextPackFor, contextPackCacheKey, linkStateStamp, parseContextPackConfig, laneType, priorAttempts, issueSymbols, bodyLinks, parentOf, renderContextRecord, DEFAULT_CONTEXT_BYTES, noComments } from "./context.mjs";
+import { normaliseFacts, renderFactsRecord, FACTS_MARKER } from "./facts.mjs";
+import { gatherContextFacts, compileContextPack, contextPackFor, contextPackCacheKey, linkStateStamp, LINK_STAMP_MAX, parseContextPackConfig, laneType, priorAttempts, issueSymbols, bodyLinks, parentOf, renderContextRecord, DEFAULT_CONTEXT_BYTES, noComments } from "./context.mjs";
 
 const REPO = "o/r";
 const BOT = { author_association: "NONE", user: { type: "Bot", login: "forge[bot]" } };
@@ -33,7 +34,7 @@ function fakes(o = {}) {
     101: [{ id: 2, body: "<!-- FORGE:DECISION -->\nKeep `compileContextPack` pure; I/O lives in gather.", ...BOT }],
     102: [],
     103: [{ id: 3, body: "<!-- FORGE:DECISION -->\nUnrelated decision about logging.", ...BOT }],
-    33: [{ id: 4, body: "<!-- FORGE:CONTRACT -->\nx", ...BOT }],
+    33: [{ id: 4, body: "<!-- FORGE:CONTRACT -->\nx", ...BOT }, ...(o.facts33 ?? [])],
   };
   const prs = { 101: { title: "feat: ranking", body: "Closes #33", head: "feat/issue-33-lean" }, 102: { title: "feat: speedup", body: "", head: "feat/issue-34-lean" }, 103: { title: "chore: logs", body: "", head: "x" } };
   const log = [
@@ -109,6 +110,21 @@ describe("context pack (forge#4275)", () => {
     assert.notEqual(contextPackCacheKey(50, "abc", cfg), contextPackCacheKey(51, "abc", cfg));
   });
 
+  it("#4432: the cache key and the prune prefix are repo-scoped, so another repo's pack for the same number survives", async () => {
+    const store = new Map();
+    const fs = { read: async (p) => { if (!store.has(p)) throw new Error("ENOENT"); return store.get(p); }, write: async (p, t) => { store.set(p, t); },
+      list: async () => [...store.keys()].map((p) => p.slice("/runs/".length)), rm: async (p) => { store.delete(p); } };
+    const cfg = parseContextPackConfig({});
+    const g = async () => gather(fakes());
+    assert.match(contextPackCacheKey(50, "abc", cfg, {}, "acme/one"), /^context-acme__one__50-abc-/);
+    assert.equal(contextPackCacheKey(50, "abc", cfg, {}), contextPackCacheKey(50, "abc", cfg), "no repo: today's key");
+    await contextPackFor({ cfg, issue: 50, repo: "acme/one", headSha: "abc", cacheDir: "/runs", fs, gather: g });
+    await contextPackFor({ cfg, issue: 50, repo: "acme/two", headSha: "def", cacheDir: "/runs", fs, gather: g });
+    assert.deepEqual([...store.keys()].map((k) => k.split("-").slice(0, 2).join("-")).sort(), ["/runs/context-acme__one__50", "/runs/context-acme__two__50"]);
+    const again = await contextPackFor({ cfg, issue: 50, repo: "acme/one", headSha: "abc", cacheDir: "/runs", fs, gather: g });
+    assert.equal(again.cached, true);
+  });
+
   it("drops whole items past the byte cap, falls back to one line for a parent body, counts truncation", async () => {
     const facts = await gather(fakes());
     const p = compileContextPack(facts, { budgetBytes: 130 });
@@ -121,7 +137,10 @@ describe("context pack (forge#4275)", () => {
     const f = fakes();
     const facts = await gather(f, { sources: ["graph", "facts"] });
     assert.equal(facts.ledger.length + facts.attempts.length, 0);
-    assert.ok(!f.calls.some((c) => c[1] === "log" || c[1] === "for-each-ref"), "a disabled source makes no calls");
+    assert.ok(!f.calls.some((c) => c[1] === "for-each-ref"), "a disabled source makes no calls");
+    const g = fakes();
+    await gather(g, { sources: ["graph"] });
+    assert.ok(!g.calls.some((c) => c[1] === "log" || c[1] === "for-each-ref"), "no ledger walk without the ledger or facts source (#4401)");
     const p = compileContextPack(facts, { sources: ["graph"] });
     assert.ok(p.text.includes("#40") && !p.text.includes("test-map"));
     assert.deepEqual(parseContextPackConfig({ sources: "ledger, bogus,graph" }).sources, ["graph", "ledger"]);
@@ -166,7 +185,9 @@ describe("context pack (forge#4275)", () => {
   });
 
   it("config, lane type and parsers", () => {
-    assert.deepEqual(parseContextPackConfig({}), { mode: "shadow", sources: ["graph", "attempts", "ledger", "facts"], budgetBytes: 6144, days: 30 });
+    assert.deepEqual(parseContextPackConfig({}), { mode: "shadow", sources: ["graph", "attempts", "pitfalls", "ledger", "facts"], budgetBytes: 6144, days: 30, pitfallLanes: 50 });
+    assert.equal(parseContextPackConfig({ pitfallLanes: 12 }).pitfallLanes, 12);
+    assert.equal(parseContextPackConfig({ pitfallLanes: -3 }).pitfallLanes, 50);
     assert.equal(parseContextPackConfig({ mode: "ON" }).mode, "on");
     assert.equal(parseContextPackConfig({ mode: "nope" }).mode, "shadow");
     assert.equal(laneType({ body: "x\n**Parent**: #3" }), "child");
@@ -183,7 +204,7 @@ describe("context pack (forge#4275)", () => {
     const p = compileContextPack(await gather(fakes()));
     const r = renderContextRecord(p, { mode: "shadow", laneType: "rerun" });
     assert.match(r, /^<details><summary>Context pack: \d+ item\(s\), \d+ bytes, 0 dropped \(mode shadow, lane rerun, hash [0-9a-f]{12}\)<\/summary>/);
-    assert.match(r, /Sources \(included\/found\): graph 5\/5, attempts 3\/3, ledger 3\/3, facts 1\/1/);
+    assert.match(r, /Sources \(included\/found\): graph 5\/5, attempts 3\/3, pitfalls 0\/0, ledger 3\/3, facts 1\/1/);
     assert.ok(r.includes(p.text));
   });
 });
@@ -221,20 +242,51 @@ describe("#4298 context-pack cache and shared names", () => {
     assert.notEqual(k({ scope: "aaa111", attempts: 1 }), k({ scope: "aaa111", attempts: 2 }));
   });
 
+  it("#4318: above LINK_STAMP_MAX the highest numbers are kept, still in one call", async () => {
+    const calls = [];
+    const gh = async (args) => { calls.push(args); return JSON.stringify({ data: { repository: {} } }); };
+    const body = Array.from({ length: LINK_STAMP_MAX + 5 }, (_, i) => `#${i + 1}`).join(" ");
+    await linkStateStamp({ gh, repo: "o/r", issue: 9999, body });
+    assert.equal(calls.length, 1);
+    const nums = [...(calls[0].find((x) => x.startsWith("query=")) ?? "").matchAll(/i(\d+):/g)].map((m) => Number(m[1]));
+    assert.equal(nums.length, LINK_STAMP_MAX);
+    assert.equal(nums[0], 6, "the lowest numbers are dropped");
+    assert.equal(nums.at(-1), LINK_STAMP_MAX + 5);
+  });
+
   it("#4316: linked-issue states are in the key; a state change recompiles; no links keeps the old key", async () => {
     const states = { 7: "open", 8: "open", 9: "closed" };
+    let rel = 2;
     const calls = [];
-    const gh = async (args) => { calls.push(args); const n = Number(/issues\/(\d+)$/.exec(args[1])?.[1]); if (n === 9 && states.fail9) throw new Error("HTTP 502"); return `${states[n]}\n`; };
+    // #4318: one GraphQL call; an alias per referenced number, plus the issue's own timeline relation count
+    const gh = async (args) => {
+      calls.push(args);
+      if (states.fail) throw new Error("HTTP 502");
+      const q = args.find((a) => a.startsWith("query=")) ?? "";
+      const repository = { self: { timelineItems: { totalCount: rel } } };
+      for (const m of q.matchAll(/i(\d+):issueOrPullRequest/g)) repository[`i${m[1]}`] = states[m[1]] ? { state: states[m[1]].toUpperCase() } : null;
+      return JSON.stringify({ data: { repository } });
+    };
+    const aliases = (a) => [...(a.find((x) => x.startsWith("query=")) ?? "").matchAll(/i(\d+):/g)].map((m) => Number(m[1]));
     const body = "**Parent**: #7\nDepends on #8\nSee #9 and #50 (self).";
     const s1 = await linkStateStamp({ gh, repo: "o/r", issue: 50, body });
     assert.match(s1, /^[0-9a-f]{12}$/);
-    assert.deepEqual(calls.map((a) => a[1]), ["repos/o/r/issues/7", "repos/o/r/issues/8", "repos/o/r/issues/9"], "parent, depends-on and links once each, never self");
+    assert.equal(calls.length, 1, "one call for every reference");
+    assert.deepEqual(calls[0].slice(0, 2), ["api", "graphql"]);
+    assert.deepEqual(aliases(calls[0]), [7, 8, 9], "parent, depends-on and links once each, never self");
+    assert.ok(calls[0].includes("o=o") && calls[0].includes("n=r"));
     assert.equal(await linkStateStamp({ gh, repo: "o/r", issue: 50, body }), s1, "stable");
     states[8] = "closed";
     const s2 = await linkStateStamp({ gh, repo: "o/r", issue: 50, body });
     assert.notEqual(s2, s1, "a linked issue closing changes the stamp");
-    states.fail9 = true;
-    assert.match(await linkStateStamp({ gh, repo: "o/r", issue: 50, body }), /^[0-9a-f]{12}$/, "an unreadable link never throws");
+    rel = 3;
+    assert.notEqual(await linkStateStamp({ gh, repo: "o/r", issue: 50, body }), s2, "a new timeline relation changes the stamp");
+    rel = 2;
+    states.fail = true;
+    const sf = await linkStateStamp({ gh, repo: "o/r", issue: 50, body });
+    assert.match(sf, /^[0-9a-f]{12}$/, "a failed call never throws");
+    assert.notEqual(sf, s2, "a failed call is n:? for every number");
+    delete states.fail;
     assert.equal(await linkStateStamp({ gh: async () => { throw new Error("x"); }, repo: "o/r", issue: 50, body: "no links here" }), "");
     const k = (s) => contextPackCacheKey(50, "abc", cfg, s);
     assert.equal(k({ scope: "s", attempts: 0, links: "" }), k({ scope: "s", attempts: 0 }), "no links: the pre-#4316 key");
@@ -303,5 +355,119 @@ describe("#4298 context-pack cache and shared names", () => {
     writeFileSync(`${d}/forge.yaml`, "engine:\n  context_pack: on\n");
     assert.deepEqual(readContextPack(d, (m) => warns.push(m)), { mode: "on" });
     assert.equal(warns.length, 1, "a valid mode does not warn");
+    writeFileSync(`${d}/forge.yaml`, "engine:\n  context_pack_pitfall_lanes: 20\n");
+    assert.deepEqual(readContextPack(d, (m) => warns.push(m)), { pitfallLanes: 20 }, "#4375: the pitfall aging window");
+  });
+});
+
+describe("#4375 recurring pitfalls in the context pack", () => {
+  const PITS = [
+    { sig: "precheck:aaaaaaaaaaaa", trigger: "precheck", lesson: "precheck: src/a.ts:12:5 error 'x' is defined but never used no-unused-vars", globs: ["src/*.ts"], count: 4, match: "files" },
+    { sig: "docs:bbbbbbbbbbbb", trigger: "docs", lesson: "docs: devdocs/modules/lean.md is stale for bin/lean/lean.mjs", globs: ["devdocs/modules/*.md"], count: 2, match: "repo" },
+  ];
+  const facts = (pitfalls) => gatherContextFacts({ io: { gh: async () => { throw new Error("no gh"); }, git: async () => "", exists: async () => false }, repo: REPO, issue: 50, iss: { number: 50, body: "plain" }, comments: [], cwd: "/wt", base: "origin/staging", sources: ["pitfalls"], pitfalls });
+
+  it("compiles the given pitfalls in order, inside the byte budget, and lists the kept signatures", async () => {
+    const p = compileContextPack(await facts(PITS));
+    assert.ok(p.text.includes("Recurring pitfalls in this repo (past rework):"), p.text);
+    const a = p.text.indexOf("[precheck]"), b = p.text.indexOf("[docs]");
+    assert.ok(a > 0 && b > a, p.text);
+    assert.ok(p.text.includes("(src/*.ts); seen 4×"));
+    assert.deepEqual(p.pitfalls, [{ sig: PITS[0].sig, match: "files" }, { sig: PITS[1].sig, match: "repo" }]);
+    assert.equal(p.sources.pitfalls, 2);
+    const small = compileContextPack(await facts(PITS), { budgetBytes: 200 });
+    assert.ok(small.bytes <= 200 && small.truncated >= 1, `${small.bytes} ${small.truncated}`);
+    assert.deepEqual(small.pitfalls, small.text.includes("[docs]") ? p.pitfalls : [p.pitfalls[0]]);
+    assert.equal(compileContextPack(await facts(PITS), { sources: ["graph"] }).pitfalls.length, 0, "source off: no pitfalls");
+  });
+
+  it("the posted FORGE:CONTEXT record never carries pitfall text, only the count", async () => {
+    const f = await gather(fakes());
+    const p = compileContextPack({ ...f, pitfalls: (await facts(PITS)).pitfalls });
+    assert.ok(p.text.includes("no-unused-vars"));
+    const r = renderContextRecord(p, { mode: "on", laneType: "first" });
+    for (const x of ["no-unused-vars", "Recurring pitfalls", "src/*.ts", "devdocs/modules/lean.md is stale"]) assert.ok(!r.includes(x), x);
+    assert.match(r, /pitfalls 2\/2/);
+    assert.ok(r.includes("Prior attempts at this issue:") && r.includes("Merged PRs on the same symbols"), "the other sections stay");
+  });
+
+  it("the cache key changes when the selected pitfall signatures change", () => {
+    const cfg = parseContextPackConfig({});
+    const k0 = contextPackCacheKey(50, "abc", cfg, { scope: "s", attempts: 0 });
+    assert.equal(contextPackCacheKey(50, "abc", cfg, { scope: "s", attempts: 0, pitfalls: [] }), k0, "no pitfalls: today's key");
+    const k1 = contextPackCacheKey(50, "abc", cfg, { scope: "s", attempts: 0, pitfalls: ["precheck:aaaaaaaaaaaa"] });
+    assert.notEqual(k1, k0);
+    assert.notEqual(contextPackCacheKey(50, "abc", cfg, { scope: "s", attempts: 0, pitfalls: ["precheck:aaaaaaaaaaaa", "docs:bbbbbbbbbbbb"] }), k1);
+  });
+
+  it("without pitfalls the pack text and hash are unchanged", async () => {
+    const f = await gather(fakes());
+    const a = compileContextPack(f), b = compileContextPack({ ...f, pitfalls: [] });
+    assert.equal(a.text, b.text); assert.equal(a.hash, b.hash);
+    assert.ok(!a.text.includes("Recurring pitfalls"));
+  });
+});
+
+describe("FORGE:FACTS in the context pack (#4401)", () => {
+  const rec = (files, approach, why = "it only hid the symptom") => `<!-- ${FACTS_MARKER} -->\n${renderFactsRecord(normaliseFacts({ facts: { rejected: [{ approach, why }], hotspots: [{ at: `${files[0]}:7`, why: "ranking loop" }] } }, { files }))}`;
+  const STRANGER = { author_association: "NONE", user: { type: "User", login: "rando" } };
+
+  it("a later lane on overlapping files receives the prior rejected approaches; the facts source is non-zero", async () => {
+    const f = fakes({ facts33: [
+      { id: 5, body: rec(["bin/lean/context.mjs"], "detection-only check"), ...BOT },
+      { id: 6, body: rec(["docs/other.md"], "unrelated file approach"), ...BOT },
+      { id: 7, body: rec(["bin/lean/context.mjs"], "forged by a stranger"), ...STRANGER },
+    ] });
+    const own = { id: "IC_9", body: rec(["bin/lean/context.mjs"], "own earlier attempt approach"), author: { login: "forge[bot]" }, authorAssociation: "NONE" };
+    const facts = await gather(f, { comments: [...COMMENTS, own] });
+    const p = compileContextPack(facts);
+    const t = p.text;
+    const at = (s) => { const i = t.indexOf(s); assert.ok(i >= 0, `missing ${s}\n${t}`); return i; };
+    const ownAt = at("- rejected: own earlier attempt approach — it only hid the symptom (#50 earlier attempt)");
+    const prior = at("- rejected: detection-only check — it only hid the symptom (#33, PR #101)");
+    const hot = at("- hot spot bin/lean/context.mjs:7: ranking loop (#33, PR #101)");
+    const ptr = at("- .forge/test-map.json");
+    assert.ok(ownAt < prior && prior < hot && hot < ptr, t);
+    assert.ok(t.includes("Facts from earlier lanes and repo facts:"));
+    assert.ok(!t.includes("unrelated file approach"), "a record on non-overlapping files is left out");
+    assert.ok(!t.includes("forged by a stranger"), "untrusted records are never read");
+    assert.equal(p.sources.facts, 5);
+    assert.equal(f.calls.filter((c) => c[0] === "gh" && c.some((x) => String(x).includes("pulls/101"))).length, 1, "ledger and facts share one read per PR");
+  });
+
+  it("works with the ledger source off and contributes nothing when no record exists", async () => {
+    const f = fakes({ facts33: [{ id: 5, body: rec(["bin/lean/context.mjs"], "detection-only check"), ...BOT }] });
+    const facts = await gather(f, { sources: ["facts"] });
+    assert.equal(facts.ledger.length, 0);
+    assert.ok(compileContextPack(facts, { sources: ["facts"] }).text.includes("detection-only check"));
+    const none = await gather(fakes(), { sources: ["facts"] });
+    assert.deepEqual([none.lanes, none.facts], [[], [".forge/test-map.json"]]);
+  });
+});
+
+describe("populated pack sources (#4400)", () => {
+  it("repo-fact files that exist only in the main checkout are listed; the worktree alone (the old lookup) lists none", async () => {
+    const io = (dir) => ({ ...fakes().io, exists: async (p) => p.startsWith(`${dir}/`) && (p.endsWith(".forge/repo-facts.json") || p.endsWith(".forge/test-map.json")) });
+    const inCheckout = await gather({ io: io("/main") }, { sources: ["facts"], checkout: "/main" });
+    assert.deepEqual(inCheckout.facts, [".forge/repo-facts.json", ".forge/test-map.json"]);
+    const worktreeOnly = await gather({ io: io("/main") }, { sources: ["facts"] });
+    assert.deepEqual(worktreeOnly.facts, []);
+    const both = await gather({ io: { ...fakes().io, exists: async (p) => p.endsWith(".forge/repo-facts.json") } }, { sources: ["facts"], checkout: "/main" });
+    assert.deepEqual(both.facts, [".forge/repo-facts.json"], "a file in both dirs is listed once");
+  });
+
+  it("an issue with a prior run, a ledger PR on its file and a FORGE:FACTS record has non-zero attempts, ledger and facts", async () => {
+    const rec = `<!-- ${FACTS_MARKER} -->\n${renderFactsRecord(normaliseFacts({ facts: { rejected: [{ approach: "retry only", why: "hid the race" }] } }, { files: ["bin/lean/context.mjs"] }))}`;
+    const f = fakes({ facts33: [{ id: 8, body: rec, ...BOT }] });
+    const p = compileContextPack(await gather(f, { checkout: "/main" }));
+    for (const s of ["attempts", "ledger", "facts"]) assert.ok(p.sources[s] > 0, `${s} is zero: ${JSON.stringify(p.sources)}`);
+  });
+});
+
+describe("#4467: priorAttempts reads App comments in gh issue view shape", () => {
+  const ghShape = (login) => ({ author: { login }, authorAssociation: "CONTRIBUTOR", body: "<!-- FORGE:NEEDS_HUMAN -->\nstuck" });
+  it("counts the App's NEEDS_HUMAN, not a stranger's", () => {
+    assert.equal(priorAttempts("", [ghShape("rapiercraft-forgedock")]), 1);
+    assert.equal(priorAttempts("", [ghShape("someone")]), 0);
   });
 });