opencode-swarm 7.194.0 → 7.195.0

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

@@ -464,6 +464,20 @@ interface PrReviewBatchCoherenceRecord {
     reviewerItemBindings?: Record<string, string>;
     /** Key encoding for reviewerItemBindings; absent means legacy raw item IDs. */
     reviewerItemBindingKeyEncoding?: 'prefixed-v1';
+    /**
+     * Issue #2906: reviewer batches only. The presentation order this batch's
+     * candidates were counterbalanced into — 'A' renders the canonical sorted
+     * inventory, 'B' the exact reverse — alternating by reviewer-batch ordinal
+     * within the reviewer window so repeated passes observe order effects.
+     */
+    presentationOrder?: 'A' | 'B';
+    /**
+     * Issue #2906: critic batches only. AUDIT-ONLY snapshot of the
+     * order-unstable item ids the critic prompt for this batch was flagged
+     * with (the prompt re-derives them live via
+     * `derivePrReviewOrderUnstableItems`); no runtime reader consumes this.
+     */
+    orderUnstableItemIds?: string[];
 }
 /** One rejected `submit_pr_review_result` attempt (issue #2859 F3 journal). */
 export interface PrReviewSubmitRejectionRecord {
@@ -474,6 +488,22 @@ export interface PrReviewSubmitRejectionRecord {
 }
 /** FIFO cap for the gate-state submit-rejection journal (issue #2859 F3). */
 export declare const MAX_PR_REVIEW_SUBMIT_REJECTIONS = 24;
+/**
+ * One rejected `write_pr_review_artifact` attempt (issue #3098 verdict-lane
+ * journal, mirroring the #2859 discovery journal). `sessionId` is the gate
+ * owner (the orchestrator session that called the tool) — provenance only;
+ * the composition joins entries to lanes via `workflowLane`/`laneId`.
+ */
+export interface PrReviewVerdictRejectionRecord {
+    sessionId: string;
+    laneId?: string;
+    workflowLane?: string;
+    boundary?: 'post_explorer' | 'post_reviewer' | 'post_critic';
+    at: number;
+    message: string;
+}
+/** FIFO cap for the gate-state verdict-write-rejection journal (issue #3098). */
+export declare const MAX_PR_REVIEW_VERDICT_REJECTIONS = 24;
 export interface PrWorkflowGateState {
     schemaVersion: 1;
     /** Monotonic durable revision used to reject stale same-session transitions. */
@@ -588,6 +618,17 @@ export interface PrWorkflowGateState {
      * to 300 chars at write time.
      */
     prReviewSubmitRejections?: PrReviewSubmitRejectionRecord[];
+    /**
+     * Bounded FIFO journal of rejected `write_pr_review_artifact` attempts
+     * (issue #3098, the verdict-lane mirror of the #2859 journal above).
+     * Observability only — surfaced in the verdict composition diagnostic so
+     * the orchestrator can see WHY a declared reviewer/critic lane produced no
+     * successful exact artifact; never consulted for artifact validity. Capped
+     * by {@link MAX_PR_REVIEW_VERDICT_REJECTIONS}; each entry's message is
+     * bounded to 300 chars at write time. `sessionId` is the gate-owner caller
+     * (provenance); lane join happens via `workflowLane`/`laneId`.
+     */
+    prReviewVerdictRejections?: PrReviewVerdictRejectionRecord[];
     prReviewHandoffPath?: string;
     prReviewHandoffRequired?: boolean;
     checkoutRecovery?: PrWorkflowCheckoutRecoveryRecord;
@@ -714,6 +755,38 @@ export declare function recordPrReviewSubmitRejection(directory: string, childSe
  * ever see its most recent rejections.
  */
 export declare function latestPrReviewSubmitRejectionMessage(state: Pick<PrWorkflowGateState, 'prReviewSubmitRejections'>, childSessionId: string): string | undefined;
+/**
+ * Issue #3098: best-effort, fail-open journal of one rejected
+ * `write_pr_review_artifact` attempt onto the CALLER's own PR_REVIEW gate
+ * state (the tool is a controller tool invoked by the gate-owner session —
+ * no delegation parent-hop, unlike the #2859 discovery journal).
+ * Observability only — never changes the rejection outcome, never creates
+ * gate state for a session that has none (the pre-read outside the
+ * session-state lock means a non-gated caller gets no lock file either).
+ */
+export declare function recordPrReviewVerdictRejection(directory: string, sessionID: string, message: string, attribution?: {
+    laneId?: string;
+    workflowLane?: string;
+    boundary?: 'post_explorer' | 'post_reviewer' | 'post_critic';
+}): Promise<void>;
+/**
+ * Issue #3098: latest journal message for a failing obligation, or undefined.
+ * Newest wins. Join keys are `workflowLane` (the declared obligation) and
+ * `laneId`; the recorded `sessionId` is the gate-owner caller (provenance),
+ * never a lane child session, so it is deliberately not a join key.
+ *
+ * The production writer only ever stamps `boundary` (the write args name the
+ * boundary, never a lane), so in practice the phase-scoped fallback below is
+ * what resolves: it reports the newest rejection recorded for the failing
+ * lane's PHASE, which is honest about being phase-scoped rather than
+ * lane-scoped. The lane-exact arms stay because a future attribution producer
+ * (or a hand-seeded state) can populate them.
+ */
+export declare function latestPrReviewVerdictRejectionForLane(state: Pick<PrWorkflowGateState, 'prReviewVerdictRejections'>, matchers: {
+    workflowLane?: string;
+    laneIds?: readonly string[];
+    boundary?: 'post_explorer' | 'post_reviewer' | 'post_critic';
+}): string | undefined;
 /**
  * Issue #2859 (F3): single wrap point over every gate-layer rejection path in
  * `submitPrReviewResultCore` (all 15 `{ status: 'rejected' }` return sites —
@@ -1253,6 +1326,13 @@ export declare function recordPrReviewMicroFamilyDispatch(directory: string, ses
 export declare function recordPrReviewValidationBatch(directory: string, sessionID: string, phase: PrReviewValidationPhase, lanes: readonly PrWorkflowLaneSpec[], options: {
     batchId: string;
     prHeadSha: string;
+    /**
+     * Issue #2906: reviewer batches only. The presentation order the dispatch
+     * prompt was counterbalanced for (from `derivePrReviewPresentationOrder`).
+     * When supplied and the re-derived ordinal disagrees, recording fails
+     * closed so the prompt can never misrepresent the stamped receipt.
+     */
+    expectedPresentationOrder?: 'A' | 'B';
 }): Promise<PrWorkflowGateState>;
 /**
  * Validate that every declared council obligation has a successful retry, and
@@ -1491,6 +1571,27 @@ export declare function markPrReviewHandoffComplete(directory: string, sessionID
     state: PrWorkflowGateState;
     alreadyOffered: boolean;
 }>;
+interface PrReviewFindingPolicyAuthority {
+    policyFindings: Array<{
+        id: string;
+        status: string;
+        severity: string;
+        action: string;
+        [key: string]: unknown;
+    }>;
+    criticSettlements: Array<{
+        findingId: string;
+        terminal: boolean;
+        status: CriticOutcome;
+    }>;
+}
+/**
+ * Read the policy sidecar as an integrity-bound projection of the final
+ * findings artifact.  A write-only sidecar is not evidence: the route receipt
+ * pins the PR head and exact findings bytes, while the sidecar digest pins the
+ * synthesized projection itself.
+ */
+export declare function readAuthoritativeFindingPolicy(directory: string, state: PrWorkflowGateState): Promise<PrReviewFindingPolicyAuthority>;
 /** Read-only final finding-policy projection for completion reports. */
 export declare function readPrReviewFinalFindingPolicyForReport(directory: string, sessionID: string): Promise<{
     policyVersion: 1;
@@ -1677,6 +1778,8 @@ export declare const _test_exports: {
             validatedInventory: string[];
             reviewerItemBindings?: Record<string, string> | undefined;
             reviewerItemBindingKeyEncoding?: "prefixed-v1" | undefined;
+            presentationOrder?: "A" | "B" | undefined;
+            orderUnstableItemIds?: string[] | undefined;
         }> | undefined;
         prReviewRetiredReviewerSessionIds?: string[] | undefined;
         prReviewRetiredConsolidatedLanes?: string[] | undefined;
@@ -1721,6 +1824,15 @@ export declare const _test_exports: {
             message: string;
             laneId?: string | undefined;
         }[] | undefined;
+        prReviewVerdictRejections?: {
+            [x: string]: unknown;
+            sessionId: string;
+            at: number;
+            message: string;
+            laneId?: string | undefined;
+            workflowLane?: string | undefined;
+            boundary?: "post_explorer" | "post_reviewer" | "post_critic" | undefined;
+        }[] | undefined;
         prReviewArtifactBoundaries?: ("post_explorer" | "post_reviewer" | "post_critic")[] | undefined;
         prReviewHandoffPath?: string | undefined;
         prReviewHandoffRequired?: boolean | undefined;
@@ -2333,6 +2445,47 @@ export declare function readAuthoritativePrReviewCriticVerdicts(directory: strin
     status: string;
     severity: string;
 }>>;
+/**
+ * Issue #2906: the presentation order the NEXT reviewer batch will be
+ * counterbalanced into — 'A' when the reviewer window holds an even number of
+ * batches, 'B' when odd. Pure function of the persisted window state; the
+ * dispatch tool derives it before prompt assembly and passes the same value to
+ * `recordPrReviewValidationBatch` as `expectedPresentationOrder`, which
+ * re-derives and fails closed on divergence.
+ *
+ * Issue #2906 review finding F-03: at the `MAX_WORKFLOW_BATCHES` cap the
+ * record guard counts the window of the PRUNED state (its read-prune-append
+ * transaction applies `prunePrWorkflowBatchesForCapacity` before deriving the
+ * stamped ordinal), while this derivation used to count the unpruned persisted
+ * window. When the prune flipped the window parity the guard threw — before
+ * `persistState`, so the prune was never durable — and every retry re-derived
+ * the same divergent value: a permanent liveness wedge that failed closed.
+ * This derivation therefore applies the SAME pure prune under the SAME
+ * >= cap condition, so both sides count the identical window. The prune is
+ * pure with respect to durable state (it reads artifacts and returns a
+ * candidate state; only the record path persists it), so running it here
+ * cannot violate the BL-6 single-transaction rule. Every prune-abort path
+ * (inventory inequality, unreadable delegation store, ledger overflow) returns
+ * the state unchanged here AND inside the record guard, so the two sides agree
+ * on those paths as well; a divergence that still reaches the guard means the
+ * state genuinely changed between derivation and recording, which fails closed
+ * and is recoverable by re-deriving.
+ */
+export declare function derivePrReviewPresentationOrder(directory: string, sessionID: string): Promise<'A' | 'B'>;
+/**
+ * Issue #2906: every currently-composed reviewer item whose verdict flipped
+ * across counterbalanced presentation orders (`orderAgreement: 'disagree'`).
+ * The critic dispatch tool renders these as `order_unstable_item_ids` so the
+ * critic prioritizes them.
+ */
+export declare function derivePrReviewOrderUnstableItems(directory: string, sessionID: string): Promise<string[]>;
+/**
+ * Issue #2906: the authoritative per-item order-agreement map for the findings
+ * writer — the same reader shape as `readAuthoritativePrReviewCriticVerdicts`,
+ * so a model-supplied `order_agreement` on a findings row can be cross-checked
+ * against the composed reviewer claims instead of being taken on trust.
+ */
+export declare function readAuthoritativePrReviewOrderAgreement(directory: string, sessionID: string): Promise<Map<string, 'agree' | 'disagree' | 'single'>>;
 interface ExpectedWorkflowLane {
     laneId: string;
     workflowLane: string;

package/dist/host/v2/session-client.d.ts

@@ -1,5 +1,5 @@
 /**
- * v2 session client shim — issue #3169 Phase 2.
+ * v2 session client shim — issue #3169 Phase 2 (+ Phase 3 lane sessions).
  *
  * A narrow `OpencodeClient` subset implementing exactly the v1 session surface
  * Epic's dispatch paths use (`session.create/prompt/abort/delete` plus `get`,
@@ -14,27 +14,36 @@
  * findings on @opencode/cli 2.0.26):
  *
  *   - `create({body:{parentID,title}, query:{directory}})` validates placement
- *     BEFORE creating anything: v2 child sessions inherit the parent's
- *     directory and ignore the requested one (Phase 0 C1 catch), so a divergent
- *     or unverifiable placement fails closed with a typed `{data: null,
- *     error}` result — routing worktree isolation to its existing degradation
- *     path instead of silently running a "lane" session in the project root.
- *     A passing precheck mints a placeholder id; the real v2 session is
- *     created at PROMPT time, when the v1 prompt body supplies the create-time
- *     options (agent/model/permissions) the published `SessionCreateInput`
- *     expects (issue R2: one session per dispatch contains the per-session
- *     shift).
+ *     BEFORE creating anything. Phase 3: a CONFIRMED parent-directory divergence
+ *     (the worktree-isolation lane shape — a lane worktree directory always
+ *     differs from the parent's project root) now takes the EAGER path: a REAL
+ *     parentless host session created immediately in the requested directory
+ *     (Phase 0 C1: parented children inherit the parent's directory; parentless
+ *     creates honor the requested one), placement verified post-create (echo,
+ *     `get` fallback) with a remove-and-fail-closed guard, and the requested
+ *     `parentID` REMEMBERED plugin-side and overlaid onto `get` results so
+ *     `prWorkflowSessionResolver`'s first-hop controller resolution
+ *     (`pr-workflow-session-resolver.ts`) and `lookupParentSessionIDForTaskRoute`
+ *     stay v1-faithful for parentless lane children (the host-side link is what
+ *     the v2 host cannot carry here). A real id is returned — the native
+ *     `subagent` tool resumes it by id (Phase 0 C7). Unverifiable parent
+ *     placement still fails closed with the Phase 2 typed error (live-verification
+ *     item), and same-directory/parentless creates keep the deferred placeholder
+ *     (the real create there must carry prompt-time options — permissions are
+ *     create-time-only on v2).
  *   - `prompt({path:{id}, body:{agent,model?,system?,tools,parts}, signal?})`
- *     emulates the v1 BLOCKING call: real create (carrying agent/model and the
- *     read-only denial map as `effect:'deny'` permissions) → one sessionID-
- *     scoped `context` hook that replaces `event.system` (fence-aware: parts
- *     carrying the `<swarm_system_directive` provenance fence survive, per
- *     #2526) and deletes denied keys from `event.tools` → `prompt` → bounded
- *     `wait` → `context()` translated into the v1 `{data:{info,parts}}`
- *     envelope so `dispatchEphemeralAgent` and `readProviderMessageError`
- *     work unchanged. A prompt addressed to a non-placeholder (real) session
- *     id takes a direct path without re-creating — the pr-event-delivery wake
- *     prompt shape.
+ *     emulates the v1 BLOCKING call over three arms keyed on the registry:
+ *     (1) an EAGER record → full treatment on the real session — `switchAgent` +
+ *     `switchModel`, a sessionID-scoped `context` hook (fence-aware system
+ *     replacement preserving `<swarm_system_directive` parts, denied-tool
+ *     deletion from `event.tools`), epoch-scoped error clear, `prompt` →
+ *     bounded `wait` → `context()`; (2) a deferred/already-prompted PLACEHOLDER
+ *     → real create carrying agent/model + the read-only denial map as
+ *     `effect:'deny'` permissions, then the same hook/prompt/wait/context
+ *     sequence, with the #3186 PRR-002 retire-and-recreate on re-prompts;
+ *     (3) a foreign real id → the direct path (agent switch only). All three
+ *     translate into the v1 `{data:{info,parts}}` envelope so
+ *     `dispatchEphemeralAgent` and `readProviderMessageError` work unchanged.
  *   - Provider failures are EVENT-SOURCED on v2 (Phase 0 C4: no error text in
  *     `context()`), so the event pump records `session.error` /
  *     `session.execution.failed` payloads here (`recordV2SessionErrorFromEnvelope`,
@@ -42,15 +51,25 @@
  *     translation surfaces them as the v1 `info.error` shape. A failed outcome
  *     without recorded detail yields a bounded `provider.unknown` error
  *     instead of a silent empty success.
- *   - `abort` maps to `interrupt`, `delete` to `remove`, `get` to the v2 get
- *     (unresolved placeholders read as `{data: null}` — never prompted means
- *     gone, satisfying `teardownEphemeralSessionVerified`).
+ *   - `abort` maps to `interrupt`, `delete` to `remove` (eager records are
+ *     pruned after the removal resolves — the id is real, so a later `get`
+ *     still resolves through to a host that reports the session gone), and
+ *     `get` maps `{path:{id}}` onto `ctx.session.get({sessionID})` returning
+ *     `{data: info}` — verified teardown through the shim resolves.
+ *
+ * Registry (invariant 8): placeholder and eager records share ONE bounded map
+ * (cap 64, FIFO). Placeholder residue is intentionally not pruned (keep-for-get);
+ * that residue shares the cap, so a live eager record can be evicted after 64
+ * later insertions of any kind — a disclosed, bounded degradation (its next
+ * prompt takes the direct path and the parentID overlay stops applying), pinned
+ * in tests/unit/host/v2/session-client-lane-3169.test.ts.
  *
  * Deferred-work marker: NONE. The unverified live-host behaviors this design
  * rests on are recorded as deferrals in the trace (context-hook firing for
  * plugin-created sessions, permission vocabulary honor, `context()` entry
- * shapes, `wait` on failed prompts, `get(parent).location` availability) with
- * the owning follow-up on #3169.
+ * shapes, `wait` on failed prompts, `get(parent).location` availability,
+ * parentless subagent resume + parentID overlay — LVD-1..LVD-4) with the owning
+ * follow-up on #3169.
  *
  * C6 await convention: every `await` lives inside a `deferredV2Session*`
  * function declaration or `const deferredV2SessionX = async (` binding — the