@mgiles/perk 3.1.0 → 3.3.0

package/extension/waves/reportWave.ts

@@ -1,56 +1,88 @@
 // The Perk-owned report-wave module: bounded sets of fresh-context, report-only children with
-// typed outcomes under stable lane keys. Report waves were previously model-authored prompt
-// mechanics (a script skeleton the parent model had to transcribe faithfully — the known
+// typed outcomes under stable assignment keys. Report waves were previously model-authored
+// prompt mechanics (a script skeleton the parent model had to transcribe faithfully — the known
 // prompt-drift risk); this module makes the mechanics CODE. It renders the complete, tested
 // `workflowScript`, launches it through a `WaveAdapter` (async-only, `mission: false`), waits on
 // the run's async-complete event with a module-owned timeout, reads the durable `status.json`
 // `workflow.value` aggregate, and normalizes `{complete, reports[], failures[]}` under a
 // flow-specific completeness policy. Each launch additionally records an OUTPUT-FREE
 // `WaveScriptReceipt` (run handle + per-child identity/artifact trail from the completion
-// payload) — write-only telemetry for correlation: `status.json.workflow.value` stays the sole
-// source of reports, and receipt absence never changes a verdict, completeness, or retry
-// selection (contracts.md §8.35).
+// payload) — correlation telemetry, not policy input. Complete runs use the durable aggregate;
+// explicit native partial settlement may retain keyed child reports, always beside its wave
+// failure. Receipt absence never changes verdict/completeness or retry selection (§8.35).
 //
-// The module hosts BOTH the blocking runner and the non-blocking streaming sibling over ONE
-// operational core: `startWaveScript` performs the front half (abort pre-check → capability
-// ping → subscribe-before-spawn → async spawn) and returns the run handle plus a NEVER-REJECTING
-// `result` promise carrying the back half (completion wait, best-effort stop on timeout/cancel,
-// aggregate read, receipt assembly, unsubscribe-on-settle); `runWaveScript` is that start +
-// await. `startReportWave`/`runReportWave` are the lane-level pair over the same split. The
-// blocking runner is live under the per-flow entrypoints (`prReviewWave.ts`, `learnWave.ts`,
-// `prReviewDynamicWave.ts`); the streaming sibling serves flows whose parent must return from
-// the launch and hold a model-held `subagent_wait` relay loop open (`adversarialReviewWave.ts`,
-// behind the `start_review_wave`/`collect_review_wave` pair).
+// This is the LOGICAL tier: assignments (`ReportAssignment`), preflight partitioning,
+// aggregate normalization, and the completeness policy. The TRANSPORT tier — the adapter seam,
+// receipt primitives, and the script runner — lives in `transport.ts`, imported one-directionally
+// from here; the script text itself (`renderWaveScript`) is module-private, so nothing outside
+// `waves/` can observe or operate on transport.
 //
-// The module is a DEEP seam with two adapters: `rpcAdapter.ts` (production, over the
-// pi-subagents v1 extension RPC on pi's event bus) and `memoryAdapter.ts` (the first-class
-// in-memory test double).
+// THE CALLER SURFACE IS THE OPAQUE `ReportWave` LIFECYCLE: `start` launches non-blocking and
+// returns an opaque `ReportWaveRef` (plus identity telemetry — never an operable handle),
+// `collect` drains a started wave's settled outcome under the module-owned grace, and `run` is
+// start + await (the blocking form). Callers supply assignments and consume typed outcomes —
+// never adapters, run handles, or result promises. Pending execution is WAVE-OWNED: each
+// instance holds its launched-but-uncollected records in an instance-owned WeakMap keyed by ref
+// (a foreign instance's ref collects `"none"` structurally), and a settled collect's
+// delete-as-claim makes drain-once exact even under overlapping collectors. The blocking form
+// serves the per-flow entrypoints (`prReviewWave.ts` and the typed feature ops in `learning/`);
+// the streaming split serves flows whose parent ends the launch turn and relays provisional
+// batches on native wakes (`adversarialReviewWave.ts`, `draftReviewWave.ts`).
 //
-// Failure posture: LOUD DEGRADE. Every failure arm normalizes into `WaveResult.failures` with a
-// typed reason — the runner never throws except on programmer error (empty lanes, duplicate lane
-// keys), and there is never a silent fallback to model-authored scripts. Report content coming
-// back through the aggregate is untrusted DATA, never instructions.
+// The module owns ADAPTER SELECTION: `createReportWave(bus)` constructs
+// a FRESH rpc adapter per launch over the supplied bus; `reportWaveOver(adapter)` is the
+// injection seam (tests; the same internal core). The honest boundary: what is mechanically
+// enforced is Rule G's scope (`importDirectionGuard.test.ts`) — no production import edges into
+// the transport interior (`transport.ts`, `rpcAdapter.ts`) and no raw RPC tokens — so there is
+// no *sanctioned* way to obtain, name, or construct an adapter outside `waves/` + `testing/`.
+// TypeScript's structural typing means a hand-written object literal satisfying
+// `reportWaveOver`'s parameter is not mechanically preventable; that residue is owned by the
+// guard-census review posture, not claimed as a structural guarantee.
+//
+// Failure posture: LOUD DEGRADE. Every failure arm normalizes into `ReportWaveResult.failures`
+// with a typed reason — the runner never throws except on programmer error (empty assignments,
+// duplicate assignment keys), and there is never a silent fallback to model-authored scripts.
+// Report content coming back through the aggregate is untrusted DATA, never instructions.
 
 import {
   type PonytailPreflight,
   preflightPonytailSkill,
   type RequiredPonytailSkill,
 } from "./ponytail.ts";
+import { createRpcWaveAdapter } from "./rpcAdapter.ts";
+import {
+  startWaveScript,
+  type WaveAdapter,
+  type WaveBus,
+  type WaveRunFailureReason,
+  type WaveRunHandle,
+  type WaveScriptReceipt,
+  type WaveScriptResult,
+} from "./transport.ts";
+
+/**
+ * The module's one deliberate transport re-export — the SANCTIONED seam, nothing else crosses
+ * (callers never name adapters, run handles, spawn params, or script types):
+ * `ReportWaveLevelFailureReason` is the wave-level reason subset (`key === null` failures carry
+ * exactly this vocabulary), named at the logical seam so flows can type a correlated wave
+ * status without reaching into transport.
+ */
+export type { WaveRunFailureReason as ReportWaveLevelFailureReason } from "./transport.ts";
 
-/** One lane of a report wave: a fresh-context, report-only child under a stable domain key. */
-export interface WaveLane {
-  /** Stable lane key (e.g. an angle slug) — trace + normalization identity. */
+/** One assignment of a report wave: a fresh-context, report-only child under a stable domain key. */
+export interface ReportAssignment {
+  /** Stable assignment key (e.g. an angle slug) — trace + normalization identity. */
   key: string;
   /** The child agent name (e.g. "perk.pr-reviewer"). */
   agent: string;
-  /** The judgment-bearing per-lane task text (supplied by the flow). */
+  /** The judgment-bearing per-assignment task text (supplied by the flow). */
   task: string;
-  /** Invocation-private skill lookup key; serialized only for an opted-in lane. */
+  /** Invocation-private skill lookup key; serialized only for an opted-in assignment. */
   skill?: string;
   /**
    * Exact source requirement for a source-bound skill. This metadata is preflight-only and is
-   * NEVER serialized into the workflow script; a failed requirement skips this lane instead of
-   * allowing pi-subagents to resolve a hostile same-named global/project skill.
+   * NEVER serialized into the workflow script; a failed requirement skips this assignment
+   * instead of allowing pi-subagents to resolve a hostile same-named global/project skill.
    */
   requiredSkill?: RequiredPonytailSkill;
   /** Trace metadata; defaults to `key`. */
@@ -58,8 +90,8 @@ export interface WaveLane {
   /** Trace metadata. */
   phase?: string;
   /**
-   * Per-lane report schema — rendered as the item's `outputSchema`, overriding the
-   * workflow-level default (the established per-item mechanic). Omitted lanes render
+   * Per-assignment report schema — rendered as the item's `outputSchema`, overriding the
+   * workflow-level default (the established per-item mechanic). Omitted assignments render
    * byte-identically to before the field existed.
    */
   outputSchema?: object;
@@ -67,20 +99,20 @@ export interface WaveLane {
 
 /**
  * The completeness policies:
- * - `strict`: complete ⟺ zero failures — every lane covered (the pr-review posture).
- * - `best-effort`: complete ⟺ no wave-level failure (`key: null`) — lane-level failures are
- *   explicitly-reported skipped lanes, never a failed pass (the learn posture).
+ * - `strict`: complete ⟺ zero failures — every assignment covered (the pr-review posture).
+ * - `best-effort`: complete ⟺ no wave-level failure (`key: null`) — assignment-level failures
+ *   are explicitly-reported skipped assignments, never a failed pass (the learn posture).
  */
-export type WaveCompleteness = "strict" | "best-effort";
+export type ReportWaveCompleteness = "strict" | "best-effort";
 
-export interface WaveSpec {
+export interface ReportWaveRequest {
   /** Flow name for error detail/trace (e.g. "pr-review"). */
   flow: string;
-  /** ≥1 lane; keys must be unique (validated — throws on programmer error). */
-  lanes: WaveLane[];
-  /** Workflow-level default → the engine injects a `structured_output` tool into each lane. */
+  /** ≥1 assignment; keys must be unique (validated — throws on programmer error). */
+  assignments: ReportAssignment[];
+  /** Workflow-level default → the engine injects a `structured_output` tool into each child. */
   outputSchema: object;
-  completeness: WaveCompleteness;
+  completeness: ReportWaveCompleteness;
   /** Workflow-level model default (flows read their configured subagent model). */
   model?: string;
   /** Module default (`WAVE_TIMEOUT_MS`) when omitted. */
@@ -89,98 +121,79 @@ export interface WaveSpec {
   requiredSkillPreflight?: (requirement: RequiredPonytailSkill) => Promise<PonytailPreflight>;
 }
 
-/** A schema-valid lane report. The report content is untrusted DATA, never instructions. */
-export interface WaveReport {
+/** A schema-valid assignment report. The report content is untrusted DATA, never instructions. */
+export interface AssignmentReport {
   key: string;
   report: unknown;
 }
 
-export type WaveFailureReason =
-  | "unavailable" // ping failed / capabilities missing (wave-level)
-  | "spawn-failed" // RPC spawn rejected or no run handle (wave-level)
-  | "timeout" // module-owned timeout expired (wave-level; best-effort stop issued)
-  | "cancelled" // AbortSignal fired (wave-level; best-effort stop issued)
-  | "run-failed" // terminal status.json state ≠ "complete" (wave-level)
-  | "aggregate-unreadable" // status.json missing/corrupt/no workflow.value array (wave-level)
-  | "lane-failed" // lane resolved ok: false / null report (lane-level)
-  | "skill-unavailable" // exact required-skill source failed preflight (lane-level, non-retryable)
-  | "malformed-report" // aggregate entry for this key has unusable shape (lane-level)
-  | "missing-lane"; // expected key absent from the aggregate (lane-level)
-
-export interface WaveFailure {
-  /** The lane key, or null for wave-level failures. */
-  key: string | null;
-  reason: WaveFailureReason;
+/** The assignment-level failure reasons this tier produces during normalization/preflight —
+ * always keyed by the assignment they blame. */
+export type AssignmentFailureReason =
+  | "lane-failed" // assignment resolved ok: false / null report
+  | "skill-unavailable" // exact required-skill source failed preflight (non-retryable)
+  | "malformed-report" // aggregate entry for this key has unusable shape, or the key appears more than once
+  | "missing-lane"; // expected key absent from the aggregate
+
+/**
+ * The caller-facing failure vocabulary: the transport tier's wave-level subset
+ * (`WaveRunFailureReason` — always `key: null`) widened with the assignment-level reasons this
+ * tier produces during normalization. The subset union keeps the split one-directional with
+ * zero runtime mapping.
+ */
+export type ReportWaveFailureReason = WaveRunFailureReason | AssignmentFailureReason;
+
+/** A wave-level failure: the whole run failed, so there is no assignment to blame — the same
+ * record shape as the transport tier's `WaveRunFailure` (script failures flow upward with zero
+ * runtime mapping). */
+export interface ReportWaveLevelFailure {
+  key: null;
+  reason: WaveRunFailureReason;
   /** Human-readable diagnosis (error strings routed here, never re-thrown). */
   detail: string;
 }
 
-export interface WaveResult {
+/** An assignment-level failure, keyed by the assignment it blames. */
+export interface AssignmentFailure {
+  key: string;
+  reason: AssignmentFailureReason;
+  detail: string;
+}
+
+/**
+ * One wave failure — a DISCRIMINATED union on `key`: `key === null` narrows the reason to
+ * exactly the wave-level subset (and a string key to the assignment-level reasons), so a
+ * wave-level failure carrying an assignment reason — or vice versa — is unrepresentable and
+ * every flow inherits the correlation without reimplementing transport knowledge.
+ */
+export type ReportWaveFailure = ReportWaveLevelFailure | AssignmentFailure;
+
+export interface ReportWaveResult {
   complete: boolean;
-  reports: WaveReport[];
-  failures: WaveFailure[];
+  reports: AssignmentReport[];
+  failures: ReportWaveFailure[];
   /** The launch's output-free attempt receipt — write-only telemetry, never a decision input. */
   receipt: WaveScriptReceipt;
 }
 
-/** The truthful preflight partition reported by every streaming report-wave start. */
-export type WaveLaunchManifest = {
-  /** The complete logical lane manifest, in `spec.lanes` order. */
+/** The truthful preflight partition reported by every report-wave start. */
+export type ReportWaveLaunchManifest = {
+  /** The complete logical assignment manifest, in `request.assignments` order. */
   requested: string[];
   /** The ordered subset rendered into the static workflow after required-skill preflight. */
   runnable: string[];
-  /** One ordered keyed `skill-unavailable` failure per preflight-omitted lane. */
-  preflightFailures: WaveFailure[];
+  /** One ordered keyed `skill-unavailable` failure per preflight-omitted assignment. */
+  preflightFailures: ReportWaveFailure[];
 };
 
 // -------------------------------------------------------------------- the attempt receipts
 
-/**
- * The terminal disposition of ONE top-level workflow launch, as the runner observed it. Every
- * launch reaches exactly one of these arms (`"running"` is unreachable — the runner always
- * settles); `"unavailable"` preserves even a pre-spawn capability failure as an attempt.
- */
-export type WaveReceiptState =
-  | "unavailable" // ping failed/incomplete — nothing launched
-  | "spawn-failed" // spawn rejected/threw — no run handle
-  | "complete" // completion observed, durable state "complete"
-  | "failed" // completion observed, durable/observed failure
-  | "timed-out" // module timeout expired (handle preserved)
-  | "cancelled"; // AbortSignal honored (handle preserved when spawned)
-
-/**
- * One child lane's identity/artifact trail from the completion payload — OUTPUT-FREE by
- * invariant: reports, summaries, and structured output never enter a receipt (they stay in the
- * durable `status.json.workflow.value`, the sole report authority).
- */
-export interface WaveChildReceipt {
-  /** The Perk lane key (mapped FROM the upstream row's overloaded `agent` field). */
-  key: string;
-  /** The child agent name, enriched from the Perk-owned lane spec where known. */
-  agent?: string;
-  /** The child's opaque run id — never parsed or synthesized from paths. */
-  runId?: string;
-  success?: boolean;
-  outputState?: "present" | "absent" | "unknown";
-  /** String path fields only; output-free. */
-  artifactPaths?: Record<string, string>;
-}
-
-/** One script launch's receipt: the run handle (where known) + the observed children. */
-export interface WaveScriptReceipt {
-  /** The top-level async run id (the spawn handle's asyncId). */
-  runId?: string;
-  asyncDir?: string;
-  state: WaveReceiptState;
-  children: WaveChildReceipt[];
-}
-
 /**
  * A flow-attributed attempt: one receipt per top-level workflow launch, ordered by `attempt`
  * (one-based, assigned by the flow entrypoint that owns retry policy). `requestedKeys` is the
- * lane manifest BEFORE launch — never reconstructed from the observed children.
+ * assignment manifest BEFORE launch — never reconstructed from the observed children.
  */
-export interface WaveAttemptReceipt extends WaveScriptReceipt {
+export interface ReportWaveAttemptReceipt extends WaveScriptReceipt {
   flow: string;
   attempt: number;
   requestedKeys: string[];
@@ -190,91 +203,12 @@ export interface WaveAttemptReceipt extends WaveScriptReceipt {
 export function toAttemptReceipt(
   flow: string,
   attempt: number,
-  requestedKeys: string[],
+  requestedKeys: readonly string[],
   receipt: WaveScriptReceipt,
-): WaveAttemptReceipt {
+): ReportWaveAttemptReceipt {
   return { flow, attempt, requestedKeys: [...requestedKeys], ...receipt };
 }
 
-// ------------------------------------------------------------------------- the adapter seam
-
-/** The minimal pi event-bus surface an adapter needs (mirrors pi's EventBus, whose `on` returns an unsubscribe function). */
-export interface WaveBus {
-  emit(channel: string, data: unknown): void;
-  on(channel: string, handler: (data: unknown) => void): () => void;
-}
-
-/** A successful capability ping; `asyncCompleteEvent` is the ADVERTISED async-complete channel. */
-export interface WavePing {
-  asyncCompleteEvent: string;
-}
-
-/** The detached async run a spawn launched. */
-export interface WaveRunHandle {
-  asyncId: string;
-  asyncDir: string;
-}
-
-/**
- * An async-complete notification; at least one identifier is present on real payloads. The
- * observability fields are optional — an identity-only completion stays valid (receipt absence
- * degrades correlation, never behavior). The adapter normalizes them output-free and leaves
- * each child's `agent` unset (enrichment happens against Perk-owned lane specs).
- */
-export interface WaveCompletion {
-  asyncId?: string;
-  asyncDir?: string;
-  /** The run's raw terminal state string, when the payload carries one. */
-  state?: string;
-  success?: boolean;
-  children?: WaveChildReceipt[];
-}
-
-/**
- * The explicit acceptance-disable every wave spawn carries. Without it, pi-subagents
- * auto-infers a generic acceptance contract for reviewer/analyst-named or read-only children
- * and injects a fenced `acceptance-report` completion instruction into each lane — a COMPETING
- * completion contract observed steering children into invalid `structured_output` attempts.
- * `{level: "none"}` is the sanctioned disable shape (pi-subagents `explicitAcceptanceCanDisable`);
- * `formatAcceptancePrompt` emits nothing at level none, so no contract block reaches a lane.
- * Deliberately module-wide with no opt-out: every report-wave child's sole completion contract
- * is the engine-validated `structured_output` report.
- */
-export const WAVE_ACCEPTANCE = {
-  level: "none",
-  reason: "perk report-wave lanes complete via the engine-validated structured_output report",
-} as const;
-
-/** The full spawn params the runner fixes: async-only, ephemeral, fresh-context by definition. */
-export interface WaveSpawnParams {
-  workflowScript: string;
-  async: true;
-  /** Waves are ephemeral by explicit decision — never mission-attached. */
-  mission: false;
-  /** A report wave is by definition fresh-context. */
-  context: "fresh";
-  /** The fixed acceptance disable (`WAVE_ACCEPTANCE`) — pi-subagents' workflow-defaults spread
-   * delivers it onto every lane child, suppressing the auto-inferred acceptance contract. */
-  acceptance: { level: "none"; reason: string };
-  outputSchema: object;
-  model?: string;
-  /** Orphan insurance: the run enforces the same deadline even if the parent session dies. */
-  timeoutMs: number;
-}
-
-export interface WaveAdapter {
-  /** Capability-checked ping; null ⇒ unavailable (loud degrade upstream). Must be called first. */
-  ping(): Promise<WavePing | null>;
-  /** Launch the async workflowScript run; throws ⇒ spawn-failed. */
-  spawn(params: WaveSpawnParams): Promise<WaveRunHandle>;
-  /** Subscribe to run completions (any run — the runner matches the handle); returns unsubscribe. */
-  onComplete(handler: (completion: WaveCompletion) => void): () => void;
-  /** Best-effort stop of a live run (timeout/cancel path); never throws. */
-  stop(handle: WaveRunHandle): Promise<void>;
-  /** Read the run's durable aggregate; throws ⇒ aggregate-unreadable. */
-  readAggregate(handle: WaveRunHandle): Promise<{ state: string; error?: string; value: unknown }>;
-}
-
 // ---------------------------------------------------------------------------- the renderer
 
 /**
@@ -287,41 +221,55 @@ export interface WaveAdapter {
 export const RUN_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 
 /**
- * Render the wave `workflowScript`: an explicit-return, all-settled `runs.all` over the lane
- * items, projected to the compact typed aggregate only (lane key, outcome, error, and the
- * schema-validated report — children's prose never enters the aggregate beyond `error`/`output`
- * on failure). Lane items are embedded via `JSON.stringify`, so hostile task text (quotes,
- * newlines, backticks, `${}`) cannot escape the array literal. Throws on programmer error:
- * empty lanes, duplicate lane keys, or a lane key outside the run-key contract.
+ * The report restriction packet (contracts.md §8.35): a constant every report child receives.
+ * With the runner bit it is the whole authorization input for the child's read-only floor.
+ */
+const REPORT_CHILD_RESTRICTIONS = { "perk.parent-restrictions/1": { readOnly: true } } as const;
+
+/**
+ * Validate the assignment manifest (throws on programmer error: empty, duplicate keys, or a key
+ * outside the run-key contract). Module-private — the script surface never leaves `waves/`.
  */
-function validateWaveLanes(lanes: WaveLane[]): void {
-  if (lanes.length === 0) {
+function validateAssignments(assignments: ReportAssignment[]): void {
+  if (assignments.length === 0) {
     throw new Error("renderWaveScript: a report wave needs at least one lane");
   }
   const seen = new Set<string>();
-  for (const lane of lanes) {
-    if (seen.has(lane.key)) {
-      throw new Error(`renderWaveScript: duplicate lane key '${lane.key}'`);
+  for (const assignment of assignments) {
+    if (seen.has(assignment.key)) {
+      throw new Error(`renderWaveScript: duplicate lane key '${assignment.key}'`);
     }
-    if (!RUN_KEY_PATTERN.test(lane.key)) {
+    if (!RUN_KEY_PATTERN.test(assignment.key)) {
       throw new Error(
-        `renderWaveScript: lane key '${lane.key}' violates the pi-subagents run-key contract`,
+        `renderWaveScript: lane key '${assignment.key}' violates the pi-subagents run-key contract`,
       );
     }
-    seen.add(lane.key);
+    seen.add(assignment.key);
   }
 }
 
-export function renderWaveScript(lanes: WaveLane[]): string {
-  validateWaveLanes(lanes);
-  const items = lanes.map((lane) => ({
-    key: lane.key,
-    agent: lane.agent,
-    task: lane.task,
-    ...(lane.skill !== undefined ? { skill: lane.skill } : {}),
-    label: lane.label ?? lane.key,
-    ...(lane.phase !== undefined ? { phase: lane.phase } : {}),
-    ...(lane.outputSchema !== undefined ? { outputSchema: lane.outputSchema } : {}),
+/**
+ * Render the wave `workflowScript`: an explicit-return, all-settled `runs.all` over the
+ * assignment items, projected to the compact typed aggregate only (assignment key, outcome,
+ * error, and the schema-validated report — children's prose never enters the aggregate beyond
+ * `error`/`output` on failure). Every report child is read-only under perk's floor and runs in
+ * the caller checkout; hostile task/assignment fields cannot override either (explicit field
+ * selection + `JSON.stringify`, so hostile task text — quotes, newlines, backticks, `${}` —
+ * cannot escape the array literal either). Module-private: the script bytes are observable
+ * outside `waves/` only through the adapter seam's spawn params.
+ */
+function renderWaveScript(assignments: ReportAssignment[]): string {
+  validateAssignments(assignments);
+  const items = assignments.map((assignment) => ({
+    key: assignment.key,
+    agent: assignment.agent,
+    task: assignment.task,
+    extensionBindings: REPORT_CHILD_RESTRICTIONS,
+    worktree: false,
+    ...(assignment.skill !== undefined ? { skill: assignment.skill } : {}),
+    label: assignment.label ?? assignment.key,
+    ...(assignment.phase !== undefined ? { phase: assignment.phase } : {}),
+    ...(assignment.outputSchema !== undefined ? { outputSchema: assignment.outputSchema } : {}),
   }));
   return (
     `const reports = await runs.all(${JSON.stringify(items, null, 2)});\n` +
@@ -332,126 +280,86 @@ export function renderWaveScript(lanes: WaveLane[]): string {
 
 // ------------------------------------------------------------------------------- the runner
 
-/**
- * The module-owned wave timeout default: a deliberate tightening vs the 30-minute foreground
- * default the prompt-mechanics wave rode. Per-flow `spec.timeoutMs` overrides; the default is
- * overridable for tests via PERK_WAVE_TIMEOUT_MS.
- */
-export const WAVE_TIMEOUT_MS = 15 * 60_000;
-
-function waveTimeoutMs(): number {
-  const raw = Number(process.env.PERK_WAVE_TIMEOUT_MS ?? "");
-  return Number.isFinite(raw) && raw > 0 ? raw : WAVE_TIMEOUT_MS;
-}
-
 function waveFailure(
-  reason: WaveFailureReason,
+  reason: WaveRunFailureReason,
   detail: string,
   receipt: WaveScriptReceipt,
-): WaveResult {
+): ReportWaveResult {
   return { complete: false, reports: [], failures: [{ key: null, reason, detail }], receipt };
 }
 
-/** The judgment-bearing pieces a script run needs (the lane-free slice of `WaveSpec`). */
-export interface WaveScriptSpec {
-  /** Flow name for error detail/trace (e.g. "pr-review-dynamic"). */
-  flow: string;
-  /** The complete, module-rendered workflowScript (never model-authored). */
-  workflowScript: string;
-  /** Workflow-level default → the engine injects a `structured_output` tool into each child. */
-  outputSchema: object;
-  /** Workflow-level model default (per-item `model` fields in the script override it). */
-  model?: string;
-  /** Module default (`WAVE_TIMEOUT_MS`) when omitted. */
-  timeoutMs?: number;
-}
-
-/** A script run's outcome: the raw `workflow.value` on success, one wave-level failure otherwise. */
-export type WaveScriptResult =
-  | { ok: true; value: unknown; receipt: WaveScriptReceipt }
-  | { ok: false; failure: WaveFailure; receipt: WaveScriptReceipt };
-
-/**
- * A launched (or launch-refused) script run. On `ok: true` the run is LIVE: `handle` is the
- * detached async run, and `result` settles when the back half finishes (completion wait under
- * the module-owned timeout, AbortSignal honor, best-effort stop on timeout/cancel, the durable
- * aggregate read, receipt assembly, unsubscribe-on-settle). `result` NEVER rejects — every arm
- * normalizes into `WaveScriptResult`, so an uncollected wave can never become an unhandled
- * rejection. Pre-spawn failures (aborted-before-launch, ping fail/null, spawn throw) take the
- * `ok: false` arm with the same failure/receipt values the blocking runner reports, and the
- * completion subscription is released immediately.
- */
-export type WaveScriptStart =
-  | { ok: true; handle: WaveRunHandle; result: Promise<WaveScriptResult> }
-  | { ok: false; failure: WaveFailure; receipt: WaveScriptReceipt };
-
-function errorDetail(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 /**
- * Normalize the aggregate's entries against the expected lane keys (defensive — the module
- * rendered the script, but the aggregate crossed a process boundary). Unknown extra keys are
- * ignored: the module owns the script, so extras cannot occur without upstream drift, and the
- * per-lane reasons below already make the wave incomplete under `strict`. Exported for the
- * per-flow entrypoints whose scripts produce the same compact lane projection (e.g. the
- * dynamic-review sibling normalizing against its runtime-selected keys).
+ * Normalize the aggregate's entries against the expected assignment keys (defensive — the
+ * module rendered the script, but the aggregate crossed a process boundary). Unknown extra keys
+ * are ignored: the module owns the script, so extras cannot occur without upstream drift, and
+ * the per-assignment reasons below already make the wave incomplete under `strict`. A key
+ * appearing more than once is ambiguous identity: `malformed-report`, every row withheld (§8.35).
+ * Module-private: the wave's settle is the only consumer.
  */
-export function normalizeLanes(
+function normalizeAssignments(
   keys: string[],
   entries: unknown[],
-): { reports: WaveReport[]; failures: WaveFailure[] } {
-  const reports: WaveReport[] = [];
-  const failures: WaveFailure[] = [];
+): { reports: AssignmentReport[]; failures: ReportWaveFailure[] } {
+  const reports: AssignmentReport[] = [];
+  const failures: ReportWaveFailure[] = [];
   for (const key of keys) {
-    const lane = { key };
-    const entry = entries.find((e) => isRecord(e) && e.key === lane.key);
-    if (!isRecord(entry)) {
+    const rows = entries.filter((e): e is Record<string, unknown> => isRecord(e) && e.key === key);
+    if (rows.length > 1) {
+      // Duplicate expected keys are ambiguous identity: withhold every row (§8.35).
+      failures.push({
+        key,
+        reason: "malformed-report",
+        detail: `lane '${key}' appears ${rows.length} times in the wave aggregate — ambiguous identity, evidence withheld`,
+      });
+      continue;
+    }
+    const entry = rows[0];
+    if (entry === undefined) {
       failures.push({
-        key: lane.key,
+        key,
         reason: "missing-lane",
-        detail: `lane '${lane.key}' is absent from the wave aggregate`,
+        detail: `lane '${key}' is absent from the wave aggregate`,
       });
       continue;
     }
     if (entry.ok === true) {
       const report = entry.report;
       if (isRecord(report)) {
-        reports.push({ key: lane.key, report });
+        reports.push({ key, report });
       } else if (report === null || report === undefined) {
         failures.push({
-          key: lane.key,
+          key,
           reason: "lane-failed",
           detail:
             typeof entry.error === "string" && entry.error !== ""
               ? entry.error
-              : `lane '${lane.key}' resolved without a schema-valid report`,
+              : `lane '${key}' resolved without a schema-valid report`,
         });
       } else {
         failures.push({
-          key: lane.key,
+          key,
           reason: "malformed-report",
-          detail: `lane '${lane.key}' carries a non-object report (${Array.isArray(report) ? "array" : typeof report})`,
+          detail: `lane '${key}' carries a non-object report (${Array.isArray(report) ? "array" : typeof report})`,
         });
       }
     } else if (entry.ok === false) {
       failures.push({
-        key: lane.key,
+        key,
         reason: "lane-failed",
         detail:
           typeof entry.error === "string" && entry.error !== ""
             ? entry.error
-            : `lane '${lane.key}' failed without error detail`,
+            : `lane '${key}' failed without error detail`,
       });
     } else {
       failures.push({
-        key: lane.key,
+        key,
         reason: "malformed-report",
-        detail: `lane '${lane.key}' aggregate entry has no boolean 'ok'`,
+        detail: `lane '${key}' aggregate entry has no boolean 'ok'`,
       });
     }
   }
@@ -459,258 +367,32 @@ export function normalizeLanes(
 }
 
 /**
- * Start one module-rendered workflowScript through the adapter — the non-blocking front half:
- * capability ping → subscribe-before-spawn (the completion-before-reply buffer) → async spawn.
- * On success the back half (block on the async-complete event under the module-owned timeout,
- * abortable → best-effort stop on timeout/cancel → read the durable aggregate → the
- * `state !== "complete"` / unreadable arms) runs behind the returned `result` promise, which
- * never rejects. The shared operational core under every runner; per-flow value normalization
- * stays with the caller.
- */
-export async function startWaveScript(
-  adapter: WaveAdapter,
-  spec: WaveScriptSpec,
-  signal?: AbortSignal,
-): Promise<WaveScriptStart> {
-  // The receipt is assembled in EVERY terminal arm — write-only telemetry: nothing below reads
-  // it back into the ok/failure decision.
-  const receiptOf = (
-    state: WaveReceiptState,
-    spawned: WaveRunHandle | null,
-    completion?: WaveCompletion,
-  ): WaveScriptReceipt => ({
-    ...(spawned !== null ? { runId: spawned.asyncId, asyncDir: spawned.asyncDir } : {}),
-    state,
-    children: completion?.children ?? [],
-  });
-  const startFailure = (
-    reason: WaveFailureReason,
-    detail: string,
-    receipt: WaveScriptReceipt,
-  ): WaveScriptStart => ({
-    ok: false,
-    failure: { key: null, reason, detail },
-    receipt,
-  });
-
-  // Read through a closure so TS's readonly-property narrowing never staples the first
-  // check's `false` onto the post-await re-check (the signal CAN flip during an await).
-  const aborted = (): boolean => signal?.aborted === true;
-  const cancelledBeforeLaunch = (): WaveScriptStart =>
-    startFailure(
-      "cancelled",
-      `wave '${spec.flow}' was cancelled before launch`,
-      receiptOf("cancelled", null),
-    );
-
-  if (aborted()) return cancelledBeforeLaunch();
-
-  // 1. Capability check — the loud-degrade arm: the result explicitly names the wave
-  //    unavailable; callers surface it, never silently fall back to model-authored scripts.
-  let ping: WavePing | null;
-  try {
-    ping = await adapter.ping();
-  } catch (error) {
-    return startFailure(
-      "unavailable",
-      `subagent RPC ping failed: ${errorDetail(error)}`,
-      receiptOf("unavailable", null),
-    );
-  }
-  if (ping === null) {
-    return startFailure(
-      "unavailable",
-      "pi-subagents did not advertise the report-wave capabilities (ping failed or incomplete)",
-      receiptOf("unavailable", null),
-    );
-  }
-
-  // An abort can arrive WHILE the ping await is pending — re-check before subscribe/spawn so a
-  // cancelled wave never launches (the pre-launch check alone leaves this window open).
-  if (aborted()) return cancelledBeforeLaunch();
-
-  // 2. Subscribe BEFORE spawn: a completion can arrive before the spawn reply resolves (the
-  //    completion-before-reply race) — every completion is buffered and re-checked once the
-  //    handle is known.
-  let handle: WaveRunHandle | null = null;
-  let notifyMatch: (() => void) | null = null;
-  const buffered: WaveCompletion[] = [];
-  const matchesHandle = (completion: WaveCompletion): boolean =>
-    handle !== null &&
-    ((completion.asyncDir !== undefined && completion.asyncDir === handle.asyncDir) ||
-      (completion.asyncId !== undefined && completion.asyncId === handle.asyncId));
-  const unsubscribe = adapter.onComplete((completion) => {
-    buffered.push(completion);
-    if (matchesHandle(completion) && notifyMatch !== null) notifyMatch();
-  });
-
-  // 3. Spawn: async-only, ephemeral, fresh-context — the module fixes those; the flow's spec
-  //    supplies the judgment-bearing pieces (lanes, schema, model, policy).
-  const timeoutMs = spec.timeoutMs ?? waveTimeoutMs();
-  try {
-    handle = await adapter.spawn({
-      workflowScript: spec.workflowScript,
-      async: true,
-      mission: false,
-      context: "fresh",
-      acceptance: WAVE_ACCEPTANCE,
-      outputSchema: spec.outputSchema,
-      ...(spec.model !== undefined ? { model: spec.model } : {}),
-      timeoutMs,
-    });
-  } catch (error) {
-    unsubscribe();
-    return startFailure(
-      "spawn-failed",
-      `wave spawn failed: ${errorDetail(error)}`,
-      receiptOf("spawn-failed", null),
-    );
-  }
-  const spawned = handle;
-
-  const scriptFailure = (
-    reason: WaveFailureReason,
-    detail: string,
-    receipt: WaveScriptReceipt,
-  ): WaveScriptResult => ({
-    ok: false,
-    failure: { key: null, reason, detail },
-    receipt,
-  });
-
-  // The back half: every arm below RETURNS a normalized `WaveScriptResult` (never throws), so
-  // `result` never rejects; the subscription is released exactly when it settles.
-  const settle = async (): Promise<WaveScriptResult> => {
-    try {
-      // 4. Block on completion with the module-owned timeout; honor the caller's AbortSignal.
-      const outcome = await new Promise<"complete" | "timeout" | "cancelled">((resolve) => {
-        if (buffered.some(matchesHandle)) {
-          resolve("complete");
-          return;
-        }
-        const settleOutcome = (value: "complete" | "timeout" | "cancelled"): void => {
-          clearTimeout(timer);
-          signal?.removeEventListener("abort", onAbort);
-          notifyMatch = null;
-          resolve(value);
-        };
-        const timer = setTimeout(() => settleOutcome("timeout"), timeoutMs);
-        const onAbort = (): void => settleOutcome("cancelled");
-        notifyMatch = () => settleOutcome("complete");
-        signal?.addEventListener("abort", onAbort, { once: true });
-        if (signal?.aborted === true) settleOutcome("cancelled");
-      });
-      if (outcome !== "complete") {
-        // Best-effort stop — adapters never throw here by contract, but a broken adapter's error
-        // is still swallowed into the detail rather than re-thrown.
-        let stopNote = "";
-        try {
-          await adapter.stop(spawned);
-        } catch (error) {
-          stopNote = ` (stop failed: ${errorDetail(error)})`;
-        }
-        return outcome === "timeout"
-          ? scriptFailure(
-              "timeout",
-              `wave '${spec.flow}' timed out after ${timeoutMs}ms${stopNote}`,
-              receiptOf("timed-out", spawned),
-            )
-          : scriptFailure(
-              "cancelled",
-              `wave '${spec.flow}' was cancelled${stopNote}`,
-              receiptOf("cancelled", spawned),
-            );
-      }
-
-      // The MATCHED completion (retained for the receipt — its normalized children are the
-      // child-lane identity/artifact trail; an identity-only completion yields empty children).
-      const matched = buffered.find(matchesHandle);
-
-      // 5. Read the durable aggregate; surface the terminal-state arms.
-      let aggregate: { state: string; error?: string; value: unknown };
-      try {
-        aggregate = await adapter.readAggregate(spawned);
-      } catch (error) {
-        // Aggregate-unreadable: the completion identity is retained — the receipt state derives
-        // from the OBSERVED completion (a correlation label, not a verdict; the authoritative
-        // failure reason stays in the wave failure).
-        return scriptFailure(
-          "aggregate-unreadable",
-          `wave aggregate unreadable: ${errorDetail(error)}`,
-          receiptOf(matched?.success === false ? "failed" : "complete", spawned, matched),
-        );
-      }
-      if (aggregate.state !== "complete") {
-        const detail = aggregate.error !== undefined ? `: ${aggregate.error}` : "";
-        return scriptFailure(
-          "run-failed",
-          `wave run ended '${aggregate.state}'${detail}`,
-          receiptOf("failed", spawned, matched),
-        );
-      }
-      return { ok: true, value: aggregate.value, receipt: receiptOf("complete", spawned, matched) };
-    } finally {
-      unsubscribe();
-    }
-  };
-  return { ok: true, handle: spawned, result: settle() };
-}
-
-/**
- * Run one module-rendered workflowScript to completion — the blocking form: `startWaveScript` +
- * await its `result` (one operational core, behavior identical to the historical blocking
- * runner).
- */
-export async function runWaveScript(
-  adapter: WaveAdapter,
-  spec: WaveScriptSpec,
-  signal?: AbortSignal,
-): Promise<WaveScriptResult> {
-  const start = await startWaveScript(adapter, spec, signal);
-  if (!start.ok) return { ok: false, failure: start.failure, receipt: start.receipt };
-  return await start.result;
-}
-
-/**
- * Enrich receipt children's `agent` from the Perk-owned lane specs by key. Children are never
- * synthesized from lanes — an identity-only completion keeps its empty children (receipt absence
- * degrades correlation, never behavior).
+ * Enrich receipt children's `agent` from the Perk-owned assignment specs by key. Children are
+ * never synthesized from assignments — an identity-only completion keeps its empty children
+ * (receipt absence degrades correlation, never behavior).
  */
-function enrichReceipt(receipt: WaveScriptReceipt, lanes: WaveLane[]): WaveScriptReceipt {
+function enrichReceipt(
+  receipt: WaveScriptReceipt,
+  assignments: ReportAssignment[],
+): WaveScriptReceipt {
   return {
     ...receipt,
     children: receipt.children.map((child) => {
       if (child.agent !== undefined) return child;
-      const agent = lanes.find((lane) => lane.key === child.key)?.agent;
+      const agent = assignments.find((assignment) => assignment.key === child.key)?.agent;
       return agent === undefined ? child : { ...child, agent };
     }),
   };
 }
 
 /**
- * A launched (or launch-failed) report wave — the lane-level sibling of `WaveScriptStart`. On
- * `ok: true` the wave is LIVE: `result` settles into the normalized `WaveResult` (lane
- * normalization + completeness policy + receipt enrichment) and never rejects. On `ok: false`
- * the launch failure is already normalized into a `WaveResult` (receipt included) — no promise
- * to await, nothing left running.
- */
-export type ReportWaveStart =
-  | {
-      ok: true;
-      handle: WaveRunHandle;
-      result: Promise<WaveResult>;
-      launch: WaveLaunchManifest;
-    }
-  | { ok: false; result: WaveResult; launch: WaveLaunchManifest };
-
-/**
- * Settle one script outcome into the lane-level `WaveResult`: receipt enrichment, the
- * workflow.value array check, per-lane-key normalization, and the completeness policy — the
- * single back half both the blocking runner and the streaming sibling apply.
+ * Settle one script outcome into the assignment-level `ReportWaveResult`: receipt enrichment,
+ * the workflow.value array check, per-key normalization, and the completeness policy — the
+ * single back half both the blocking and streaming lifecycles apply.
  */
-function settleReportWave(run: WaveScriptResult, spec: WaveSpec): WaveResult {
-  const receipt = enrichReceipt(run.receipt, spec.lanes);
-  if (!run.ok) {
+function settleReportWave(run: WaveScriptResult, request: ReportWaveRequest): ReportWaveResult {
+  const receipt = enrichReceipt(run.receipt, request.assignments);
+  if (!run.ok && !Array.isArray(run.value)) {
     return { complete: false, reports: [], failures: [run.failure], receipt };
   }
   if (!Array.isArray(run.value)) {
@@ -721,64 +403,176 @@ function settleReportWave(run: WaveScriptResult, spec: WaveSpec): WaveResult {
     );
   }
 
-  const { reports, failures } = normalizeLanes(
-    spec.lanes.map((lane) => lane.key),
+  const normalized = normalizeAssignments(
+    request.assignments.map((assignment) => assignment.key),
     run.value,
   );
+  const { reports } = normalized;
+  // Retained evidence does not imply completion under either policy. Keep the transport
+  // failure first, followed by keyed normalization failures in request order.
+  const failures = run.ok ? normalized.failures : [run.failure, ...normalized.failures];
   const complete =
-    spec.completeness === "strict"
+    request.completeness === "strict"
       ? failures.length === 0
       : failures.every((failure) => failure.key !== null);
   return { complete, reports, failures, receipt };
 }
 
+// -------------------------------------------------------------------- the opaque lifecycle
+
+declare const REPORT_WAVE_REF: unique symbol;
+
+/**
+ * The opaque handle to one started, uncollected report wave — NOMINAL by a declared
+ * (value-less) unique-symbol brand: no structural forgery can satisfy it, and it exposes no
+ * operational members. Minted at exactly one internal site (immediately after the runtime
+ * evidence of a successful launch); meaningful only to the instance that minted it — a foreign
+ * instance's `collect` answers `"none"` structurally.
+ */
+export interface ReportWaveRef {
+  readonly [REPORT_WAVE_REF]: true;
+}
+
+/** The optional per-call controls; `signal` cancels pre-launch and best-effort stops post-launch. */
+export interface WaveControl {
+  signal?: AbortSignal;
+}
+
+/**
+ * A started (or launch-failed) report wave. On `ok: true` the wave is LIVE behind the opaque
+ * `ref` — `runId`/`asyncDir` are identity telemetry only (receipt vocabulary), never an
+ * operable handle. On `ok: false` the launch failure is already normalized into a
+ * `ReportWaveResult` (receipt included) — nothing left running, nothing to collect.
+ */
+export type StartWaveResult =
+  | {
+      ok: true;
+      ref: ReportWaveRef;
+      /** Identity telemetry only (receipt vocabulary) — never an operable handle. */
+      runId: string;
+      asyncDir: string;
+      launch: ReportWaveLaunchManifest;
+    }
+  | { ok: false; result: ReportWaveResult; launch: ReportWaveLaunchManifest };
+
+/**
+ * A collect's outcome:
+ * - `"none"`: unknown ref — never started here, already drained, or a foreign instance's.
+ * - `"running"`: unsettled after the grace — the ref stays pending. A premature collector
+ *   yields until matching workflow completion; expiry after observed completion is a lifecycle
+ *   contradiction for owner diagnosis, not a polling cue. The module-owned timeout stays.
+ * - `"settled"`: this collector won the drain — `keys` is the launch's frozen requested
+ *   manifest snapshot, `result` the normalized outcome. Drain-once is exact even under
+ *   overlapping collectors (delete-as-claim).
+ */
+export type CollectWaveResult =
+  | { kind: "none" }
+  | { kind: "running" }
+  | { kind: "settled"; keys: readonly string[]; result: ReportWaveResult };
+
+/**
+ * The deep seam: callers supply assignments and consume typed outcomes — never adapters, run
+ * handles, or result promises. `start`/`collect` are the streaming split (the parent returns
+ * from the launch, ends its turn, and resumes on native wakes); `run` is the blocking form (start + await, no
+ * ref escapes). The only throws are programmer errors (empty assignments, duplicate keys, keys
+ * outside `RUN_KEY_PATTERN`); every operational failure normalizes into `ReportWaveResult`.
+ */
+export interface ReportWave {
+  start(request: ReportWaveRequest, control?: WaveControl): Promise<StartWaveResult>;
+  collect(ref: ReportWaveRef): Promise<CollectWaveResult>;
+  run(request: ReportWaveRequest, control?: WaveControl): Promise<ReportWaveResult>;
+}
+
+/**
+ * The grace a collect allows a not-yet-settled wave before answering `"running"`: long enough
+ * to absorb ordering skew between the native completion notice and aggregate resolution,
+ * bounded so a premature call can yield again. The `PERK_WAVE_COLLECT_GRACE_MS` env knob is the ONE grace seam
+ * (module-private — there is no per-call grace parameter); invalid values fall back.
+ */
+const WAVE_COLLECT_GRACE_MS = 15_000;
+
+function collectGraceMs(): number {
+  const raw = Number(process.env.PERK_WAVE_COLLECT_GRACE_MS ?? "");
+  return Number.isFinite(raw) && raw > 0 ? raw : WAVE_COLLECT_GRACE_MS;
+}
+
+/**
+ * One pending (started, uncollected) wave: the frozen pre-launch key manifest snapshot (copied
+ * from the launch manifest at start — caller mutation of the returned `StartWaveResult.launch`
+ * can never change a later collect's keys) plus the never-rejecting result promise. NO drained
+ * flag: presence in the instance's map IS pending. After settlement the normalized promise
+ * owns retained partial reports until collection; no later artifact read or resume recovers them.
+ */
+interface PendingRecord {
+  keys: readonly string[];
+  result: Promise<ReportWaveResult>;
+}
+
+/**
+ * A launched (or launch-failed) wave as the internal core reports it — the module-private
+ * predecessor shape the opaque lifecycle wraps (the run handle and result promise never leave
+ * the module).
+ */
+type InternalStart =
+  | {
+      ok: true;
+      handle: WaveRunHandle;
+      result: Promise<ReportWaveResult>;
+      launch: ReportWaveLaunchManifest;
+    }
+  | { ok: false; result: ReportWaveResult; launch: ReportWaveLaunchManifest };
+
 /**
- * Start a report wave without blocking on completion: render the all-settled lane script (the
- * programmer-error throws — empty lanes / duplicate keys — are preserved), launch it via
- * `startWaveScript`, and on success return the run handle plus a `result` promise that applies
- * the shared settle (normalization + completeness + receipt enrichment) when the run finishes.
- * A launch failure comes back as an already-settled, normalized `WaveResult`.
+ * The internal launch core: validate the COMPLETE requested manifest (the programmer-error
+ * throws — empty/duplicate/invalid keys — are preserved even for an unavailable required
+ * skill), run the required-skill preflight partition, render the all-settled assignment script
+ * over the runnable subset, and launch it via `startWaveScript`. On success the never-rejecting
+ * `result` promise applies the shared settle (normalization + completeness + receipt
+ * enrichment + preflight-failure merge) when the run finishes; a launch failure comes back as
+ * an already-settled, normalized `ReportWaveResult`.
  */
-export async function startReportWave(
-  adapter: WaveAdapter,
-  spec: WaveSpec,
+async function startWave(
+  supplyAdapter: () => WaveAdapter,
+  request: ReportWaveRequest,
   signal?: AbortSignal,
-): Promise<ReportWaveStart> {
-  // Validate the COMPLETE requested manifest before source preflight partitions any lane out.
-  // This preserves the programmer-error contract even for an unavailable required skill.
-  validateWaveLanes(spec.lanes);
-  const preflight = spec.requiredSkillPreflight ?? preflightPonytailSkill;
+): Promise<InternalStart> {
+  validateAssignments(request.assignments);
+  const preflight = request.requiredSkillPreflight ?? preflightPonytailSkill;
   const checked = new Map<string, PonytailPreflight>();
-  const runnable: WaveLane[] = [];
-  const skillFailures: WaveFailure[] = [];
-  for (const lane of spec.lanes) {
-    if (lane.requiredSkill === undefined) {
-      runnable.push(lane);
+  const runnable: ReportAssignment[] = [];
+  const skillFailures: ReportWaveFailure[] = [];
+  for (const assignment of request.assignments) {
+    if (assignment.requiredSkill === undefined) {
+      runnable.push(assignment);
       continue;
     }
-    let result = checked.get(lane.requiredSkill.skillFile);
+    let result = checked.get(assignment.requiredSkill.skillFile);
     if (result === undefined) {
-      result = await preflight(lane.requiredSkill);
-      checked.set(lane.requiredSkill.skillFile, result);
+      result = await preflight(assignment.requiredSkill);
+      checked.set(assignment.requiredSkill.skillFile, result);
     }
     if (result.ok) {
-      runnable.push(lane);
+      runnable.push(assignment);
     } else {
-      skillFailures.push({ key: lane.key, reason: "skill-unavailable", detail: result.detail });
+      skillFailures.push({
+        key: assignment.key,
+        reason: "skill-unavailable",
+        detail: result.detail,
+      });
     }
   }
 
-  const launch: WaveLaunchManifest = {
-    requested: spec.lanes.map((lane) => lane.key),
-    runnable: runnable.map((lane) => lane.key),
+  const launch: ReportWaveLaunchManifest = {
+    requested: request.assignments.map((assignment) => assignment.key),
+    runnable: runnable.map((assignment) => assignment.key),
     preflightFailures: [...skillFailures],
   };
 
-  const settleWithSkillFailures = (result: WaveResult): WaveResult => {
+  const settleWithSkillFailures = (result: ReportWaveResult): ReportWaveResult => {
     if (skillFailures.length === 0) return result;
     const failures = [...result.failures, ...skillFailures];
     const complete =
-      spec.completeness === "strict"
+      request.completeness === "strict"
         ? failures.length === 0
         : failures.every((failure) => failure.key !== null);
     return { ...result, complete, failures };
@@ -793,18 +587,18 @@ export async function startReportWave(
     };
   }
 
-  // Required-skill metadata never reaches the renderer; only runnable lanes spawn.
-  const runnableSpec: WaveSpec = { ...spec, lanes: runnable };
+  // Required-skill metadata never reaches the renderer; only runnable assignments spawn.
+  const runnableRequest: ReportWaveRequest = { ...request, assignments: runnable };
   const workflowScript = renderWaveScript(runnable);
 
   const start = await startWaveScript(
-    adapter,
+    supplyAdapter(),
     {
-      flow: spec.flow,
+      flow: request.flow,
       workflowScript,
-      outputSchema: spec.outputSchema,
-      ...(spec.model !== undefined ? { model: spec.model } : {}),
-      ...(spec.timeoutMs !== undefined ? { timeoutMs: spec.timeoutMs } : {}),
+      outputSchema: request.outputSchema,
+      ...(request.model !== undefined ? { model: request.model } : {}),
+      ...(request.timeoutMs !== undefined ? { timeoutMs: request.timeoutMs } : {}),
     },
     signal,
   );
@@ -814,7 +608,7 @@ export async function startReportWave(
       result: settleWithSkillFailures(
         settleReportWave(
           { ok: false, failure: start.failure, receipt: start.receipt },
-          runnableSpec,
+          runnableRequest,
         ),
       ),
       launch,
@@ -824,22 +618,88 @@ export async function startReportWave(
     ok: true,
     handle: start.handle,
     result: start.result.then((run) =>
-      settleWithSkillFailures(settleReportWave(run, runnableSpec)),
+      settleWithSkillFailures(settleReportWave(run, runnableRequest)),
     ),
     launch,
   };
 }
 
+const STILL_RUNNING = Symbol("wave-still-running");
+
 /**
- * Run a report wave to completion — the blocking form: `startReportWave` + await its `result`
- * (one operational core). Every operational failure normalizes into `WaveResult` — the only
- * throws are programmer errors (empty lanes / duplicate keys, via `renderWaveScript`).
+ * The one internal core both factories share: an instance-owned pending map over a per-launch
+ * adapter supplier. Pending state belongs to the wave INSTANCE — `waveB.collect(refFromA)` is
+ * `"none"` structurally — and the WeakMap plus the settled drain's delete both release retained
+ * results promptly.
  */
-export async function runReportWave(
-  adapter: WaveAdapter,
-  spec: WaveSpec,
-  signal?: AbortSignal,
-): Promise<WaveResult> {
-  const start = await startReportWave(adapter, spec, signal);
-  return start.ok ? await start.result : start.result;
+function waveOver(supplyAdapter: () => WaveAdapter): ReportWave {
+  const records = new WeakMap<ReportWaveRef, PendingRecord>();
+
+  return {
+    async start(request, control) {
+      const start = await startWave(supplyAdapter, request, control?.signal);
+      if (!start.ok) {
+        return { ok: false, result: start.result, launch: start.launch };
+      }
+      // The ONE mint site — the isolated assertion, immediately after the runtime evidence of
+      // a successful launch. The keys snapshot is frozen and copied, never an alias of the
+      // returned manifest.
+      const ref = {} as ReportWaveRef;
+      records.set(ref, { keys: Object.freeze([...start.launch.requested]), result: start.result });
+      return {
+        ok: true,
+        ref,
+        runId: start.handle.asyncId,
+        asyncDir: start.handle.asyncDir,
+        launch: start.launch,
+      };
+    },
+
+    async collect(ref) {
+      const record = records.get(ref);
+      if (record === undefined) return { kind: "none" };
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let raced: ReportWaveResult | typeof STILL_RUNNING;
+      try {
+        raced = await Promise.race([
+          record.result,
+          new Promise<typeof STILL_RUNNING>((resolve) => {
+            timer = setTimeout(() => resolve(STILL_RUNNING), collectGraceMs());
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (raced === STILL_RUNNING) {
+        // The record stays in the map: its bound remains the module-owned wave timeout, and a
+        // later collect drains whatever it settles into.
+        return { kind: "running" };
+      }
+      // The delete IS the atomic drain claim: single-threaded JS makes the post-await
+      // delete-as-claim exact — overlapping collects of one ref yield exactly one settled
+      // winner; the loser (already-deleted) answers `"none"`.
+      if (!records.delete(ref)) return { kind: "none" };
+      return { kind: "settled", keys: record.keys, result: raced };
+    },
+
+    async run(request, control) {
+      const start = await startWave(supplyAdapter, request, control?.signal);
+      return start.ok ? await start.result : start.result;
+    },
+  };
+}
+
+/**
+ * The PRODUCTION factory — the wave owns adapter selection: constructs a FRESH rpc adapter per
+ * launch over the supplied bus (per-execute adapter freshness; no shared mutable ping state).
+ * One per-activation instance is constructed at the composition root (`extension/index.ts`) and
+ * threaded to the installers.
+ */
+export function createReportWave(bus: WaveBus): ReportWave {
+  return waveOver(() => createRpcWaveAdapter(bus));
+}
+
+/** The injection seam (tests; the same internal core over one supplied adapter). */
+export function reportWaveOver(adapter: WaveAdapter): ReportWave {
+  return waveOver(() => adapter);
 }