@mrciphersmith/keryx 0.3.116 → 0.3.117

package/README.md

@@ -1154,7 +1154,7 @@ Every managed review start, attach or ingest (and any `dispatch-check` or `blast
 
 ### Gates that keep a review report honest
 
-`keryx review complete` on a pull-request package refuses a merged PR or a moved head until the first line of `report.md` names the reviewed SHA and says so, and refuses a report with no `Evidence level:` line (`static only — did not run: <what>` or `ran — <what>`; a package ingested before the field existed only warns). `keryx review ingest` reads each finding's quote at its `path` at the reviewed SHA and refuses one that does not resolve there, adds a `citation not found` line to a rebuttal that cites a rule or document missing from the tree (the finding is never deleted), and a finding can close as `narrowed` only with a "what remains" text. See [review with a record](docs/docs/guides/review-with-a-record.md).
+`keryx review complete` on a pull-request package (one that targets a PR, or whose `--ref` is a PR URL under any `--target`) refuses a merged PR or a moved head until the first line of `report.md` names the reviewed SHA and says so, and refuses a report with no `Evidence level:` line (`static only — did not run: <what>` or `ran — <what>`; a package ingested before the field existed only warns). `keryx review ingest` reads each finding's quote at its `path` at the reviewed SHA and refuses one that does not resolve there, adds a `citation not found` line to a rebuttal that cites a rule or document missing from the tree (the finding is never deleted), and a finding can close as `narrowed` only with a "what remains" text. See [review with a record](docs/docs/guides/review-with-a-record.md).
 
 ### Review bot on pull requests
 

package/dist/cli.js

@@ -23156,7 +23156,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@mrciphersmith/keryx",
-    version: "0.3.116",
+    version: "0.3.117",
     description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
     private: false,
     publishConfig: {
@@ -79130,7 +79130,7 @@ var init_rebuttal_citation = __esm(() => {
 // src/review/complete-head-gate.ts
 async function completeHeadGate(input) {
   const { target } = input.manifest;
-  if (target.kind !== "pr")
+  if (!isPrBound(target))
     return { warnings: [] };
   let pr;
   try {
@@ -79155,13 +79155,14 @@ async function completeHeadGate(input) {
     return { warnings: unusable };
   throw new Error(`Cannot complete managed review; ${what}. The report's first line must name the reviewed SHA${reviewed === null ? "" : ` (${reviewed.slice(0, 7)})`} and say the PR moved, for example: "Reviewed ${(reviewed ?? "<sha>").slice(0, 7)} \u2014 the PR has since ${merged ? "merged" : "moved on"}."`);
 }
-var MOVE_WORD = "(?:merged|moved|advanced|superseded|closed|force-pushed)", PR_WORD = "(?:pr|pull request|head)", SAYS_SO, USABLE_SHA, sameCommit = (a, b) => {
+var MOVE_WORD = "(?:merged|moved|advanced|superseded|closed|force-pushed)", PR_WORD = "(?:pr|pull request|head)", SAYS_SO, USABLE_SHA, PR_URL2, isPrBound = (target) => target.kind === "pr" || PR_URL2.test(target.ref), sameCommit = (a, b) => {
   const [x, y] = [a.toLowerCase(), b.toLowerCase()];
   return x.startsWith(y) || y.startsWith(x);
 };
 var init_complete_head_gate = __esm(() => {
   SAYS_SO = new RegExp(`\\b${PR_WORD}\\b.{0,40}\\b${MOVE_WORD}\\b|\\b${MOVE_WORD}\\b.{0,40}\\b${PR_WORD}\\b`, "i");
   USABLE_SHA = /^[0-9a-f]{7,40}$/i;
+  PR_URL2 = /github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+/;
 });
 
 // src/review/evidence-level.ts
@@ -80575,12 +80576,27 @@ async function reviewCompletionBlockers(packageDir) {
 async function completeManagedReview(cwd, ref, options = {}) {
   const packageDir = await resolveReviewPackagePath(cwd, ref);
   const manifestPath = path189.join(packageDir, "manifest.json");
-  const manifest = JSON.parse(await readFile99(manifestPath, "utf8"));
+  const stored = JSON.parse(await readFile99(manifestPath, "utf8"));
   const missing = await missingArtifacts(packageDir);
   if (missing.length > 0) {
     throw new Error(`Cannot complete managed review; missing artifacts: ${missing.join(", ")}`);
   }
   const warnings = [];
+  let manifest = stored;
+  if (options.head !== undefined) {
+    if (!isPrBound(stored.target)) {
+      throw new Error(`--head applies to a pull request package; ${stored.reviewId} targets a ${stored.target.kind}.`);
+    }
+    const head = options.head.trim().toLowerCase();
+    if (!/^[0-9a-f]{7,40}$/.test(head)) {
+      throw new Error(`--head "${options.head}" is not a commit SHA. Give the commit this round ran against, 7-40 hex characters.`);
+    }
+    const recordedHead = stored.target.head;
+    if (typeof recordedHead === "string" && recordedHead !== "" && !recordedHead.toLowerCase().startsWith(head) && !head.startsWith(recordedHead.toLowerCase())) {
+      warnings.push(`--head ${head.slice(0, 7)} replaces the head recorded when the round started (${recordedHead.slice(0, 7)}); the manifest now records ${head.slice(0, 7)}`);
+    }
+    manifest = { ...stored, target: { ...stored.target, head } };
+  }
   const reportText = await readFile99(path189.join(packageDir, "report.md"), "utf8");
   if (options.prLookup !== undefined)
     warnings.push(...(await completeHeadGate({ manifest, report: reportText, lookup: options.prLookup })).warnings);
@@ -99680,7 +99696,7 @@ function shellExecTool(root, run = makeCommandRunner(root), jobRegistry, options
     workingDirectory: root,
     definition: {
       name: "shell_exec",
-      description: "Run a shell command in the project root (e.g. `git status`, `bun test`). Requires the user's approval " + "before it runs. Input: { command: string, background?: boolean, description?: string, " + "idle_timeout_ms?: integer }. EVERY command returns within a bounded wait \u2014 a short one returns its " + "output directly, and one still running when the wait elapses keeps running as a task: you get " + "{task_id, pid, status, output} instead of its final output, and read the rest with " + "shell_job_output(task_id) and stop it with shell_job_kill(task_id). So a slow command never freezes " + "the session and never needs to be guessed at in advance. background:true only SKIPS the wait (use it " + "for a dev server or a watch build you know you will not read inline); it changes nothing else. " + "description is a short label for the task list. idle_timeout_ms is for a command that is deliberately " + "SILENT for a long time (a sleep, a slow poll) \u2014 a task that produces no output for its idle timeout " + "is killed, so raise it rather than lose the command. Output over 20,000 characters is saved in full to a " + "file: you see the head, the tail, the last lines of stderr, the line and byte counts of both streams " + "and the file's path, and read the rest with read_file or search_code on that path. Do not use " + "sed/grep/cat/awk here to locate code; use search_code or graph_symbol instead, which are built " + "for that and stay within the cap.",
+      description: "Run a shell command in the project root (e.g. `git status`, `bun test`). Requires the user's approval " + "before it runs. Input: { command: string, background?: boolean, description?: string, " + "idle_timeout_ms?: integer }. EVERY command returns within a bounded wait \u2014 a short one returns its " + "output directly, and one still running when the wait elapses keeps running as a task: you get " + "{task_id, pid, status, output} instead of its final output, and read the rest with " + "shell_job_output(task_id) and stop it with shell_job_kill(task_id). So a slow command never freezes " + "the session and never needs to be guessed at in advance. background:true only SKIPS the wait (use it " + "for a dev server or a watch build you know you will not read inline); it changes nothing else. " + "description is a short label for the task list. idle_timeout_ms is for a command that is deliberately " + "SILENT for a long time (a sleep, a slow poll) \u2014 a task that produces no output for its idle timeout " + "is killed, so raise it rather than lose the command. The accepted range is 1000 to 1800000 (30 minutes); " + "a value outside it is clamped and the result says so. A command that stays silent for longer than 30 " + "minutes cannot be kept alive this way: make it print progress, or start it detached from the shell " + "(`setsid nohup <command> > <log> 2>&1 &`) and read its log. Output over 20,000 characters is saved in full to a " + "file: you see the head, the tail, the last lines of stderr, the line and byte counts of both streams " + "and the file's path, and read the rest with read_file or search_code on that path. Do not use " + "sed/grep/cat/awk here to locate code; use search_code or graph_symbol instead, which are built " + "for that and stay within the cap.",
       inputSchema: {
         type: "object",
         properties: {
@@ -99707,11 +99723,18 @@ function shellExecTool(root, run = makeCommandRunner(root), jobRegistry, options
         return run(command, ctx?.signal !== undefined ? { signal: ctx.signal } : {});
       }
       const startOpts = { phase: background ? "background" : "foreground" };
+      let clampNote;
+      const withClamp = (notice) => clampNote === undefined ? notice : `${notice}; ${clampNote}`;
       if (typeof input.description === "string" && input.description.length > 0) {
         startOpts.description = input.description;
       }
       if (typeof input.idle_timeout_ms === "number") {
-        startOpts.idleTimeoutMs = clampTaskIdleTimeoutMs(input.idle_timeout_ms);
+        const effective = clampTaskIdleTimeoutMs(input.idle_timeout_ms);
+        startOpts.idleTimeoutMs = effective;
+        const requested = input.idle_timeout_ms;
+        if (requested > MAX_TASK_IDLE_TIMEOUT_MS || requested < MIN_TASK_IDLE_TIMEOUT_MS || Number.isNaN(requested)) {
+          clampNote = `idle_timeout_ms ${requested} was clamped to ${effective} (allowed ${MIN_TASK_IDLE_TIMEOUT_MS}-${MAX_TASK_IDLE_TIMEOUT_MS}); ` + (requested > MAX_TASK_IDLE_TIMEOUT_MS ? `a command silent for longer than ${MAX_TASK_IDLE_TIMEOUT_MS}ms is killed, so make it print progress or start it detached from the shell` : `a command silent for longer than ${effective}ms is killed`);
+        }
       }
       const started = await jobRegistry.start(command, startOpts);
       if (!started.ok) {
@@ -99723,7 +99746,7 @@ function shellExecTool(root, run = makeCommandRunner(root), jobRegistry, options
           taskId,
           pid: started.pid,
           output: started.output,
-          notice: `running as a background task; read new output with shell_job_output("${taskId}") and stop it with shell_job_kill("${taskId}")`
+          notice: withClamp(`running as a background task; read new output with shell_job_output("${taskId}") and stop it with shell_job_kill("${taskId}")`)
         });
       }
       const yieldMs = options?.yieldMs ?? resolveShellYieldMs();
@@ -99754,7 +99777,7 @@ function shellExecTool(root, run = makeCommandRunner(root), jobRegistry, options
           taskId,
           pid: started.pid,
           output: collected,
-          notice,
+          notice: withClamp(notice),
           ...promoted.overCap !== undefined ? { overCap: promoted.overCap } : {}
         });
       }
@@ -99768,14 +99791,15 @@ ${lost}` : lost, isError: true };
       const exitCode = info.exitCode ?? 0;
       const idleKilled = info.status === "killed" && info.killReason === "idle";
       const idleNotice = idleKilled ? `shell_exec: no output for ${info.idleTimeoutMs}ms, so the command was killed (raise it for this command with idle_timeout_ms, or change the default with ${ENV_SHELL_IDLE_MS})` : undefined;
+      const resultNotice = clampNote === undefined ? idleNotice : idleNotice === undefined ? `shell_exec: ${clampNote}` : `${idleNotice}; ${clampNote}`;
       const transcript = jobRegistry.takeTranscript?.(taskId);
       if (transcript !== undefined) {
-        return transcriptResult(transcript, info.status !== "completed", idleNotice, `(no output; exit ${exitCode})`);
+        return transcriptResult(transcript, info.status !== "completed", resultNotice, `(no output; exit ${exitCode})`);
       }
       const bounded = boundOutput2((info.outputHead ?? collected).trim());
       const body = bounded.length > 0 ? bounded : `(no output; exit ${exitCode})`;
-      const output = idleNotice !== undefined ? `${body}
-${idleNotice}` : body;
+      const output = resultNotice !== undefined ? `${body}
+${resultNotice}` : body;
       return { output, isError: info.status !== "completed" };
     }
   };
@@ -143690,7 +143714,7 @@ function exitCodeFor(status) {
   return AUTONOMOUS_EXIT[status];
 }
 function parseAutonomousTarget(ref) {
-  const match = PR_URL2.exec(ref.trim());
+  const match = PR_URL3.exec(ref.trim());
   if (match === null) {
     throw new Error(`--ref must be a pull request URL (https://github.com/<owner>/<repo>/pull/<number>), got: ${ref}`);
   }
@@ -143721,8 +143745,13 @@ function buildAutonomousPrompt(input) {
     `Open at most ${AUTONOMOUS_PROFILE.roundLimit} review rounds and dispatch at most ${AUTONOMOUS_PROFILE.waveSize} reviewers per wave. Stop opening rounds when a round finds no new blocker or major.`,
     `Dispatch the full reviewer set: run \`keryx review required --mode all\` and dispatch every reviewer it prints, with dispatch mode "all". Nobody can name a narrower review in a run like this, so do not use mode "diff".`,
     `Run the whole orchestration yourself in this session. A subagent has no shell and cannot dispatch reviewers (it answers BLOCKED nested_dispatch_unavailable), so hand a subagent only the review of one slice, never the orchestration, the ledger, the ingest or the complete.`,
+    `The review skills live in this clone under \`.metaproject/skills/gdskills/review/\` (the orchestration is \`review-orchestrator/SKILL.md\` there): read them from that path and do not search the filesystem or \`$HOME/.keryx\` for them.`,
+    `A guard refuses raw \`git diff\`, \`cat\`, \`sed\`, \`find\` and \`tail\` in the shell. Use \`keryx ctx diff\`, \`keryx ctx read <file>\` and \`keryx ctx run -- <command>\` instead, or end a command that must stay raw with \`# keryx:raw <why>\`.`,
     `The run is finished only when keryx review complete has closed the package.`
   ];
+  if (input.head !== undefined && input.head !== null) {
+    lines.push(`The pull request head is ${input.head}. Review exactly that commit, in a detached worktree at it, and pass \`--head ${input.head}\` to \`keryx review start\` (or attach) to \`keryx review ingest\` and to \`keryx review complete\`: without it keryx records the commit checked out in this directory, which is not the commit you reviewed, and the close is checked against that commit.`);
+  }
   if (input.resumePackage !== undefined) {
     lines.push(`A package for this pull request request already exists: ${input.resumePackage}. Resume it and continue from where it stopped instead of starting a new one.`);
   }
@@ -143732,7 +143761,10 @@ function buildAutonomousPrompt(input) {
 function isFloorRefusal(output) {
   return FLOOR_REFUSAL_PATTERNS.some((pattern) => pattern.test(output));
 }
-var AUTONOMOUS_PROFILE_ID = "review-autonomous", AUTONOMOUS_PROFILE, AUTONOMOUS_STATUSES, AUTONOMOUS_EXIT, PR_URL2, FLOOR_REFUSAL_PATTERNS;
+function isLoopGuardRefusal(output) {
+  return LOOP_GUARD_REFUSAL.test(output);
+}
+var AUTONOMOUS_PROFILE_ID = "review-autonomous", AUTONOMOUS_PROFILE, AUTONOMOUS_STATUSES, AUTONOMOUS_EXIT, PR_URL3, FLOOR_REFUSAL_PATTERNS, LOOP_GUARD_REFUSAL;
 var init_autonomous_profile = __esm(() => {
   init_review_system();
   AUTONOMOUS_PROFILE = {
@@ -143752,17 +143784,18 @@ var init_autonomous_profile = __esm(() => {
     budget: 4,
     stalled: 5
   };
-  PR_URL2 = /^https:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/(\d+)\/?$/;
+  PR_URL3 = /^https:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/(\d+)\/?$/;
   FLOOR_REFUSAL_PATTERNS = [
     /not approved by the user; not executed/i,
     new RegExp(REFUSED_EARLIER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i")
   ];
+  LOOP_GUARD_REFUSAL = /same tool call already tried \d+\u00D7 \(hash budget\)/;
 });
 
 // src/review/autonomous-progress.ts
 import { closeSync as closeSync9, existsSync as existsSync58, openSync as openSync9, readSync as readSync5, statSync as statSync18 } from "fs";
 function emptyProgress() {
-  return { toolCalls: 0, openCalls: 0, phase: "starting", tokens: 0, usageSum: 0, rounds: 0, turnEnded: false, floorRefusals: [] };
+  return { toolCalls: 0, openCalls: 0, phase: "starting", tokens: 0, usageSum: 0, rounds: 0, turnEnded: false, floorRefusals: [], endedOnLoopGuard: false };
 }
 function phaseOf(tool, rawInput) {
   try {
@@ -143800,6 +143833,7 @@ function foldEvent(state, event) {
       return {
         ...state,
         openCalls: Math.max(0, state.openCalls - 1),
+        endedOnLoopGuard: event.isError === true && isLoopGuardRefusal(output),
         floorRefusals: refused ? [...state.floorRefusals, { phase: state.phase, output }] : state.floorRefusals
       };
     }
@@ -144111,7 +144145,7 @@ async function runLocked2(options, target, runDir) {
   const startedAt = new Date(startedAtMs).toISOString();
   const spec = {
     argv: buildAutonomousShellArgv({
-      prompt: buildAutonomousPrompt({ ref: target.ref, resumePackage }),
+      prompt: buildAutonomousPrompt({ ref: target.ref, resumePackage, head }),
       eventsFile,
       provider: options.provider,
       model: options.model
@@ -144249,7 +144283,8 @@ async function runLocked2(options, target, runDir) {
   } else if (progress.floorRefusals.length > 0) {
     status = "floor";
     const first = progress.floorRefusals[0];
-    reason = `a floor refused ${progress.floorRefusals.length} call(s) nobody could approve (first at ${first.phase}) and the package was not closed`;
+    const refused = `a floor refused ${progress.floorRefusals.length} call(s) nobody could approve (first at ${first.phase})`;
+    reason = progress.endedOnLoopGuard ? `the loop guard stopped a repeated call at ${progress.phase} after ${refused} and the package was not closed` : `${refused} and the package was not closed`;
   } else if (found === undefined) {
     status = "incomplete";
     reason = `the shell ended (exit ${exitCode ?? 1}) before a review package was opened`;
@@ -197206,6 +197241,44 @@ function parseRunArgs(args) {
     json: args.includes("--json")
   };
 }
+function createHeartbeat(write, now = Date.now, minGapMs = HEARTBEAT_MIN_GAP_MS, keepAliveMs) {
+  let lastKey = "";
+  let lastAt = Number.NEGATIVE_INFINITY;
+  let latest = { state: "running", phase: "starting", rounds: 0, tokens: 0 };
+  let timer;
+  let stopped = false;
+  const emit = (progress) => {
+    lastKey = `${progress.phase}|${progress.rounds}|${progress.tokens}`;
+    lastAt = now();
+    write(`heartbeat: phase ${progress.phase}, ${progress.rounds} round(s), ${progress.tokens} tokens`);
+    arm();
+  };
+  const arm = () => {
+    if (keepAliveMs === undefined || stopped)
+      return;
+    if (timer !== undefined)
+      clearTimeout(timer);
+    timer = setTimeout(() => emit(latest), keepAliveMs);
+    timer.unref?.();
+  };
+  const beat = (progress) => {
+    if (stopped || progress.state !== "running")
+      return;
+    latest = progress;
+    const key = `${progress.phase}|${progress.rounds}|${progress.tokens}`;
+    if (key === lastKey || now() - lastAt < minGapMs)
+      return;
+    emit(progress);
+  };
+  beat.stop = () => {
+    stopped = true;
+    if (timer !== undefined)
+      clearTimeout(timer);
+    timer = undefined;
+  };
+  arm();
+  return beat;
+}
 async function runReviewRunCommand(args, deps = {}) {
   const log = deps.log ?? ((line) => console.log(line));
   const error = deps.error ?? ((line) => console.error(line));
@@ -197224,6 +197297,7 @@ async function runReviewRunCommand(args, deps = {}) {
   const target = parseAutonomousTarget(parsed.ref);
   const notifier = deps.notifier ?? (parsed.notify ? createTelegramNotifier({ project: path379.basename(cwd), target }) : NO_NOTIFIER);
   const run = deps.run ?? runAutonomousReview;
+  const heartbeat = createHeartbeat(error, deps.now, undefined, deps.keepAliveMs ?? HEARTBEAT_KEEPALIVE_MS);
   const stop = new AbortController;
   const onSignal = () => stop.abort();
   process.on("SIGTERM", onSignal);
@@ -197234,6 +197308,7 @@ async function runReviewRunCommand(args, deps = {}) {
       cwd,
       ref: parsed.ref,
       signal: stop.signal,
+      onProgress: heartbeat,
       stallMs: parsed.stallMinutes * 60000,
       ...parsed.budgetMinutes === undefined ? {} : { budgetMinutes: parsed.budgetMinutes },
       ...parsed.budgetTokens === undefined ? {} : { budgetTokens: parsed.budgetTokens },
@@ -197260,6 +197335,7 @@ async function runReviewRunCommand(args, deps = {}) {
     error(problem instanceof Error ? problem.message : String(problem));
     return 1;
   } finally {
+    heartbeat.stop();
     process.off("SIGTERM", onSignal);
     process.off("SIGINT", onSignal);
     await notifier.close();
@@ -197268,7 +197344,7 @@ async function runReviewRunCommand(args, deps = {}) {
 async function runReviewRun(args) {
   process.exitCode = await runReviewRunCommand(args);
 }
-var RUN_FLAGS, RUN_USAGE2 = "keryx review run --autonomous --target pr --ref <pull request URL> [--budget-minutes N] [--budget-tokens N] [--stall-minutes N] [--out <dir>] [--provider p] [--model m] [--no-notify] [--json]", RUN_HELP;
+var RUN_FLAGS, RUN_USAGE2 = "keryx review run --autonomous --target pr --ref <pull request URL> [--budget-minutes N] [--budget-tokens N] [--stall-minutes N] [--out <dir>] [--provider p] [--model m] [--no-notify] [--json]", RUN_HELP, HEARTBEAT_MIN_GAP_MS = 60000, HEARTBEAT_KEEPALIVE_MS = 60000;
 var init_review_run = __esm(() => {
   init_args();
   init_review_notify();
@@ -197294,7 +197370,11 @@ var init_review_run = __esm(() => {
 
 Runs one review of a pull request with nobody at the keyboard, in the review-autonomous profile.
 Exit codes: 0 complete, 2 incomplete, 3 stopped at a floor, 4 budget spent, 5 stalled, 1 refused
-(bad arguments, or another run of the same pull request holds the lock).`;
+(bad arguments, or another run of the same pull request holds the lock).
+While it runs it writes a "heartbeat:" line to stderr when the phase, round count or token count
+changes (at most one a minute), and again whenever a minute passes with no line, so a wrapper with an
+idle timeout sees the run is alive. Also with --json, whose verdict is the only thing on stdout.
+A run that really stalls is still stopped by --stall-minutes (exit 5), and the lines end with it.`;
 });
 
 // src/review/ledger.ts
@@ -202420,6 +202500,10 @@ async function runComplete3(args, seams) {
     throw new Error("Usage: keryx review complete <review-id-or-path>");
   }
   const dispositions = parseDispositions(args);
+  const headFlag = flagTokens(args).find((token) => token.name === "--head");
+  if (headFlag !== undefined && (headFlag.value === undefined || headFlag.value.trim() === "")) {
+    throw new Error("--head needs a commit SHA: --head <sha> (the commit this round ran against, 7-40 hex characters).");
+  }
   const waiver = flagTokens(args).find((token) => token.name === "--waive-coverage");
   if (waiver !== undefined && (waiver.value === undefined || waiver.value.trim() === "")) {
     throw new Error(`--waive-coverage needs the operator's own words: --waive-coverage "<operator quote>".`);
@@ -202434,7 +202518,7 @@ async function runComplete3(args, seams) {
     dispositions: tally,
     coverageWaiver,
     warnings
-  } = await completeManagedReview(process.cwd(), ref, { dispositions, prLookup: seams?.prLookup ?? trackerPrLookup, ...waiver?.value === undefined ? {} : { waiveCoverage: waiver.value } });
+  } = await completeManagedReview(process.cwd(), ref, { dispositions, prLookup: seams?.prLookup ?? trackerPrLookup, ...waiver?.value === undefined ? {} : { waiveCoverage: waiver.value }, ...headFlag?.value === undefined ? {} : { head: headFlag.value } });
   for (const warning of warnings)
     console.error(`warning: ${warning}`);
   if (coverageWaiver !== undefined) {
@@ -202478,7 +202562,7 @@ function parseDispositions(args) {
     if (token.value === undefined) {
       throw new Error(`${token.name} needs a value.`);
     }
-    if (token.name === "--waive-coverage") {
+    if (token.name === "--waive-coverage" || token.name === "--head") {
       continue;
     }
     if (token.name === "--finding") {
@@ -202805,7 +202889,7 @@ ${COMMENTS_USAGE}
   keryx review report-parity <review-id-or-path>
   keryx review complete <review-id-or-path>
                         [--finding <id> --disposition <state> --evidence <text>]...
-                        [--waive-coverage "<operator quote>"]
+                        [--waive-coverage "<operator quote>"] [--head <sha>]
   keryx review lightweight
 
 An unrecognised option is REFUSED, not ignored. A flag that is silently dropped
@@ -202822,6 +202906,11 @@ Modes:
   the tree the reviewers actually read, which is deliberately preferred over a
   \`pr\` target's own head so that a round run against something other than what
   will merge FAILS the gate instead of passing it.
+  \`review complete --head <sha>\` names the commit the round actually reviewed
+  when the one recorded at start is wrong or missing; the head gate then checks
+  that commit, and the manifest records it. The gate is not loosened: a head that
+  is not the pull request's head still needs the report's first line to name it
+  and say the PR moved.
 
 scope:
   Deterministic pre-filter, no model call. Drops generated, lockfile, snapshot,
@@ -203276,7 +203365,7 @@ var init_review = __esm(() => {
     "--catalog",
     "--json"
   ];
-  COMPLETE_FLAGS = ["--finding", "--disposition", "--evidence", "--waive-coverage"];
+  COMPLETE_FLAGS = ["--finding", "--disposition", "--evidence", "--waive-coverage", "--head"];
   STACK_FLAGS = ["--json"];
   REVIEWERS_FLAGS = ["--json"];
   COMPARE_REFERENCE_FLAGS = ["--reference", "--package", "--input", "--json"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.116",
+  "version": "0.3.117",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {