@mgiles/perk 3.2.0 → 3.3.0

package/extension/substrate/worktreeResolverLock.ts

@@ -0,0 +1,261 @@
+// Participating submit/address writers exclude each other by canonical worktree Git identity.
+// There is NO reclamation policy. Death, age, reload and cancellation cannot prove quiescence.
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  openSync,
+  readSync,
+  type Stats,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { worktreeGitDir } from "./git.ts";
+
+const OWNER_LIMIT = 16 * 1024;
+export const WORKTREE_RESOLVER_LOCK = "perk-submit-conflict.lock";
+
+interface LockRecord {
+  schema: 1;
+  token: string;
+  pid: number;
+  parentSessionId: string;
+  ownerRunId: string;
+  requestId: string;
+  worktreeIdentity: string;
+  createdAt: string;
+}
+export type LockOwner = Omit<LockRecord, "token" | "schema">;
+export type LockFinish = {
+  kind: "released" | "retained" | "ownership-error" | "io-error";
+  path: string;
+};
+export interface WorktreeResolverClaim {
+  readonly path: string;
+  check(): "owned" | "ownership-error" | "io-error";
+  /** First choice wins, locally idempotent. Retain closes resources but never removes metadata. */
+  finish(disposition: "release" | "retain"): LockFinish;
+}
+export type WorktreeResolverAcquisition =
+  | { kind: "acquired"; claim: WorktreeResolverClaim }
+  | { kind: "unavailable" }
+  | { kind: "busy"; path: string; owner?: LockOwner }
+  | { kind: "io-error"; path: string; residue: boolean };
+
+/** Only deterministic filesystem fault tests substitute these operations. */
+export interface WorktreeLockFs {
+  open: typeof openSync;
+  close: typeof closeSync;
+  fstat: (fd: number) => Stats;
+  lstat: (path: string) => Stats;
+  read: (fd: number, buffer: Buffer, offset: number, length: number, position: number) => number;
+  write: (fd: number, data: string) => void;
+  sync: (fd: number) => void;
+  unlink: (path: string) => void;
+}
+const realFs: WorktreeLockFs = {
+  open: openSync,
+  close: closeSync,
+  fstat: fstatSync,
+  lstat: lstatSync,
+  read: readSync,
+  write: (fd, data) => writeFileSync(fd, data, "utf8"),
+  sync: fsyncSync,
+  unlink: unlinkSync,
+};
+function code(error: unknown): unknown {
+  return typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+}
+function sameFile(a: Stats, b: Stats): boolean {
+  return a.isFile() && b.isFile() && a.dev === b.dev && a.ino === b.ino;
+}
+function readRecord(fs: WorktreeLockFs, fd: number): LockRecord | null {
+  const size = fs.fstat(fd).size;
+  if (size <= 0 || size > OWNER_LIMIT) return null;
+  const bytes = Buffer.alloc(size);
+  let read = 0;
+  while (read < size) {
+    const n = fs.read(fd, bytes, read, size - read, read);
+    if (n === 0) return null;
+    read += n;
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const r = raw as Record<string, unknown>;
+  if (
+    r.schema !== 1 ||
+    typeof r.token !== "string" ||
+    !r.token ||
+    typeof r.pid !== "number" ||
+    !Number.isInteger(r.pid) ||
+    r.pid <= 0
+  )
+    return null;
+  for (const field of [
+    "parentSessionId",
+    "ownerRunId",
+    "requestId",
+    "worktreeIdentity",
+    "createdAt",
+  ] as const) {
+    if (typeof r[field] !== "string" || !r[field]) return null;
+  }
+  return r as unknown as LockRecord;
+}
+function ownerOf(r: LockRecord): LockOwner {
+  return {
+    pid: r.pid,
+    parentSessionId: r.parentSessionId,
+    ownerRunId: r.ownerRunId,
+    requestId: r.requestId,
+    worktreeIdentity: r.worktreeIdentity,
+    createdAt: r.createdAt,
+  };
+}
+
+function incumbent(fs: WorktreeLockFs, path: string): WorktreeResolverAcquisition {
+  let fd: number | undefined;
+  try {
+    const stat = fs.lstat(path);
+    if (!stat.isFile() || stat.size > OWNER_LIMIT) return { kind: "busy", path };
+    fd = fs.open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    if (!sameFile(stat, fs.fstat(fd))) return { kind: "busy", path };
+    const record = readRecord(fs, fd);
+    return { kind: "busy", path, ...(record ? { owner: ownerOf(record) } : {}) };
+  } catch (error) {
+    // Even a disappearing incumbent doesn't invite a retry. A racing external replacement is
+    // outside the protocol; ELOOP never follows the new symlink for diagnostic reads.
+    if (code(error) === "ENOENT" || code(error) === "ELOOP") return { kind: "busy", path };
+    return { kind: "io-error", path, residue: true };
+  } finally {
+    if (fd !== undefined) fs.close(fd);
+  }
+}
+
+export function acquireWorktreeResolverLock(
+  cwd: string,
+  parent: { sessionId: string; runId: string; requestId: string },
+  opts: {
+    fs?: Partial<WorktreeLockFs>;
+    gitDir?: (cwd: string) => string | null;
+    /** The token minter (default `randomUUID`) — only deterministic fault tests substitute it. */
+    token?: () => string;
+  } = {},
+): WorktreeResolverAcquisition {
+  const identity = (opts.gitDir ?? worktreeGitDir)(cwd);
+  if (identity === null) return { kind: "unavailable" };
+  const path = join(identity, WORKTREE_RESOLVER_LOCK);
+  const fs = { ...realFs, ...opts.fs };
+  let fd: number;
+  try {
+    fd = fs.open(path, "wx", 0o600);
+  } catch (error) {
+    if (code(error) === "EEXIST") {
+      try {
+        return incumbent(fs, path);
+      } catch {
+        return { kind: "io-error", path, residue: true };
+      }
+    }
+    return { kind: "io-error", path, residue: false };
+  }
+  // Everything after the exclusive create runs inside the cleanup-protected block — the record
+  // construction included: a token-minting failure must take the same identity-fenced unlink
+  // path as a write failure, never escape with the descriptor open and an empty lock file that
+  // would wedge every later acquisition as busy.
+  let stat: Stats | undefined;
+  let token: string;
+  try {
+    stat = fs.fstat(fd);
+    if (!stat.isFile()) throw new Error("not a regular file");
+    token = (opts.token ?? randomUUID)();
+    const record: LockRecord = {
+      schema: 1,
+      token,
+      pid: process.pid,
+      parentSessionId: parent.sessionId,
+      ownerRunId: parent.runId,
+      requestId: parent.requestId,
+      worktreeIdentity: identity,
+      createdAt: new Date().toISOString(),
+    };
+    fs.write(fd, `${JSON.stringify(record)}\n`);
+    fs.sync(fd);
+  } catch {
+    let residue = true;
+    try {
+      if (stat && sameFile(stat, fs.lstat(path))) {
+        fs.unlink(path);
+        residue = false;
+      }
+    } catch {
+      /* Report residue; never remove an unidentified or successor file. */
+    }
+    try {
+      fs.close(fd);
+    } catch {
+      residue = true;
+    }
+    return { kind: "io-error", path, residue };
+  }
+  const acquiredStat = stat;
+  let finished: LockFinish | undefined;
+  function check(): "owned" | "ownership-error" | "io-error" {
+    if (finished) return "ownership-error";
+    try {
+      if (!sameFile(acquiredStat, fs.lstat(path)) || !sameFile(acquiredStat, fs.fstat(fd)))
+        return "ownership-error";
+      const reader = fs.open(
+        path,
+        constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+      );
+      try {
+        if (!sameFile(acquiredStat, fs.fstat(reader))) return "ownership-error";
+        return readRecord(fs, reader)?.token === token ? "owned" : "ownership-error";
+      } finally {
+        fs.close(reader);
+      }
+    } catch (error) {
+      return code(error) === "ENOENT" ? "ownership-error" : "io-error";
+    }
+  }
+  return {
+    kind: "acquired",
+    claim: {
+      path,
+      check,
+      finish(disposition) {
+        if (finished) return finished;
+        let kind: LockFinish["kind"] = "retained";
+        try {
+          if (disposition === "release") {
+            const ownership = check();
+            if (ownership === "owned") {
+              fs.unlink(path);
+              kind = "released";
+            } else kind = ownership;
+          }
+        } catch {
+          kind = "io-error";
+        } finally {
+          try {
+            fs.close(fd);
+          } catch {
+            kind = "io-error";
+          }
+        }
+        finished = { kind, path };
+        return finished;
+      },
+    },
+  };
+}

package/extension/surfaces/surfaces.ts

@@ -6,11 +6,11 @@
 // surfaces module" is surfaces.ts + report.ts for the surfaces guard).
 //
 // Perk status (charter §6 D2): perk presents ONE footer status under the single
-// `perk` slot — the single-value objective segment (the checkpoint substrate is retired, so
-// there is no composition step). The per-feature status slots and widgets are retired (D8
-// sanctioned). The perk-owned footer (`perkFooter`/`installPerkFooter` below) renders the value
-// directly; the `perk` status slot keeps publishing — it is the RPC-visible surface (setFooter
-// is an RPC no-op).
+// `perk` slot — the objective segment composed with the ref-counted activity facet
+// (`<objective> · <activity>`, either half optional). The per-feature status slots and widgets
+// are retired (D8 sanctioned). The perk-owned footer (`perkFooter`/`installPerkFooter` below)
+// renders the value directly; the `perk` status slot keeps publishing — it is the RPC-visible
+// surface (setFooter is an RPC no-op).
 
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { ReportDetailSink } from "./report.ts";
@@ -35,6 +35,19 @@ export const STATUS_SLOT_PERK = "perk";
 // --- footer identity marks (charter §5 / D3: emoji are footer-only identity, 2 cells wide) ---
 export const MARK_OBJECTIVE = "🎯";
 
+// --- activity vocabulary (the optional second half of the composed `perk` status) ---
+// Plain text, no emoji (D3 keeps emoji as identity marks): a Perk-owned wait the operator
+// cannot otherwise see.
+export const ACTIVITY_BROWSER_REVIEW = "waiting on browser review";
+/** The slice an activity owner takes: begin a wait with its text, receive the matching `end`. */
+export type ActivitySink = (text: string) => () => void;
+/**
+ * The least-capable slice a wiring layer threads toward an activity owner: begin a wait against
+ * the live target, nothing else. The full `PerkStatusHandle` stays at the composition root, the
+ * objective publisher and the footer.
+ */
+export type ActivityHandle = Pick<PerkStatusHandle, "beginActivity">;
+
 // --- glyph vocabulary (charter §5 / D3) — charter-law data, pinned by tests ---
 export type GlyphKind = "done" | "current" | "pending" | "warning" | "failure";
 export const GLYPHS: Record<GlyphKind, { glyph: string; themeColor: string }> = {
@@ -101,41 +114,80 @@ export function setWorkingMessage(target: WorkingMessageTarget, message?: string
 // --- the perk status (charter D2) --------------------------------------------
 
 /**
- * The single-value status handle: the objective publisher sets the one value through `set`, and
- * the handle republishes the single `perk` status slot. The footer reads the value back via `get`
- * and repaints via `subscribe` — the slot's `setStatus` dual-publish is deliberate (RPC clients
- * see the slot; setFooter is an RPC no-op).
+ * The composed status handle: the objective publisher sets its half through `set`, activity
+ * owners hold ref-counted waits through `beginActivity`, and the handle republishes the single
+ * `perk` status slot with the composed value. The footer reads it back via `get` and repaints via
+ * `subscribe` — the slot's `setStatus` dual-publish is deliberate (RPC clients see the slot;
+ * setFooter is an RPC no-op).
  */
 export interface PerkStatusHandle {
-  /** Set (or clear, with undefined) the one value; publishes the slot. No-op headless. */
+  /** Set (or clear, with undefined) the objective half; publishes the slot. No-op headless. */
   set(target: StandingTarget, text: string | undefined): void;
-  /** The current text (undefined when unset). */
+  /**
+   * Begin one activity wait: the newest live wait's text shows while any begun wait is unended;
+   * returns this wait's `end` (idempotent; inert after a reset — no publish). No-op headless
+   * (returns a no-op `end`, records nothing).
+   */
+  beginActivity(target: StandingTarget, text: string): () => void;
+  /** Reset every wait (session shutdown); a late `end` of a reset wait is inert. No-op headless. */
+  clearActivity(target: StandingTarget): void;
+  /** The composed value (`<objective> · <activity>`, either half optional; undefined when neither). */
   get(): string | undefined;
   /**
-   * Subscribe to publishes: the listener fires after every headful `set` (headless `set`
-   * calls are full no-ops, so nothing fires). Returns an unsubscribe.
+   * Subscribe to publishes: the listener fires after every headful `set`, begin, end and clear
+   * (headless calls are full no-ops, so nothing fires). Returns an unsubscribe.
    */
   subscribe(listener: () => void): () => void;
 }
 
 /**
- * Create the single-value `perk` status handle (one per extension instance — created in index.ts
- * and passed to the objective publisher; no hidden module state). Headless calls are full no-ops
- * (never record the text, so headless-era text can't resurrect in a later headful render).
- * `undefined` clears the slot. No width handling: pi's footer truncates the status line itself.
+ * Create the composed `perk` status handle (one per extension instance — created in index.ts
+ * and passed to the objective publisher and the activity owners; no hidden module state).
+ * Headless calls are full no-ops (never record text, so headless-era text can't resurrect in a
+ * later headful render). The activity is a SET of live wait tokens, not a set/clear: the browser
+ * doors accept a concurrent double-open, so an older wait's settle must not blank a newer one —
+ * the text clears only when the LAST wait ends (the newest live wait's text shows meanwhile, so
+ * ending one restores the remainder). An ended or reset token is simply absent, so its late `end`
+ * finds nothing to remove and publishes nothing — a wait begun after a reset can never be
+ * consumed by a stale `end`. No width handling: pi's footer truncates.
  */
 export function createPerkStatus(): PerkStatusHandle {
-  let value: string | undefined;
+  let objective: string | undefined;
+  const live = new Set<{ text: string }>(); // insertion-ordered: the last entry is the newest
   const listeners = new Set<() => void>();
+  const compose = (): string | undefined => {
+    const activity = [...live].at(-1)?.text;
+    const halves = [objective, activity].filter((half) => half !== undefined);
+    return halves.length === 0 ? undefined : halves.join(" · ");
+  };
+  const publish = (target: StandingTarget): void => {
+    target.ui.setStatus(STATUS_SLOT_PERK, compose());
+    for (const listener of listeners) listener();
+  };
   return {
     set(target, text) {
       if (!target.hasUI) return;
-      value = text;
-      target.ui.setStatus(STATUS_SLOT_PERK, text);
-      for (const listener of listeners) listener();
+      objective = text;
+      publish(target);
+    },
+    beginActivity(target, text) {
+      if (!target.hasUI) return () => {};
+      const token = { text };
+      live.add(token);
+      publish(target);
+      return () => {
+        // Already ended, or reset by `clearActivity`: nothing to remove, nothing to publish.
+        if (!live.delete(token)) return;
+        publish(target);
+      };
+    },
+    clearActivity(target) {
+      if (!target.hasUI) return;
+      live.clear();
+      publish(target);
     },
     get() {
-      return value;
+      return compose();
     },
     subscribe(listener) {
       listeners.add(listener);
@@ -155,7 +207,7 @@ export function createPerkStatus(): PerkStatusHandle {
 export interface FooterParts {
   /** e.g. `perk v0.0.1` — standing identity (D7), dim. */
   identity: string;
-  /** The 🎯 objective segment, verbatim (`handle.get()`). */
+  /** The composed perk status value (`handle.get()`), verbatim — it carries its own 🎯 mark. */
   objective?: string;
   /** Git branch (dim); omitted when not in a repo. */
   branch?: string;
@@ -329,9 +381,9 @@ export type PerkFooterFactory = (
 /**
  * The perk-owned footer factory (charter D2): replaces pi's default footer wholesale with one
  * line in the intended split layout. `render` gathers everything live per call (D10 stateless
- * render): the objective value via the handle, branch/guests via `footerData` (excluding perk's
- * own `STATUS_SLOT_PERK` — the slot keeps publishing for RPC, but the footer renders the value
- * directly), model/cache/context via the deps closures. Reactivity (the D2 contract): repaints on
+ * render): the composed status value via the handle, branch/guests via `footerData` (excluding
+ * perk's own `STATUS_SLOT_PERK` — the slot keeps publishing for RPC, but the footer renders the
+ * value directly), model/cache/context via the deps closures. Reactivity (the D2 contract): repaints on
  * every handle recompose and on branch change; `dispose` detaches both. Lifecycle (pi ≥ 0.84,
  * verified at 0.84.1): `setExtensionFooter` disposes a replaced factory's component, and pi's
  * `resetExtensionUI` restores the built-in footer (disposing this one) on /reload and before
@@ -412,7 +464,7 @@ export function formatBudgetLine(args: { tokens: number; elapsedMs: number }): s
 }
 
 // --- display-only transcript entry renderers -----------------------------------------------------
-// The audit §2.3 verdict (docs/design/pi-adoption-audit.md): perk's custom-entry families are
+// The audit §2.3 verdict (docs/design/archive/pi-adoption-audit.md): perk's custom-entry families are
 // display-only. Most render as durable one-line transition markers; report detail is the generic
 // full-diagnostic family and always renders every logical row. Renderer BODIES live here (a
 // transcript renderer IS a rich-UI surface the surfaces module owns); registration is wiring at the

package/extension/waves/adversarialReviewWave.ts

@@ -1,29 +1,31 @@
-// The adversarial-review `WaveSpec`-building entrypoint over the shared report-wave runner — the
-// human-in-the-loop review doors' (/pr-review-browser, /pr-review-terminal) vocabulary as tested
-// code (sibling of `prReviewWave.ts`): the four door angles, the per-lane completion-report
-// schema, and the lane/task composition are module-owned here, launched NON-BLOCKING via
-// `startReportWave` so the parent can return from the launch and hold the model-held
-// `subagent_wait` relay loop open while the children stream finding batches.
+// The adversarial-review `ReportWaveRequest`-building entrypoint over the shared report-wave
+// module — the human-in-the-loop review doors' (/pr-review-browser, /pr-review-terminal)
+// vocabulary as tested code (sibling of `prReviewWave.ts`): the four door angles, the per-lane
+// completion-report schema, and the lane/task composition are module-owned here, launched
+// NON-BLOCKING via `wave.start` so the parent ends its turn after launch and relays batches
+// on native supervisor wakes before collecting on the matching workflow-completion notice.
 //
 // ZERO retries — deliberate: the doors' contract is honest incompleteness surfaced to the human
 // during triage (an `ok: false` lane is reported, never papered over), so the pr-review
 // bounded-retry policy does not carry over.
 //
-// The surface handle (URL/port) is STRUCTURALLY UNREPRESENTABLE: `buildAdversarialReviewLanes`
-// has no URL parameter at all, so the children can never learn the review surface — enforced by
-// construction, pinned by the suite.
+// The surface handle (URL/port) is STRUCTURALLY UNREPRESENTABLE:
+// `buildAdversarialReviewAssignments` has no URL parameter at all, so the children can never
+// learn the review surface — enforced by construction, pinned by the suite.
 //
 // Driven live by the registered `start_review_wave` / `collect_review_wave` tool pair
-// (`extension/doors/reviewWaveTools.ts`); the `agents/adversarial-reviewer.md` def completes via
+// (`extension/pi/v1/codeReview/reviewWave.ts`); the `agents/adversarial-reviewer.md` def completes via
 // the `structured_output` tool this wave's `outputSchema` injects per lane.
 
+import { reclassifyBlockedReports } from "./blockedReports.ts";
 import { PONYTAIL_REVIEW_SKILL } from "./ponytail.ts";
-import {
-  type ReportWaveStart,
-  startReportWave,
-  type WaveAdapter,
-  type WaveLane,
-  type WaveSpec,
+import type {
+  CollectWaveResult,
+  ReportAssignment,
+  ReportWave,
+  ReportWaveRef,
+  ReportWaveRequest,
+  StartWaveResult,
 } from "./reportWave.ts";
 
 /** The four-slug adversarial-review angle allowlist (claimed-intent is mandatory at the tool boundary). */
@@ -50,22 +52,29 @@ export function isAdversarialReviewAngle(value: string): value is AdversarialRev
  * The per-lane completion-report schema the wave enforces as its `outputSchema` — the engine
  * injects a `structured_output` tool into each lane and fails any lane whose report is missing
  * or schema-invalid. Transcribes the adversarial-reviewer's completion-report contract
- * (contracts.md §8.4): closed shapes, `{angle, summary, findings, fyi}` all required, and
- * DELIBERATELY NO VERDICT FIELD — the human triages every finding, so there is no clean/
- * actionable derivation to make consistent (hence also no if/then conditional). Finding rows
- * anchor candidate GitHub review comments: `line` is required-nullable (a real finding that
- * cannot anchor to a diff line keeps `line: null`), `side` optional (omitted ⇒ RIGHT), and the
- * severity/confidence enums match the agent def's triage tags.
+ * (contracts.md §8.4): closed shapes, `{angle, summary, findings, fyi, streamed, blocked}` all
+ * required, and DELIBERATELY NO VERDICT FIELD — the human triages every finding, so there is no
+ * clean/actionable derivation to make consistent. `blocked: true` is NOT a verdict: it marks a
+ * required review that could not complete (context fetch failed, a context file unreadable, the
+ * hunt stopped early) — `collectAdversarialReviewWave` normalizes it into an uncovered
+ * `lane-failed` BEFORE coverage is computed, so a schema-valid-but-empty report never counts as
+ * "no findings". The conditional mirrors `PR_REVIEW_REPORT_SCHEMA`'s blocked arm: empty
+ * `findings` and a nonblank `fyi` (the blocker first). Finding rows anchor candidate GitHub review
+ * comments: `line` is required-nullable (a real finding that cannot anchor to a diff line keeps
+ * `line: null`), `side` optional (omitted ⇒ RIGHT), and the severity/confidence enums match the
+ * agent def's triage tags.
  */
 export const ADVERSARIAL_REVIEW_REPORT_SCHEMA = {
   type: "object",
   additionalProperties: false,
-  required: ["angle", "summary", "findings", "fyi"],
+  required: ["angle", "summary", "findings", "fyi", "streamed", "blocked"],
   properties: {
     angle: {
       type: "string",
       enum: ["claimed-intent", "correctness", "tests", "quality", "ponytail"],
     },
+    streamed: { type: "boolean" },
+    blocked: { type: "boolean" },
     summary: { type: "string" },
     findings: {
       type: "array",
@@ -88,12 +97,25 @@ export const ADVERSARIAL_REVIEW_REPORT_SCHEMA = {
       items: { type: "string" },
     },
   },
+  allOf: [
+    {
+      // `blocked` is top-level required, so this `if` cannot vacuously match an absent key.
+      if: { properties: { blocked: { const: true } } },
+      // biome-ignore lint/suspicious/noThenProperty: JSON-Schema conditional, not a thenable.
+      then: {
+        properties: {
+          findings: { maxItems: 0 },
+          fyi: { minItems: 1, items: { type: "string", pattern: "\\S" } },
+        },
+      },
+    },
+  ],
 };
 
 /**
- * Build the reviewer lanes for a selection: key = label = slug, the fixed agent/phase, and a
- * task naming the angle, the PR number, and the head-worktree path — AND NOTHING ELSE: no URL
- * parameter exists, so the surface handle is unrepresentable by construction (the children
+ * Build the reviewer assignments for a selection: key = label = slug, the fixed agent/phase,
+ * and a task naming the angle, the PR number, and the head-worktree path — AND NOTHING ELSE: no
+ * URL parameter exists, so the surface handle is unrepresentable by construction (the children
  * re-derive everything else themselves via `perk pr review-context`).
  *
  * `stack` is a DISCRIMINATOR, not a member array: with `stack: true` the task names the stack
@@ -101,16 +123,16 @@ export const ADVERSARIAL_REVIEW_REPORT_SCHEMA = {
  * children learn the authoritative ordered membership from the context worker, never from
  * relayed prose. Without it, tasks are byte-identical to the single-PR form.
  */
-export function buildAdversarialReviewLanes(opts: {
+export function buildAdversarialReviewAssignments(opts: {
   angles: AdversarialReviewAngle[];
   pr: number;
   worktree: string;
   directive?: string;
   stack?: boolean;
-}): WaveLane[] {
-  // ONE uniform suffix on every lane (the `buildPrReviewLanes` byte-posture): the parent's
-  // judgment lever stays angle selection — the directive never re-scopes a lane, it only sets
-  // emphasis inside the assigned angle.
+}): ReportAssignment[] {
+  // ONE uniform suffix on every assignment (the `buildPrReviewAssignments` byte-posture): the
+  // parent's judgment lever stays angle selection — the directive never re-scopes an angle, it
+  // only sets emphasis inside the assigned angle.
   const suffix =
     opts.directive === undefined
       ? ""
@@ -121,14 +143,14 @@ export function buildAdversarialReviewLanes(opts: {
       ? `Review the PR stack topped by PR #${opts.pr} (combined diff) at ${opts.worktree}. ` +
         `Fetch context with \`perk pr review-context --pr ${opts.pr} --stack\`.`
       : `Review PR #${opts.pr} at ${opts.worktree}.`;
-  const lanes: WaveLane[] = opts.angles.map((angle) => ({
+  const assignments: ReportAssignment[] = opts.angles.map((angle) => ({
     key: angle,
     label: angle,
     agent: "perk.adversarial-reviewer",
     phase: "review",
     task: `${ADVERSARIAL_REVIEW_ANGLES[angle]} ${subject}${suffix}`,
   }));
-  lanes.push({
+  assignments.push({
     key: "ponytail",
     label: "ponytail",
     agent: "perk.adversarial-reviewer",
@@ -137,7 +159,7 @@ export function buildAdversarialReviewLanes(opts: {
     skill: "ponytail-review",
     requiredSkill: PONYTAIL_REVIEW_SKILL,
   });
-  return lanes;
+  return assignments;
 }
 
 export interface AdversarialReviewWaveOptions {
@@ -157,25 +179,44 @@ export interface AdversarialReviewWaveOptions {
   /** Accepted for parity/tests only — the flow tool deliberately never threads its own signal. */
   signal?: AbortSignal;
   /** Test seam; production validates the exact source-bound Ponytail review skill. */
-  requiredSkillPreflight?: WaveSpec["requiredSkillPreflight"];
+  requiredSkillPreflight?: ReportWaveRequest["requiredSkillPreflight"];
+}
+
+// Only the typed flag classifies an adversarial report as blocked; diagnostic prose never does.
+function isBlockedFlag(report: Record<string, unknown>): boolean {
+  return report.blocked === true;
+}
+
+/**
+ * Collect the adversarial-review wave and apply the flow's lane semantics: a settled result has
+ * every `blocked: true` report reclassified into an uncovered assignment-keyed `lane-failed`
+ * (`reclassifyBlockedReports` — the same detail string as `prReviewWave.ts`) BEFORE the caller
+ * computes `covered`/`complete`; `none`/`running` pass through unchanged. The report stays
+ * verdict-free — only coverage changes.
+ */
+export async function collectAdversarialReviewWave(
+  wave: ReportWave,
+  ref: ReportWaveRef,
+): Promise<CollectWaveResult> {
+  const collected = await wave.collect(ref);
+  if (collected.kind !== "settled") return collected;
+  return { ...collected, result: reclassifyBlockedReports(collected.result, isBlockedFlag) };
 }
 
 /**
- * Start the adversarial-review wave NON-BLOCKING (the streaming sibling): build the lanes from
- * the angle vocabulary and launch under the strict completeness policy — zero retries, so an
- * uncovered angle stays an honest, human-visible incompleteness. Returns the `startReportWave`
- * outcome: the run handle + never-rejecting `result` on success, or the normalized launch
- * failure.
+ * Start the adversarial-review wave NON-BLOCKING (the streaming split): build the assignments
+ * from the angle vocabulary and launch under the strict completeness policy — zero retries, so an
+ * uncovered angle stays an honest, human-visible incompleteness. Returns the `wave.start`
+ * outcome: the opaque ref + identity telemetry on success, or the normalized launch failure.
  */
 export async function startAdversarialReviewWave(
-  adapter: WaveAdapter,
+  wave: ReportWave,
   opts: AdversarialReviewWaveOptions,
-): Promise<ReportWaveStart> {
-  return await startReportWave(
-    adapter,
+): Promise<StartWaveResult> {
+  return await wave.start(
     {
       flow: "adversarial-review",
-      lanes: buildAdversarialReviewLanes({
+      assignments: buildAdversarialReviewAssignments({
         angles: opts.angles,
         pr: opts.pr,
         worktree: opts.worktree,
@@ -190,6 +231,6 @@ export async function startAdversarialReviewWave(
         ? { requiredSkillPreflight: opts.requiredSkillPreflight }
         : {}),
     },
-    opts.signal,
+    { signal: opts.signal },
   );
 }