opencode-swarm 7.132.2 → 7.134.0

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

@@ -4,8 +4,8 @@
  * Parses the mandated reviewer OUTPUT FORMAT (`VERDICT:` / `RISK:` /
  * `ISSUES:` / `FIXES:`) from a returning reviewer Task delegation and
  * persists it as a durable review receipt under `.swarm/review-receipts/`
- * via the existing receipt store (scope-fingerprinted over the delegation
- * prompt, which defines the reviewed scope).
+ * via the existing receipt store. Scope is derived from guardrails-observed
+ * modified files and their current content, never architect-authored prose.
  *
  * Before this collector, reviewer verdicts existed only as free text inside
  * the architect's context — re-reviews and drift verification had no durable
@@ -15,7 +15,14 @@
  *
  * Fail-open: parsing or persistence failures never block tool execution.
  */
-export type ParsedReviewSeverity = 'critical' | 'high' | 'medium';
+import { type ReviewFinding } from '../agents/agent-output-schema.js';
+import { type AutoReviewConfig } from '../config/schema.js';
+import type { ReviewModelDispatcher } from '../review/contracts.js';
+import { type FindingValidationScheduler } from '../review/finding-validator.js';
+import { type ReviewAgentModelRegistry } from '../review/runtime.js';
+import { persistReviewReceipt, type ReviewFindingSeverity, updateReviewReceiptValidations } from './review-receipt.js';
+import { buildReviewerTaskScope, resolveReviewerTaskScope } from './review-receipt-scope.js';
+export type ParsedReviewSeverity = ReviewFindingSeverity;
 export interface ParsedReviewIssue {
     /** Raw issue line (trimmed, bullet stripped) */
     text: string;
@@ -23,6 +30,8 @@ export interface ParsedReviewIssue {
     severity: ParsedReviewSeverity;
     /** `path:line` reference when one appears in the line */
     location?: string;
+    /** Machine-readable source finding, when structured output parsed. */
+    finding?: ReviewFinding;
 }
 export interface ParsedReviewerOutput {
     verdict: 'approved' | 'rejected';
@@ -32,30 +41,64 @@ export interface ParsedReviewerOutput {
     issues: ParsedReviewIssue[];
     /** Required-change lines from the FIXES section */
     fixes: string[];
+    outputMode: 'structured' | 'legacy';
+    overallConfidence?: number;
+    structuredFindings?: ReviewFinding[];
 }
 /**
  * Parse the reviewer agent's mandated output block. Returns null when no
- * unambiguous line-anchored `VERDICT: APPROVED|REJECTED` is present —
- * including when multiple anchored verdict lines DISAGREE (ambiguous output
- * fails toward "no machine-readable verdict", never toward approval).
+ * single unambiguous line-anchored `VERDICT: APPROVED|REJECTED` is present,
+ * including missing, duplicate, or contradictory verdict lines. A structured
+ * verdict must match that single legacy line so ambiguous output fails toward
+ * "no machine-readable verdict", never toward approval.
  */
-export declare function parseReviewerOutput(text: string): ParsedReviewerOutput | null;
+export declare function parseReviewerOutput(text: string, options?: {
+    structured?: boolean;
+}): ParsedReviewerOutput | null;
 export interface ReviewerReceiptInput {
     tool: unknown;
     args?: unknown;
     sessionID?: unknown;
+    callID?: unknown;
 }
 export interface ReviewerReceiptOutput {
     output?: unknown;
+    state?: unknown;
+    status?: unknown;
+    error?: unknown;
+    errors?: unknown;
+    metadata?: unknown;
+    result?: unknown;
 }
 export interface ReviewerReceiptTranscriptInput {
     targetAgent?: string;
-    prompt: string;
+    prompt?: string;
     transcript: string;
     sessionID?: string;
     sessionId?: string;
+    taskId?: string;
+    reviewerCallID?: string;
+    /** Production collectors consume the exact claimed coder generation. */
+    consumeHandoff?: boolean;
 }
-export declare function collectReviewerReceiptFromTranscript(directory: string, input: ReviewerReceiptTranscriptInput): Promise<string | null>;
+export interface ReviewerReceiptValidationOptions {
+    dispatcher?: ReviewModelDispatcher;
+    config?: AutoReviewConfig;
+    generatedAgentNames?: Iterable<string>;
+    agentModelRegistry?: ReviewAgentModelRegistry;
+    injectAdvisory?: (sessionID: string, message: string) => void;
+    /** Shared only within the owning plugin instance. */
+    validationScheduler?: FindingValidationScheduler;
+}
+/** Test seam for the otherwise process-global telemetry sink. */
+export declare const _internals: {
+    delegationEnd: (sessionId: string, agentName: string, taskId: string, result: string, costFields?: Partial<import("../services/cost-accounting.js").DelegationCostFields>) => void;
+    resolveReviewerTaskScope: typeof resolveReviewerTaskScope;
+    buildReviewerTaskScope: typeof buildReviewerTaskScope;
+    persistReviewReceipt: typeof persistReviewReceipt;
+    updateReviewReceiptValidations: typeof updateReviewReceiptValidations;
+};
+export declare function collectReviewerReceiptFromTranscript(directory: string, input: ReviewerReceiptTranscriptInput, validationOptions?: ReviewerReceiptValidationOptions): Promise<string | null>;
 /**
  * `tool.execute.after` collector. When a reviewer Task returns, parse its
  * verdict block and persist a durable review receipt. No-op for non-reviewer
@@ -63,4 +106,4 @@ export declare function collectReviewerReceiptFromTranscript(directory: string,
  *
  * Returns the persisted receipt path (for tests/telemetry) or null.
  */
-export declare function collectReviewerReceiptAfter(directory: string, input: ReviewerReceiptInput, output: ReviewerReceiptOutput): Promise<string | null>;
+export declare function collectReviewerReceiptAfter(directory: string, input: ReviewerReceiptInput, output: ReviewerReceiptOutput, validationOptions?: ReviewerReceiptValidationOptions): Promise<string | null>;

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

@@ -0,0 +1,74 @@
+/**
+ * Canonical scope construction for Stage-B reviewer receipts.
+ *
+ * The architect-authored reviewer prompt is not authoritative scope: it can
+ * omit files that the coder actually changed. Guardrails records every
+ * write-tool target in `modifiedFilesThisCoderTask`, so receipts fingerprint a
+ * bounded manifest of repository HEAD, those paths, and their current byte
+ * content instead. A base change therefore invalidates the receipt even when
+ * the working-file bytes happen to remain identical.
+ *
+ * Any missing session state, unsafe path, symlink/reparse point, concurrent
+ * mutation, or size overflow fails toward no receipt. A durable receipt must
+ * never claim a scope the harness could not reconstruct exactly.
+ */
+import * as child_process from 'node:child_process';
+import * as fs from 'node:fs';
+export declare const REVIEWER_TASK_SCOPE_DESCRIPTION = "reviewer-task-files-v1";
+export interface ReviewerTaskScope {
+    content: string;
+    description: typeof REVIEWER_TASK_SCOPE_DESCRIPTION;
+    files: string[];
+    headSha: string;
+    taskId?: string;
+    coderCallID?: string;
+    generation?: number;
+    sessionIncarnation?: string;
+}
+export interface ReviewerTaskScopeProvenance {
+    taskId: string;
+    coderCallID: string;
+    generation: number;
+    sessionIncarnation: string;
+}
+export interface ResolveReviewerTaskScopeOptions {
+    /** Consume the completed coder's one-shot scope instead of the live list. */
+    consumeHandoff?: boolean;
+    /** Exact task expected by the returning reviewer/background record. */
+    expectedTaskId?: string;
+    /** Exact reviewer Task call that claimed the generation. */
+    reviewerCallID?: string;
+    /** Injectable clock used only for deterministic expiry tests. */
+    now?: number;
+}
+/**
+ * Resolve the exact known plan task carried by reviewer/coder Task arguments.
+ *
+ * This deliberately reuses delegation-gate's canonical extractor so lifecycle
+ * identity cannot drift from scope authorization. It checks all supported Task
+ * text fields, prefers an unambiguous TASK line, rejects ambiguity, and filters
+ * numeric-dot tokens against the current plan.
+ */
+export declare function resolveReviewerScopeTaskId(directory: string, args: unknown): Promise<string | null>;
+/**
+ * Test-only dependency-injection seam. Keeping the spawn binding local avoids
+ * process-global `mock.module()` pollution while allowing tests to prove that
+ * the production call really creates a child with ignored stdin.
+ */
+export declare const _internals: {
+    spawn: typeof child_process.spawn;
+    realpath: typeof fs.promises.realpath;
+    lstatBigInt: (path: fs.PathLike) => Promise<fs.BigIntStats>;
+    open: typeof fs.promises.open;
+    fileHandleStatBigInt: (handle: fs.promises.FileHandle) => Promise<fs.BigIntStats>;
+};
+/**
+ * Build the exact scope fingerprint input for a guardrails-observed file list.
+ */
+export declare function buildReviewerTaskScope(directory: string, modifiedFiles: readonly string[], maxBytes?: number, provenance?: ReviewerTaskScopeProvenance): Promise<ReviewerTaskScope | null>;
+/**
+ * Resolve scope only from the architect session's guardrails-owned task state.
+ * Receipt collection consumes the completed coder handoff exactly once; direct
+ * callers retain the legacy live-list view for diagnostics and drift probes.
+ */
+export declare function resolveReviewerTaskScope(directory: string, sessionID: string, maxBytes?: number, options?: ResolveReviewerTaskScopeOptions): Promise<ReviewerTaskScope | null>;

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;
 /**