opencode-swarm 7.157.1 → 7.158.0

package/dist/hooks/pr-workflow-gate.d.ts

@@ -3,12 +3,18 @@ import { z } from 'zod';
 import { type CandidateSeverity, type FindingsSeverity, type RowFormatFamily } from '../background/candidate-contract.js';
 import { type LaneOutputArtifact } from '../background/lane-output-store.js';
 import { type BackgroundDelegationRecord, type BackgroundDelegationResult, type BackgroundDelegationWorkflowLaneFailureClass, type BackgroundDelegationWorkflowLaneRecovery, findByBatchId, sweepStaleDelegations } from '../background/pending-delegations.js';
+import { PR_REVIEW_BASE_DIMENSION_IDS, type PrReviewRiskImpact, type PrReviewRiskTag } from '../background/pr-review-contract.js';
 import { type PrReviewInlineTriggerRow } from '../background/pr-review-trigger-contract.js';
 import { type RevisionDigestResult, resolveCommitCountSince, resolveCommitCountSinceAsync, resolveCurrentGitHead, resolveCurrentGitHeadAsync, resolveCurrentLocalHeadRefAsync, resolveCurrentUpstreamPushTarget, resolveCurrentUpstreamPushTargetAsync, resolveCurrentUpstreamRemoteRef, resolveExactRemoteBranchHead, resolveExactRemoteBranchHeadAsync, resolveIsExactSingleChildCommit, resolveIsExactSingleChildCommitAsync, resolveIsWorkingTreeClean, resolveIsWorkingTreeCleanAsync, resolvePrReviewDiffStats, resolvePrReviewDiffStatsAsync, resolvePrWorkflowRevisionDigest, resolvePrWorkflowRevisionDigestDetailed, resolveRemoteRefsContainingHead, resolveRemoteRefsContainingHeadAsync, resolveRemoteUrlIdentity, resolveRemoteUrlIdentityAsync } from '../background/workspace-snapshot.js';
 import { type PrReviewResilienceConfig } from '../config/schema.js';
 import { classifyPrWorkflowGitState, type PrWorkflowGitState } from '../git/pr-workflow-state.js';
 import { classifyPrReviewCircuitSignal, type PrReviewCircuitLegacyRecord, type PrReviewCircuitRecordV2 } from './pr-review-resilience-circuit.js';
-export declare const PR_REVIEW_BASE_DIMENSION_IDS: readonly ["intent-architecture", "correctness-state", "tests-falsifiability", "security-trust", "reliability-performance", "compatibility-delivery"];
+/**
+ * Re-exported for compatibility: the canonical six-dimension list is owned by
+ * the PR-review contract module (issue #2383 single-source rule; a
+ * source-scan guard test enforces it).
+ */
+export { PR_REVIEW_BASE_DIMENSION_IDS };
 export declare const PR_REVIEW_REQUIRED_MICRO_LANE_IDS: ("auth-identity-secrets" | "untrusted-input-boundaries" | "subprocess-platform" | "concurrency-state" | "dependencies-build-release" | "api-schema-migrations" | "test-infrastructure" | "ui-accessibility-i18n" | "privacy-observability" | "generated-provenance" | "unclassified-risk")[];
 export type PrReviewBaseDimensionId = (typeof PR_REVIEW_BASE_DIMENSION_IDS)[number];
 export type PrWorkflowMode = 'PR_REVIEW' | 'PR_FEEDBACK';
@@ -362,6 +368,14 @@ type PrReviewArtifactRecord = {
      * omitted severity as a mismatch rather than skipping the check (issue #2279).
      */
     severity?: FindingsSeverity;
+    /**
+     * Typed risk metadata (issue #2383). Optional in the TYPE for the same
+     * legacy-read reason as `severity`; the WRITE boundary requires both on
+     * every CONFIRMED record, and this validator compares CONFIRMED records
+     * against the authoritative reviewer verdict's typed values.
+     */
+    risk_impact?: PrReviewRiskImpact;
+    risk_tags?: PrReviewRiskTag[];
 };
 interface PrFeedbackScopeDeclarationRecord {
     taskId: string;
@@ -486,6 +500,13 @@ export interface PrWorkflowGateState {
     prReviewPartialBaseCoverage?: PrReviewPartialBaseCoverageRecord;
     prReviewCoverageDisclosurePath?: string;
     prReviewCoverageDisclosureDigest?: string;
+    /**
+     * Explicit per-dimension cancellations (issue #2383), written only by the
+     * audited armed-recovery operation. A cancelled dimension is terminal for
+     * settlement purposes and never counts as covered. Bounded to the six
+     * canonical dimensions by key.
+     */
+    prReviewDimensionCancellations?: Partial<Record<PrReviewBaseDimensionId, PrReviewDimensionCancellationRecord>>;
     prReviewHandoffPath?: string;
     prReviewHandoffRequired?: boolean;
     checkoutRecovery?: PrWorkflowCheckoutRecoveryRecord;
@@ -522,6 +543,13 @@ export interface PrWorkflowGateState {
      * older binaries, via the root `.passthrough()`) loads unchanged.
      */
     prFeedbackPublication?: PrFeedbackPublicationState;
+    /**
+     * Issue #2383: audited armed-recovery marker. Present only after an armed
+     * workflow was explicitly recovered — lanes settled, one bounded audit
+     * event appended, staged publication authorization invalidated — leaving a
+     * recoverable terminal state that preserves validated work.
+     */
+    prFeedbackArmedRecovery?: PrFeedbackArmedRecoveryRecord;
     /**
      * Issue #2131 criterion C2: count of controlled base-sync/rebind transitions.
      * Each rebind moves the immutable intake head to a new verified remote PR
@@ -532,7 +560,44 @@ export interface PrWorkflowGateState {
     prFeedbackRebindCount?: number;
     prFeedbackScopes?: PrFeedbackScopeDeclarationRecord[];
 }
-export interface PrReviewPartialBaseCoverageRecord {
+/**
+ * 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;
@@ -541,6 +606,32 @@ export interface PrReviewPartialBaseCoverageRecord {
     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';
+}
 /**
  * Bound on the PR_FEEDBACK inventory-amendment audit ledger (issue #2242 R3).
  *
@@ -552,6 +643,12 @@ export interface PrReviewPartialBaseCoverageRecord {
  * instead.
  */
 export declare const MAX_PR_FEEDBACK_INVENTORY_AMENDMENTS = 128;
+/**
+ * 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;
 /**
  * One appended PR_FEEDBACK inventory entry (issue #2242 R3). `batch` groups the
  * entries appended by a single `declarePrFeedbackInventory` call so an auditor
@@ -834,6 +931,55 @@ export declare function abortPrWorkflow(directory: string, sessionID: string, op
     stateSalvageDisclosure?: string;
     casEscapeDisclosure?: string;
 }>;
+/** Marker record left by an audited armed recovery (issue #2383). */
+export interface PrFeedbackArmedRecoveryRecord {
+    recoveredAt: string;
+    prHeadSha: string;
+    /** Revision digest of the invalidated staged publication authorization. */
+    revisionDigest: string;
+    /** Gate state revision (CAS generation) at recovery time. */
+    generation: number;
+    reason: string;
+}
+/**
+ * Audited armed recovery (issue #2383): the explicit, identity-correlated
+ * escape for a publication-armed workflow whose exact publication cannot
+ * proceed.
+ *
+ * Requires the exact active session (state is session-keyed; a foreign session
+ * finds no armed state), workflow identity, base/head SHA, the staged
+ * authorization's revision digest, and the CURRENT gate-state generation.
+ * Every mismatch fails closed. There is deliberately NO `force` parameter —
+ * force never bypasses identity or revision checks. Exact approved publication
+ * remains available and preferred: this operation never runs when publication
+ * can still proceed by the normal path.
+ *
+ * Order of effects, all under the session-state mutation lock with CAS:
+ *   1. settle/cancel remaining lanes FIRST (fresh open lanes refuse recovery);
+ *   2. append exactly ONE bounded audit event (`pr_workflow_armed_recovery`);
+ *   3. invalidate the staged publication authorization;
+ *   4. transition to a recoverable terminal state — the state is PRESERVED
+ *      (not cleared) with a `prFeedbackArmedRecovery` marker, so validated
+ *      work survives and the controller can re-arm after repair or abort
+ *      cleanly.
+ */
+export declare function recoverArmedPrWorkflow(directory: string, sessionID: string, request: {
+    expectedMode?: PrWorkflowMode;
+    prHeadSha: string;
+    /** Exact merge-base SHA; REQUIRED when the active state carries one. */
+    baseSha?: string;
+    revisionDigest: string;
+    generation: number;
+    workflowInstanceId?: string;
+    reason: string;
+}): Promise<{
+    mode: PrWorkflowMode;
+    prHeadSha: string;
+    openLanes: number;
+    settledLanes: number;
+    cancelledDimensions: PrReviewBaseDimensionId[];
+    recoveredAt: string;
+}>;
 /** Bind an active PR workflow to one immutable PR head. */
 export declare function bindPrWorkflowHead(directory: string, sessionID: string, prHeadSha: string): Promise<PrWorkflowGateState>;
 /**
@@ -903,7 +1049,7 @@ interface EnforcePrReviewBaseDimensionsOptions {
 export declare function enforcePrReviewBaseDimensions(directory: string, sessionID: string, lanes: readonly PrWorkflowLaneSpec[], options: EnforcePrReviewBaseDimensionsOptions): Promise<PrWorkflowGateState>;
 export declare function rollbackPrReviewBaseAdmissionIfUnlaunched(directory: string, sessionID: string, batchId: string, contractRetry?: boolean): Promise<boolean>;
 declare function minimumConsolidatedLaneCover(sets: ReadonlyArray<readonly string[]>): number;
-export declare function admitPrReviewPartialBaseCoverage(directory: string, sessionID: string, runId: string, missingDimension: PrReviewBaseDimensionId): Promise<PrWorkflowGateState>;
+export declare function admitPrReviewPartialBaseCoverage(directory: string, sessionID: string, runId: string, unresolvedDimensions: readonly PrReviewBaseDimensionId[]): Promise<PrWorkflowGateState>;
 /**
  * Undo a newly admitted partial-base disclosure when the findings checkpoint
  * cannot be completed. The compare-and-clear checks keep a stale writer from
@@ -915,8 +1061,23 @@ export declare function rollbackPrReviewPartialBaseCoverageAdmission(directory:
     relativePath: string;
     digest: string;
 }): Promise<boolean>;
-/** Validate durable exact-six or explicitly admitted N-1 PR review evidence. */
-export declare function assertPrReviewBaseCoverageSettled(directory: string, sessionID: string, gateContext?: PrReviewGateContext): Promise<PrWorkflowGateState>;
+/**
+ * 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?: PrReviewGateContext): Promise<{
+    state: PrWorkflowGateState;
+    settlement: PrReviewTerminalCoverageSettlement & {
+        liveDimensions: PrReviewBaseDimensionId[];
+    };
+}>;
 /** Persist a council/reviewer/critic validation batch before launch. */
 export declare function recordPrReviewValidationBatch(directory: string, sessionID: string, phase: PrReviewValidationPhase, lanes: readonly PrWorkflowLaneSpec[], options: {
     batchId: string;
@@ -1173,7 +1334,42 @@ export declare function validatePrFeedbackScopeBinding(directory: string, bindin
 }): Promise<boolean>;
 export declare function enforcePrWorkflowToolBefore(directory: string, sessionID: string, toolName: string, args: Record<string, unknown> | undefined, generatedAgentNames?: readonly string[], callID?: string): Promise<void>;
 /** Validate the terminal PR workflow contract before removing its durable gate. */
-export declare function completePrWorkflow(directory: string, sessionID: string, expectedMode: PrWorkflowMode, prHeadSha: string): Promise<PrWorkflowCompletionStatus>;
+/**
+ * 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>;
+/**
+ * Read-only identity binding for reviewer re-entry authorization (issue
+ * #2383). Returns the exact active-session PR_REVIEW identity a one-use
+ * authorization must be issued against and re-verified under at consume time:
+ * bound head SHA, current worktree revision digest, gate generation (CAS
+ * revision), workflow instance id, and the active run id. Null when no active
+ * head-bound PR_REVIEW gate exists for the session.
+ */
+export declare function readPrReviewReentryBindingContext(directory: string, sessionID: string): Promise<{
+    prHeadSha: string;
+    revisionDigest: string;
+    generation: number;
+    workflowInstanceId?: string;
+    runId?: string;
+} | null>;
+export declare function completePrWorkflow(directory: string, sessionID: string, expectedMode: PrWorkflowMode, prHeadSha: string, options?: {
+    reportVerdict?: PrReviewReportVerdict;
+}): Promise<PrWorkflowCompletionStatus>;
 export declare const _test_exports: {
     classifyPrReviewCircuitSignal: typeof classifyPrReviewCircuitSignal;
     minimumConsolidatedLaneCover: typeof minimumConsolidatedLaneCover;
@@ -1475,6 +1671,12 @@ interface PrReviewItemClaim {
     /** 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.
@@ -1579,7 +1781,7 @@ interface IndexedVerdictRows {
 declare function indexVerdictRows(text: string, marker: '[REVIEWED]' | '[CRITIC]'): IndexedVerdictRows;
 /**
  * Digest of the FULL canonical reviewer row, not the classification/severity
- * pair a reviewer verdict projects to. Only 2 of the 10 required fields survive
+ * 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.
@@ -1593,6 +1795,8 @@ declare function reviewerVerdictRowDigest(fields: readonly string[]): string;
 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;
 }>;
 /** Exact assigned-row contract used by both normal and recovered collection. */
@@ -1698,4 +1902,3 @@ export declare function ensurePrWorkflowSafeParentDirectory(directory: string, f
  * rename contention as canonical gate state.
  */
 export declare function writePrWorkflowAtomicJson(directory: string, filePath: string, value: unknown): Promise<void>;
-export {};