opencode-swarm 7.132.2 → 7.133.0

package/dist/hooks/review-receipt.d.ts

@@ -22,13 +22,21 @@
  * but MUST NOT blindly trust them — staleness check is mandatory.
  *
  * Scope-description heterogeneity: receipts in one index may be fingerprinted
- * over different canonical contents (e.g. 'reviewer-task-prompt' hashes the
- * delegation prompt; 'auto-review-*-diff' hashes the reviewed diff). A prompt
- * fingerprint does NOT change when the worktree changes, so consumers MUST
- * filter by `scope_fingerprint.scope_description` (or compare like-for-like
- * content) before treating an approved receipt as fresh via isScopeStale().
+ * over different canonical contents (e.g. `reviewer-task-files-v1` hashes the
+ * guardrails-observed file scope plus HEAD and current content; auto-review
+ * receipts hash a canonical diff). Consumers MUST filter by
+ * `scope_fingerprint.scope_description` and compare like-for-like content
+ * before treating an approved receipt as fresh via isScopeStale().
  */
+import * as fs from 'node:fs';
+import type { FindingValidation, ReviewFinding } from '../agents/agent-output-schema.js';
 export type ReceiptVerdict = 'rejected' | 'approved';
+export type ReviewFindingSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+/** Raised when reviewed bytes stop matching immediately before a durable commit. */
+export declare class ReviewScopeStaleError extends Error {
+    readonly code = "REVIEW_SCOPE_STALE";
+    constructor(message: string);
+}
 /** Identity of the reviewer/curator that produced the receipt. */
 export interface ReviewerIdentity {
     /** Agent name (e.g. 'reviewer', 'critic', 'curator') */
@@ -45,7 +53,12 @@ export interface ScopeFingerprint {
     /** Length of the original content in characters */
     content_length: number;
 }
-/** A blocking finding recorded in a rejected review. */
+/**
+ * A finding recorded in a rejected review.
+ *
+ * The `blocking_findings` JSON field name is retained for schema-v1
+ * compatibility, but `effective_severity` is authoritative when present.
+ */
 export interface BlockingFinding {
     /** File path (relative) or identifier */
     location: string;
@@ -53,8 +66,23 @@ export interface BlockingFinding {
     summary: string;
     /** Line number if applicable */
     line?: number;
-    /** Severity: 'critical' | 'high' | 'medium' */
-    severity: 'critical' | 'high' | 'medium';
+    /** Reviewer-reported severity. */
+    severity: ReviewFindingSeverity;
+    /** Structured-finding fields are additive so legacy v1 receipts remain readable. */
+    finding_id?: string;
+    title?: string;
+    body?: string;
+    confidence?: number;
+    file?: string;
+    line_start?: number;
+    line_end?: number;
+    /** Severity after confidence, anchoring, and validation policy is applied. */
+    effective_severity?: ReviewFindingSeverity;
+    validator_disposition?: FindingValidation['disposition'];
+    validator_confidence?: number;
+    validator_evidence?: string;
+    anchor_status?: 'anchored' | 'unanchored' | 'truncated' | 'rejected';
+    anchor_reason?: string;
 }
 /**
  * Rejected review receipt.
@@ -71,7 +99,10 @@ export interface RejectedReviewReceipt {
     reviewed_at: string;
     /** Fingerprint of the reviewed scope */
     scope_fingerprint: ScopeFingerprint;
-    /** Blocking findings that caused rejection */
+    /**
+     * Rejected findings retained under the schema-v1 field name.
+     * Consumers must use effective severity when deciding which can block.
+     */
     blocking_findings: BlockingFinding[];
     /** Exact evidence references (file paths, line numbers, etc.) */
     evidence_references: string[];
@@ -79,6 +110,11 @@ export interface RejectedReviewReceipt {
     pass_conditions: string[];
     /** Optional free-text summary */
     summary?: string;
+    /** Original machine-readable reviewer payload, when one was available. */
+    structured_findings?: ReviewFinding[];
+    review_overall_confidence?: number;
+    /** Independent validator output, when validation was requested. */
+    finding_validations?: FindingValidation[];
 }
 /**
  * Approved review receipt.
@@ -101,6 +137,11 @@ export interface ApprovedReviewReceipt {
     validated_claims: string[];
     /** Residual risk or caveats */
     caveats?: string[];
+    /** Original machine-readable reviewer payload, when one was available. */
+    structured_findings?: ReviewFinding[];
+    review_overall_confidence?: number;
+    /** Independent validator output, when validation was requested. */
+    finding_validations?: FindingValidation[];
 }
 export type ReviewReceipt = RejectedReviewReceipt | ApprovedReviewReceipt;
 /** Index entry for fast lookup without reading every receipt file. */
@@ -121,6 +162,20 @@ export interface ReceiptIndex {
 export declare function resolveReceiptsDir(directory: string): string;
 /** Returns the index file path. */
 export declare function resolveReceiptIndexPath(directory: string): string;
+export declare const _internals: {
+    openSync: typeof fs.openSync;
+    lstatBigIntSync: (path: fs.PathLike) => fs.BigIntStats;
+    fstatBigIntSync: (fd: number) => fs.BigIntStats;
+};
+/**
+ * Read a direct review-receipt file without following redirected ancestors.
+ *
+ * The directory identities are captured before opening, then revalidated
+ * around a descriptor-owned read. Comparing the opened descriptor with the
+ * pathname snapshots prevents a project/.swarm/review-receipts swap from
+ * redirecting the read outside the project between validation and open.
+ */
+export declare function readReviewReceiptText(directory: string, receiptPath: string, maxBytes?: number): string | null;
 /**
  * Compute a SHA-256 scope fingerprint for a given content string.
  * The hash is deterministic: same content → same hash.
@@ -135,12 +190,45 @@ export declare function computeScopeFingerprint(content: string, scopeDescriptio
  * is treated as stale (conservative: assume the scope has changed).
  */
 export declare function isScopeStale(receipt: ReviewReceipt, currentContent: string | undefined): boolean;
+export interface PersistReviewReceiptOptions {
+    /**
+     * Rebuild and verify the immutable reviewed scope immediately before each
+     * synchronous atomic rename. A false result aborts without publishing stale
+     * receipt/index state.
+     */
+    verifyCurrent?: () => Promise<boolean>;
+}
+export interface UpdateReviewReceiptValidationsOptions {
+    /** Refuse to update a receipt that no longer has the expected immutable identity. */
+    expectedIdentity?: {
+        id: string;
+        scopeHash: string;
+        scopeDescription: string;
+    };
+    /**
+     * Rebuild and verify the exact reviewer generation and scope immediately before
+     * the synchronous atomic rename. A false result discards the temporary update.
+     */
+    verifyCurrent?: () => Promise<boolean>;
+}
 /**
  * Persist a review receipt (rejected or approved) to disk.
  * Creates .swarm/review-receipts/<date>-<id>.json and updates the index.
  * Returns the absolute path of the written receipt file.
  */
-export declare function persistReviewReceipt(directory: string, receipt: ReviewReceipt): Promise<string>;
+export declare function persistReviewReceipt(directory: string, receipt: ReviewReceipt, options?: PersistReviewReceiptOptions): Promise<string>;
+/**
+ * Remove a just-persisted receipt after a later persistence step fails.
+ *
+ * The index entry is committed first so a crash can leave at most an unindexed
+ * orphan file, never a dangling index entry that points at missing evidence.
+ */
+export declare function removeReviewReceipt(directory: string, receiptPath: string, receiptId: string): Promise<void>;
+/**
+ * Atomically attach independent finding-validation results to an existing
+ * receipt. The receipt identity and index entry remain unchanged.
+ */
+export declare function updateReviewReceiptValidations(receiptPath: string, validations: FindingValidation[], options?: UpdateReviewReceiptValidationsOptions): Promise<void>;
 /**
  * Read a single receipt by ID. Returns null if not found or unreadable.
  */
@@ -168,6 +256,9 @@ export declare function buildRejectedReceipt(opts: {
     evidenceReferences: string[];
     passConditions: string[];
     summary?: string;
+    structuredFindings?: ReviewFinding[];
+    reviewOverallConfidence?: number;
+    findingValidations?: FindingValidation[];
 }): RejectedReviewReceipt;
 /**
  * Build an ApprovedReviewReceipt.
@@ -181,6 +272,9 @@ export declare function buildApprovedReceipt(opts: {
     checkedAspects: string[];
     validatedClaims: string[];
     caveats?: string[];
+    structuredFindings?: ReviewFinding[];
+    reviewOverallConfidence?: number;
+    findingValidations?: FindingValidation[];
 }): ApprovedReviewReceipt;
 /**
  * Build a structured context summary of prior receipts for critic drift

package/dist/hooks/reviewer-scope-file-fingerprint.d.ts

@@ -0,0 +1,21 @@
+import * as fs from 'node:fs';
+export declare const MAX_REVIEWER_SCOPE_FINGERPRINT_BYTES = 1048576;
+export declare const MAX_REVIEWER_SCOPE_FINGERPRINT_AGGREGATE_BYTES = 4194304;
+export type ReviewerScopeFileFingerprint = {
+    file: string;
+    kind: 'file';
+    size: number;
+    hash: string;
+} | {
+    file: string;
+    kind: 'deleted';
+};
+export declare const _internals: {
+    readFileSync: typeof fs.readFileSync;
+};
+/**
+ * Capture the exact post-write file state with a bounded read. Oversized,
+ * non-regular, path-racing, and unreadable targets fail closed to null.
+ */
+export declare function captureReviewerScopeFileFingerprint(directory: string, file: string, maxBytes?: number): ReviewerScopeFileFingerprint | null;
+export declare function reviewerScopeFileFingerprintsEqual(left: ReviewerScopeFileFingerprint, right: ReviewerScopeFileFingerprint): boolean;

package/dist/hooks/reviewer-scope-lifecycle.d.ts

@@ -0,0 +1,19 @@
+export type ReviewerScopeLifecycleTransition = 'coder_started' | 'coder_ready' | 'reviewer_claimed';
+/** Run only after the complete blocking before-chain approved this Task call. */
+export declare function beginApprovedReviewerScopeLifecycle(input: {
+    directory: string;
+    tool: unknown;
+    args: unknown;
+    parentSessionID: string;
+    callID: string;
+    maxBytes?: number;
+}): Promise<ReviewerScopeLifecycleTransition | null>;
+/** Mark a synchronous coder terminal; background running placeholders are inert. */
+export declare function completeReviewerScopeLifecycle(input: {
+    directory: string;
+    tool: unknown;
+    args: unknown;
+    output: unknown;
+    parentSessionID: string;
+    callID: string;
+}): Promise<ReviewerScopeLifecycleTransition | null>;

package/dist/hooks/task-result-classifier.d.ts

@@ -0,0 +1,6 @@
+export type TaskResultClassification = 'running' | 'success' | 'non_success';
+/**
+ * Shared Task-result classifier for every Stage-B lifecycle consumer.
+ * Explicit state/status and error fields win. Unknown shapes fail closed.
+ */
+export declare function classifyTaskResult(output: unknown): TaskResultClassification;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import type { Plugin } from '@opencode-ai/plugin';
 import { loadPluginConfigWithMetaAsync } from './config';
+import { resolveAutoReviewConfig } from './config/schema';
 import { createRepoGraphBuilderHook } from './hooks';
 import { loadSnapshot } from './session/snapshot-reader.js';
 import { ensureSwarmGitExcluded } from './utils/gitignore-warning';
@@ -24,6 +25,7 @@ export declare function overrideIndexInternalsForTest(overrides: {
     loadPluginConfigWithMetaAsync?: typeof loadPluginConfigWithMetaAsync;
     loadSnapshot?: typeof loadSnapshot;
     ensureSwarmGitExcluded?: typeof ensureSwarmGitExcluded;
+    resolveAutoReviewConfig?: typeof resolveAutoReviewConfig;
 }): () => void;
 export declare function schedulePostResolutionTasksForTest(tasks: readonly PostResolutionTask[]): void;
 /**