@gobing-ai/spur 0.4.1 → 0.4.2

package/plugins/sp/lib/transcript.ts

@@ -34,6 +34,12 @@ export interface Row {
     isMeta?: boolean;
     isCompactSummary?: boolean;
     id?: string; // pi: the row id doubles as the once-per-message usage key
+    /** pi `custom_message` body: a hook-relayed prompt's text. */
+    content?: string;
+    /** pi `custom_message` visibility; `false` keeps the row out of the operator-visible transcript. */
+    display?: boolean;
+    /** pi `custom_message` producer id (e.g. a hook), carried for diagnostics only. */
+    customType?: string;
     message?: {
         id?: string;
         role?: string;
@@ -88,17 +94,32 @@ export function formatTokenSplit(t: Tokens | null): string {
     return `${formatTokens(nonCached + t.cacheRead)} / ${formatTokens(nonCached)}`;
 }
 
-/** Operator prompt text, or undefined for tool results, meta rows and compaction summaries. */
+/**
+ * Operator prompt text, or undefined for tool results, meta rows and compaction summaries.
+ *
+ * pi (1151 R1/R3): pi records the OPERATOR'S own `/skill` invocation as a user message that opens
+ * with `<skill name="X" …>` and whose arguments follow the closing tag — it does not inject skill
+ * bodies as user rows (a 2,452-row census of local transcripts found none; the one synthetic
+ * body-only fixture row had no real counterpart). Every such row is therefore an operator prompt,
+ * rendered `/X <args>`; an ARGUMENT-LESS wrapper is still an invocation and renders `/X` (the skill
+ * name is the stage label the review groups by, so arguments alone would lose which command ran).
+ *
+ * pi (1151 follow-up): a hook-relayed `custom_message` (`display: true`) is a real operator prompt —
+ * the host shows it and the agent answers it — so it opens a segment like typed text; a
+ * `display: false` row is a host-only notice and stays non-segmenting activity.
+ */
 export function promptText(row: Row): string | undefined {
+    if (row.type === 'custom_message') {
+        if (row.display === false) return undefined;
+        const text = typeof row.content === 'string' ? row.content.trim() : '';
+        return text === '' ? undefined : text;
+    }
     if (row.type === 'message') {
         // pi (1130): only a user-role message with text content is a prompt; toolResult rows are not.
         if (row.message?.role !== 'user') return undefined;
-        // pi (1138 R2): a skill-injected body is activity, not an operator prompt.
-        if (isInjectedPrompt(row)) return undefined;
-        const content = row.message.content;
-        if (typeof content === 'string') return content;
-        if (!Array.isArray(content)) return undefined;
-        return (content as Block[]).find((b) => b.type === 'text')?.text;
+        const text = firstTextContent(row);
+        if (text === undefined) return undefined;
+        return skillInvocationPrompt(text) ?? text;
     }
     if (row.type !== 'user' || row.isMeta || row.isCompactSummary) return undefined;
     const content = row.message?.content;
@@ -107,22 +128,29 @@ export function promptText(row: Row): string | undefined {
     return (content as Block[]).find((b) => b.type === 'text')?.text;
 }
 
+/** First `type:text` block of a pi message, or its string content. */
+function firstTextContent(row: Row): string | undefined {
+    const content = row.message?.content;
+    if (typeof content === 'string') return content;
+    if (!Array.isArray(content)) return undefined;
+    return (content as Block[]).find((b) => b.type === 'text')?.text;
+}
+
 /**
- * 1138 R2: a pi user row whose first text block, after leading whitespace, opens with
- * `<skill name="`, is an injected body (pi has no `isMeta` to key on). It is accumulated as
- * activity and must not open a segment. Operator text that merely CONTAINS `<skill` later in the
- * body is still a prompt. Claude rows are unaffected: their injected bodies already arrive as `isMeta`.
+ * 1151 R1: `/X <args>` for a pi operator `/skill` invocation wrapper, undefined for anything else.
+ *
+ * The wrapper is `^\s*<skill name="X"` — the anchored, complete quoted name is the only signal;
+ * text that merely CONTAINS `<skill` later in the body stays plain operator text. Arguments are the
+ * text after the LAST `</skill>` (a body may itself quote the tag); a wrapper with no closing tag
+ * renders `/X` alone rather than dumping the body as the prompt. A malformed name (no closing quote)
+ * is not a wrapper.
  */
-export function isInjectedPrompt(row: Row): boolean {
-    if (row.type !== 'message' || row.message?.role !== 'user') return false;
-    const content = row.message.content;
-    const text =
-        typeof content === 'string'
-            ? content
-            : Array.isArray(content)
-              ? (content as Block[]).find((b) => b.type === 'text')?.text
-              : undefined;
-    return typeof text === 'string' && text.replace(/^\s+/, '').startsWith('<skill name="');
+export function skillInvocationPrompt(text: string): string | undefined {
+    const name = /^\s*<skill name="([^"]+)"/.exec(text)?.[1];
+    if (name === undefined) return undefined;
+    const close = text.lastIndexOf('</skill>');
+    const args = close < 0 ? '' : text.slice(close + '</skill>'.length).trim();
+    return args === '' ? `/${name}` : `/${name} ${args}`;
 }
 
 export function sumTokens(all: Tokens[]): Tokens {

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.4.1",
+    "version": "0.4.2",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/references/roles.md

@@ -62,7 +62,7 @@ roles:
     stages: [verify, review, dogfood]
   - id: planner
     tier: capable-2
-    commands: [dev-plan, dev-refine, dev-brainstorm, dev-find-way, dev-idea, dev-runall, dev-parallel, dev-next, dev-job-resume, dev-arch, dev-refineall, dev-find-next, dev-feature-change]
+    commands: [dev-plan, dev-refine, dev-brainstorm, dev-find-way, dev-idea, dev-runall, dev-next, dev-job-resume, dev-arch, dev-refineall, dev-find-next, dev-feature-change]
     stages: [plan, refine, brainstorm]
 ```
 

package/plugins/sp/scripts/batch-plan.mjs

@@ -222,6 +222,118 @@ function buildBatchPlan(tasks) {
   }
   return waves;
 }
+var byWbs = (a, b) => a.localeCompare(b, "en", { numeric: true });
+function kahnOrder(nodes, preds) {
+  const indegree = new Map(nodes.map((n) => [n, preds.get(n)?.size ?? 0]));
+  const succ = new Map(nodes.map((n) => [n, []]));
+  for (const [n, ps] of preds)
+    for (const p of ps)
+      succ.get(p)?.push(n);
+  const ready = nodes.filter((n) => indegree.get(n) === 0).sort(byWbs);
+  const order = [];
+  for (let n = ready.shift();n !== undefined; n = ready.shift()) {
+    order.push(n);
+    for (const s of succ.get(n) ?? []) {
+      const d = (indegree.get(s) ?? 0) - 1;
+      indegree.set(s, d);
+      if (d === 0) {
+        ready.push(s);
+        ready.sort(byWbs);
+      }
+    }
+  }
+  return order;
+}
+function findCycle(remaining, preds) {
+  const state = new Map;
+  const stack = [];
+  const visit = (n) => {
+    state.set(n, "visiting");
+    stack.push(n);
+    for (const p of [...preds.get(n) ?? []].sort(byWbs)) {
+      if (!remaining.has(p))
+        continue;
+      if (state.get(p) === "visiting")
+        return [...stack.slice(stack.indexOf(p)), p];
+      if (!state.has(p)) {
+        const cycle = visit(p);
+        if (cycle)
+          return cycle;
+      }
+    }
+    stack.pop();
+    state.set(n, "done");
+    return null;
+  };
+  for (const n of [...remaining].sort(byWbs)) {
+    if (state.has(n))
+      continue;
+    const cycle = visit(n);
+    if (cycle)
+      return cycle;
+  }
+  return [];
+}
+function scheduleBatch(tasks, opts = {}) {
+  const byId = new Map;
+  for (const t of tasks)
+    if (!byId.has(t.wbs))
+      byId.set(t.wbs, t);
+  const nodes = [...byId.keys()].sort(byWbs);
+  const preds = new Map(nodes.map((n) => [n, new Set((byId.get(n)?.dependencies ?? []).filter((d) => byId.has(d)))]));
+  const depOrder = kahnOrder(nodes, preds);
+  if (depOrder.length < nodes.length) {
+    const cycle = findCycle(new Set(nodes.filter((n) => !depOrder.includes(n))), preds);
+    return {
+      order: [],
+      waves: [],
+      cycle,
+      overlaps: [],
+      mode: "sequential",
+      reason: `dependency cycle ${cycle.join(" → ")}`
+    };
+  }
+  const files = new Map(nodes.map((n) => [n, new Set((byId.get(n)?.files ?? []).map(normalizeTaskPath))]));
+  const overlaps = [];
+  for (let i = 0;i < depOrder.length; i++) {
+    const before = depOrder[i];
+    const beforeFiles = files.get(before) ?? new Set;
+    for (const after of depOrder.slice(i + 1)) {
+      const shared = [...beforeFiles].filter((f) => files.get(after)?.has(f)).sort();
+      if (shared.length === 0)
+        continue;
+      overlaps.push({ before, after, files: shared });
+      preds.get(after)?.add(before);
+    }
+  }
+  const order = kahnOrder(nodes, preds);
+  const level = new Map;
+  for (const n of order) {
+    let l = 0;
+    for (const p of preds.get(n) ?? [])
+      l = Math.max(l, (level.get(p) ?? 0) + 1);
+    level.set(n, l);
+  }
+  const waves = [];
+  for (const n of order) {
+    const l = level.get(n) ?? 0;
+    waves[l] = [...waves[l] ?? [], n].sort(byWbs);
+  }
+  const widest = Math.max(0, ...waves.map((w) => w.length));
+  const concurrency = opts.concurrency ?? 2;
+  let reason = `widest wave holds ${widest} independent tasks`;
+  if (nodes.length < 2)
+    reason = "fewer than two tasks";
+  else if (concurrency < 2)
+    reason = "concurrency is 1";
+  else if (widest < 2)
+    reason = "every wave holds one task (dependency or file-overlap chain)";
+  const mode = nodes.length >= 2 && concurrency >= 2 && widest >= 2 ? "parallel" : "sequential";
+  return { order, waves, cycle: null, overlaps, mode, reason };
+}
+function normalizeTaskPath(path) {
+  return path.trim().replace(/^\.\//, "");
+}
 function taskPhaseChildren(taskLetter, plan) {
   if (!Array.isArray(plan))
     return [];
@@ -250,13 +362,22 @@ function hostText(item) {
 }
 
 // plugins/sp/scripts/batch-plan.ts
-var BATCH_PLAN_USAGE = "usage: batch-plan.ts waves --tasks <tasks.json> | task-children --letter <A-Z> --plan <plan.json>";
+var BATCH_PLAN_USAGE = "usage: batch-plan.ts waves --tasks <tasks.json> | order --tasks <tasks.json> [--concurrency <n>] | task-children --letter <A-Z> --plan <plan.json>";
 function readJsonFile(path) {
   return JSON.parse(readFileSync(path, "utf8"));
 }
 function isBatchTask(value) {
   return typeof value === "object" && value !== null && typeof value.wbs === "string" && typeof value.name === "string";
 }
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+function isScheduleTask(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const t = value;
+  return typeof t.wbs === "string" && (t.dependencies === undefined || isStringArray(t.dependencies)) && (t.files === undefined || isStringArray(t.files));
+}
 function main(argv) {
   const mode = argv[0];
   if (mode === "waves") {
@@ -279,6 +400,37 @@ function main(argv) {
       return 1;
     }
     process.stdout.write(`${JSON.stringify({ waves: buildBatchPlan(tasks) })}
+`);
+    return 0;
+  }
+  if (mode === "order") {
+    let tasksPath = "";
+    let concurrency = 2;
+    for (let i = 1;i + 1 < argv.length; i += 2) {
+      if (argv[i] === "--tasks")
+        tasksPath = argv[i + 1] ?? "";
+      else if (argv[i] === "--concurrency")
+        concurrency = Number(argv[i + 1]);
+    }
+    if (tasksPath === "" || !Number.isInteger(concurrency) || concurrency < 1) {
+      process.stderr.write(`${BATCH_PLAN_USAGE}
+`);
+      return 2;
+    }
+    let tasks;
+    try {
+      tasks = readJsonFile(tasksPath);
+    } catch (error) {
+      process.stderr.write(`batch-plan: cannot read ${tasksPath} \u2014 ${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+    if (!Array.isArray(tasks) || !tasks.every(isScheduleTask)) {
+      process.stderr.write(`batch-plan: --tasks file must be a JSON array of {wbs, dependencies?, files?}
+`);
+      return 1;
+    }
+    process.stdout.write(`${JSON.stringify(scheduleBatch(tasks, { concurrency }))}
 `);
     return 0;
   }
@@ -323,6 +475,7 @@ function main(argv) {
 export {
   validatePhaseTable,
   taskPhaseChildren,
+  scheduleBatch,
   planLetter,
   planChild,
   main,

package/plugins/sp/scripts/batch-plan.ts

@@ -9,6 +9,10 @@
  * Modes:
  *   waves --tasks <file>  file: JSON array of {wbs, name}; prints `{ waves: [...] }` — waves
  *                         of 24 tasks as A Prepare batch + A1..A4 + B..Y task rows + Z Batch report.
+ *   order --tasks <file> [--concurrency <n>]
+ *                         file: JSON array of {wbs, dependencies?, files?}; prints the scheduleBatch
+ *                         result `{ order, waves, cycle, overlaps, mode, reason }` (dev-runall §2.4
+ *                         order + the --mode auto recommendation). A cycle is data, not an error.
  *   task-children --letter <A-Z> --plan <file>
  *                         file: a `workflow show --format todo --json` payload (or a bare plan
  *                         array); prints the task's phase digits as a JSON array.
@@ -16,13 +20,13 @@
  * `node batch-plan.mjs` (committed twin) — keep the twin in lockstep.
  */
 import { readFileSync } from 'node:fs';
-import type { BatchTask, PhasedPlanItem } from '../lib/plan-projection.generated.mjs';
-import { buildBatchPlan, taskPhaseChildren } from '../lib/plan-projection.generated.mjs';
+import type { BatchTask, PhasedPlanItem, ScheduleTask } from '../lib/plan-projection.generated.mjs';
+import { buildBatchPlan, scheduleBatch, taskPhaseChildren } from '../lib/plan-projection.generated.mjs';
 
 export * from '../lib/plan-projection.generated.mjs';
 
 export const BATCH_PLAN_USAGE =
-    'usage: batch-plan.ts waves --tasks <tasks.json> | task-children --letter <A-Z> --plan <plan.json>';
+    'usage: batch-plan.ts waves --tasks <tasks.json> | order --tasks <tasks.json> [--concurrency <n>] | task-children --letter <A-Z> --plan <plan.json>';
 
 function readJsonFile(path: string): unknown {
     return JSON.parse(readFileSync(path, 'utf8'));
@@ -37,6 +41,20 @@ function isBatchTask(value: unknown): value is BatchTask {
     );
 }
 
+function isStringArray(value: unknown): value is string[] {
+    return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+
+function isScheduleTask(value: unknown): value is ScheduleTask {
+    if (typeof value !== 'object' || value === null) return false;
+    const t = value as ScheduleTask;
+    return (
+        typeof t.wbs === 'string' &&
+        (t.dependencies === undefined || isStringArray(t.dependencies)) &&
+        (t.files === undefined || isStringArray(t.files))
+    );
+}
+
 export function main(argv: string[]): number {
     const mode = argv[0];
     if (mode === 'waves') {
@@ -60,6 +78,33 @@ export function main(argv: string[]): number {
         process.stdout.write(`${JSON.stringify({ waves: buildBatchPlan(tasks) })}\n`);
         return 0;
     }
+    if (mode === 'order') {
+        let tasksPath = '';
+        let concurrency = 2;
+        for (let i = 1; i + 1 < argv.length; i += 2) {
+            if (argv[i] === '--tasks') tasksPath = argv[i + 1] ?? '';
+            else if (argv[i] === '--concurrency') concurrency = Number(argv[i + 1]);
+        }
+        if (tasksPath === '' || !Number.isInteger(concurrency) || concurrency < 1) {
+            process.stderr.write(`${BATCH_PLAN_USAGE}\n`);
+            return 2;
+        }
+        let tasks: unknown;
+        try {
+            tasks = readJsonFile(tasksPath);
+        } catch (error) {
+            process.stderr.write(
+                `batch-plan: cannot read ${tasksPath} — ${error instanceof Error ? error.message : String(error)}\n`,
+            );
+            return 1;
+        }
+        if (!Array.isArray(tasks) || !tasks.every(isScheduleTask)) {
+            process.stderr.write('batch-plan: --tasks file must be a JSON array of {wbs, dependencies?, files?}\n');
+            return 1;
+        }
+        process.stdout.write(`${JSON.stringify(scheduleBatch(tasks, { concurrency }))}\n`);
+        return 0;
+    }
     if (mode === 'task-children') {
         let letter = '';
         let planPath = '';

package/plugins/sp/scripts/inline-run-setup.mjs

@@ -60,17 +60,19 @@ function formatTokenSplit(t) {
   return `${formatTokens(nonCached + t.cacheRead)} / ${formatTokens(nonCached)}`;
 }
 function promptText(row) {
+  if (row.type === "custom_message") {
+    if (row.display === false)
+      return;
+    const text = typeof row.content === "string" ? row.content.trim() : "";
+    return text === "" ? undefined : text;
+  }
   if (row.type === "message") {
     if (row.message?.role !== "user")
       return;
-    if (isInjectedPrompt(row))
-      return;
-    const content2 = row.message.content;
-    if (typeof content2 === "string")
-      return content2;
-    if (!Array.isArray(content2))
+    const text = firstTextContent(row);
+    if (text === undefined)
       return;
-    return content2.find((b) => b.type === "text")?.text;
+    return skillInvocationPrompt(text) ?? text;
   }
   if (row.type !== "user" || row.isMeta || row.isCompactSummary)
     return;
@@ -81,12 +83,21 @@ function promptText(row) {
     return;
   return content.find((b) => b.type === "text")?.text;
 }
-function isInjectedPrompt(row) {
-  if (row.type !== "message" || row.message?.role !== "user")
-    return false;
-  const content = row.message.content;
-  const text = typeof content === "string" ? content : Array.isArray(content) ? content.find((b) => b.type === "text")?.text : undefined;
-  return typeof text === "string" && text.replace(/^\s+/, "").startsWith('<skill name="');
+function firstTextContent(row) {
+  const content = row.message?.content;
+  if (typeof content === "string")
+    return content;
+  if (!Array.isArray(content))
+    return;
+  return content.find((b) => b.type === "text")?.text;
+}
+function skillInvocationPrompt(text) {
+  const name = /^\s*<skill name="([^"]+)"/.exec(text)?.[1];
+  if (name === undefined)
+    return;
+  const close = text.lastIndexOf("</skill>");
+  const args = close < 0 ? "" : text.slice(close + "</skill>".length).trim();
+  return args === "" ? `/${name}` : `/${name} ${args}`;
 }
 function sumTokens(all) {
   const total = zeroTokens();

package/plugins/sp/scripts/pr-reviewing.mjs

@@ -480,6 +480,15 @@ ${requestMarker(pr.headRefOid)}`;
   writeStatus(args, "REQUESTED");
   emit(args, { ok: true, requested: true, pr: pr.number, url: pr.url, head: pr.headRefOid, requestedAt, body }, `Requested GitHub Codex review on PR #${pr.number} (${pr.url}) at HEAD ${pr.headRefOid.slice(0, 7)}.`);
 }
+function revalidateWaitTarget(args, number) {
+  const fresh = viewPr();
+  if (!fresh || fresh.number !== number) {
+    writeStatus(args, "FAIL");
+    fail(args, `PR #${number} is no longer the branch's PR (view reports ${fresh ? `#${fresh.number}` : "none"}) \u2014 request a fresh review`, 2);
+  }
+  requireExpectedHead(args, fresh);
+  return fresh;
+}
 function cmdWait(args) {
   const since = args.flags.get("--since") ?? new Date().toISOString();
   const timeoutSec = Number(args.flags.get("--timeout") ?? "600");
@@ -494,24 +503,29 @@ function cmdWait(args) {
     writeStatus(args, "FAIL");
     fail(args, "no PR for the current branch", 2);
   }
+  const number = pr.number;
   requireExpectedHead(args, pr);
   const deadline = Date.now() + timeoutSec * 1000;
   for (;; ) {
-    const reviews = fetchReviews(ctx, pr.number);
-    const findings = normalizeFindings(reviews, fetchInlineComments(ctx, pr.number), fetchIssueComments(ctx, pr.number), since, pr.headRefOid);
+    const observed = revalidateWaitTarget(args, number);
+    const reviews = fetchReviews(ctx, number);
+    const findings = normalizeFindings(reviews, fetchInlineComments(ctx, number), fetchIssueComments(ctx, number), since, observed.headRefOid);
     if (findings.length > 0) {
+      revalidateWaitTarget(args, number);
       writeStatus(args, "FOUND");
       emit(args, { ok: true, verdict: "FOUND", findings }, renderFindings(findings));
       return;
     }
-    if (hasCurrentCleanReview(reviews, since, pr.headRefOid)) {
+    if (hasCurrentCleanReview(reviews, since, observed.headRefOid)) {
+      const fresh = revalidateWaitTarget(args, number);
       writeStatus(args, "CLEAN");
-      emit(args, { ok: true, verdict: "CLEAN", pr: pr.number, url: pr.url, head: pr.headRefOid, findings: [] }, `Codex review completed cleanly for HEAD ${pr.headRefOid.slice(0, 7)}.`);
+      emit(args, { ok: true, verdict: "CLEAN", pr: fresh.number, url: fresh.url, head: fresh.headRefOid, findings: [] }, `Codex review completed cleanly for HEAD ${fresh.headRefOid.slice(0, 7)}.`);
       return;
     }
     if (Date.now() >= deadline) {
+      revalidateWaitTarget(args, number);
       writeStatus(args, "TIMEOUT");
-      emit(args, { ok: true, verdict: "TIMEOUT", pr: pr.number, url: pr.url }, `No Codex review within ${timeoutSec}s \u2014 still pending. Collect later with /sp:dev-pr-review collect.
+      emit(args, { ok: true, verdict: "TIMEOUT", pr: number, url: pr.url }, `No Codex review within ${timeoutSec}s \u2014 still pending. Collect later with /sp:dev-pr-review collect.
 PR: ${pr.url}`);
       throw new ScriptExit("", 3, args.booleans.has("--json"));
     }

package/plugins/sp/scripts/pr-reviewing.ts

@@ -703,6 +703,26 @@ function cmdRequest(args: ParsedArgs): void {
     );
 }
 
+/**
+ * 1161 R1: re-read the PR and re-assert the pinned identity + expected head. Called at the start of
+ * every poll and again immediately before any FOUND/CLEAN/TIMEOUT status or output, because a head
+ * captured once at wait start lets a later push return CLEAN for an old commit. A vanished PR, a
+ * different PR on the branch, or a moved head is FAIL/exit2 through the existing error channel.
+ */
+function revalidateWaitTarget(args: ParsedArgs, number: number): GhPr {
+    const fresh = viewPr();
+    if (!fresh || fresh.number !== number) {
+        writeStatus(args, 'FAIL');
+        fail(
+            args,
+            `PR #${number} is no longer the branch's PR (view reports ${fresh ? `#${fresh.number}` : 'none'}) — request a fresh review`,
+            2,
+        );
+    }
+    requireExpectedHead(args, fresh);
+    return fresh;
+}
+
 function cmdWait(args: ParsedArgs): void {
     const since = args.flags.get('--since') ?? new Date().toISOString();
     const timeoutSec = Number(args.flags.get('--timeout') ?? '600');
@@ -715,36 +735,41 @@ function cmdWait(args: ParsedArgs): void {
         writeStatus(args, 'FAIL');
         fail(args, 'no PR for the current branch', 2);
     }
+    const number = pr.number; // 1161 R1: pinned — a switched PR number is a failure, not a retarget.
     requireExpectedHead(args, pr);
-    const deadline = Date.now() + timeoutSec * 1000;
+    const deadline = Date.now() + timeoutSec * 1000; // fixed once; validation never resets it
     for (;;) {
-        const reviews = fetchReviews(ctx, pr.number);
+        const observed = revalidateWaitTarget(args, number);
+        const reviews = fetchReviews(ctx, number);
         const findings = normalizeFindings(
             reviews,
-            fetchInlineComments(ctx, pr.number),
-            fetchIssueComments(ctx, pr.number),
+            fetchInlineComments(ctx, number),
+            fetchIssueComments(ctx, number),
             since,
-            pr.headRefOid,
+            observed.headRefOid,
         );
         if (findings.length > 0) {
+            revalidateWaitTarget(args, number); // pre-return recheck: never FOUND for a moved head
             writeStatus(args, 'FOUND');
             emit(args, { ok: true, verdict: 'FOUND', findings }, renderFindings(findings));
             return;
         }
-        if (hasCurrentCleanReview(reviews, since, pr.headRefOid)) {
+        if (hasCurrentCleanReview(reviews, since, observed.headRefOid)) {
+            const fresh = revalidateWaitTarget(args, number); // pre-return recheck: never CLEAN for a moved head
             writeStatus(args, 'CLEAN');
             emit(
                 args,
-                { ok: true, verdict: 'CLEAN', pr: pr.number, url: pr.url, head: pr.headRefOid, findings: [] },
-                `Codex review completed cleanly for HEAD ${pr.headRefOid.slice(0, 7)}.`,
+                { ok: true, verdict: 'CLEAN', pr: fresh.number, url: fresh.url, head: fresh.headRefOid, findings: [] },
+                `Codex review completed cleanly for HEAD ${fresh.headRefOid.slice(0, 7)}.`,
             );
             return;
         }
         if (Date.now() >= deadline) {
+            revalidateWaitTarget(args, number); // a head moved while pending is a failure, not a timeout
             writeStatus(args, 'TIMEOUT');
             emit(
                 args,
-                { ok: true, verdict: 'TIMEOUT', pr: pr.number, url: pr.url },
+                { ok: true, verdict: 'TIMEOUT', pr: number, url: pr.url },
                 `No Codex review within ${timeoutSec}s — still pending. Collect later with /sp:dev-pr-review collect.\nPR: ${pr.url}`,
             );
             throw new ScriptExit('', 3, args.booleans.has('--json'));