opencode-swarm 7.193.0 → 7.195.0

package/dist/cli/{worktree-isolation-pt1rws6p.js → worktree-isolation-379tmkta.js}

@@ -25,77 +25,77 @@ import {
   sanitizeWorktreeTaskId,
   standardWorktreeByCallID,
   standardWorktreeSerializationSessions
-} from "./index-jx80ed6g.js";
-import"./index-bkpyff61.js";
-import"./index-4mq8r4be.js";
-import"./index-ma71x1aa.js";
+} from "./index-7kbpzg05.js";
+import"./index-akb436kn.js";
+import"./index-gns3gc87.js";
+import"./index-780g1hht.js";
 import"./index-j2vv0h13.js";
-import"./index-668npagp.js";
-import"./index-7njm9jk1.js";
+import"./index-c5xvm318.js";
+import"./index-necqa5bj.js";
 import"./index-txdagbh7.js";
-import"./index-prvancd0.js";
+import"./index-8448vj9w.js";
 import"./index-rdec0y3z.js";
-import"./index-d2emv8ap.js";
-import"./index-ymnathfr.js";
-import"./index-r3mffz78.js";
-import"./index-5n760fzn.js";
-import"./index-fd6b9f38.js";
-import"./index-hfnyykvm.js";
+import"./index-863hst4e.js";
+import"./index-fk4j26km.js";
+import"./index-yryy781f.js";
+import"./index-gz16dke1.js";
+import"./index-ghckhk16.js";
+import"./index-ypkfhqbc.js";
 import"./index-cjapb4hy.js";
-import"./index-6s3ab22d.js";
+import"./index-dfrcc46h.js";
 import"./index-pt7h91zc.js";
 import"./index-q7sjgr1y.js";
-import"./index-nktwf2xm.js";
-import"./index-he2nyr7x.js";
+import"./index-xs9cn3c0.js";
+import"./index-epdzvp4w.js";
 import"./index-6b295cas.js";
 import"./index-9nyqt3kb.js";
-import"./index-bgtfvst1.js";
+import"./index-peyz4k9k.js";
 import"./index-v3bmwmqw.js";
-import"./index-4gacy6y6.js";
-import"./index-nz6ehpjn.js";
-import"./index-x2phyvcv.js";
+import"./index-z59414gv.js";
+import"./index-kmvy5fr8.js";
+import"./index-479kf368.js";
 import"./index-g4fs6z4e.js";
-import"./index-6dn16dre.js";
-import"./index-tr47q89d.js";
-import"./index-cs0p582p.js";
+import"./index-3k65kdfp.js";
+import"./index-bftpd2m5.js";
+import"./index-c4hx57tz.js";
 import"./index-m9zzj4ee.js";
-import"./index-84k9zzv1.js";
+import"./index-kphy4we7.js";
 import"./index-2s7dvzff.js";
-import"./index-jxs9qnad.js";
-import"./index-w2vbaczx.js";
+import"./index-tc8x0zc5.js";
+import"./index-hy2fqapm.js";
 import"./index-rtry5xyf.js";
 import {
   resolveWorktreeIsolationConfig
-} from "./index-vbp35frb.js";
+} from "./index-82aj6gaj.js";
 import"./index-g22dps7x.js";
 import"./index-0725jpp7.js";
-import"./index-1p24bfn2.js";
-import"./index-5ev6f1gj.js";
-import"./index-qh93qjc2.js";
-import"./index-st80sjg7.js";
-import"./index-vg8sxg12.js";
-import"./index-0e318vgt.js";
+import"./index-6vpqe4ws.js";
+import"./index-1hcjxz6w.js";
+import"./index-6183at3v.js";
+import"./index-j8t1g5qd.js";
+import"./index-crz772sx.js";
+import"./index-app2rmxv.js";
 import"./index-ry16d01s.js";
 import"./index-rdm3px0g.js";
 import"./index-7pmbnjvj.js";
-import"./index-ndec8akq.js";
-import"./index-bg19b84s.js";
+import"./index-gc0aeth5.js";
+import"./index-5gf2wx2c.js";
 import"./index-vzm6zre7.js";
 import"./index-ae75rja9.js";
-import"./index-3atkcqpb.js";
-import"./index-5rkh69f3.js";
-import"./index-e8k0v19e.js";
+import"./index-ry5g9s8d.js";
+import"./index-4gmxdkcd.js";
+import"./index-xmbtwtgw.js";
 import"./index-t7hmqgjy.js";
-import"./index-mtqwyjrg.js";
+import"./index-7rtq2t5n.js";
 import"./index-fzpt2djt.js";
 import"./index-ejhxgyvm.js";
 import"./index-7g4c7s5r.js";
-import"./index-hfssjyxs.js";
+import"./index-yf2z4j7s.js";
 import"./index-gx2vp8gx.js";
-import"./index-ngk8hpc3.js";
+import"./index-c6hyd8hg.js";
 import"./index-zxdawwc7.js";
-import"./index-1dx5zyss.js";
-import"./index-py8wpe81.js";
+import"./index-jn4mmhqc.js";
+import"./index-hqrkr9ag.js";
 import"./index-bk5tah7q.js";
 import"./index-gknz3bv1.js";
 import"./index-zpsr8rpc.js";

package/dist/commands/registry.d.ts

@@ -715,7 +715,7 @@ export declare const COMMAND_REGISTRY: {
     readonly epic: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Open, inspect, and close a plan-scoped epic (coupling-aware parallel execution of the current plan)";
-        readonly details: "An epic is bound to ONE plan: `start` opens it for the current plan, `close` ends it. Requires `epic.mode.enabled: true` in config (top-level `epic` block; no `turbo` block needed — the legacy `turbo.epic` path is still accepted and migrated). `start [--force]` refuses, in order: epic-disabled-by-config, host-unsupported (the host gives the plugin no OpenCode SDK client — OpenCode 2 does not yet — so worktree-isolated coders and the phase review cannot run), no-plan / plan-ledger-unreadable, epic-already-open (idempotent for the same plan) / epic-open-for-other-plan, turbo-active (config turbo_mode, a session with Turbo on, or a running Lean run — Epic enables neither Lean nor Turbo and never waives per-task QA), dirty-baseline (git: uncommitted changes outside .swarm/), detached-head / epic-branch-exists (epic-branch policy), in-flight-coders (any coder dispatch, background delegation, unsettled settlement, or preserved/recovery lane), not-epic-sized (too few pending tasks, insufficient scope coverage, or insufficient effective speedup — run it in Balanced, or reshape it with the plan-shaping suggestions shown; `--force` overrides and is recorded). Non-git projects run an epic serially (one task per wave). Git epics default to `epic.commit_policy: \"epic-branch\"`: start checks out `swarm/epic/<epicKey>` and every Epic commit goes there (epic_next_wave blocks with epic-branch-mismatch, and no landing or residue is committed, while HEAD is elsewhere); `current-branch` keeps commits on the starting branch. In a git epic every coder runs in an isolated worktree (refused EPIC_ISOLATION_DEGRADED when isolation is unavailable) and lands as a `swarm(task <id>): …` merge commit; main-tree files a non-coder writer (test_engineer, docs) wrote for a task are committed as residue of that task; update_task_status writes nothing to git; wave close records the commit of each task as `refs/swarm/epics/<epicKey>/tasks/<id>` (deleted at close unless `epic.retain_refs`; never pushed by default). While open, the architect calls epic_next_wave and does what its status says: it issues one wave at a time (tasks with non-conflicting declared scopes — exclusive tasks alone, at most one task per densely coupled component; phases strictly in order), the architect dispatches one Task per taskId in ONE message and runs per-task QA (pre_check_batch → reviewer + test_engineer → update_task_status(completed)), and the next epic_next_wave closes the wave (recording outcomes and declared-vs-actual divergence) and issues the next; when a phase is done it returns phase-ready-for-review → epic_phase_review → phase_complete. `close [--abandon] [--land squash|merge|none]` refuses while tasks are pending (or the epic is orphaned / unreadable) unless `--abandon`, refuses a dirty tree before landing, writes a close report (epic-report-v2, embedding the epic scorecard) to .swarm/epic/reports/ and .swarm/epic-prior/reports/ (newest 50 kept), and lands the epic branch onto the original branch: squash (default — staged, uncommitted changes for you to review and commit), merge (a --no-ff merge commit), or none (switch back only). The epic branch is kept (remove it with `git branch -D` once committed). A landing conflict is rolled back (the attempted squash or merge is undone) and the epic stays closing — rerun close to resume. `--abandon` never lands; it switches back to the original branch when the tree is clean. `status [--repair-refs]` (also bare /swarm epic) shows the epic, its waves, phases, the task components recorded with the latest wave and recorded divergence, orphan detection (plan renamed or replaced), sentinel/row repair, recorded worktree merge failures, and retires legacy Epic v1 session state once; `--repair-refs` re-adopts task commits a rebase or amend made unreachable from HEAD. `report [<key>|last] [--format json]` shows the epic scorecard: live for the open epic (bare `report`), else from the close report of a past epic in .swarm/epic-prior/reports/ (`last` = newest; `<key>` = a report or epic key) — tasks completed in the epic, waves (count, width), time over closed waves (wave span, task issue→resolve time, and their ratio, a concurrency factor that is NOT a speedup: it includes queueing behind serialized QA), conflicts (merge-back failures, undeclared writes), rework (extra generations, reopens), first-pass gate rates (upper bounds: the failure history is bounded), forced/sizing at start and learned hot files. Epics learn from their outcomes: undeclared writes teach learned co-writes (a task declaring D that also wrote f makes later tasks declaring D conflict with tasks on f — planner analysis only, never write authorization) and incidents (undeclared writes, merge conflicts, Stage B failures, rework, reopens) in excess of clean exposures make a file hot (a task declaring it runs alone) — undeclared writes its strongest learned co-writer explains are discounted (expansion already separates them), so one declarer writing a file is not heat; an empty history learns nothing (neutral start). Each wave close updates the posterior of the epic; close merges it into the project prior .swarm/epic-prior/learning.json (decayed per epic and by age; kept across /swarm close; `epic.learning.*`). `learning` shows what the planner learned and uses now; `prior [show]` shows the project prior; `prior reset` previews and prints a single-use confirm token (15 minutes); `prior reset --confirm=<token>` clears it. Also: clear-merge-failure <taskId> [--confirm]. The former `on` / `off` toggles, the `decide` / `last` subcommands and `calibration` (renamed `learning`) were removed.";
+        readonly details: "An epic is bound to ONE plan: `start` opens it for the current plan, `close` ends it. Requires `epic.mode.enabled: true` in config (top-level `epic` block; no `turbo` block needed — the legacy `turbo.epic` path is still accepted and migrated). `start [--force]` refuses, in order: epic-disabled-by-config, host-unsupported (the host gives the plugin no OpenCode SDK client; on OpenCode 2 the v2 adapter now ships one, so this refusal no longer fires there — v2 is held by the child-session placement work instead), no-plan / plan-ledger-unreadable, epic-already-open (idempotent for the same plan) / epic-open-for-other-plan, turbo-active (config turbo_mode, a session with Turbo on, or a running Lean run — Epic enables neither Lean nor Turbo and never waives per-task QA), dirty-baseline (git: uncommitted changes outside .swarm/), detached-head / epic-branch-exists (epic-branch policy), in-flight-coders (any coder dispatch, background delegation, unsettled settlement, or preserved/recovery lane), not-epic-sized (too few pending tasks, insufficient scope coverage, or insufficient effective speedup — run it in Balanced, or reshape it with the plan-shaping suggestions shown; `--force` overrides and is recorded). Non-git projects run an epic serially (one task per wave). Git epics default to `epic.commit_policy: \"epic-branch\"`: start checks out `swarm/epic/<epicKey>` and every Epic commit goes there (epic_next_wave blocks with epic-branch-mismatch, and no landing or residue is committed, while HEAD is elsewhere); `current-branch` keeps commits on the starting branch. In a git epic every coder runs in an isolated worktree (refused EPIC_ISOLATION_DEGRADED when isolation is unavailable) and lands as a `swarm(task <id>): …` merge commit; main-tree files a non-coder writer (test_engineer, docs) wrote for a task are committed as residue of that task; update_task_status writes nothing to git; wave close records the commit of each task as `refs/swarm/epics/<epicKey>/tasks/<id>` (deleted at close unless `epic.retain_refs`; never pushed by default). While open, the architect calls epic_next_wave and does what its status says: it issues one wave at a time (tasks with non-conflicting declared scopes — exclusive tasks alone, at most one task per densely coupled component; phases strictly in order), the architect dispatches one Task per taskId in ONE message and runs per-task QA (pre_check_batch → reviewer + test_engineer → update_task_status(completed)), and the next epic_next_wave closes the wave (recording outcomes and declared-vs-actual divergence) and issues the next; when a phase is done it returns phase-ready-for-review → epic_phase_review → phase_complete. `close [--abandon] [--land squash|merge|none]` refuses while tasks are pending (or the epic is orphaned / unreadable) unless `--abandon`, refuses a dirty tree before landing, writes a close report (epic-report-v2, embedding the epic scorecard) to .swarm/epic/reports/ and .swarm/epic-prior/reports/ (newest 50 kept), and lands the epic branch onto the original branch: squash (default — staged, uncommitted changes for you to review and commit), merge (a --no-ff merge commit), or none (switch back only). The epic branch is kept (remove it with `git branch -D` once committed). A landing conflict is rolled back (the attempted squash or merge is undone) and the epic stays closing — rerun close to resume. `--abandon` never lands; it switches back to the original branch when the tree is clean. `status [--repair-refs]` (also bare /swarm epic) shows the epic, its waves, phases, the task components recorded with the latest wave and recorded divergence, orphan detection (plan renamed or replaced), sentinel/row repair, recorded worktree merge failures, and retires legacy Epic v1 session state once; `--repair-refs` re-adopts task commits a rebase or amend made unreachable from HEAD. `report [<key>|last] [--format json]` shows the epic scorecard: live for the open epic (bare `report`), else from the close report of a past epic in .swarm/epic-prior/reports/ (`last` = newest; `<key>` = a report or epic key) — tasks completed in the epic, waves (count, width), time over closed waves (wave span, task issue→resolve time, and their ratio, a concurrency factor that is NOT a speedup: it includes queueing behind serialized QA), conflicts (merge-back failures, undeclared writes), rework (extra generations, reopens), first-pass gate rates (upper bounds: the failure history is bounded), forced/sizing at start and learned hot files. Epics learn from their outcomes: undeclared writes teach learned co-writes (a task declaring D that also wrote f makes later tasks declaring D conflict with tasks on f — planner analysis only, never write authorization) and incidents (undeclared writes, merge conflicts, Stage B failures, rework, reopens) in excess of clean exposures make a file hot (a task declaring it runs alone) — undeclared writes its strongest learned co-writer explains are discounted (expansion already separates them), so one declarer writing a file is not heat; an empty history learns nothing (neutral start). Each wave close updates the posterior of the epic; close merges it into the project prior .swarm/epic-prior/learning.json (decayed per epic and by age; kept across /swarm close; `epic.learning.*`). `learning` shows what the planner learned and uses now; `prior [show]` shows the project prior; `prior reset` previews and prints a single-use confirm token (15 minutes); `prior reset --confirm=<token>` clears it. Also: clear-merge-failure <taskId> [--confirm]. The former `on` / `off` toggles, the `decide` / `last` subcommands and `calibration` (renamed `learning`) were removed.";
         readonly args: "start [--force] | close [--abandon] [--land squash|merge|none] | status [--repair-refs] | report [<key>|last] [--format json] | learning | prior [show|reset [--confirm=<token>]] | clear-merge-failure <taskId> [--confirm]";
         readonly category: "diagnostics";
         readonly toolPolicy: "human-only";

package/dist/epic/start.d.ts

@@ -97,7 +97,7 @@ export interface EpicStartOptions {
  * with `client: undefined` (`src/host/v2/setup.ts`), so an epic there could
  * neither dispatch a coder nor complete a phase.
  */
-export declare const EPIC_HOST_UNSUPPORTED_MESSAGE = "This OpenCode host gives the plugin no SDK client (OpenCode 2 does not yet, see docs/host/v2-hook-inventory.md). Epic needs it for worktree-isolated coders and for the epic_phase_review reviewer/critic, so an epic here could neither run its coders nor complete a phase. Run the plan in Balanced, or use an OpenCode 1.x host (1.18.29+).";
+export declare const EPIC_HOST_UNSUPPORTED_MESSAGE = "This OpenCode host gives the plugin no SDK client. Epic needs it for worktree-isolated coders and for the epic_phase_review reviewer/critic, so an epic here could neither run its coders nor complete a phase. Run the plan in Balanced, or use an OpenCode 1.x host (1.18.29+). (On OpenCode 2 the v2 adapter now ships a session-capable client, so this refusal no longer fires there \u2014 Epic on v2 is held by the #3169 child-session placement work instead.)";
 /** Durable Lean run marked `running` — read without the migrating Lean reader. */
 declare function findRunningLeanRun(directory: string): string | null;
 /** Why Turbo blocks the start, or null (M-a). */
@@ -163,10 +163,13 @@ export declare const _internals: {
     hasActiveTurboMode: () => boolean;
     /**
      * False only when the plugin was initialized on a host that supplies no
-     * SDK client: the v1 init stores the host client, the OpenCode 2 adapter
-     * stores `undefined`, and an uninitialized process (tests, scripts) keeps
-     * the initial `null` — which is not a host verdict, so it is allowed.
-     * Capability-based: once a v2 client is wired, Epic starts there too.
+     * SDK client: the v1 init stores the host client, an uninitialized process
+     * (tests, scripts) keeps the initial `null`, and only a genuinely
+     * client-less host stores `undefined` — which is not a host verdict, so
+     * it is allowed. Capability-based: the v2 adapter now ships a
+     * session-capable client (the #3169 session shim), so this passes on v2;
+     * Epic's v2 execution is held by the entry-point double-gate and the
+     * child-session placement work, not by this check.
      */
     hostProvidesClient: () => boolean;
     findRunningLeanRun: typeof findRunningLeanRun;

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;
@@ -2208,6 +2320,32 @@ interface PrReviewGateContext {
      */
     candidateSeverities?: Map<string, CandidateSeverity>;
 }
+/**
+ * Issue #3095: read-surface reuse of the derivation above for
+ * `pr_workflow_status`. The derivation itself stays single-sourced: every
+ * production caller is a validation/enforcement path that must keep throwing,
+ * so this wrapper exists only to thread the SAME result to a read-only status
+ * tool and to degrade fail-soft instead of blocking an observation. A status
+ * read must never fail the whole tool for an unbound head or an unreadable
+ * revision digest — the caller renders the `unavailable` arm (with the
+ * bounded reason) and still projects boundaries and lane coverage.
+ *
+ * Read-only by construction: it performs no writes and mutates no state.
+ * COST DISCLOSURE (not free): resolving the derivation context runs the
+ * revision-digest computation on every bound PR_REVIEW call — three bounded
+ * git processes plus a re-read/hash of every changed file
+ * (`createPrReviewGateContext` → `resolvePrWorkflowRevisionDigestForGate` →
+ * the workspace-snapshot digest path). An observation surface pays the same
+ * digest price an enforcement call would.
+ */
+export type PrReviewCandidateInventoryForStatus = {
+    state: 'available';
+    inventory: string[];
+} | {
+    state: 'unavailable';
+    reason: string;
+};
+export declare function derivePrReviewCandidateInventoryForStatus(directory: string, state: PrWorkflowGateState): Promise<PrReviewCandidateInventoryForStatus>;
 /**
  * Extract candidate ids from a discovery artifact's [CANDIDATE] rows. When
  * `scopeToLanes` is given (base-dimension sources credited for only a subset
@@ -2307,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;
@@ -2406,6 +2585,17 @@ export interface PrWorkflowGateRecoveryRead {
      * availability one.
      */
     armedShapeUnreadable: boolean;
+    /**
+     * true when the salvage reconstructed ONLY the abort-relevant fields and
+     * every `prReview*` projection field (base dispatches, artifact
+     * boundaries, run id, findings path, settlement digests) was dropped
+     * because the shadow bytes failed schema validation. The status tool uses
+     * this to mark its derived PR_REVIEW sections `unavailable` instead of
+     * reporting healthy-but-empty coverage — an absent field on a salvaged
+     * state proves nothing about the workflow. Present only when true; a
+     * schema-valid shadow (or an ordinary healthy read) keeps full fidelity.
+     */
+    prReviewProjectionDropped?: boolean;
 }
 /**
  * Recovery-only gate-state reader (issue #2242 R4, wedge W-5).

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

@@ -0,0 +1,96 @@
+/**
+ * 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`,
+ * which verified teardown requires), backed by the v2 host's `ctx.session`
+ * domain. Installed as the synthetic v1 PluginInput's `client` field by
+ * `setup.ts`, it flows through the shared init core's single client write site
+ * into `swarmState.opencodeClient` and every init-path `ctx.client` consumer —
+ * the tracking issue's Decision 2 (a client subset instead of v2 branches
+ * spread through consumers).
+ *
+ * Translation contract (per the issue §4 gap table and the Phase 0 live
+ * findings on @opencode/cli 2.0.26):
+ *
+ *   - `create({body:{parentID,title}, query:{directory}})` validates placement
+ *     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 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`,
+ *     called pump-side beside `seedSessionIdentityFromEnvelope`) and the
+ *     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` (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,
+ * 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
+ * dual-shape-parity scan's function tracker does not recognize object-literal
+ * method properties, so the client object's methods never await directly.
+ */
+import type { OpencodeClient } from '@opencode-ai/sdk';
+import type { V2EventEnvelope, V2PluginContext, V2SessionPermission } from './types';
+/**
+ * Record a `session.error` / `session.execution.failed` envelope's error
+ * payload for the shim's result translation. SYNC by contract — the event pump
+ * calls it inline in its iteration loop. Accepts the same dual payload dialect
+ * `mapV2EventToV1` accepts (live `data`, SDK `properties`).
+ */
+export declare function recordV2SessionErrorFromEnvelope(envelope: V2EventEnvelope): void;
+/** Drop all shim-held state (v2 cleanup path; bounded residue documented in the trace). */
+export declare function clearV2SessionClientState(): void;
+/**
+ * Map a v1 read-only denial map onto v2 create-time permission entries.
+ * Fail-closed shape: only `effect: 'deny'` entries are ever produced.
+ */
+export declare function readOnlyToolsToV2Permissions(tools: Readonly<Record<string, false>> | undefined): V2SessionPermission[];
+/** Feature-detect the full surface the shim requires (types.ts host-tolerance contract). */
+export declare function createV2SessionClient(ctx: V2PluginContext): OpencodeClient | undefined;

package/dist/host/v2/types.d.ts

@@ -14,11 +14,13 @@
  *
  * Drift guard: DEFERRED to the #2910 follow-up PR (a check-host-contract v2 digest leg over this corpus, plus the dual-host CI lane); until it lands, type truth rests on this provenance pin (now 2.0.26) and the live-host smoke. See docs/host/v2-hook-inventory.md for the full v1-to-v2 map.
  *
- * Host-tolerance contract for the session/worktree method surface (issue #3169 Phase 1):
- * the members below are REQUIRED to mirror the published `SessionDomain`/`WorktreeDomain`,
- * but nothing in Phase 1 calls them. Phase 2 call sites MUST feature-detect
- * (`typeof ctx.session.create === 'function'`) and degrade — requiredness is type-level
- * only and a 2.0.2x host lacking a member must never crash the adapter.
+ * Host-tolerance contract for the session/worktree method surface (issue #3169):
+ * the members below are REQUIRED to mirror the published `SessionDomain`/`WorktreeDomain`.
+ * Since Phase 2 the session-client shim (`src/host/v2/session-client.ts`) is the call
+ * site — it feature-detects every member it consumes, including `hook` (`typeof
+ * ctx.session.create === 'function'`), and returns `undefined` when any is missing, so
+ * requiredness stays type-level only and a 2.0.2x host lacking a member must never crash
+ * the adapter.
  *
  * Only the surfaces this adapter consumes are typed. Unknown fields are
  * intentionally left off; the adapter never relies on their absence.