opencode-swarm 7.160.0 → 7.160.2

package/.opencode/skills/critic-gate/SKILL.md

@@ -41,13 +41,20 @@ one-line `reason` (or ask the user to run `/swarm approve-plan-critic
 <reason>`). This records a manual `plan_critic_gate` approval snapshot
 tagged `method: "manual_override"`, audited to `.swarm/events.jsonl`.
 Architect-only. Use ONLY when a legitimate APPROVED was lost — this is an
-escape hatch, not a substitute for running the critic review.
+escape hatch, not a substitute for running the critic review. It is also the sanctioned recovery for a bookkeeping-grade hashed-field repair under PLAN FREEZE below.
 
 CRITIC-GATE TRIGGER: Run ONCE when you first write the complete .swarm/plan.md.
 Do NOT re-run CRITIC-GATE before every project phase.
 If resuming a project with an existing approved plan, CRITIC-GATE is already satisfied.
 Caveat: this assumption breaks if the plan lacks a `plan_critic_gate`-tagged approval snapshot (e.g. a plan approved before this mechanical gate existed, or one where the recording heuristic didn't fire) — in that case the first coder dispatch will fail with `PLAN_CRITIC_GATE_VIOLATION`. If that happens, do not assume CRITIC-GATE is satisfied; re-run it and get a fresh APPROVED verdict.
 
+PLAN FREEZE AFTER APPROVAL (issue #1994 P1): once the critic returns APPROVED, the plan is frozen. The coder dispatch gate compares the plan against the approval snapshot via the structure hash (`computePlanStructureHash`), so classify post-approval changes by what that hash actually covers:
+- STATUS-ONLY changes (task status transitions via `update_task_status`) are excluded from the hash and never invalidate the approval — no re-critic needed.
+- MATERIAL (invalidates the approval): adding or removing tasks; changing any task's `id`, `phase`, `description`, `acceptance`, or `depends`; or enumerating `removed_task_ids` on a re-save. Re-run MODE: CRITIC-GATE exactly ONCE on the revised plan and get a fresh APPROVED before the next coder dispatch — the dispatch fails `PLAN_CRITIC_GATE_VIOLATION` against the stale snapshot otherwise.
+- `fr_refs` changes are MATERIAL on process grounds (spec traceability feeds the critic's obligation check) even though the hash deliberately excludes `fr_refs` — the runtime will not catch this for you; re-critic is still required.
+- BOOKKEEPING-GRADE hashed fields (`size`, `evidence_path`, `blocked_reason`, `title`, `current_phase`, `files_touched`) trip the gate mechanically even for pure bookkeeping edits. For a genuine bookkeeping repair — most commonly a `files_touched`-only reconciliation aligned with an active `declare_scope` binding (the sanctioned `SCOPE_CONFLICT` repair path in the execute skill) — use the gate's own recovery: `approve_plan_critic` with a truthful one-line reason (audited to `.swarm/events.jsonl`), not a full re-critic. Any substantive scope growth beyond reconciliation is MATERIAL: re-critic.
+Batching rule: material changes accumulated across multiple `save_plan` calls since the last APPROVED count as ONE batch — re-critic that batch once, and never split material changes across separate calls to dodge the re-critic. The pre-change approval is never valid for the changed plan.
+
 6j. SPEC-GATE (Execute BEFORE any save_plan call):
 - An effective spec exists iff `/swarm sdd status` reports a resolved spec (it reflects `readEffectiveSpecSync`, which returns null — NO effective spec — for no sources, multiple competing sources (openspec+specify), multi-feature Spec-Kit without a selected feature, or any unresolvable state). `save_plan` rejects (SPEC_REQUIRED) when `/swarm sdd status` reports no resolved spec. The gate is overridable via `SWARM_SKIP_SPEC_GATE=1`.
 - Before calling save_plan, verify an effective spec exists (via `/swarm sdd status` or `lint_spec`).

package/.opencode/skills/execute/SKILL.md

@@ -73,8 +73,9 @@ All other gates: failure → return to coder. No self-fixes. No workarounds.
     → REQUIRED: Print "diff: [PASS | CONTRACT CHANGE — details]"
     5d. Run `syntax_check` tool. SYNTACTIC ERRORS → return to coder. NO ERRORS → proceed to placeholder_scan.
     → REQUIRED: Print "syntaxcheck: [PASS | FAIL — N errors]"
-    5e. Run `placeholder_scan` tool. PLACEHOLDER FINDINGS → return to coder. NO FINDINGS → proceed to imports.
-    → REQUIRED: Print "placeholderscan: [PASS | FAIL — N findings]"
+    5e. Run `placeholder_scan` tool WITH DIFF SCOPING: pass `added_lines` — a map of workspace-relative file path → the line numbers ADDED by this task's uncommitted work (from `git diff -U0 HEAD -- <task files>` for tracked files; the coder's edits are not committed yet, so a commit-range diff like `<base>...HEAD` returns zero added lines here) — so only task-added lines drive the verdict. PLACEHOLDER FINDINGS (on added lines) → return to coder. NO FINDINGS → proceed to imports.
+    → Diff-scope fallback: for a file whose added lines you cannot map (new/untracked file, no diff available) or whose computed added-line set is EMPTY, OMIT that file from `added_lines` entirely — the tool then scans it unfiltered (fail-closed) — and manually cross-check that file's findings against the changed lines before returning to coder. NEVER pass an empty line array for a file (an empty array suppresses every finding in it) and NEVER hand-enumerate guessed line numbers (a wrong map silently suppresses findings). A pre-existing TODO/FIXME on an unchanged line is existing debt to surface to the reviewer, not a coder bounce.
+    → REQUIRED: Print "placeholderscan: [PASS | FAIL — N findings (diff-scoped) | FAIL — N findings (unscoped — cross-checked against changed lines)]"
     5f. Run `imports` tool for dependency audit. ISSUES → return to coder.
     → REQUIRED: Print "imports: [PASS | ISSUES — details]"
     5g. Run `lint` tool with fix mode for auto-fixes. If issues remain → run `lint` tool with check mode. FAIL → return to coder.
@@ -193,7 +194,7 @@ This step supplements (not replaces) the existing regression-sweep and test-drif
 5o. ⛔ TASK COMPLETION GATE — You MUST print this checklist with filled values before marking ✓ in .swarm/plan.md:
   [TOOL] diff: PASS / SKIP — value: ___
   [TOOL] syntax_check: PASS — value: ___
-  [TOOL] placeholder_scan: PASS — value: ___
+  [TOOL] placeholder_scan: PASS — value: ___ (diff-scoped | unscoped — cross-checked)
   [TOOL] imports: PASS — value: ___
   [TOOL] lint: PASS — value: ___
   [TOOL] build_check: PASS / SKIPPED — value: ___

package/.opencode/skills/phase-wrap/SKILL.md

@@ -105,6 +105,8 @@ If any required agent is missing, `phase_complete` returns `{ success: false, st
 
 The `docs` agent requirement is controlled by `phase_complete.require_docs` in plugin configuration, not by the QA gate profile returned by `get_qa_gate_profile`. It defaults to `true`. Set it to `false` only when the phase genuinely has no documentation obligation. A successful docs completion is persisted as plan- and phase-bound participation proof so `phase_complete` can recover it after a session restart; unrelated task-gate evidence does not count as docs participation.
 
+Docs-attestation integrity (issue #1994 P2): when the docs agent concludes that a phase — especially a doc-only phase — needs no further documentation edits, that attestation is valid ONLY if the docs agent actually inspected the phase's changed files and recorded what it checked (files read, per-file verdict) in its completion report. A mechanical "no edits needed" reply dispatched only to satisfy `agentsDispatched` — without inspecting the phase's changes — is a process violation: the gate exists to catch documentation drift, not to be acknowledged past.
+
 The `coder` and `test_engineer` agents are required because every phase that modifies source code or tests must have at least one implementation and one test-verification delegation. For pure documentation or retrospective phases, these may be waived by the user explicitly.
 
 This is a hard enforcement mechanism, not a suggestion. `phase_complete` will not return `status: success` if any required agent is missing from `agentsDispatched`.

package/.opencode/skills/running-tests/SKILL.md

@@ -232,6 +232,12 @@ git worktree remove "$env:TEMP\repro-check"
 
 ---
 
+## Placeholder Scans Without Diff Line Numbers
+
+`placeholder_scan` is diff-aware: when you can supply `added_lines` (a map of workspace-relative file path → added line numbers from the task/PR diff), its verdict covers only the added lines, so a pre-existing TODO/FIXME on an unchanged line inside a changed file no longer fails the gate. When you CANNOT map a file's added lines (new/untracked file, no diff access) — or the computed added-line set is EMPTY — omit that file from `added_lines` entirely: the tool scans it unfiltered, fail-closed, and you manually cross-check that file's findings against the changed lines before treating a finding as introduced by the change. NEVER pass an empty line array for a file (an empty array suppresses every finding in it) and NEVER hand-enumerate guessed line numbers: a wrong `added_lines` map silently suppresses findings.
+
+---
+
 ## Failure Classification
 
 Not all failures are equal. Before deciding what to do, classify the failure:

package/.opencode/skills/swarm-implement/SKILL.md

@@ -117,6 +117,8 @@ Implement in coherent, reviewable chunks. Follow existing repository patterns.
 
 **`declare_scope` discipline.** Before every coder or test-engineer delegation (and before every retry), call `declare_scope({ taskId, files, replace_existing: true })` with the exact workspace-relative file list the delegated agent may modify — including generated or lockfile paths the change will produce (for example, `dist/*`, `package-lock.json`, or `bun.lock`). Direct and shell writes are both scope-enforced. If the file list is not completely obvious, declare the containing workspace-relative directories instead. Treat `SCOPE_CONFLICT`, `SCOPE_BINDING_EXPIRED`, `SCOPE_BINDING_AMBIGUOUS`, and `SCOPE_WORKSPACE_MISMATCH` as architect-owned recovery signals: reconcile the named scope sources or lane root, replace the declaration, then redispatch. Never instruct the delegated agent to bypass the gate or switch write mechanisms.
 
+**Smallest justified scope on `SCOPE_CONFLICT` (issue #1994 S4).** The replacement declaration must be the SMALLEST justified scope: first reconcile what the delegation actually intends to write (the task's files vs the conflicting scope source named in the diagnostic), then narrow the conflicting lower-precedence source to a subset of that list — repair stale plan scope with `save_plan` and/or the delegation's `FILE:` lines — and only then re-declare exactly that file list; re-declaring alone leaves the non-subset relation and reproduces the same `SCOPE_CONFLICT`. Split the task into separate delegations if the conflict reveals two disjoint write sets. NEVER resolve a `SCOPE_CONFLICT` by widening to a plan-inferred superset: auto-widening over-authorizes writes and hides an inaccurate plan or delegation prompt behind a bigger scope. This matches the execute skill's scope-recovery contract ("Do not widen scope just to make the sets agree"); a `save_plan` scope repair is a bookkeeping change covered by the critic-gate plan-freeze rule.
+
 If the project exposes `sast_scan` with `capture_baseline`, capture the
 phase-scoped SAST baseline before first coder delegation so later scans fail only
 on new findings rather than pre-existing infrastructure noise.

package/.opencode/skills/swarm-pr-review/SKILL.md

@@ -66,12 +66,7 @@ This protocol runs on any agent harness. Before Phase 0, detect which profile
 this session is in by checking the actual tool list — never assume from the
 harness name, and never guess:
 
-- **Profile A — structured PR-workflow controller.** The swarm plugin's
-  controller tools are available in this session: `dispatch_lanes_async`,
-  `collect_lane_results`, `retrieve_lane_output`, `parse_lane_candidates`,
-  `write_pr_review_artifact`, `write_pr_review_trigger_eval`,
-  `complete_pr_workflow`. Typical host: OpenCode with the swarm plugin. The
-  controller mechanically enforces this skill's accounting: it computes the
+- **Profile A — structured PR-workflow controller.** The swarm plugin's controller tools are available in this session: `dispatch_lanes_async`, `collect_lane_results`, `retrieve_lane_output`, `parse_lane_candidates`, `submit_pr_review_result`, `write_pr_review_artifact`, `write_pr_review_trigger_eval`, `complete_pr_workflow`. Typical host: OpenCode with the swarm plugin. The controller mechanically enforces this skill's accounting: it computes the
   depth tier itself from the bound merge-base diff (never from caller
   claims), enforces the tier's lane floors and full dimension/family
   partitions for consolidated dispatch, and gates structured reviewer/critic
@@ -101,11 +96,19 @@ harness name, and never guess:
 
 | Harness (typical) | Profile | Lane dispatch | Ledger persistence | Completion gate |
 |---|---|---|---|---|
-| OpenCode + swarm plugin | A | `dispatch_lanes_async` / `collect_lane_results` | `write_pr_review_artifact`, `write_pr_review_trigger_eval` | `complete_pr_workflow` |
+| OpenCode + swarm plugin | A | `dispatch_lanes_async` / `collect_lane_results` | `submit_pr_review_result`, `write_pr_review_artifact`, `write_pr_review_trigger_eval` | `complete_pr_workflow` |
 | Claude Code | B | parallel `Agent`/`Task` subagents | ledger files in the session task workspace | Pre-Synthesis Gate checklist |
 | OpenAI Codex | B | parallel subagents (fresh context) | ledger files in working notes | Pre-Synthesis Gate checklist |
 | ZCode | B | parallel subagents (fresh context) | ledger files in working notes | Pre-Synthesis Gate checklist |
 
+Host-native JSON-schema transport is optional and currently unregistered on the
+tested OpenCode, Claude Code, Codex, and ZCode host matrix. Profile A therefore
+uses the child-bound `submit_pr_review_result` tool as its supported baseline.
+Any future native integration must implement the fixed internal
+`promptJsonSchema({ sessionId, agent, schema, parts })` seam and pass the
+adapter-present, unsupported-before-execution, provider-failure, timeout, and
+per-session capability tests before registration.
+
 **Completion-gate assurance is NOT equivalent across profiles.** Only Profile A
 enforces completion MECHANICALLY: the controller's `complete_pr_workflow` receipt
 gate refuses synthesis unless base coverage, the 11-family trigger ledger, and the
@@ -155,10 +158,14 @@ ordering, vocabulary, or schema.
 Controller order is exact: bind the immutable head/base range; dispatch,
 settle, and parse base lanes; evaluate every trigger row; dispatch micro lanes;
 settle and parse every matched micro family; persist the trigger evaluation;
-persist post-explorer findings; run reviewers; run critics; then persist the
-final artifact and complete the workflow. The **initial** micro dispatch MUST
-supply the complete trigger-evaluation ledger; that dispatch freezes it for the
-session.
+submit exactly one `submit_pr_review_result` receipt for each base/micro
+discovery lane and then stop; persist post-explorer findings; run reviewers;
+run critics; then persist the final artifact and complete the workflow. Transcript
+`[CANDIDATE]` / `[CLEAN]` rows are deprecated legacy compatibility only for
+lanes whose snapped `pr_review_legacy_transcript_compatibility` contract
+explicitly enables them.
+The **initial** micro dispatch MUST supply the complete trigger-evaluation
+ledger; that dispatch freezes it for the session.
 Any subsequent micro batch in that same session MAY omit `trigger_evaluation`
 and reuse the frozen ledger. If a subsequent batch explicitly supplies a copy,
 that copy MUST remain exactly identical to the frozen ledger.
@@ -825,6 +832,7 @@ Tool candidate rules:
 
 - Confirm reachability before reporting.
 - Confirm PR-introducedness before reporting as a PR blocker.
+- When `placeholder_scan` output is used as a signal, pass `added_lines` (file path → PR-added line numbers from the merge-base diff) so only added lines drive the scan; a placeholder finding on an unchanged line is a pre-existing-debt candidate, not a PR blocker. If added-line mapping is unavailable, treat the findings as unscoped and cross-check them against the PR diff before recording the row.
 - Confirm that a framework, schema, middleware, caller guard, or test isolation rule does not already mitigate it.
 - Do not report scanner output verbatim without reviewer validation.
 - Redact secrets; never paste raw credentials into the final output.
@@ -1107,28 +1115,17 @@ machine-readable rows as unfenced plain text; do not emit the backticks.
 [CANDIDATE] | candidate_id | lane | severity | category | file:line | claim | evidence_summary | impact_context | confidence | risk_impact | risk_tags
 ```
 
-Profile A stores the full assistant transcript, so earlier unmarked progress
-turns may precede the machine-readable section. The parser locates that section
-at the first pipe-delimited line whose first field is exactly `[CANDIDATE]` and
-ignores unmarked preamble, including incidental pipe-delimited text. That first
-marker is authoritative and must be the exact canonical base or micro header;
-a malformed marker or marker-prefixed data row without a header fails closed.
-The Profile A controller coverage gate also refuses a missing marker. The pure
-parser retains markerless positional fallback only for legacy callers outside
-that controller trust boundary. Explorers should continue to make the canonical
-header the first line of their final machine-readable response.
+Profile A now treats `submit_pr_review_result` as the authoritative settlement path for base and micro discovery lanes. The caller-bound structured receipt dominates later prose, truncation, or transcript incompleteness. Transcript candidate/clean rows remain deprecated compatibility only when `pr_review_legacy_transcript_compatibility` was explicitly enabled for that lane and no structured receipt exists; a present-but-invalid structured result fails closed and never falls back.
+
+When compatibility mode is active, Profile A stores the full assistant transcript. The parser locates the first pipe-delimited line whose first field is exactly `[CANDIDATE]`, ignores unmarked preamble, and requires the exact canonical base/micro header; malformed markers or marker-prefixed rows without a header fail closed. The controller refuses a missing marker. Markerless positional fallback remains only for legacy callers outside that trust boundary; explorers should put the canonical header first.
 
 The confidence data value must be exactly LOW, MEDIUM, or HIGH.
 
-Under Profile A the parser normalizes this into a structured `candidates[]`
-array. On Profiles B/C — and as a Profile A fallback when the parser is
-unavailable — the explorer emits the `[CANDIDATE]` row format directly in the
-lane output as the extraction contract.
+Under Profile A the parser-backed transcript path is compatibility-only; a successful `submit_pr_review_result` receipt is authoritative. On Profiles B/C — and on a Profile A lane whose snapped contract explicitly enables deprecated legacy transcript compatibility and lacks a structured receipt — the explorer emits `[CANDIDATE]` rows directly as the extraction contract.
 
 Explorers must not use `CONFIRMED`, `DISPROVED`, or `PRE_EXISTING`.
 
-A base lane that finds no surviving candidates must emit exactly one fully
-populated clean row:
+A base lane that finds no surviving candidates must submit exactly one structured CLEAN result and then stop. Only a lane in the deprecated transcript-compatibility path may instead emit exactly one fully populated clean row:
 
 The fence below is documentation formatting only. Emit the clean attestation
 as unfenced plain text; do not emit the backticks.
@@ -1225,7 +1222,10 @@ artifact; and the completed ledger is persisted as `trigger-eval.json` in the
 session/task workspace before reviewer dispatch. A matched family with no
 attestation row is an unclosed coverage gap.
 
-For each micro `output_ref` (Profile A), call `parse_lane_candidates` with
+For each micro lane in Profile A, prefer the single structured
+`submit_pr_review_result` receipt over transcript parsing. Only for a lane
+whose snapped contract explicitly enables deprecated transcript compatibility
+and lacks a structured receipt should you fall back to `parse_lane_candidates` against its `output_ref`, with
 `producer: "swarm-pr-review"`, `expected_family: "micro_lane"`, and
 `expected_micro_lane` set to the launch-micro-lane value from the
 provenance-linked trigger row. When the artifact came from a consolidated
@@ -1249,7 +1249,7 @@ errors, zero malformed rows, and a complete, non-degraded source:
 [CLEAN] | micro_lane | coverage_scope | evidence
 ```
 
-Header-only or malformed zero output is `UNATTESTED`; apply the COVERAGE GATE (Phase 3). Under Profile A, the structured async PR-workflow path is required to preserve `L1`, exact-head, batch, and workflow-lane provenance; the active controller rejects blocking and direct-Task substitutes, and Task-derived findings or CLEAN prose cannot satisfy Phase 4's controller ledger. Under Profiles B/C, acceptance is the row contract itself: accept a candidate or clean row only when its `micro_lane` field matches the trigger row it claims, and treat prose-only "clean" claims as `UNATTESTED`.
+Header-only or malformed zero output is `UNATTESTED`; apply the COVERAGE GATE (Phase 3). Under Profile A, the structured async PR-workflow path must preserve `L1`, exact-head, batch, and workflow-lane provenance; the active controller rejects blocking and direct-Task substitutes, and Task-derived findings or CLEAN prose cannot satisfy Phase 4's controller ledger unless the lane explicitly runs deprecated transcript compatibility. Under Profiles B/C, acceptance is the row contract: accept a candidate or clean row only when its `micro_lane` matches the trigger row, and treat prose-only "clean" claims as `UNATTESTED`.
 
 Each micro-lane receives:
 

package/.opencode/skills/swarm-pr-review/references/prompt-templates.md

@@ -73,6 +73,13 @@ Use this template when dispatching a base explorer:
 ```text
 You are a base explorer. Optimize for recall, not final judgment.
 Return candidates only. Do not use CONFIRMED, DISPROVED, or PRE_EXISTING.
+On Profile A structured PR-review discovery lanes, call `submit_pr_review_result`
+exactly once with the canonical base-lane result and then stop. Do not append
+duplicate `[CANDIDATE]` / `[CLEAN]` transcript rows or recap prose after that
+tool call.
+The transcript rows below are deprecated legacy compatibility only. Emit them
+only when the dispatched lane explicitly enables
+`pr_review_legacy_transcript_compatibility`.
 Do not narrate progress or repeat the prompt. Keep the complete final response at or below 12,000 characters; spend that budget on evidence-bearing rows and the minimum prose needed to make them auditable. When the controller-appended contract declares a per-lane final_response_char_budget, that number is authoritative over this template default.
 
 Lane:
@@ -114,6 +121,13 @@ Use this template when dispatching a micro-lane or council explorer:
 ```text
 You are a micro-lane or council explorer. Optimize for recall, not final judgment.
 Return candidates only. Do not use CONFIRMED, DISPROVED, or PRE_EXISTING.
+On Profile A structured PR-review discovery lanes, call `submit_pr_review_result`
+exactly once with the canonical micro-lane result and then stop. Do not append
+duplicate `[CANDIDATE]` / `[CLEAN]` transcript rows or recap prose after that
+tool call.
+The transcript rows below are deprecated legacy compatibility only. Emit them
+only when the dispatched lane explicitly enables
+`pr_review_legacy_transcript_compatibility`.
 Do not narrate progress or repeat the prompt. Keep the complete final response at or below 12,000 characters; spend that budget on evidence-bearing rows and the minimum prose needed to make them auditable. When the controller-appended contract declares a per-lane final_response_char_budget, that number is authoritative over this template default.
 
 Micro/council lane:
@@ -146,10 +160,12 @@ Emit the final machine-readable header and rows as unfenced plain text. The
 Markdown fence around this prompt is documentation only; do not emit backticks.
 ```
 
-Under Profile A the orchestrator extracts candidates from the full lane
-artifact via `parse_lane_candidates` as the primary mechanism. On Profiles
-B/C — and as a Profile A fallback when the parser is unavailable — the
-`[CANDIDATE]` row format above IS the extraction contract. Explorers emit
-structured records regardless of which harness runs them.
+Under Profile A the authoritative discovery-settlement path is exactly one
+`submit_pr_review_result` call per base/micro lane. Transcript
+`[CANDIDATE]` / `[CLEAN]` rows remain a deprecated fallback only when the
+lane's snapped `pr_review_legacy_transcript_compatibility` contract enables
+them and no structured receipt exists. On Profiles B/C the `[CANDIDATE]` row
+format above remains the extraction contract. Explorers emit structured
+records regardless of which harness runs them.
 
 Do not let speed degrade validation quality.

package/dist/agents/architect.d.ts

@@ -20,7 +20,7 @@ export declare const ARCHITECT_MEMORY_OUTCOME_GUIDANCE = "After using recalled m
  * 5. Memory Rule (line ~101): Never store swarm identity in memory blocks
  * 6. CRITIC GATE (lines ~102-107): Plan review before implementation
  * 7. MANDATORY QA GATE (lines ~108-165):
- *    - Stage A: Automated tool gates (diff → syntax_check → placeholder_scan → imports → lint → build_check → pre_check_batch)
+ *    - Stage A: Automated tool gates (diff → syntax_check → placeholder_scan (diff-scoped via added_lines) → imports → lint → build_check → pre_check_batch)
  *    - Stage B: Agent review gates (reviewer → security reviewer → test_engineer)
  *    - ANTI-EXEMPTION RULES: 8 "WRONG thoughts" to ignore
  *    - PARTIAL GATE RATIONALIZATIONS: 6 "WRONG thoughts" to ignore

package/dist/background/pending-delegations.d.ts

@@ -36,6 +36,7 @@
  * escape `.swarm/` (Invariant 4).
  */
 import { type DelegationCheckpointAuditSummary } from './delegation-health.js';
+import { type PrReviewResultReceipt } from './pr-review-contract.js';
 export declare const BACKGROUND_DELEGATIONS_FILE = "background-delegations.jsonl";
 export declare const BACKGROUND_DELEGATION_FALLBACK_DIR = "background-delegation-fallback";
 export declare const BACKGROUND_CODER_RESERVATIONS_FILE = "background-coder-reservations.json";
@@ -129,7 +130,7 @@ export type SweepableDelegationStatus = 'pending' | 'running' | 'ingestion_error
  */
 export declare const DEFAULT_SWEEPABLE_DELEGATION_STATUSES: ReadonlySet<SweepableDelegationStatus>;
 export interface BackgroundDelegationRecord {
-    schemaVersion: 1 | 2 | 3;
+    schemaVersion: 1 | 2 | 3 | 4;
     /** Subagent session id from the dispatch envelope — the correlation key. */
     correlationId: string;
     /** Structured jobId from dispatch metadata when available, else null. */
@@ -164,6 +165,8 @@ export interface BackgroundDelegationRecord {
      * singleton lanes (legacy and tier-L dispatches).
      */
     ownedWorkflowLanes?: string[];
+    /** Dispatch-time snapshot; absent legacy records keep transcript compatibility. */
+    prReviewLegacyTranscriptCompatibility?: boolean;
     /** Canonical hash of prompt/provenance inputs captured at dispatch time. */
     promptHash?: string;
     /** Project/root provenance captured at dispatch time. */
@@ -281,6 +284,12 @@ export interface BackgroundDelegationResult {
     outputArtifactError?: string;
     transcriptIncomplete?: boolean;
     messageCount?: number;
+    /**
+     * Issue #2384: authoritative structured PR-review result receipt. Persisted
+     * separately from transcript text so compaction and preview truncation can
+     * never promote presentation-layer text into machine authority.
+     */
+    prReviewResultReceipt?: import('./pr-review-contract.js').PrReviewResultReceipt;
     /**
      * Durable failure provenance for a lane-atomic PR-workflow terminalization.
      * Optional because successful lanes and legacy terminal results have none.
@@ -487,6 +496,7 @@ export interface RecordPendingInput {
     mode?: string;
     workflowLane?: string;
     ownedWorkflowLanes?: string[];
+    prReviewLegacyTranscriptCompatibility?: boolean;
     promptHash?: string;
     workspace?: BackgroundWorkspaceSnapshot;
     taskChangeContext?: BackgroundTaskChangeContext;
@@ -533,6 +543,41 @@ export declare function appendDelegationTransition(directory: string, correlatio
     completedAt?: number;
     expectedCurrentStatuses?: readonly BackgroundDelegationStatus[];
 }): Promise<BackgroundDelegationRecord | null>;
+export type PublishPrReviewResultReceiptOutcome = {
+    status: 'recorded';
+    record: BackgroundDelegationRecord;
+} | {
+    status: 'duplicate';
+    record: BackgroundDelegationRecord;
+} | {
+    status: 'conflict';
+    reason: string;
+} | {
+    status: 'not_found';
+    reason: string;
+} | {
+    status: 'terminal';
+    reason: string;
+} | {
+    status: 'uncertain';
+    reason: string;
+};
+/**
+ * Atomically publish the child-bound PR-review receipt while its delegation is
+ * still live. The workflow gate performs the outer session-state validation;
+ * this inner transaction rechecks immutable delegation identity under the
+ * evidence lock and provides semantic exactly-once behavior.
+ */
+export declare function publishPrReviewResultReceipt(directory: string, input: {
+    parentSessionId: string;
+    childSessionId: string;
+    batchId: string;
+    laneId: string;
+    expectedWorkflowInstanceId: string;
+    expectedWorkflowRevision: number;
+    expectedBaseSha: string;
+    receipt: PrReviewResultReceipt;
+}): Promise<PublishPrReviewResultReceiptOutcome>;
 export interface BuildBackgroundCompletionEventIdInput {
     correlationId: string;
     jobId: string | null;

package/dist/background/pr-review-contract.d.ts

@@ -25,6 +25,249 @@ export type PrReviewRiskImpact = (typeof PR_REVIEW_RISK_IMPACTS)[number];
  */
 export declare const PR_REVIEW_RISK_TAGS: readonly ["SECURITY", "AUTH_PERMISSIONS", "STATE_INTEGRITY", "WRITE_PATH", "EVIDENCE_INTEGRITY", "GIT", "CONFIGURATION"];
 export type PrReviewRiskTag = (typeof PR_REVIEW_RISK_TAGS)[number];
+export declare const PR_REVIEW_RESULT_LANE_MODES: readonly ["swarm-pr-review:base", "swarm-pr-review:micro"];
+export declare const PR_REVIEW_RESULT_OUTCOMES: readonly ["CLEAN", "FINDINGS", "INCOMPLETE"];
+export declare const PR_REVIEW_RESULT_FINDING_SEVERITIES: readonly ["CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"];
+export declare const PR_REVIEW_RESULT_UNRESOLVED_REASONS: readonly ["NOT_EXECUTED", "PARTIAL_OUTPUT", "CONTRACT_FAILURE", "RESOURCE_LIMIT", "DEADLINE_EXCEEDED", "STALE_BINDING", "PARENT_CANCELLED"];
+export declare const MAX_PR_REVIEW_RESULT_OWNED_LANES = 11;
+export declare const MAX_PR_REVIEW_RESULT_FINDINGS = 256;
+export declare const MAX_PR_REVIEW_RESULT_RECEIPT_BYTES: number;
+export type PrReviewResultLaneMode = (typeof PR_REVIEW_RESULT_LANE_MODES)[number];
+export type PrReviewResultOutcome = (typeof PR_REVIEW_RESULT_OUTCOMES)[number];
+export type PrReviewResultFindingSeverity = (typeof PR_REVIEW_RESULT_FINDING_SEVERITIES)[number];
+export type PrReviewResultUnresolvedReason = (typeof PR_REVIEW_RESULT_UNRESOLVED_REASONS)[number];
+export declare function prReviewLegacyTranscriptCompatibilityEnabled(value: boolean | undefined): boolean;
+export declare const PrReviewResultLocationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"local">;
+    file: z.ZodString;
+    line: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
+    column: z.ZodOptional<z.ZodNumber>;
+    endColumn: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"non_local">;
+    label: z.ZodString;
+    detail: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type PrReviewResultLocation = z.infer<typeof PrReviewResultLocationSchema>;
+export declare const PrReviewResultFindingSchema: z.ZodObject<{
+    id: z.ZodString;
+    workflowLane: z.ZodString;
+    severity: z.ZodEnum<{
+        CRITICAL: "CRITICAL";
+        HIGH: "HIGH";
+        MEDIUM: "MEDIUM";
+        LOW: "LOW";
+        INFO: "INFO";
+    }>;
+    riskImpact: z.ZodEnum<{
+        ORDINARY: "ORDINARY";
+        HIGH_IMPACT: "HIGH_IMPACT";
+        UNKNOWN: "UNKNOWN";
+    }>;
+    riskTags: z.ZodArray<z.ZodEnum<{
+        SECURITY: "SECURITY";
+        AUTH_PERMISSIONS: "AUTH_PERMISSIONS";
+        STATE_INTEGRITY: "STATE_INTEGRITY";
+        WRITE_PATH: "WRITE_PATH";
+        EVIDENCE_INTEGRITY: "EVIDENCE_INTEGRITY";
+        GIT: "GIT";
+        CONFIGURATION: "CONFIGURATION";
+    }>>;
+    title: z.ZodString;
+    body: z.ZodString;
+    evidence: z.ZodString;
+    location: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"local">;
+        file: z.ZodString;
+        line: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+        column: z.ZodOptional<z.ZodNumber>;
+        endColumn: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"non_local">;
+        label: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export type PrReviewResultFinding = z.infer<typeof PrReviewResultFindingSchema>;
+export declare const PrReviewCleanAttestationSchema: z.ZodObject<{
+    workflowLane: z.ZodString;
+    coverageScope: z.ZodString;
+    evidence: z.ZodString;
+}, z.core.$strict>;
+export type PrReviewCleanAttestation = z.infer<typeof PrReviewCleanAttestationSchema>;
+export declare const PrReviewUnresolvedLaneSchema: z.ZodObject<{
+    workflowLane: z.ZodString;
+    reason: z.ZodEnum<{
+        NOT_EXECUTED: "NOT_EXECUTED";
+        PARTIAL_OUTPUT: "PARTIAL_OUTPUT";
+        CONTRACT_FAILURE: "CONTRACT_FAILURE";
+        RESOURCE_LIMIT: "RESOURCE_LIMIT";
+        DEADLINE_EXCEEDED: "DEADLINE_EXCEEDED";
+        STALE_BINDING: "STALE_BINDING";
+        PARENT_CANCELLED: "PARENT_CANCELLED";
+    }>;
+    detail: z.ZodString;
+}, z.core.$strict>;
+export type PrReviewUnresolvedLane = z.infer<typeof PrReviewUnresolvedLaneSchema>;
+export declare const PrReviewLaneResultEnvelopeSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    outcome: z.ZodEnum<{
+        CLEAN: "CLEAN";
+        FINDINGS: "FINDINGS";
+        INCOMPLETE: "INCOMPLETE";
+    }>;
+    creditedLanes: z.ZodArray<z.ZodString>;
+    findings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        workflowLane: z.ZodString;
+        severity: z.ZodEnum<{
+            CRITICAL: "CRITICAL";
+            HIGH: "HIGH";
+            MEDIUM: "MEDIUM";
+            LOW: "LOW";
+            INFO: "INFO";
+        }>;
+        riskImpact: z.ZodEnum<{
+            ORDINARY: "ORDINARY";
+            HIGH_IMPACT: "HIGH_IMPACT";
+            UNKNOWN: "UNKNOWN";
+        }>;
+        riskTags: z.ZodArray<z.ZodEnum<{
+            SECURITY: "SECURITY";
+            AUTH_PERMISSIONS: "AUTH_PERMISSIONS";
+            STATE_INTEGRITY: "STATE_INTEGRITY";
+            WRITE_PATH: "WRITE_PATH";
+            EVIDENCE_INTEGRITY: "EVIDENCE_INTEGRITY";
+            GIT: "GIT";
+            CONFIGURATION: "CONFIGURATION";
+        }>>;
+        title: z.ZodString;
+        body: z.ZodString;
+        evidence: z.ZodString;
+        location: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"local">;
+            file: z.ZodString;
+            line: z.ZodOptional<z.ZodNumber>;
+            endLine: z.ZodOptional<z.ZodNumber>;
+            column: z.ZodOptional<z.ZodNumber>;
+            endColumn: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"non_local">;
+            label: z.ZodString;
+            detail: z.ZodString;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>>;
+    cleanAttestations: z.ZodArray<z.ZodObject<{
+        workflowLane: z.ZodString;
+        coverageScope: z.ZodString;
+        evidence: z.ZodString;
+    }, z.core.$strict>>;
+    unresolved: z.ZodArray<z.ZodObject<{
+        workflowLane: z.ZodString;
+        reason: z.ZodEnum<{
+            NOT_EXECUTED: "NOT_EXECUTED";
+            PARTIAL_OUTPUT: "PARTIAL_OUTPUT";
+            CONTRACT_FAILURE: "CONTRACT_FAILURE";
+            RESOURCE_LIMIT: "RESOURCE_LIMIT";
+            DEADLINE_EXCEEDED: "DEADLINE_EXCEEDED";
+            STALE_BINDING: "STALE_BINDING";
+            PARENT_CANCELLED: "PARENT_CANCELLED";
+        }>;
+        detail: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PrReviewLaneResultEnvelope = z.infer<typeof PrReviewLaneResultEnvelopeSchema>;
+export declare function serializedPrReviewResultReceiptBytes(value: unknown): number;
+export declare function prReviewLaneResultEnvelopeDigest(value: PrReviewLaneResultEnvelope): string;
+export declare const PrReviewResultReceiptSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    mode: z.ZodEnum<{
+        "swarm-pr-review:base": "swarm-pr-review:base";
+        "swarm-pr-review:micro": "swarm-pr-review:micro";
+    }>;
+    workflowInstanceId: z.ZodString;
+    workflowRevision: z.ZodNumber;
+    batchId: z.ZodString;
+    laneId: z.ZodString;
+    workflowLane: z.ZodString;
+    ownedWorkflowLanes: z.ZodArray<z.ZodString>;
+    baseSha: z.ZodString;
+    headSha: z.ZodString;
+    dispatchRevisionDigest: z.ZodString;
+    childSessionId: z.ZodString;
+    generation: z.ZodNumber;
+    semanticEnvelopeDigest: z.ZodString;
+    envelope: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        outcome: z.ZodEnum<{
+            CLEAN: "CLEAN";
+            FINDINGS: "FINDINGS";
+            INCOMPLETE: "INCOMPLETE";
+        }>;
+        creditedLanes: z.ZodArray<z.ZodString>;
+        findings: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            workflowLane: z.ZodString;
+            severity: z.ZodEnum<{
+                CRITICAL: "CRITICAL";
+                HIGH: "HIGH";
+                MEDIUM: "MEDIUM";
+                LOW: "LOW";
+                INFO: "INFO";
+            }>;
+            riskImpact: z.ZodEnum<{
+                ORDINARY: "ORDINARY";
+                HIGH_IMPACT: "HIGH_IMPACT";
+                UNKNOWN: "UNKNOWN";
+            }>;
+            riskTags: z.ZodArray<z.ZodEnum<{
+                SECURITY: "SECURITY";
+                AUTH_PERMISSIONS: "AUTH_PERMISSIONS";
+                STATE_INTEGRITY: "STATE_INTEGRITY";
+                WRITE_PATH: "WRITE_PATH";
+                EVIDENCE_INTEGRITY: "EVIDENCE_INTEGRITY";
+                GIT: "GIT";
+                CONFIGURATION: "CONFIGURATION";
+            }>>;
+            title: z.ZodString;
+            body: z.ZodString;
+            evidence: z.ZodString;
+            location: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"local">;
+                file: z.ZodString;
+                line: z.ZodOptional<z.ZodNumber>;
+                endLine: z.ZodOptional<z.ZodNumber>;
+                column: z.ZodOptional<z.ZodNumber>;
+                endColumn: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"non_local">;
+                label: z.ZodString;
+                detail: z.ZodString;
+            }, z.core.$strict>], "kind">;
+        }, z.core.$strict>>;
+        cleanAttestations: z.ZodArray<z.ZodObject<{
+            workflowLane: z.ZodString;
+            coverageScope: z.ZodString;
+            evidence: z.ZodString;
+        }, z.core.$strict>>;
+        unresolved: z.ZodArray<z.ZodObject<{
+            workflowLane: z.ZodString;
+            reason: z.ZodEnum<{
+                NOT_EXECUTED: "NOT_EXECUTED";
+                PARTIAL_OUTPUT: "PARTIAL_OUTPUT";
+                CONTRACT_FAILURE: "CONTRACT_FAILURE";
+                RESOURCE_LIMIT: "RESOURCE_LIMIT";
+                DEADLINE_EXCEEDED: "DEADLINE_EXCEEDED";
+                STALE_BINDING: "STALE_BINDING";
+                PARENT_CANCELLED: "PARENT_CANCELLED";
+            }>;
+            detail: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type PrReviewResultReceipt = z.infer<typeof PrReviewResultReceiptSchema>;
 export declare const PR_REVIEW_CONTRACT_CARD_HEADER = "[PR-REVIEW CONTRACT CARD]";
 export declare const PR_REVIEW_FINDINGS_MAX_BYTES: number;
 export declare const PR_REVIEW_FINDINGS_WRITE_MAX_BYTES: number;
@@ -36,10 +279,10 @@ export declare const PrReviewRunIdSchema: z.ZodString;
 export declare const PrReviewFindingSchema: z.ZodObject<{
     finding_id: z.ZodString;
     status: z.ZodEnum<{
-        PENDING: "PENDING";
         CONFIRMED: "CONFIRMED";
         DISPROVED: "DISPROVED";
         PRE_EXISTING: "PRE_EXISTING";
+        PENDING: "PENDING";
     }>;
     file_line: z.ZodString;
     evidence: z.ZodString;
@@ -135,10 +378,10 @@ export declare const WritePrReviewArtifactArgsSchema: z.ZodDiscriminatedUnion<[z
     records: z.ZodArray<z.ZodObject<{
         finding_id: z.ZodString;
         status: z.ZodEnum<{
-            PENDING: "PENDING";
             CONFIRMED: "CONFIRMED";
             DISPROVED: "DISPROVED";
             PRE_EXISTING: "PRE_EXISTING";
+            PENDING: "PENDING";
         }>;
         file_line: z.ZodString;
         evidence: z.ZodString;

package/dist/build/command-resolution.d.ts

@@ -0,0 +1,13 @@
+export interface ResolvedCommand {
+    argv: string[];
+    shellCommand: string;
+}
+/**
+ * Tokenize a generated command into argv without invoking a shell. Supports
+ * single and double quotes for grouping, but never interprets shell
+ * metacharacters.
+ */
+export declare function tokenizeCommand(command: string): string[];
+/** Resolve a plugin-generated command without invoking a package downloader. */
+export declare function resolveLocalCommand(command: string, workingDir: string, isAvailable: (binary: string) => boolean, platform?: NodeJS.Platform): ResolvedCommand | null;
+export declare function resolveLocalNodeTool(tool: string, args: string[], workingDir: string, platform?: NodeJS.Platform, isAvailable?: (binary: string) => boolean): string[] | null;