opencode-swarm 7.162.0 → 7.162.1

package/dist/{hooks/pr-review-reentry-authorization.d.ts → pr-review/authorization.d.ts}

@@ -1,21 +1,29 @@
-import { z } from 'zod';
 /**
- * Correlated one-use reviewer re-entry authorization (issue #2383).
+ * PR-review authorization boundary (issues #2383, #2385).
+ *
+ * Correlated one-use reviewer re-entry authorization, moved behind the
+ * `src/pr-review/` boundary (issue #2385). This module replaces prompt-text
+ * inspection (`MODE: PR_REVIEW`) as the ONLY way a direct Task dispatch of
+ * `reviewer`/`test_engineer` may bypass the generic Stage-A task-workflow
+ * requirement. The PR workflow controller issues an authorization bound to
+ * the exact active session, workflow, run, base/head SHA, worktree revision
+ * digest, role, and gate generation; the Task delegation gate consumes it
+ * atomically, exactly once. Stale, cross-session, wrong-role, replayed,
+ * expired, or revision-drifted requests fail closed to the normal gating
+ * path.
  *
- * Replaces prompt-text inspection (`MODE: PR_REVIEW`) as the ONLY way a
- * direct Task dispatch of `reviewer`/`test_engineer` may bypass the generic
- * Stage-A task-workflow requirement. The PR workflow controller issues an
- * authorization bound to the exact active session, workflow, run, base/head
- * SHA, worktree revision digest, role, and gate generation; the Task
- * delegation gate consumes it atomically, exactly once. Stale, cross-session,
- * wrong-role, replayed, expired, or revision-drifted requests fail closed to
- * the normal gating path.
+ * Binding verification: the CURRENT gate binding (head/revision/generation)
+ * is supplied by the owning gate through a bound reader
+ * (`bindPrReviewReentryBindingReader`) — the boundary must not import the
+ * orchestration gate back. The gate binds its
+ * `readPrReviewReentryBindingContext` at module init.
  *
  * Persistence: `.swarm/pr-review/reentry-authorizations/<session-stem>.json`,
  * guarded by a `proper-lockfile` lock (the same dependency the candidate
  * sidecar store uses). Bounded: at most MAX_ACTIVE_AUTHORIZATIONS unconsumed
  * authorizations per session; expired/unconsumed records are pruned on write.
  */
+import { z } from 'zod';
 export type PrReviewReentryRole = 'reviewer' | 'test_engineer';
 export interface PrReviewReentryAuthorizationRecord {
     schemaVersion: 1;
@@ -32,6 +40,20 @@ export interface PrReviewReentryAuthorizationRecord {
     consumedAt?: string;
     consumedCallId?: string;
 }
+/**
+ * The CURRENT active-workflow binding an authorization must match at issue
+ * AND at consume time. Supplied by the owning gate (which reads state through
+ * the persistence boundary) via `bindPrReviewReentryBindingReader`.
+ */
+export interface PrReviewReentryBindingContext {
+    prHeadSha: string;
+    revisionDigest: string;
+    generation: number;
+    workflowInstanceId?: string;
+    runId?: string;
+}
+export type PrReviewReentryBindingReader = (directory: string, sessionID: string) => Promise<PrReviewReentryBindingContext | null>;
+export declare function bindPrReviewReentryBindingReader(reader: PrReviewReentryBindingReader): void;
 declare const AuthorizationFileSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     sessionId: z.ZodString;

package/dist/{hooks/pr-review-resilience-circuit.d.ts → pr-review/circuit.d.ts}

@@ -1,5 +1,6 @@
 /**
- * PR-review resilience circuit — typed, recoverable, versioned (issue #2382).
+ * PR-review resilience circuit — typed, recoverable, versioned (issues
+ * #2382, #2385).
  *
  * Pure state machine + typed-signal classification for the PR_REVIEW
  * resilience circuit. No I/O: the owning gate (`pr-workflow-gate.ts`) reads
@@ -17,9 +18,17 @@
  *   waterline) or back to OPEN (new interval). Legacy unversioned records
  *   migrate once to a nonblocking v2 CLOSED record with an evidence waterline;
  *   malformed records fail open.
+ *
+ * Issue #2385 additionally makes this module the ONLY authority that may
+ * construct or transition circuit records: policy snapshot resolution, the
+ * re-enable reset, and the rolled-back-probe transition live here (previously
+ * inline record constructions in the gate). The parallel-rule guardrail
+ * (`src/pr-review/guardrails.ts`) enforces that no circuit record is built
+ * outside `src/pr-review/`.
  */
 import { z } from 'zod';
 import type { BackgroundDelegationRecord } from '../background/pending-delegations.js';
+import { type PrReviewResilienceConfig } from '../config/schema.js';
 /** Bounded contributor ledger. Mirrors `MAX_WORKFLOW_BATCHES (128) × 6` base dimensions. */
 export declare const PR_REVIEW_CIRCUIT_CONTRIBUTOR_LIMIT = 768;
 export type PrReviewCircuitIgnoredReason = 'observer_deadline' | 'client_unavailable' | 'parser' | 'validation' | 'policy' | 'filesystem' | 'git' | 'cancellation' | 'stale_observation' | 'unknown';
@@ -67,6 +76,20 @@ export interface PrReviewCircuitLegacyRecord {
     }>;
     openedAt: string;
 }
+/**
+ * The persisted circuit union: a v2 record or a legacy unversioned record
+ * awaiting migration.
+ */
+export type PrReviewCircuitRecord = PrReviewCircuitLegacyRecord | PrReviewCircuitRecordV2;
+export interface PrReviewResiliencePolicyRecord {
+    enabled: boolean;
+    canaryProbeMs: number;
+    statusProbeTimeoutMs: number;
+    correlatedFailureThreshold: number;
+    maxRetryAttemptsAfterInitial: number;
+    /** Issue #2382. Optional: policies persisted before the field existed parse unchanged. */
+    circuitOpenDurationMs?: number;
+}
 export declare const PrReviewCircuitLegacyRecordSchema: z.ZodObject<{
     signature: z.ZodString;
     count: z.ZodNumber;
@@ -130,6 +153,12 @@ export declare const PrReviewCircuitRecordSchema: z.ZodUnion<readonly [z.ZodObje
         admittedAt: z.ZodString;
     }, z.core.$strict>>;
 }, z.core.$strict>]>;
+/**
+ * The terminal delegation statuses the circuit consults. The single shared
+ * definition (issue #2385): the gate's settlement paths and this module read
+ * the same vocabulary.
+ */
+export declare const CIRCUIT_TERMINAL_DELEGATION_STATUSES: ReadonlySet<string>;
 /**
  * Derive the typed circuit signal from a durable delegation record's LATEST
  * terminal state. Returns `null` for anything that is not a terminal failure
@@ -190,7 +219,7 @@ export interface PrReviewCircuitAdvanceInput {
     admission?: {
         batchId: string;
         laneId: string;
-    };
+    } | undefined;
     /** Latest-record signals for every dispatch lane of the current workflow. */
     laneSignals: readonly PrReviewCircuitSignal[];
     /**
@@ -202,7 +231,7 @@ export interface PrReviewCircuitAdvanceInput {
         terminalStatus: string;
         signal: PrReviewCircuitSignal | null;
         terminalAtMs: number;
-    };
+    } | undefined;
 }
 export type PrReviewCircuitAdvanceResult = {
     action: 'admit';
@@ -230,3 +259,31 @@ export type PrReviewCircuitAdvanceResult = {
  * gate passes an explicit waterlined record for migration / re-enable births).
  */
 export declare function advancePrReviewCircuit(current: PrReviewCircuitRecordV2 | null, input: PrReviewCircuitAdvanceInput): PrReviewCircuitAdvanceResult;
+/**
+ * Resolve the effective resilience policy record from optional config. Every
+ * default comes from `DEFAULT_PR_REVIEW_RESILIENCE_CONFIG` (single source);
+ * a hardcoded literal here would drift from the config schema (issue #2385
+ * recurrence class G-2).
+ */
+export declare function resolvePrReviewResiliencePolicy(policy?: PrReviewResilienceConfig): PrReviewResiliencePolicyRecord;
+/**
+ * Issue #2382 re-enable semantics (issue #2385: moved behind the machine).
+ * Re-enabling resilience after a live disable starts from a fresh v2 CLOSED
+ * generation with an evidence waterline at `nowMs` — pre-disable evidence can
+ * never resurrect. Generation strictly increases.
+ */
+export declare function resetPrReviewResilienceForReEnable(args: {
+    previousCircuit?: PrReviewCircuitRecord | null;
+    policy: PrReviewResiliencePolicyRecord;
+    nowMs: number;
+}): PrReviewCircuitRecordV2;
+/**
+ * Issue #2382 review (PRR-002) rolled-back-probe transition (issue #2385:
+ * moved behind the machine). A rolled-back HALF_OPEN probe can never produce
+ * a terminal record — the rollback's own precondition is that the batch has
+ * zero delegation records — so leaving the probe in place would wedge the
+ * circuit on probe_in_flight forever. End the probe lifecycle exactly the way
+ * an ignored outcome does: state stays OPEN with a restarted recovery
+ * cooldown, and no contributor, generation, or waterline changes.
+ */
+export declare function rollbackPrReviewCircuitProbe(circuit: PrReviewCircuitRecordV2, nowMs: number, openDurationMs: number): PrReviewCircuitRecordV2;

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

@@ -0,0 +1,373 @@
+/**
+ * PR-review completion / coverage-settlement authority (issues #2383, #2385).
+ *
+ * The six-dimension coverage reduction and terminal report eligibility
+ * machinery, moved out of `src/hooks/pr-workflow-gate.ts` behind the
+ * `src/pr-review/` boundary (issue #2385). This module owns:
+ *
+ * - the coverage-disclosure record vocabulary (v2 plural + legacy v1 singular),
+ *   its Zod schemas, and the single legacy→v2 normalization read boundary;
+ * - the per-dimension attempt summary (`summarizePrReviewBaseDimensionAttempts`)
+ *   and the terminal N-of-6 settlement derivation
+ *   (`derivePrReviewDimensionSettlement`);
+ * - the disclosure admission / rollback / settled-assertion state machine
+ *   (`admitPrReviewPartialBaseCoverage`,
+ *   `rollbackPrReviewPartialBaseCoverageAdmission`,
+ *   `assertPrReviewBaseCoverageSettled`);
+ * - the verdict eligibility matrix for terminal reports
+ *   (`allowedPrReviewReportVerdicts`) and the read-only report projection
+ *   (`readPrReviewTerminalCoverageForReport`).
+ *
+ * Binding contract (same precedent as `bindPrReviewReentryBindingReader` in
+ * `authorization.ts`): the boundary must never import the orchestration gate
+ * back. Gate-owned derivation helpers (`successfulObligationsFromExactBatch`,
+ * `recordsPassingBatchIntegrity`, `validatePrReviewDiscoveryLaneCompletion`,
+ * `validateExactStructuredReceiptCoverage`, `readBoundedSwarmRegularFile`,
+ * `createPrReviewGateContext`, `requireBoundState`,
+ * `readPrWorkflowGateStateFromDisk`) are supplied by the owning gate through
+ * `bindPrReviewCompletionHelpers`, bound once at gate module init.
+ *
+ * State typing: the moved functions read only the PR-review slice of
+ * `PrWorkflowGateState`, expressed as the local structural interface
+ * `PrReviewCompletionState`. The gate passes its full state, which satisfies
+ * the slice structurally. Durable reads/writes still go through
+ * `src/pr-review/persistence.ts` (the atomic persistence boundary) — this
+ * module never writes state outside `withSessionStateMutation` /
+ * `writeStateWhileLocked`.
+ */
+import { z } from 'zod';
+import { type LaneOutputArtifact } from '../background/lane-output-store.js';
+import { type BackgroundDelegationRecord, type BackgroundDelegationResult, type BackgroundDelegationWorkflowLaneFailureClass } from '../background/pending-delegations.js';
+import { type PrReviewBaseDimensionId, type PrReviewResultReceipt } from '../background/pr-review-contract.js';
+/** Declared lane shape of a base dispatch, as the settlement reads it. */
+export interface PrReviewCompletionLane {
+    laneId: string;
+    workflowLane: string;
+    ownedWorkflowLanes?: readonly string[];
+}
+/** Base dispatch batch, as the settlement reads it. */
+export interface PrReviewCompletionBaseDispatchRecord {
+    batchId: string;
+    lanes: ReadonlyArray<PrReviewCompletionLane>;
+    validatedAt: string;
+}
+/**
+ * The PR-review slice of the owning gate's `PrWorkflowGateState`: exactly the
+ * fields the moved settlement machinery reads. The gate's full state type
+ * satisfies this structurally, so the gate passes its state without a
+ * projection step. `schemaVersion`/`revision`/`sessionID` mirror
+ * `PrWorkflowPersistedStateBase` in `persistence.ts` so the CAS write generic
+ * accepts the slice.
+ */
+export interface PrReviewCompletionState {
+    schemaVersion: number;
+    revision: number;
+    sessionID: string;
+    workflowInstanceId?: string;
+    mode?: string;
+    prHeadSha?: string;
+    prReviewBaseSha?: string;
+    prReviewBaseDispatches?: PrReviewCompletionBaseDispatchRecord[];
+    prReviewContractRetryDimensions?: PrReviewBaseDimensionId[];
+    prReviewReservedRunId?: string;
+    prReviewArtifactRunId?: string;
+    prReviewArtifactBoundaries?: Array<'post_explorer' | 'post_reviewer' | 'post_critic'>;
+    prReviewDimensionCancellations?: Partial<Record<PrReviewBaseDimensionId, PrReviewDimensionCancellationRecord>>;
+    prReviewPartialBaseCoverage?: PrReviewPartialBaseCoverageRecord;
+    prReviewCoverageDisclosurePath?: string;
+    prReviewCoverageDisclosureDigest?: string;
+}
+/** The gate-context surface the settlement consumes (full ctx is gate-owned). */
+export interface PrReviewCompletionGateContext {
+    readonly revisionDigest: string;
+}
+/** A batch-integrity-qualified record, as the settlement consumes it. */
+export interface PrReviewCompletionQualifiedRecord {
+    record: BackgroundDelegationRecord;
+    expectedLane: PrReviewCompletionLane;
+    expectedWorkflowLane: string;
+    expectedOwnedLanes: string[];
+}
+/** Discovery-lane validation input, as the settlement supplies it. */
+export interface PrReviewCompletionDiscoveryValidationInput {
+    record: BackgroundDelegationRecord;
+    result: BackgroundDelegationResult;
+    artifact: LaneOutputArtifact | null;
+    expected: {
+        mode: string;
+        workflowLane: string;
+        ownedWorkflowLanes?: readonly string[];
+        prHeadSha: string;
+        gitHead: string;
+        revisionDigest: string;
+        workflowInstanceId?: string;
+        workflowRevision?: number;
+        baseSha?: string;
+        reviewScope?: string;
+        checkWorkflowLane?: boolean;
+    };
+}
+/** Structured-receipt coverage verdict, as the settlement consumes it. */
+export type PrReviewCompletionStructuredReceiptCoverage = {
+    status: 'absent';
+} | {
+    status: 'accepted';
+    receipt: PrReviewResultReceipt;
+} | {
+    status: 'rejected';
+};
+/**
+ * Gate-owned derivation 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 result
+ * types, which are structural supersets of the slices below, and interface
+ * method parameters are checked bivariantly.
+ */
+export interface PrReviewCompletionGateHelpers {
+    createPrReviewGateContext(directory: string, state: PrReviewCompletionState): Promise<PrReviewCompletionGateContext>;
+    requireBoundState(directory: string, sessionID: string, expectedMode: string): Promise<PrReviewCompletionState>;
+    readPrWorkflowGateStateFromDisk(directory: string, sessionID: string): Promise<PrReviewCompletionState | null>;
+    readBoundedSwarmRegularFile(directory: string, relativePath: string, maxBytes: number, label: string): Promise<string>;
+    successfulObligationsFromExactBatch(directory: string, state: PrReviewCompletionState, batchId: string, expectedLanes: ReadonlyArray<PrReviewCompletionLane>, expectedMode: string, validatedAt: string, checkWorkflowLane?: boolean, forbiddenSubagentSessionIds?: ReadonlySet<string>, expectedRevisionDigest?: string, diagnostics?: string[]): Set<string>;
+    recordsPassingBatchIntegrity(directory: string, state: PrReviewCompletionState, batchId: string, expectedLanes: ReadonlyArray<PrReviewCompletionLane>, expectedMode: string, validatedAt: string, checkWorkflowLane?: boolean, forbiddenSubagentSessionIds?: ReadonlySet<string>, diagnostics?: string[]): PrReviewCompletionQualifiedRecord[];
+    validatePrReviewDiscoveryLaneCompletion(input: PrReviewCompletionDiscoveryValidationInput): {
+        ok: boolean;
+    };
+    validateExactStructuredReceiptCoverage(input: PrReviewCompletionDiscoveryValidationInput): PrReviewCompletionStructuredReceiptCoverage;
+}
+export declare function bindPrReviewCompletionHelpers(helpers: PrReviewCompletionGateHelpers): void;
+/**
+ * Normalized terminal state of one canonical base dimension (issue #2383).
+ * Every dimension ends in exactly one of these; completion requires every
+ * LAUNCHED lane to be terminal (COVERED/FAILED) or explicitly cancelled, with
+ * no in-flight lane and no late result creditable to the active generation.
+ */
+export type PrReviewDimensionTerminalState = 'COVERED' | 'FAILED' | 'CANCELLED' | 'NOT_LAUNCHED';
+/** Gate-derived per-dimension terminal evidence for an unresolved dimension. */
+export interface PrReviewUnresolvedDimensionRecord {
+    dimension: PrReviewBaseDimensionId;
+    terminalState: 'FAILED' | 'CANCELLED' | 'NOT_LAUNCHED';
+    reasonKind: 'lane_failure' | 'cancelled' | 'not_launched';
+    failureClass?: BackgroundDelegationWorkflowLaneFailureClass;
+    terminalEventId?: string;
+    /** Contributing lane/batch identity, when available. */
+    batchId?: string;
+    laneId?: string;
+    /**
+     * Bounded safe detail derived from the failure-class vocabulary — never
+     * lane output, prompts, or secrets.
+     */
+    safeDetail?: string;
+}
+/** v2 terminal-settlement disclosure (issue #2383). The ONLY shape new writers emit. */
+export interface PrReviewPartialBaseCoverageRecordV2 {
+    schemaVersion: 2;
+    runId: string;
+    prHeadSha: string;
+    revisionDigest: string;
+    unresolvedDimensions: PrReviewUnresolvedDimensionRecord[];
+    admittedAt: string;
+}
+/**
+ * Legacy v1 disclosure (pre-#2383): singular `missingDimension` with a typed
+ * terminal failure. Read-only — normalized to the v2 in-memory view at the
+ * single read boundary; never rewritten on disk.
+ */
+export interface PrReviewPartialBaseCoverageRecordV1 {
+    runId: string;
+    prHeadSha: string;
+    revisionDigest: string;
+    missingDimension: PrReviewBaseDimensionId;
+    failureClass: BackgroundDelegationWorkflowLaneFailureClass;
+    terminalEventId: string;
+    admittedAt: string;
+}
+export type PrReviewPartialBaseCoverageRecord = PrReviewPartialBaseCoverageRecordV2 | PrReviewPartialBaseCoverageRecordV1;
+/** Terminal report kind of an N-of-6 settlement (issue #2383). */
+export type PrReviewTerminalCoverageKind = 'COMPLETE' | 'PARTIAL' | 'NO_COVERAGE';
+/** Controller-declared terminal verdict for a PR_REVIEW completion (issue #2383). */
+export declare const PR_REVIEW_REPORT_VERDICTS: readonly ["APPROVE", "REQUEST_CHANGES", "INCOMPLETE"];
+export type PrReviewReportVerdict = (typeof PR_REVIEW_REPORT_VERDICTS)[number];
+/**
+ * Verdicts a terminal report may carry by coverage kind (issue #2383):
+ * PARTIAL may only request changes or declare itself incomplete; NO_COVERAGE
+ * is a forced INCOMPLETE operational report. Neither may ever APPROVE or
+ * claim a full review.
+ */
+export declare function allowedPrReviewReportVerdicts(kind: PrReviewTerminalCoverageKind): readonly PrReviewReportVerdict[];
+export interface PrReviewTerminalCoverageSettlement {
+    kind: PrReviewTerminalCoverageKind;
+    coveredDimensions: PrReviewBaseDimensionId[];
+    unresolvedDimensions: PrReviewUnresolvedDimensionRecord[];
+    /** False while any dimension still has a live (in-flight) lane. */
+    allLaunchedTerminal: boolean;
+}
+/** Per-dimension explicit cancellation, written by armed recovery (issue #2383). */
+export interface PrReviewDimensionCancellationRecord {
+    reason: string;
+    cancelledAt: string;
+    source: 'armed_recovery';
+}
+export declare const PrReviewPartialBaseCoverageRecordSchema: z.ZodUnion<readonly [z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    runId: z.ZodString;
+    prHeadSha: z.ZodString;
+    revisionDigest: z.ZodString;
+    unresolvedDimensions: z.ZodArray<z.ZodObject<{
+        dimension: z.ZodEnum<{
+            "intent-architecture": "intent-architecture";
+            "correctness-state": "correctness-state";
+            "tests-falsifiability": "tests-falsifiability";
+            "security-trust": "security-trust";
+            "reliability-performance": "reliability-performance";
+            "compatibility-delivery": "compatibility-delivery";
+        }>;
+        terminalState: z.ZodEnum<{
+            FAILED: "FAILED";
+            CANCELLED: "CANCELLED";
+            NOT_LAUNCHED: "NOT_LAUNCHED";
+        }>;
+        reasonKind: z.ZodEnum<{
+            cancelled: "cancelled";
+            lane_failure: "lane_failure";
+            not_launched: "not_launched";
+        }>;
+        failureClass: z.ZodOptional<z.ZodEnum<{
+            contract: "contract";
+            resource: "resource";
+            deadline: "deadline";
+        }>>;
+        terminalEventId: z.ZodOptional<z.ZodString>;
+        batchId: z.ZodOptional<z.ZodString>;
+        laneId: z.ZodOptional<z.ZodString>;
+        safeDetail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    admittedAt: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    runId: z.ZodString;
+    prHeadSha: z.ZodString;
+    revisionDigest: z.ZodString;
+    missingDimension: z.ZodEnum<{
+        "intent-architecture": "intent-architecture";
+        "correctness-state": "correctness-state";
+        "tests-falsifiability": "tests-falsifiability";
+        "security-trust": "security-trust";
+        "reliability-performance": "reliability-performance";
+        "compatibility-delivery": "compatibility-delivery";
+    }>;
+    failureClass: z.ZodEnum<{
+        contract: "contract";
+        resource: "resource";
+        deadline: "deadline";
+    }>;
+    terminalEventId: z.ZodString;
+    admittedAt: z.ZodString;
+}, z.core.$strict>]>;
+export declare const PrReviewDimensionCancellationRecordSchema: z.ZodObject<{
+    reason: z.ZodString;
+    cancelledAt: z.ZodString;
+    source: z.ZodLiteral<"armed_recovery">;
+}, z.core.$strict>;
+/**
+ * Normalize any disclosure record to the v2 in-memory view. A legacy v1
+ * record maps to exactly one FAILED entry; the durable file is never
+ * rewritten (its digest stays bound to the original bytes).
+ */
+export declare function normalizePrReviewPartialBaseCoverageRecord(record: PrReviewPartialBaseCoverageRecord): PrReviewPartialBaseCoverageRecordV2;
+export interface PrReviewBaseDimensionAttempts {
+    /** Dimensions with a currently authoritative successful artifact. */
+    successful: Set<string>;
+    /** Dimensions with a currently in-flight or retryable recorded lane. */
+    inFlight: Set<string>;
+    /** Dimensions whose terminal record was a contract failure. */
+    contractFailed: Set<string>;
+    /** Dimensions that already consumed the dedicated contract retry channel. */
+    contractRetried: Set<string>;
+    /**
+     * The subset of `successful` supplied by a lane that owns that dimension
+     * alone. Used by the cumulative tier-L lane floor to decide when an earlier
+     * consolidated lane has been superseded and no longer spends lane budget.
+     */
+    dedicatedSuccessful: Set<string>;
+    /** Dimensions whose recorded lane ran to a terminal, non-successful end. */
+    terminallyFailed: Set<string>;
+}
+/**
+ * Per-dimension success/failure across every recorded base batch.
+ *
+ * The two halves deliberately use different evidence:
+ *
+ * - **successful** is revision-aware (`successfulObligationsFromExactBatch`
+ *   compares each artifact's `revisionDigest` against the current worktree), so
+ *   a stale artifact is correctly not a current source.
+ * - **terminallyFailed** is revision-INdependent on purpose.
+ *   `recordsPassingBatchIntegrity` plus
+ *   `hasRevisionIndependentDiscoverySemantics` use the artifact's recorded
+ *   revision rather than the current worktree digest. If failure were
+ *   derived from the revision-aware set instead, any working-tree edit would
+ *   make all six dimensions read as "failed" at once and a caller could then
+ *   consolidate the whole base wave into two lanes — re-opening the tier-L lane
+ *   floor by a second route (issue #1968 BL-4).
+ */
+export declare function summarizePrReviewBaseDimensionAttempts(directory: string, state: PrReviewCompletionState, revisionDigest: string): PrReviewBaseDimensionAttempts;
+export declare function coverageDisclosureRelativePath(runId: string): string;
+/**
+ * Derive the normalized terminal N-of-6 settlement (issue #2383).
+ *
+ * Pure over durable state: no mutation, no audit. Every dimension maps to
+ * exactly one view — COVERED, a terminal unresolved record (FAILED /
+ * CANCELLED / NOT_LAUNCHED), or a live (in-flight) dimension that blocks
+ * settlement. Coverage success is revision-aware (a stale artifact never
+ * counts on the current worktree), and a FAILED dimension carries the typed
+ * terminal-failure evidence plus its contributing lane/batch identity.
+ */
+export declare function derivePrReviewDimensionSettlement(directory: string, state: PrReviewCompletionState, revisionDigest: string): PrReviewTerminalCoverageSettlement & {
+    liveDimensions: PrReviewBaseDimensionId[];
+};
+export declare function admitPrReviewPartialBaseCoverage(directory: string, sessionID: string, runId: string, unresolvedDimensions: readonly PrReviewBaseDimensionId[]): Promise<PrReviewCompletionState>;
+/**
+ * Undo a newly admitted partial-base disclosure when the findings checkpoint
+ * cannot be completed. The compare-and-clear checks keep a stale writer from
+ * deleting a disclosure that another writer has already committed.
+ */
+export declare function rollbackPrReviewPartialBaseCoverageAdmission(directory: string, sessionID: string, options: {
+    runId: string;
+    boundary: 'post_explorer' | 'post_reviewer' | 'post_critic';
+    relativePath: string;
+    digest: string;
+}): Promise<boolean>;
+/**
+ * Validate durable terminal N-of-6 coverage evidence (issue #2383).
+ *
+ * Returns the settlement: COMPLETE when all six dimensions are covered, or
+ * PARTIAL / NO_COVERAGE when an admitted, still-accurate disclosure exactly
+ * matches the currently derived terminal settlement. Throws while any
+ * unresolved dimension still has a live lane, or when the disclosure has been
+ * invalidated by later evidence (e.g. a late success landing on the same
+ * revision) — the disclosure is immutable, so such a run must re-settle or
+ * restart rather than silently re-crediting.
+ */
+export declare function assertPrReviewBaseCoverageSettled(directory: string, sessionID: string, gateContext?: PrReviewCompletionGateContext): Promise<{
+    state: PrReviewCompletionState;
+    settlement: PrReviewTerminalCoverageSettlement & {
+        liveDimensions: PrReviewBaseDimensionId[];
+    };
+}>;
+/**
+ * Read-only terminal-coverage projection for the completion report surface
+ * (issue #2383). Pure derivation over the CURRENT state; returns null when no
+ * active PR_REVIEW gate exists. The completion tool reads this BEFORE the
+ * terminal clear so the response carries the truthful settlement summary.
+ */
+export declare function readPrReviewTerminalCoverageForReport(directory: string, sessionID: string): Promise<{
+    kind: PrReviewTerminalCoverageKind;
+    coveredDimensions: PrReviewBaseDimensionId[];
+    unresolvedDimensions: Array<{
+        dimension: PrReviewBaseDimensionId;
+        terminal_state: PrReviewUnresolvedDimensionRecord['terminalState'];
+        reason_kind: PrReviewUnresolvedDimensionRecord['reasonKind'];
+        failure_class?: BackgroundDelegationWorkflowLaneFailureClass;
+    }>;
+    liveDimensions: PrReviewBaseDimensionId[];
+    allowedVerdicts: readonly PrReviewReportVerdict[];
+} | null>;

package/dist/pr-review/critic-routing.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PR-review critic routing — the single severity/impact/tag predicate
+ * (issues #2383, #2385).
+ *
+ * Issue #2385 makes `src/pr-review/critic-routing.ts` the canonical home of
+ * the shared production critic-routing predicate. `src/background/
+ * pr-review-contract.ts` re-exports it (single definition, two import paths —
+ * no duplication). Every production consumer (critic inventory derivation,
+ * artifact-record validation, coverage admission, reducer transitions)
+ * imports THIS predicate; inline severity triples are forbidden and a
+ * centralization guard test enforces it.
+ */
+import type { PrReviewRiskImpact, PrReviewRiskTag } from '../background/pr-review-contract.js';
+export interface PrReviewCriticRoutingInput {
+    classification?: string;
+    severity?: string;
+    risk_impact?: PrReviewRiskImpact;
+    risk_tags?: readonly PrReviewRiskTag[];
+}
+/**
+ * THE shared production critic-routing predicate (issue #2383).
+ *
+ * Exactly one definition, imported by every production consumer (critic
+ * inventory derivation, artifact-record validation, coverage admission).
+ * Inline severity triples are forbidden — a parity/centralization guard test
+ * enforces it. Accepts only the normalized canonical shape:
+ *
+ * - non-CONFIRMED classifications are never critic-routed;
+ * - UNKNOWN/missing/invalid risk metadata routes to critic (fail-safe);
+ * - CRITICAL/HIGH always route to critic;
+ * - MEDIUM routes iff HIGH_IMPACT or at least one risk tag;
+ * - LOW/INFO/NONE follow the existing no-critic policy once metadata is known.
+ *
+ * Paths, dimensions, keywords, and prompt prose may suggest risk to the model
+ * but can never override this typed result.
+ */
+export declare function prReviewFindingRequiresCritic(input: PrReviewCriticRoutingInput): boolean;

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

@@ -0,0 +1,67 @@
+/**
+ * PR-review recurrence guardrails (issue #2385).
+ *
+ * Exported source scanners implementing the mechanical guardrails the issue
+ * requires. Each scanner is a PURE function over `{ path, content }` source
+ * maps; unit tests prove each scanner flags a synthetic violating snippet
+ * (the guardrail "biting") and then apply it over the real `src/` tree.
+ *
+ * 1. `scanObserverTerminalization` — (a) the historical wait-deadline/no-client
+ *    terminalizer may never reappear by name; (b) in
+ *    `src/tools/dispatch-lanes.ts`, durable delegation-transition writes are
+ *    allowed only inside the sanctioned settlement functions.
+ * 2. `scanParallelCircuitRuleConstruction` — circuit-record construction may
+ *    exist only under `src/pr-review/` (the inline-construction recurrence
+ *    class G-1).
+ *
+ * Issue #2385 originally specified a third scanner for transcript-parsing
+ * locality (the 13 conversion symbols restricted to the legacy adapter),
+ * but its only test consumer was a synthetic-input bite demo with no
+ * production caller. The boundary is already enforced structurally
+ * (the legacy-transcript-adapter is the sole module that owns those symbols,
+ * and the two retained scanners cover the real recurrence classes). A
+ * scanner with no caller would create the appearance of a guardrail where
+ * there is none — per the issue's "no unwired functionality" bar, it was
+ * removed instead.
+ */
+export interface GuardrailSource {
+    path: string;
+    content: string;
+}
+export interface GuardrailHit {
+    path: string;
+    line: number;
+    rule: string;
+    excerpt: string;
+}
+/**
+ * The historical PR-review wait-deadline terminalizer (issue #2381 deleted
+ * it). Any reappearance of these names in `src/` is the exact recurrence
+ * class the issue forbids: a collection wait budget or an unavailable host
+ * messages client must never write a terminal delegation transition.
+ */
+export declare const FORBIDDEN_OBSERVER_TERMINALIZER_SYMBOLS: readonly string[];
+/**
+ * Enclosing functions in `src/tools/dispatch-lanes.ts` that are allowed to
+ * write delegation transitions. Every entry is child-evidence-driven
+ * settlement (typed terminal error, explicit caller cancellation, or the
+ * age+liveness presumed-stale backstop) — never observer-deadline evidence:
+ * - `startAsyncLanePrompt`: `running` transition after a successful launch.
+ * - `appendAsyncLaneLaunchError`: typed `error` for a failed child launch.
+ * - `collectOnce`: explicit caller `cancelled` transition.
+ * - `settleCollectedLane`: `completed`/`error` settlement from child evidence.
+ * - `sweepStaleAsyncLaneRecords`: the presumed-stale `stale` backstop.
+ * Additions must document their evidence source here.
+ */
+export declare const DELEGATION_WRITE_ALLOWED_FUNCTIONS: ReadonlySet<string>;
+/**
+ * Guardrail 2. (a) flags any forbidden historical-terminalizer symbol;
+ * (b) for `src/tools/dispatch-lanes.ts`, flags delegation-transition writes
+ * inside any enclosing function outside the sanctioned allowlist. This
+ * module itself is exempt from rule (a): it DEFINES the forbidden names
+ * (the definition site is not a recurrence, same reasoning as the adapter
+ * allowlist in guardrail 1).
+ */
+export declare function scanObserverTerminalization(sources: readonly GuardrailSource[]): GuardrailHit[];
+/** Guardrail 3 (issue #2385 recurrence class G-1). */
+export declare function scanParallelCircuitRuleConstruction(sources: readonly GuardrailSource[]): GuardrailHit[];