opencode-swarm 7.161.1 → 7.162.1

package/dist/pr-review/legacy-transcript-adapter.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Legacy transcript adapter — the transcript/artifact-text → canonical
+ * conversion authority (issue #2385).
+ *
+ * This is the ONLY module allowed to convert raw transcript / artifact text
+ * into canonical PR-review data (verdict rows, per-item verdicts, feedback
+ * classifications). The locality contract is enforced mechanically by
+ * `scanTranscriptParsingOutsideAdapter` in `src/pr-review/guardrails.ts`:
+ * every identifier in `TRANSCRIPT_CONVERSION_SYMBOLS` may appear only in this
+ * file across `src/`. The gate therefore consumes this boundary through the
+ * `legacy*`-prefixed aliases and the test surface exported below — never
+ * through the conversion identifiers themselves.
+ *
+ * Compat gating: the settlement path that accepts legacy (pre-structured-
+ * receipt) transcript text is governed by the delegation record's
+ * `pr_review_legacy_transcript_compatibility` flag (default false), read
+ * through `prReviewLegacyTranscriptCompatibilityEnabled` from
+ * `src/background/pr-review-contract.ts`. That settlement path emits no
+ * deprecation diagnostic today and none is added here; this header documents
+ * the gate only.
+ *
+ * Binding contract (same precedent as `bindPrReviewCompletionHelpers` in
+ * `completion.ts` and `bindPrReviewReentryBindingReader` in
+ * `authorization.ts`): this boundary must never import the orchestration gate
+ * back. Gate-owned composition/settlement helpers are supplied by the owning
+ * gate through `bindPrReviewTranscriptAdapterHelpers`, bound once at gate
+ * module init.
+ *
+ * State typing: the moved functions read only the PR-review slices of the
+ * gate's `PrWorkflowGateState` and `PrReviewGateContext`, expressed as the
+ * local structural interfaces below; the gate passes its full state and
+ * context, which satisfy the slices structurally without a projection step.
+ */
+import { type LaneOutputArtifact } from '../background/lane-output-store.js';
+import { type BackgroundDelegationRecord } from '../background/pending-delegations.js';
+import { type PrReviewRiskImpact, type PrReviewRiskTag } from '../background/pr-review-contract.js';
+export type PrReviewComposablePhase = 'reviewer' | 'critic';
+/** One item's admitted verdict plus the lane provenance that admitted it. */
+export interface PrReviewItemClaim {
+    batchId: string;
+    laneId: string;
+    workflowLane: string;
+    /** Reviewer classification, or critic status. */
+    classification: string;
+    severity: string;
+    /**
+     * Typed risk metadata from the reviewer row (issue #2383). Reviewer claims
+     * only; absent on critic claims, which never re-assess routing risk.
+     */
+    riskImpact?: PrReviewRiskImpact;
+    riskTags?: PrReviewRiskTag[];
+    /**
+     * sha256 of the full canonical `[REVIEWED]` row this claim was parsed from.
+     * Reviewer claims only — this is what a critic batch binds to per item.
+     */
+    rowDigest?: string;
+}
+export interface PrReviewPhaseComposition {
+    /** Item id -> winning claim. Most recent successful lane per item wins. */
+    claims: Map<string, PrReviewItemClaim>;
+    requiredInventory: string[];
+    unclaimed: string[];
+    contributingBatchIds: string[];
+    diagnostics: string[];
+}
+/** Validation-batch shape, as the transcript composition reads it. */
+export interface PrReviewTranscriptBatch {
+    batchId: string;
+    lanes: ReadonlyArray<PrReviewTranscriptLane>;
+    validatedAt: string;
+}
+/** Declared lane shape, as the transcript composition reads it. */
+export interface PrReviewTranscriptLane {
+    laneId: string;
+    workflowLane: string;
+    reviewItemIds?: string[];
+}
+/**
+ * Per-batch coherence keys for item-keyed reviewer/critic composition, as the
+ * adapter reads them (structural slice of the gate's record).
+ */
+export interface PrReviewTranscriptBatchCoherence {
+    /**
+     * The exact candidate/critic inventory this batch's ownership was validated
+     * against at record time.
+     */
+    validatedInventory: string[];
+    /** Critic batches only: per-item sha256 of the authoritative `[REVIEWED]` row. */
+    reviewerItemBindings?: Record<string, string>;
+    /** Key encoding for reviewerItemBindings; absent means legacy raw item IDs. */
+    reviewerItemBindingKeyEncoding?: 'prefixed-v1';
+}
+/** Settled PR_FEEDBACK verification batch, as the adapter reads it. */
+export interface PrReviewTranscriptFeedbackVerification {
+    batchId: string;
+    ownership: ReadonlyArray<{
+        laneId: string;
+    }>;
+}
+/**
+ * The PR-review slice of the owning gate's `PrWorkflowGateState`: exactly the
+ * fields the moved conversion/composition machinery reads directly. The gate's
+ * full state type satisfies this structurally.
+ */
+export interface PrReviewTranscriptState {
+    sessionID: string;
+    prReviewBatchCoherence?: Record<string, PrReviewTranscriptBatchCoherence>;
+    prFeedbackVerifications?: PrReviewTranscriptFeedbackVerification[];
+}
+/** The gate-context surface the transcript composition consumes (full ctx is gate-owned). */
+export interface PrReviewTranscriptContext {
+    readonly revisionDigest: string;
+    reviewer?: PrReviewPhaseComposition;
+    critic?: PrReviewPhaseComposition;
+}
+/** A batch-integrity-qualified record, as the transcript composition consumes it. */
+export interface PrReviewTranscriptQualifiedBatchRecord {
+    record: BackgroundDelegationRecord;
+    expectedLane: PrReviewTranscriptLane;
+    expectedWorkflowLane: string;
+}
+/**
+ * Gate-owned composition/settlement helpers, bound by the owning gate at
+ * module init so this boundary never imports the gate back. Declared with
+ * method syntax on purpose: the gate's implementations accept/return its FULL
+ * state and context types, which are structural supersets of the slices
+ * above, and interface method parameters are checked bivariantly.
+ */
+export interface PrReviewTranscriptGateHelpers {
+    derivePrReviewCandidateInventory(directory: string, state: PrReviewTranscriptState, ctx: PrReviewTranscriptContext): string[];
+    derivePrReviewCriticInventory(directory: string, state: PrReviewTranscriptState, ctx: PrReviewTranscriptContext): string[];
+    authoritativeReviewerClaims(directory: string, state: PrReviewTranscriptState, ctx: PrReviewTranscriptContext): ReadonlyMap<string, PrReviewItemClaim>;
+    reviewerSubagentSessionIds(directory: string, state: PrReviewTranscriptState): Set<string>;
+    prReviewPhaseWindow(state: PrReviewTranscriptState, phase: PrReviewComposablePhase): PrReviewTranscriptBatch[];
+    batchMayContributeClaims(directory: string, state: PrReviewTranscriptState, batch: PrReviewTranscriptBatch, phase: PrReviewComposablePhase, requiredInventory: readonly string[], forbiddenSubagentSessionIds: ReadonlySet<string>, reviewerClaims: ReadonlyMap<string, PrReviewItemClaim> | undefined, ctx: PrReviewTranscriptContext): boolean;
+    recordsPassingBatchIntegrity(directory: string, state: PrReviewTranscriptState, batchId: string, expectedLanes: ReadonlyArray<PrReviewTranscriptLane>, expectedMode: string, validatedAt: string, checkWorkflowLane?: boolean, forbiddenSubagentSessionIds?: ReadonlySet<string>, diagnostics?: string[]): PrReviewTranscriptQualifiedBatchRecord[];
+    loadArtifactPassingLaneIntegrity(directory: string, state: PrReviewTranscriptState, record: BackgroundDelegationRecord, expectedMode: string, expectedWorkflowLane: string, expectedRevisionDigest: string, diagnostics?: string[]): LaneOutputArtifact | null;
+}
+export declare function bindPrReviewTranscriptAdapterHelpers(helpers: PrReviewTranscriptGateHelpers): void;
+/**
+ * Prefix item IDs before using them as persisted object keys. In particular,
+ * assigning a raw `__proto__` key to an ordinary object invokes JavaScript's
+ * prototype setter instead of creating an own property.
+ */
+export declare function reviewerItemBindingKey(itemId: string): string;
+/**
+ * The single item-keyed computation behind reviewer/critic settlement AND every
+ * reviewer/critic verdict derivation.
+ *
+ * Settlement *is* `unclaimed.length === 0` over this map, so settlement can never
+ * pass while derivation returns nothing — the failure mode that would let
+ * CONFIRMED CRITICAL/HIGH findings ship without critic coverage.
+ *
+ * Scanning the window reverse-chronologically and claiming only *unclaimed*
+ * items makes first-write-wins equal "most recent successful lane per item wins",
+ * which is the explicit conflict rule for the case where two batches both carry a
+ * parseable verdict for one item. Memoized per gate context so two passes never
+ * hold two different verdict maps.
+ *
+ * The scan stops as soon as every required item is claimed (issue #1968 FIX 5).
+ * `readLaneOutput` is a synchronous `readFileSync` per lane per batch, and the
+ * window can hold up to `MAX_WORKFLOW_BATCHES` batches, so scanning past a
+ * complete claim set is unbounded blocking I/O for no verdict change — first
+ * write wins, and every required item has already been written.
+ *
+ * `exhaustive` turns the exit off for the batch GC, which prunes a reviewer
+ * batch on "it contributed no claim". Being precise about what that buys: with
+ * *this* exit condition the two scans yield the same `contributingBatchIds`,
+ * because the exit fires only when every required item is claimed and a batch
+ * reached after that point could never have claimed anything anyway. The flag is
+ * therefore not fixing a live divergence — it decouples a durable-state decision
+ * from a performance heuristic, so that weakening the exit condition later
+ * cannot silently turn "not examined" into "proven inert". It also keeps the
+ * whole-window abandoned-lane diagnostics intact for the GC's scan.
+ */
+export declare function composePrReviewPhaseVerdicts(directory: string, state: PrReviewTranscriptState, phase: PrReviewComposablePhase, ctx: PrReviewTranscriptContext, exhaustive?: boolean): PrReviewPhaseComposition;
+export interface IndexedVerdictRows {
+    markerRows: string[][];
+    rowsByItemId: Map<string, string[][]>;
+    recoveries: Array<{
+        marker: '[REVIEWED]' | '[CRITIC]';
+        itemId: string;
+        recovery: 'legacy-fidelity-safe' | 'legacy-lossy';
+    }>;
+}
+export declare function indexVerdictRows(text: string, marker: '[REVIEWED]' | '[CRITIC]'): IndexedVerdictRows;
+export declare function validateReviewerVerdictFields(fields: string[]): string[] | null;
+/**
+ * Digest of the FULL canonical reviewer row, not the classification/severity
+ * pair a reviewer verdict projects to. Only 2 of the 12 required fields survive
+ * that projection, so a tuple binding would still match a row whose evidence,
+ * file:line and root cause all changed. Fields are joined on NUL, which
+ * `pipeFields` can never produce, so no field boundary is forgeable.
+ */
+export declare function reviewerVerdictRowDigest(fields: readonly string[]): string;
+/**
+ * Per-item verdicts an artifact actually carries, as a map rather than a
+ * boolean. This is the granularity the composition needs: one unparseable item
+ * must not discard its healthy siblings in the same lane.
+ */
+export declare function parseLaneItemVerdicts(text: string, itemIds: readonly string[], phase: PrReviewComposablePhase, reviewerClaims?: ReadonlyMap<string, PrReviewItemClaim>): Map<string, {
+    classification: string;
+    severity: string;
+    riskImpact?: PrReviewRiskImpact;
+    riskTags?: PrReviewRiskTag[];
+    rowDigest?: string;
+}>;
+export declare function parsePrReviewVerdictRows(text: string, itemIds: readonly string[], phase: PrReviewComposablePhase, reviewerClaims?: ReadonlyMap<string, PrReviewItemClaim>): {
+    markerRows: string[][];
+    parsed: Map<string, {
+        classification: string;
+        severity: string;
+        riskImpact?: PrReviewRiskImpact;
+        riskTags?: PrReviewRiskTag[];
+        rowDigest?: string;
+    }>;
+    recoveries: IndexedVerdictRows['recoveries'];
+};
+/** Exact assigned-row contract used by both normal and recovered collection. */
+export declare function analyzePrReviewVerdictRowContract(text: string, itemIds: readonly string[], phase: PrReviewComposablePhase, reviewerClaims?: ReadonlyMap<string, PrReviewItemClaim>): {
+    ok: boolean;
+    expected: string;
+    actual: string;
+    recoveries: IndexedVerdictRows['recoveries'];
+};
+export declare function parseCriticVerdict(text: string, itemId: string, reviewerSeverity?: string): {
+    status: string;
+    severity: string;
+} | null;
+export declare function validateCriticVerdictFields(fields: string[], reviewerSeverity?: string): {
+    status: string;
+    severity: string;
+} | null;
+export declare function artifactHasExactPositiveVerdictRow(text: string, marker: string, itemId: string, positiveVerdict: string): boolean;
+export declare function pipeFields(line: string): string[];
+/**
+ * `pipeFields` capped at the row's canonical field count: separators beyond the
+ * expected count merge back into the trailing (free-text) field. Verdict rows
+ * ([REVIEWED], [CRITIC], [FEEDBACK-VERIFIED]) carry prose evidence in their
+ * last field, and prose containing literal pipes (regex text, `,;|`, shell
+ * snippets) otherwise splits the row past its strict field-count check and the
+ * whole verdict becomes unparseable. Deterministic: the enumerated leading
+ * fields are never merged.
+ */
+export declare function pipeFieldsCapped(line: string, expectedFieldCount: number): string[];
+export declare function feedbackArtifactCoversItems(directory: string, state: PrReviewTranscriptState, batchId: string, laneId: string, itemIds: readonly string[]): boolean;
+export declare function feedbackArtifactTextCoversItems(text: string, itemIds: readonly string[]): boolean;
+/**
+ * Read the settled verification classification of every inventory item from the
+ * settled verification batches' lane outputs (issue #2131 criterion C1). An
+ * item missing from the map has no settled verified classification.
+ */
+export declare function readSettledFeedbackClassifications(directory: string, state: PrReviewTranscriptState): Map<string, string>;
+/**
+ * Issue #2385 guardrail aliases: the transcript-conversion identifiers may
+ * appear only in this module (`scanTranscriptParsingOutsideAdapter` in
+ * `src/pr-review/guardrails.ts`), so the owning gate imports these aliases
+ * instead of the canonical names.
+ */
+export declare const analyzeLegacyVerdictRowContract: typeof analyzePrReviewVerdictRowContract;
+export declare const legacyArtifactHasExactPositiveVerdictRow: typeof artifactHasExactPositiveVerdictRow;
+export declare const legacyFeedbackArtifactCoversItems: typeof feedbackArtifactCoversItems;
+export declare const legacyFeedbackArtifactTextCoversItems: typeof feedbackArtifactTextCoversItems;
+export declare const readLegacySettledFeedbackClassifications: typeof readSettledFeedbackClassifications;
+/**
+ * The gate's historical `_test_exports` surface for this cluster: spread onto
+ * the gate's `_test_exports` at module init so the existing suites keep seeing
+ * the same property names without the gate naming the conversion identifiers.
+ */
+export declare const legacyTranscriptAdapterTestSurface: {
+    pipeFieldsCapped: typeof pipeFieldsCapped;
+    indexVerdictRows: typeof indexVerdictRows;
+    reviewerVerdictRowDigest: typeof reviewerVerdictRowDigest;
+    analyzePrReviewVerdictRowContract: typeof analyzePrReviewVerdictRowContract;
+    parseLaneItemVerdicts: typeof parseLaneItemVerdicts;
+};

package/dist/pr-review/persistence.d.ts

@@ -0,0 +1,107 @@
+/**
+ * PR-review workflow persistence adapter (issues #2385).
+ *
+ * The single atomic persistence boundary for PR-review workflow state, moved
+ * from `src/hooks/pr-workflow-gate.ts` (region: state locks, CAS write,
+ * bounded parsing, atomic JSON writes, safe-parent/identity assertions, path
+ * helpers, in-memory caches). Every durable PR-review gate-state write goes
+ * through this module; the recurrence sweep (issue #2385) forbids direct
+ * writes to the state shape outside this boundary.
+ *
+ * Binding contract (issue #2385 plan, critic item 1): the owning gate binds
+ * (a) its full Zod state codec via `bindPrReviewStateCodec` and (b) its
+ * `_test_exports` object via `bindPrReviewPersistenceHooks`. Properties are
+ * read at CALL time through the bound reference — never destructured at bind
+ * time — so test-time property mutation and `resetTrackedStateCache` remain
+ * fully visible. Defaults in `defaultPersistenceHooks` make the module usable
+ * standalone and are what the gate resets seams back to.
+ *
+ * The recovery-salvage reader (`readPrWorkflowGateStateForRecovery`) remains
+ * in the gate: it composes PR_FEEDBACK sub-schemas (gate-owned) and is a
+ * read-only diagnostic built on these primitives.
+ */
+import type { BigIntStats } from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import type { ZodError } from 'zod';
+export declare function normalizeSessionID(sessionID: string): string;
+export declare function prWorkflowSessionFileStem(sessionID: string): string;
+export declare const WORKFLOW_GATE_DIR = "pr-workflow-gates";
+export declare function workflowGateStateRelativePath(sessionID: string): string;
+export declare function workflowGateStateLockRelativePath(sessionID: string): string;
+export declare function workflowCheckoutMutationLockRelativePath(): string;
+export declare function workflowGateStatePath(directory: string, sessionID: string): string;
+export declare const MAX_TRACKED_SESSIONS = 200;
+export declare const CHECKOUT_MUTATION_ACTION_TIMEOUT_MS: number;
+export declare const trackedStatesByProjectSession: Map<string, PrWorkflowPersistedStateBase>;
+export declare function isoNow(): string;
+export declare function delay(ms: number): Promise<void>;
+export declare function sameBigIntFileIdentity(left: Pick<BigIntStats, 'dev' | 'ino'>, right: Pick<BigIntStats, 'dev' | 'ino'>): boolean;
+export declare function normalizeComparableFsPath(value: string): string;
+export declare function stateCacheKey(directory: string, sessionID: string): string;
+export declare function rememberState<S extends PrWorkflowPersistedStateBase>(directory: string, state: S): void;
+/** Drop one session's cached state (gate clear/abort paths). */
+export declare function forgetTrackedPrWorkflowState(directory: string, sessionID: string): void;
+/** Test reset: clear every in-process persistence cache/queue. */
+export declare function resetPrReviewPersistenceCaches(): void;
+export interface PrReviewPersistenceHooks {
+    nowMs: () => number;
+    isProcessAlive: (pid: number) => boolean;
+    openCheckoutLock: (lockPath: string) => ReturnType<typeof fsp.open>;
+    removeCheckoutLock: (lockPath: string) => Promise<void>;
+    checkoutMutationActionTimeoutMs: number;
+    rename: (from: string, to: string) => Promise<void>;
+    beforeSessionStateLockWrite?: () => Promise<void>;
+    beforeCheckoutLockWrite?: () => Promise<void>;
+    beforeSafeDirectoryCreate?: (parentPath: string, nextPath: string) => Promise<void>;
+    beforeAtomicTempWrite?: () => Promise<void>;
+    beforeAtomicRename?: () => Promise<void>;
+}
+export declare const defaultPersistenceHooks: PrReviewPersistenceHooks;
+/**
+ * Bind the persistence seam. The gate passes its `_test_exports` object (same
+ * reference) so property mutation by tests is read at call time.
+ */
+export declare function bindPrReviewPersistenceHooks(nextHooks: PrReviewPersistenceHooks): void;
+/** Structural minimum the CAS machinery relies on. */
+export interface PrWorkflowPersistedStateBase {
+    schemaVersion: number;
+    revision: number;
+    sessionID: string;
+    workflowInstanceId?: string;
+}
+export interface PrReviewStateCodec<S extends PrWorkflowPersistedStateBase> {
+    safeParse: (data: unknown) => {
+        success: true;
+        data: S;
+    } | {
+        success: false;
+        error: ZodError;
+    };
+    parse: (data: unknown) => S;
+}
+export declare function bindPrReviewStateCodec<S extends PrWorkflowPersistedStateBase>(nextCodec: PrReviewStateCodec<S>): void;
+export declare function ensurePrWorkflowSafeParentDirectory(directory: string, filePath: string): Promise<string>;
+export declare function writeAtomicJson(directory: string, filePath: string, value: unknown): Promise<void>;
+/**
+ * Write a PR-workflow artifact with the gate's Windows-safe atomic persistence
+ * contract. Checkout-preparation receipts must survive the same transient
+ * rename contention as canonical gate state.
+ */
+export declare function writePrWorkflowAtomicJson(directory: string, filePath: string, value: unknown): Promise<void>;
+export declare function readPrWorkflowGateStateFromDisk<S extends PrWorkflowPersistedStateBase>(directory: string, sessionID: string): Promise<S | null>;
+export declare function readPrWorkflowGateStateFileFromDisk<S extends PrWorkflowPersistedStateBase>(filePath: string, stateLabel: string): Promise<S | null>;
+/** Persist one CAS-checked state replacement while the session lock is held. */
+export declare function writeStateWhileLocked<S extends PrWorkflowPersistedStateBase>(directory: string, state: S, options?: {
+    replaceWorkflowInstanceId?: string;
+}): Promise<S>;
+/** A bounded checkout-mutation refusal that never permits unsafe late overlap. */
+export declare class PrWorkflowCheckoutMutationTimeoutError extends Error {
+    readonly phase: 'queue' | 'action';
+    readonly code: "PR_WORKFLOW_CHECKOUT_MUTATION_TIMEOUT";
+    readonly retryable: false;
+    constructor(phase: 'queue' | 'action');
+}
+/** Serialize project-wide checkout mutations before any session state lock. */
+export declare function withPrWorkflowCheckoutMutationLock<T>(directory: string, action: () => Promise<T>): Promise<T>;
+/** Serialize in-process mutations; the durable revision rejects stale callers. */
+export declare function withSessionStateMutation<T>(directory: string, sessionID: string, action: () => Promise<T>): Promise<T>;

package/dist/pr-review/reducer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * PR-review transition authority (issue #2385).
+ *
+ * Pure `(state, event) -> { state, effects }` reducer over the closed
+ * `PrReviewEvent` union. Rule computation is delegated to the focused
+ * boundary modules (`circuit.ts`, `completion.ts` via its settlement inputs,
+ * `critic-routing.ts`, `lifecycle.ts`); this module owns transition
+ * composition and the explicit rejection of every invalid transition class
+ * named by issue #2385:
+ *
+ * - observer deadline / client absence → terminal child failure
+ * - raw transcript / parser failure → provider circuit signal
+ * - one lane → multiple circuit samples (delegated to circuit.ts's
+ *   distinct-`(generation, batch, lane)` scan; asserted by property tests)
+ * - unresolved/live lane → terminal coverage report
+ * - partial/no coverage → approval
+ * - ordinary MEDIUM → critic without typed high-impact/vulnerability evidence
+ *   (enforced where critic inventory is composed, via critic-routing.ts)
+ * - stale/foreign authorization → reviewer or publication access
+ * - late old-generation result → current-state mutation
+ * - structured receipt → downgrade by later transcript parsing
+ *
+ * The owning gate and `dispatch-lanes` are orchestration adapters: they build
+ * events from real I/O, apply the returned state, and map typed rejections to
+ * the operator-facing BLOCKED messages. Effects are the transition's OUTPUT
+ * CONTRACT — every effect kind maps to an executor that exists in production
+ * (see `PrReviewEffect` in types.ts): the gate executes `persist_state`
+ * through the persistence CAS write; `settle_delegation` describes the
+ * delegation settlement the dispatch/collect adapters perform through
+ * `pending-delegations.ts`; `emit_diagnostic` describes the collect
+ * observer's bounded diagnostics channel; `block_dispatch` describes the
+ * circuit-open admission refusal. No effect kind is emitted without a real
+ * executor (reviewer finding 1, issue #2385 Phase 8b).
+ *
+ * Probe outcomes other than an admission rollback are processed by the
+ * machine on the NEXT staged admission: the gate feeds the recorded probe's
+ * observation into `advancePrReviewCircuit` (`probeObservationForCircuit`),
+ * which is the design's single advance-per-admission cadence.
+ */
+import type { PrReviewEffect, PrReviewEvent, PrReviewTransitionRejection, PrReviewWorkflowState } from './types.js';
+export type PrReviewReduceResult = {
+    status: 'applied';
+    state: PrReviewWorkflowState;
+    effects: PrReviewEffect[];
+} | {
+    status: 'rejected';
+    state: PrReviewWorkflowState;
+    rejection: PrReviewTransitionRejection;
+};
+/**
+ * The transition authority. Pure: every I/O input arrives on the event; every
+ * write leaves as an effect. The state is never mutated in place.
+ */
+export declare function reducePrReviewEvent(state: PrReviewWorkflowState, event: PrReviewEvent): PrReviewReduceResult;

package/dist/pr-review/types.d.ts

@@ -0,0 +1,225 @@
+/**
+ * PR-review typed state boundary (issue #2385).
+ *
+ * The closed event/effect vocabulary for the PR-review transition authority
+ * (`reducer.ts`) plus the PR-review slice of the workflow gate state. The
+ * owning gate's full `PrWorkflowGateState` satisfies this slice structurally
+ * (a compile-time assertion in the gate enforces it), so there is ONE field
+ * definition — the gate adds only non-PR-review fields.
+ *
+ * Invalid transitions from issue #2385 are rejected with typed codes
+ * (`PrReviewTransitionRejectionCode`) rather than made representable-by-type
+ * alone: several of them depend on runtime evidence (generations, digests,
+ * ledger state), so the reducer is the enforcement point.
+ */
+import type { PrReviewBaseDimensionId } from '../background/pr-review-contract.js';
+import type { PrReviewCircuitSignal, PrReviewResiliencePolicyRecord } from './circuit.js';
+/** A declared base-dispatch lane (subset the reducer governs). */
+export interface PrReviewBaseDispatchLane {
+    laneId: string;
+    workflowLane: PrReviewBaseDimensionId;
+    ownedWorkflowLanes?: PrReviewBaseDimensionId[];
+}
+export interface PrReviewBaseDispatchRecordLite {
+    batchId: string;
+    lanes: PrReviewBaseDispatchLane[];
+    validatedAt: string;
+}
+export interface PrReviewDimensionCancellationLite {
+    reason: string;
+    cancelledAt: string;
+    source: 'armed_recovery';
+}
+export interface PrReviewResilienceSlice {
+    policy: PrReviewResiliencePolicyRecord;
+    /** Attempt bookkeeping is adapter-owned; the reducer carries it opaquely. */
+    attempts: readonly unknown[];
+    circuit?: import('./circuit.js').PrReviewCircuitRecord | undefined;
+}
+/**
+ * The PR-review slice of the workflow gate state. The gate's full state type
+ * satisfies this structurally; the reducer may therefore be applied to the
+ * live gate state object without a projection step.
+ */
+export interface PrReviewWorkflowState {
+    sessionID: string;
+    workflowInstanceId?: string | undefined;
+    revision: number;
+    prHeadSha?: string | undefined;
+    prReviewBaseSha?: string | undefined;
+    prReviewBaseDispatches?: PrReviewBaseDispatchRecordLite[] | undefined;
+    prReviewBaseDispatch?: PrReviewBaseDispatchRecordLite | undefined;
+    prReviewResilience?: PrReviewResilienceSlice | undefined;
+    prReviewContractRetryDimensions?: PrReviewBaseDimensionId[] | undefined;
+    prReviewDimensionCancellations?: Partial<Record<PrReviewBaseDimensionId, PrReviewDimensionCancellationLite>> | undefined;
+    /** Coverage disclosure fields are carried opaquely (owned by completion.ts). */
+    prReviewPartialBaseCoverage?: unknown | undefined;
+}
+export type PrReviewTerminalCoverageKind = 'COMPLETE' | 'PARTIAL' | 'NO_COVERAGE';
+export type PrReviewReportVerdict = 'APPROVE' | 'INCOMPLETE' | 'REQUEST_CHANGES';
+export interface PrReviewCoverageSettlementInput {
+    kind: PrReviewTerminalCoverageKind;
+    coveredDimensions: PrReviewBaseDimensionId[];
+    unresolvedDimensions: Array<{
+        dimension: PrReviewBaseDimensionId;
+        terminalState: 'FAILED' | 'CANCELLED' | 'NOT_LAUNCHED';
+        reasonKind: string;
+    }>;
+    /** Dimensions with a live (non-terminal) lane — blocks finalization. */
+    liveDimensions: PrReviewBaseDimensionId[];
+}
+export type PrReviewEffect = {
+    kind: 'persist_state';
+} | {
+    kind: 'settle_delegation';
+    batchId: string;
+    laneId: string;
+    status: 'completed' | 'error' | 'cancelled' | 'stale';
+    replay?: boolean;
+} | {
+    kind: 'emit_diagnostic';
+    source: 'collection_observer' | 'legacy_transcript_adapter';
+    code: string;
+    boundedDetail?: string | undefined;
+} | {
+    kind: 'block_dispatch';
+    reason: 'circuit_open' | 'probe_in_flight';
+};
+/**
+ * Effect kinds map to executors that exist in production (issue #2385
+ * Phase 8b review): `persist_state` is executed by the gate through the
+ * persistence CAS write; `settle_delegation` describes the settlement the
+ * dispatch/collect adapters perform via `pending-delegations.ts`;
+ * `emit_diagnostic` describes the collect observer's bounded diagnostics
+ * channel; `block_dispatch` describes the circuit-open admission refusal.
+ * A kind with no executor is not emitted and not declared.
+ */
+export type PrReviewCircuitProbeOutcome = {
+    result: 'typed_success';
+} | {
+    result: 'provider_failure';
+    providerClass: string;
+} | {
+    result: 'ignored';
+} | {
+    result: 'rolled_back_admission';
+};
+export type PrReviewEvent = {
+    type: 'base_admission_requested';
+    batchId: string;
+    lanes: PrReviewBaseDispatchLane[];
+    depthTier: 'S' | 'M' | 'L';
+    maxBatches: number;
+    validatedAt: string;
+} | {
+    type: 'base_admission_rolled_back';
+    batchId: string;
+    batchDelegationRecordsExist: boolean;
+} | {
+    type: 'collection_observed';
+    diagnostic: 'busy' | 'retry' | 'idle_unknown' | 'host_unavailable' | 'probe_error' | 'wait_expired';
+    pendingLaneIds: readonly string[];
+    boundedDetail?: string | undefined;
+} | {
+    type: 'lane_structured_result_submitted';
+    batchId: string;
+    laneId: string;
+    generation: number;
+    semanticEnvelopeDigest: string;
+    outcome: 'CLEAN' | 'FINDINGS' | 'INCOMPLETE';
+    existingReceiptDigest?: string | undefined;
+} | {
+    type: 'transcript_evidence_presented';
+    batchId: string;
+    laneId: string;
+    laneHasStructuredReceipt: boolean;
+} | {
+    type: 'provider_terminal_observed';
+    batchId: string;
+    laneId: string;
+    generation: number;
+    evidence: {
+        source: 'typed_terminal_error_class';
+        category: string;
+        kind: string;
+    } | {
+        source: 'observer_deadline';
+    } | {
+        source: 'client_unavailable';
+    } | {
+        source: 'parser_or_transcript';
+    } | {
+        source: 'stale_observation';
+    };
+} | {
+    type: 'lane_cancelled';
+    batchId: string;
+    laneId: string;
+    generation: number;
+} | {
+    type: 'circuit_advance_requested';
+    nowMs: number;
+    laneSignals: readonly PrReviewCircuitSignal[];
+    probeObservation?: {
+        terminalStatus: string;
+        signal: PrReviewCircuitSignal | null;
+        terminalAtMs: number;
+    } | undefined;
+    admission?: {
+        batchId: string;
+        laneId: string;
+    } | undefined;
+    policy: PrReviewResiliencePolicyRecord;
+} | {
+    type: 'circuit_probe_settled';
+    outcome: PrReviewCircuitProbeOutcome;
+    nowMs: number;
+    policy: PrReviewResiliencePolicyRecord;
+} | {
+    type: 'resilience_config_changed';
+    enabled: boolean;
+    policy?: import('../config/schema.js').PrReviewResilienceConfig | undefined;
+    nowMs: number;
+} | {
+    type: 'coverage_finalization_requested';
+    settlement: PrReviewCoverageSettlementInput;
+    requestedVerdict?: PrReviewReportVerdict;
+} | {
+    type: 'critic_result_recorded';
+    criticRequiredFindingIds: readonly string[];
+    criticConfirmedFindingIds: readonly string[];
+} | {
+    type: 'publication_armed';
+    coverageKind: PrReviewTerminalCoverageKind;
+    verdict: PrReviewReportVerdict;
+} | {
+    type: 'publication_published';
+    binding: PrReviewAuthorizationBinding;
+} | {
+    type: 'armed_recovery_requested';
+    binding: PrReviewAuthorizationBinding;
+    dimensionsToCancel: PrReviewBaseDimensionId[];
+    nowIso: string;
+} | {
+    type: 'reviewer_authorization_consumed';
+    binding: PrReviewAuthorizationBinding;
+    expectedRole: 'reviewer' | 'test_engineer';
+    role: 'reviewer' | 'test_engineer';
+};
+/**
+ * The exact-identity binding an armed recovery, publication, or re-entry
+ * authorization must carry (issue #2383/#2385). Stale or foreign values are
+ * rejected with `stale_foreign_authorization`.
+ */
+export interface PrReviewAuthorizationBinding {
+    sessionID: string;
+    workflowInstanceId?: string | undefined;
+    prHeadSha: string;
+    revisionDigest?: string;
+    generation: number;
+}
+export type PrReviewTransitionRejectionCode = 'observer_deadline_not_terminal_evidence' | 'client_absence_not_terminal_evidence' | 'parser_failure_not_provider_signal' | 'stale_observation_not_provider_signal' | 'live_lane_blocks_coverage' | 'partial_coverage_cannot_approve' | 'no_coverage_cannot_approve' | 'critic_required_unfulfilled' | 'stale_foreign_authorization' | 'stale_generation_result' | 'receipt_cannot_be_downgraded' | 'duplicate_conflicting_result' | 'base_batch_limit_reached' | 'rollback_preconditions_failed' | 'lane_not_stale_eligible' | 'unknown_event';
+export interface PrReviewTransitionRejection {
+    code: PrReviewTransitionRejectionCode;
+    detail: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.161.1",
+	"version": "7.162.1",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",