opencode-swarm 7.87.2 → 7.88.0

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

@@ -78,6 +78,8 @@ The orchestrator may:
 - determine scope,
 - build or request the context pack,
 - launch explorers and triggered micro-lanes,
+- extract candidates from lane artifacts via `parse_lane_candidates` or equivalent parser,
+- filter, group, and chunk candidates for reviewer dispatch,
 - route candidates to reviewers,
 - route reviewer-confirmed findings to critics,
 - group validated findings,
@@ -88,7 +90,8 @@ The orchestrator MUST NOT:
 - re-read a candidate's target code to decide if it is valid,
 - silently downgrade or discard an explorer candidate,
 - treat tool output as a confirmed finding,
-- report a finding that no reviewer validated.
+- report a finding that no reviewer validated,
+- classify or judge candidates based on preview text alone — always use the structured parser output.
 
 If the orchestrator catches itself validating code, it must stop and delegate validation to a reviewer subagent.
 
@@ -495,9 +498,43 @@ Launch all base lanes with `dispatch_lanes_async` when available. Pass the six l
 
 Before Phase 4 or synthesis, call `collect_lane_results` with `wait: true` for the base-lane batch and treat the collected `lane_results` as the join barrier. Missing, stale, cancelled, or failed base lanes are explicit review coverage gaps. If `dispatch_lanes_async` is unavailable, use blocking `dispatch_lanes`; if that is also unavailable, simulate isolated passes. Do not let one lane's conclusions bias another lane, and record unavailable deterministic dispatch in the validation gate.
 
-When any collected or blocking `lane_results[]` item has `output_ref`, treat `output` as a preview only. Call `retrieve_lane_output` and consume the full artifact before extracting candidates, deciding that a lane produced no candidates, or routing work to reviewers. If a lane has `output_truncated: true`, `output_degraded: true`, `transcript_incomplete: true`, or no usable `output_ref`, record an explicit coverage gap and re-dispatch a narrower lane or mark affected candidates/coverage UNVERIFIED; never infer candidate absence from a preview.
-
-**lane id uniqueness for parallel dispatches:** When re-dispatching failed or re-running explorer lanes, every `dispatch_lanes_async` or `dispatch_lanes` lane `id` MUST be unique within that dispatch batch and should include lane and attempt suffixes (e.g. `pr_review_explore_lane1_attempt2`). Never reuse an id in the same batch unless intentionally replacing that exact lane before dispatch.
+### Candidate extraction via parser
+
+After `collect_lane_results` returns for base lanes, process each lane result
+that carries an `output_ref`. The orchestrator MUST use the candidate parser
+rather than preview-text extraction:
+
+1. For each `output_ref` (or batched), call `parse_lane_candidates` (or the
+   internal `parseAndPersist` module function) with `output_ref` and `producer`
+   flags; the parser auto-detects the format family per row. The parser reads
+   the full artifact from disk (no preview truncation issue) and returns
+   structured `ParseResultWithSidecar` records.
+2. Filter the returned `candidates[]` array by `producer: "swarm-pr-review"` and
+   the relevant `row_format_family` (e.g., `base_explorer` for base lanes,
+   `micro_lane` for micro-lanes). Filtering happens on the parsed results, NOT
+   on the tool input.
+3. Group the filtered candidates into reviewer-sized chunks:
+   - by file area (group by the directory or module of the `file_line` field),
+   - by category (group by the `category` field),
+   - by count (target max 50 candidates per chunk; smaller chunks are fine).
+4. Dispatch reviewer lanes (one per chunk) with bounded in-context candidate
+   lists. Each reviewer lane receives only the candidates from its assigned
+   chunk.
+
+If a lane has `output_degraded: true`, `transcript_incomplete: true`, or no usable `output_ref`, record an explicit
+coverage gap and re-dispatch a narrower lane or mark affected candidates
+UNVERIFIED. Never infer candidate absence from a preview.
+
+**Fallback convention:** If the parser is unavailable, the explorer MAY emit
+`[CANDIDATE]` rows in the lane output as a fallback convention (see the
+Explorer Prompt Template at the end of this skill), but the orchestrator
+SHOULD use the parser as the primary extraction mechanism.
+
+**lane id uniqueness for parallel dispatches:** When re-dispatching failed or
+re-running explorer lanes, every `dispatch_lanes_async` or `dispatch_lanes`
+lane `id` MUST be unique within that dispatch batch and should include lane and
+attempt suffixes (e.g., `pr_review_explore_lane1_attempt2`). Never reuse an id
+in the same batch unless intentionally replacing that exact lane before dispatch.
 
 Explorers optimize for recall. Over-reporting is expected. Explorers produce candidates only.
 
@@ -507,7 +544,7 @@ Explorers optimize for recall. Over-reporting is expected. Explorers produce can
 | Lane 2: Security and trust boundaries | Injection, authz/authn bypass, SSRF, path traversal, secret exposure, unsafe deserialization, prompt injection | untrusted input sources, sanitization, credential handling, permission boundary, private network access, output escaping |
 | Lane 3: Dependencies and deployment safety | Import changes, version bumps, lockfile drift, breaking APIs, package scripts, runtime assumptions | lockfile consistency, new transitive deps, Node/Bun/runtime compatibility, platform assumptions, license red flags |
 | Lane 4: Docs, intent, and drift | PR claims vs implementation, docs mismatch, migration/changelog gaps, stale examples | obligation mapping, changed behavior not documented, docs promising behavior not implemented |
-| Lane 5: Tests and falsifiability | Weak assertions, missing edge tests, flaky patterns, mock leakage, fixture drift | assertion strength, tautology patterns (`expect(true).toBe(true)`, `expect(res).toBeDefined()` without further checks, `assertDoesNotThrow` wrapping trivial code), negative paths, isolation, deterministic timing, cross-platform path coverage |
+| Lane 5: Tests and falsifiability | Weak assertions, missing edge tests, flaky patterns, mock leakage, fixture drift | assertion strength, tautology patterns (`expect(true).toBe(true)`, `expect(res).toBeDefined()` without further checks), `assertDoesNotThrow` wrapping trivial code), negative paths, isolation, deterministic timing, cross-platform path coverage |
 | Lane 6: Performance and architecture | Complexity regressions, memory leaks, over-coupling, inefficient graph scans, global mutable state | algorithmic deltas, caching, resource lifecycle, state ownership, architectural boundary violations |
 
 ### Explorer context contract
@@ -523,12 +560,19 @@ Every explorer must inspect or explicitly mark unavailable:
 7. relevant Swarm knowledge/evidence entries, if present.
 8. the commit range to analyze (`base_ref..head_ref`),
 
-Explorer output format:
+### Explorer output format
+
+Explorers emit structured candidate records. The parser reads the full lane
+artifact and extracts these records. The canonical record shape is:
 
 ```text
 [CANDIDATE] | candidate_id | lane | severity | category | file:line | claim | evidence_summary | impact_context | confidence: LOW/MEDIUM/HIGH
 ```
 
+The parser normalizes this into a structured `candidates[]` array. If the
+parser is unavailable, the explorer MAY emit the `[CANDIDATE]` row format
+directly in the lane output as a fallback convention.
+
 Explorers must not use `CONFIRMED`, `DISPROVED`, or `PRE_EXISTING`.
 
 ---
@@ -537,7 +581,7 @@ Explorers must not use `CONFIRMED`, `DISPROVED`, or `PRE_EXISTING`.
 
 After `collect_lane_results` returns for base lanes, inspect the context pack risk triggers. Launch focused micro-lanes for triggered categories only, using `dispatch_lanes_async` again when more than one read-only micro-lane is needed. Collect every micro-lane batch with `wait: true` before reviewer classification. Do not launch irrelevant micro-lanes.
 
-Apply the same `output_ref` rule to micro-lanes: retrieve full output before candidate routing, and treat degraded or incomplete lane artifacts as UNVERIFIED coverage rather than as clean negative evidence.
+Apply the same parser-based extraction to micro-lanes: call `parse_lane_candidates` on each micro-lane `output_ref` (filter the returned `candidates[]` array by `row_format_family === "micro_lane"` after parsing), and treat degraded or incomplete lane artifacts as UNVERIFIED coverage rather than as clean negative evidence.
 
 Each micro-lane receives:
 
@@ -547,7 +591,8 @@ Each micro-lane receives:
 - relevant deterministic signals,
 - related historical knowledge with quarantine/staleness status,
 - expected invariants,
-- output format as `[CANDIDATE]` only.
+- structured candidate output (parser-extracted). If the parser is unavailable,
+  the micro-lane MAY emit `[CANDIDATE]` rows as a fallback convention.
 
 ### Swarm plugin risk trigger map
 
@@ -596,7 +641,12 @@ Verifier output is advisory until incorporated by the independent reviewer or cr
 
 ## Phase 6: Independent Reviewer Confirmation
 
-Route candidates to reviewer subagents. The reviewer must re-read the candidate's file:line evidence and relevant context pack entries directly.
+Route candidates to reviewer subagents. The orchestrator routes candidates
+in bounded chunks produced by the parser-based extraction in Phase 3-4. Each
+reviewer lane receives a bounded list of candidates from a single chunk — by
+file area, category, or count — not the full candidate set. The reviewer must
+re-read the candidate's file:line evidence and relevant context pack entries
+directly.
 
 ### Noise budget and universal validation
 
@@ -813,6 +863,245 @@ Update the verdict only after re-verifying all previously blocking findings.
 
 ---
 
+## Dry-Run: Parser-Based Candidate Extraction
+
+This section demonstrates the new parser-based extraction path end-to-end
+using synthetic data. It is concrete enough to implement the same pattern in
+another skill.
+
+### Scenario
+
+A PR review has dispatched six base explorer lanes via `dispatch_lanes_async`.
+The batch completed and `collect_lane_results` returned:
+
+```json
+{
+  "batch_id": "batch-a1b2c3",
+  "lane_results": [
+    {
+      "lane_id": "pr_review_lane1_correctness",
+      "status": "completed",
+      "output_ref": ".swarm/lane-results/batch-a1b2c3/lane-1/out-abc123.json",
+      "output_degraded": false
+    },
+    {
+      "lane_id": "pr_review_lane2_security",
+      "status": "completed",
+      "output_ref": ".swarm/lane-results/batch-a1b2c3/lane-2/out-def456.json",
+      "output_degraded": false
+    }
+  ]
+}
+```
+
+### Step 1 — Call the parser
+
+The orchestrator calls `parse_lane_candidates` for each `output_ref`:
+
+```json
+{
+  "tool": "parse_lane_candidates",
+  "arguments": {
+    "output_ref": ".swarm/lane-results/batch-a1b2c3/lane-1/out-abc123.json",
+    "producer": "swarm-pr-review"
+  }
+}
+```
+
+### Step 2 — Structured response
+
+The parser returns a `ParseResultWithSidecar`. On success, `error` and `error_code` are absent:
+
+```json
+{
+  "candidates": [
+    {
+      "record_type": "candidate",
+      "row_format_family": "base_explorer",
+      "row_format_version": 1,
+      "record_version": { "major": 1, "minor": 0 },
+      "source_output_ref": ".swarm/lane-results/batch-a1b2c3/lane-1/out-abc123.json",
+      "source_batch_id": "B-2025-06-22-001",
+      "source_lane_id": "explorer-1",
+      "source_agent": "paid_explorer",
+      "source_digest": "sha256:abc123def456...",
+      "extracted_from_partial_source": false,
+      "sessionId": "ses_01HXYZ...",
+      "parentSessionId": "ses_01HABC...",
+      "producer": "swarm-pr-review",
+      "candidate_id": "C-001",
+      "lane": "Lane 1: Correctness and edge cases",
+      "micro_lane": null,
+      "severity": "HIGH",
+      "category": "null-safety",
+      "file_line": "src/utils/cache.ts:142",
+      "claim": "Uncached getter may return undefined on cold start",
+      "evidence_summary": "The `getCached` function returns `cache[key]` without a fallback when the cache is empty.",
+      "impact_context": "Downstream callers in `src/handlers/*.ts` expect a defined value and call `.toString()` directly.",
+      "invariant_violated": null,
+      "confidence": "HIGH"
+    },
+    {
+      "record_type": "candidate",
+      "row_format_family": "base_explorer",
+      "row_format_version": 1,
+      "record_version": { "major": 1, "minor": 0 },
+      "source_output_ref": ".swarm/lane-results/batch-a1b2c3/lane-1/out-abc123.json",
+      "source_batch_id": "B-2025-06-22-001",
+      "source_lane_id": "explorer-1",
+      "source_agent": "paid_explorer",
+      "source_digest": "sha256:abc123def456...",
+      "extracted_from_partial_source": false,
+      "sessionId": "ses_01HXYZ...",
+      "parentSessionId": "ses_01HABC...",
+      "producer": "swarm-pr-review",
+      "candidate_id": "C-002",
+      "lane": "Lane 1: Correctness and edge cases",
+      "micro_lane": null,
+      "severity": "MEDIUM",
+      "category": "async-ordering",
+      "file_line": "src/services/queue.ts:88",
+      "claim": "Race between `drain` and `processNext` may drop items",
+      "evidence_summary": "`drain` sets `active = false` before awaiting `processNext`, which also checks `active`.",
+      "impact_context": "Items submitted during the drain window are silently dropped.",
+      "invariant_violated": null,
+      "confidence": "MEDIUM"
+    }
+  ],
+  "invocation_envelope": {
+    "record_type": "invocation",
+    "source_output_ref": ".swarm/lane-results/batch-a1b2c3/lane-1/out-abc123.json",
+    "source_batch_id": "B-2025-06-22-001",
+    "source_lane_id": "explorer-1",
+    "source_agent": "paid_explorer",
+    "source_digest": "sha256:abc123def456...",
+    "row_format_version": 1,
+    "record_version": { "major": 1, "minor": 0 },
+    "sessionId": "ses_01HXYZ...",
+    "parentSessionId": "ses_01HABC...",
+    "producer": "swarm-pr-review",
+    "produced_at": "2025-06-22T14:30:00.000Z",
+     "format_families_detected": ["base_explorer"],
+     "candidate_count": 2,
+     "parse_errors": 2,
+     "malformed_rows": 0
+  },
+  "diagnostics": {
+    "candidate_count": 2,
+    "parse_errors": 2,
+    "parse_error_details": [
+      {
+        "row_index": 0,
+        "field": "row",
+        "message": "Both format-family discriminators present; defaulting to base_explorer"
+      },
+      {
+        "row_index": 1,
+        "field": "row",
+        "message": "Both format-family discriminators present; defaulting to base_explorer"
+      }
+    ],
+    "malformed_rows": 0,
+    "duplicate_id_count": 0,
+    "duplicate_id_warnings": [],
+    "degraded_source_count": 0,
+    "incomplete_source_count": 0,
+     "format_families_detected": ["base_explorer"]
+   }
+}
+```
+> **Note**: `parse_errors: 2` reflects FR-017/SC-017 position-based detection: when a `[CANDIDATE]` row has both `evidence_summary` and `impact_context` populated, the parser emits a `parse_error_details` entry per row with `field: "row"` and `message: "Both format-family discriminators present; defaulting to base_explorer"`. This is documented behavior, not a parser bug. To get `parse_errors: 0` with the row format, leave one of the two fields empty; to silence the warning entirely, emit structured JSON candidate records.
+
+On refusal (e.g. `output_ref` does not exist), `error` and `error_code` are present; `candidates` is `[]`; `invocation_envelope` and `diagnostics` are populated with empty fields for traceability:
+
+```json
+{
+  "error": "Artifact reference not found in store",
+  "error_code": "ref-not-found",
+  "candidates": [],
+  "invocation_envelope": {
+    "record_type": "invocation",
+    "source_output_ref": ".swarm/lane-results/batch-a1b2c3/lane-1/missing.json",
+    "source_batch_id": "",
+    "source_lane_id": "",
+    "source_agent": "",
+    "source_digest": "",
+    "row_format_version": 1,
+    "record_version": { "major": 1, "minor": 0 },
+    "produced_at": "2025-06-22T14:30:00.000Z",
+    "format_families_detected": [],
+    "candidate_count": 0,
+    "parse_errors": 0,
+    "malformed_rows": 0
+  },
+  "diagnostics": {
+    "candidate_count": 0,
+    "parse_errors": 0,
+    "parse_error_details": [],
+    "malformed_rows": 0,
+    "duplicate_id_count": 0,
+    "duplicate_id_warnings": [],
+    "degraded_source_count": 0,
+    "incomplete_source_count": 0,
+     "format_families_detected": []
+   }
+}
+```
+
+### Step 3 — Filter and group
+
+The orchestrator filters the returned `candidates[]` array by `producer: "swarm-pr-review"` and `row_format_family` (e.g. `base_explorer` or `micro_lane`), then groups
+the candidates. In this synthetic example, the two candidates above are grouped
+by file area:
+
+- **Chunk A — `src/utils/`** (1 candidate): C-001
+- **Chunk B — `src/services/`** (1 candidate): C-002
+
+If there were more candidates, the orchestrator would also group by category
+(e.g., `null-safety`, `async-ordering`) and cap each chunk at 50 candidates.
+
+### Step 4 — Dispatch reviewer lanes
+
+The orchestrator dispatches one reviewer lane per chunk:
+
+```text
+You are the independent reviewer. Validate only the candidates assigned below.
+Do not search for new issues except where needed to validate reachability or
+mitigation. Do not trust explorer severity.
+
+Context pack summary:
+- scope: ...
+- obligations: ...
+- impact cone: ...
+- deterministic signals: ...
+- relevant Swarm artifacts / knowledge: ...
+- base_ref: <commit SHA of base branch>
+- head_ref: <commit SHA of PR head branch>
+
+Candidates (Chunk A — src/utils/):
+- C-001 | HIGH | null-safety | src/utils/cache.ts:142 | Uncached getter may return undefined on cold start
+
+For each candidate, return:
+[REVIEWED] | candidate_id | CONFIRMED/DISPROVED/UNVERIFIED/PRE_EXISTING | evidence_type | final_severity | introduced_by_pr | file:line | rationale | falsification_probe | reviewer_id
+
+You must check caller context, reachability, schema/middleware/framework mitigations, state-machine constraints, test coverage, PR-introducedness, and severity.
+
+IMPORTANT: If a finding claims behavior is "new" or "introduced by the PR", you MUST read the equivalent code on the base branch (git show <base_ref>:<file>) to verify it was not present before. A reviewer claim of "this is new" is invalid without base-branch evidence. Do not compare the new code to an idealized baseline — compare it to what actually existed on the base branch at the time of the PR.
+```
+
+### Key invariants
+
+- The parser reads the **full artifact**, not a preview. Truncation in the
+  `dispatch_lanes` preview does not affect candidate extraction.
+- The orchestrator never classifies candidates — it only filters, groups, and
+  routes them.
+- Each reviewer receives a bounded chunk. A chunk with more than 50 candidates
+  is split before dispatch.
+- The `invocation_envelope` in the parser response provides audit provenance
+  for every extracted candidate.
+
+---
+
 # Council Mode Workflow
 
 Council mode is opt-in only and adversarial.
@@ -1116,4 +1405,10 @@ Return:
 [CANDIDATE] | candidate_id | lane | severity | category | file:line | claim | evidence_summary | impact_context | confidence
 ```
 
+The orchestrator extracts candidates from the full lane artifact via
+`parse_lane_candidates` as the primary mechanism. The `[CANDIDATE]` row
+format above is a fallback convention for environments where the parser is
+unavailable. Explorers should still emit structured records regardless of
+whether the parser is present.
+
 Do not let speed degrade validation quality.

package/README.md

@@ -800,6 +800,7 @@ Every candidate passes a 3-gate pipeline before entering quarantine:
 | mutation_test | Applies LLM-generated mutation patches to source files and runs tests to measure kill rate; verdict is pass/warn/fail based on configurable thresholds; used by the mutation_test gate (opt-in, off by default) |
 | generate_mutants | Architect-only: generates LLM-based mutation patches (5–10 per function across 6 types: off-by-one, null substitution, operator swap, guard removal, branch swap, side-effect deletion) for direct consumption by the mutation_test tool; returns SKIP verdict on LLM failure rather than throwing |
 | write_mutation_evidence | Architect-only: writes mutation gate results atomically to `.swarm/evidence/{phase}/mutation-gate.json`; accepts verdict (PASS/WARN/FAIL/SKIP), kill rate metrics, and optional survived mutant details; normalizes uppercase-to-lowercase before persisting |
+| parse_lane_candidates | Architect-only: parses `[CANDIDATE]` rows from a `dispatch_lanes` or `collect_lane_results` artifact by `output_ref`; produces structured records with provenance and optional sidecar JSONL persistence; returns `ParseResultWithSidecar` on success or `{ error, error_code, candidates: [] }` on refusal |
 | git_blame | Per-line git blame metadata (sha, author, date, summary) via `git blame --porcelain`; supports optional line range filtering |
 | diff | Structured git diff with contract change detection; supports `summaryOnly` mode returning file list with additions/deletions counts |
 | suggest_patch | Reviewer-safe structured patch suggestion; supports `format` parameter ('json' or 'unified') where unified outputs valid unified diff with `diff --git` headers, hunks, and context |

package/dist/background/candidate-parser.d.ts

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+declare const ArtifactInputSchema: z.ZodObject<{
+    output_ref: z.ZodString;
+    batchId: z.ZodString;
+    laneId: z.ZodString;
+    agent: z.ZodString;
+    role: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    parentSessionId: z.ZodOptional<z.ZodString>;
+    digest: z.ZodString;
+    text: z.ZodString;
+    transcriptIncomplete: z.ZodOptional<z.ZodBoolean>;
+    artifact_status: z.ZodEnum<{
+        ok: "ok";
+        "ref-not-found": "ref-not-found";
+        "artifact-corrupted": "artifact-corrupted";
+    }>;
+    source: z.ZodEnum<{
+        dispatch_lanes: "dispatch_lanes";
+        collect_lane_results: "collect_lane_results";
+    }>;
+    produced_at: z.ZodString;
+}, z.core.$strict>;
+declare const ParseFlagsSchema: z.ZodObject<{
+    accept_partial: z.ZodBoolean;
+    accept_degraded: z.ZodBoolean;
+    degraded: z.ZodBoolean;
+    row_format_version: z.ZodNumber;
+    producer: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ArtifactInput = z.infer<typeof ArtifactInputSchema>;
+export type ParseFlags = z.infer<typeof ParseFlagsSchema>;
+/**
+ * The two supported pipe-delimited format families produced by lane agents.
+ */
+export type RowFormatFamily = 'base_explorer' | 'micro_lane';
+/**
+ * A single parsed candidate record extracted from lane text.
+ */
+export interface CandidateRecord {
+    record_type: 'candidate';
+    row_format_family: RowFormatFamily;
+    row_format_version: number;
+    record_version: {
+        major: number;
+        minor: number;
+    };
+    source_output_ref: string;
+    source_batch_id: string;
+    source_lane_id: string;
+    source_agent: string;
+    source_digest: string;
+    extracted_from_partial_source: boolean;
+    sessionId?: string;
+    parentSessionId?: string;
+    producer?: string;
+    candidate_id: string;
+    lane: string | null;
+    micro_lane: string | null;
+    severity: string | null;
+    category: string | null;
+    file_line: string | null;
+    claim: string | null;
+    evidence_summary: string | null;
+    impact_context: string | null;
+    invariant_violated: string | null;
+    confidence: string | null;
+}
+/**
+ * One invocation-envelope record per parseCandidates call.
+ * Part of the return value but not persisted to a sidecar in this phase.
+ */
+export interface InvocationEnvelope {
+    record_type: 'invocation';
+    source_output_ref: string;
+    source_batch_id: string;
+    source_lane_id: string;
+    source_agent: string;
+    source_digest: string;
+    row_format_version: number;
+    producer?: string;
+    produced_at: string;
+    record_version: {
+        major: number;
+        minor: number;
+    };
+    sessionId?: string;
+    parentSessionId?: string;
+    format_families_detected: string[];
+    candidate_count: number;
+    parse_errors: number;
+    malformed_rows: number;
+}
+/**
+ * Detail record for a required-field violation inside a data row.
+ */
+export interface ParseErrorDetail {
+    row_index: number;
+    field: string;
+    message: string;
+}
+/**
+ * Warning record for a candidate_id that occurs more than once.
+ */
+export interface DuplicateIdWarning {
+    candidate_id: string;
+    occurrences: number;
+}
+/**
+ * Aggregate diagnostics returned alongside every parse result.
+ */
+export interface DiagnosticsSummary {
+    candidate_count: number;
+    parse_errors: number;
+    parse_error_details: ParseErrorDetail[];
+    malformed_rows: number;
+    duplicate_id_count: number;
+    duplicate_id_warnings: DuplicateIdWarning[];
+    degraded_source_count: number;
+    incomplete_source_count: number;
+    format_families_detected: string[];
+}
+/**
+ * Top-level return value from parseCandidates.
+ */
+export interface ParseResult {
+    error?: string;
+    error_code?: string;
+    candidates: CandidateRecord[];
+    invocation_envelope: InvocationEnvelope;
+    diagnostics: DiagnosticsSummary;
+}
+/**
+ * Options for the parse-and-persist path.
+ */
+export interface ParsePersistOptions {
+    /** Project root directory (OpenCode process working directory). */
+    projectRoot: string;
+    /** Override the batch digest. When omitted, SHA-256(batchId) is used. */
+    batchDigest?: string;
+    /**
+     * Passed through to the sidecar store's `useLockfile` option.
+     * When true, a proper-lockfile lock is acquired on the batch directory
+     * before the append; on lock failure `sidecar_write_error` is set.
+     * Default: false (no lock — existing append-only pattern).
+     */
+    useLockfile?: boolean;
+}
+/**
+ * ParseResult extended with an optional sidecar write error.
+ * When sidecar_write_error is present, the parse succeeded but the
+ * sidecar append failed; the caller should treat the parse as valid
+ * and log/report the write error separately.
+ */
+export interface ParseResultWithSidecar extends ParseResult {
+    sidecar_write_error?: string;
+}
+/**
+ * Parse candidate records from structured lane-output text.
+ *
+ * This is a pure function: no filesystem writes, no store lookups, no I/O.
+ * The caller is responsible for store lookup, constructing the ArtifactInput,
+ * and setting artifact_status based on lookup outcome.
+ *
+ * @param input  Structured artifact metadata and raw text.
+ * @param flags  Caller-controlled acceptance flags and format version.
+ * @returns      Parsed candidates, invocation envelope, and diagnostics.
+ */
+export declare function parseCandidates(input: ArtifactInput, flags: ParseFlags): ParseResult;
+/**
+ * Parse candidates and append the invocation envelope + candidate records
+ * to the sidecar JSONL file.
+ *
+ * parseCandidates remains pure (no I/O). This wrapper adds sidecar
+ * persistence: on success the envelope + candidates are appended to
+ * `.swarm/lane-results/{batchDigest}/candidates.jsonl`; on append
+ * failure the parse still succeeds and sidecar_write_error is populated
+ * (SC-023).
+ *
+ * batchDigest is derived as SHA-256(batchId) when not explicitly provided
+ * in options (Option A — consistent with lane-output-store.ts internals).
+ *
+ * @param input   Structured artifact metadata and raw text.
+ * @param flags   Caller-controlled acceptance flags and format version.
+ * @param options Persistence options (projectRoot, optional batchDigest).
+ * @returns       Parse result with optional sidecar_write_error field.
+ */
+export declare function parseAndPersist(input: ArtifactInput, flags: ParseFlags, options: ParsePersistOptions): ParseResultWithSidecar;
+export {};

package/dist/background/candidate-sidecar-store.d.ts

@@ -0,0 +1,56 @@
+export interface SidecarStoreOptions {
+    /** Project root directory (the OpenCode process working directory). */
+    projectRoot: string;
+    /** Override the batch digest. When omitted, SHA-256(batchId) is used. */
+    batchDigest?: string;
+    /**
+     * When true, acquire a `proper-lockfile` lock on the batch directory
+     * before the append and release it afterwards.  Default: false (no lock —
+     * matches the existing append-only pattern the codebase already uses).
+     *
+     * On lock acquisition failure the function throws; the caller
+     * (`parseAndPersist`) catches and records `sidecar_write_error`.
+     */
+    useLockfile?: boolean;
+}
+/**
+ * Sanitize a single string value for sidecar persistence.
+ *
+ * Transformations applied in order:
+ * 1. NUL bytes (`\x00`) → `\u0000` escape (preserves information).
+ * 2. ANSI escape sequences (`\x1B[...]`) → entire sequence stripped.
+ *    Handles CSI (`ESC [ params intermediate final`), OSC (`ESC ] ... BEL/ST`),
+ *    and two-character escape sequences.
+ * 3. Unicode bidi markers (U+202A–U+202E, U+2066–U+2069) → stripped.
+ *
+ * All other characters pass through unchanged.
+ *
+ * @param value - Raw string value (may contain NUL bytes, ANSI, bidi markers).
+ * @returns Sanitized string safe for JSONL persistence.
+ */
+export declare function sanitizeString(value: string): string;
+/**
+ * Append an invocation envelope followed by zero or more candidate records
+ * to the sidecar JSONL file for the given batch.
+ *
+ * The envelope is always the first record in the append batch (SC-015).
+ * Cross-skill coexistence is enabled via the `producer` field on the
+ * envelope (FR-019).
+ *
+ * Content sanitization (FR-021) is applied to the persisted copy: NUL bytes
+ * are escaped to `\u0000`, ANSI ESC bytes are stripped, and Unicode bidi
+ * markers are stripped.  The caller's in-memory records are NOT mutated.
+ *
+ * Concurrency safety (FR-014): when `options.useLockfile` is true, a
+ * `proper-lockfile` lock is acquired on the batch directory before the
+ * append and released afterwards.  Lock acquisition failures propagate as
+ * throws.  Default behaviour (useLockfile omitted or false) is lockless
+ * append — the existing pattern used throughout the codebase.
+ *
+ * @param options  Store configuration (projectRoot, optional batchDigest, useLockfile).
+ * @param batchId  The batch identifier (used to derive batchDigest when not provided).
+ * @param envelope The invocation envelope record (validated before write).
+ * @param candidates Candidate records to append after the envelope (validated before write).
+ * @throws If schema validation fails, lock acquisition fails, or the filesystem write fails.
+ */
+export declare function appendToSidecar(options: SidecarStoreOptions, batchId: string, envelope: unknown, candidates: unknown[]): void;

package/dist/cli/{config-doctor-6h64pn8n.js → config-doctor-jzbgpbdh.js}

@@ -12,8 +12,8 @@ import {
   shouldRunOnStartup,
   writeBackupArtifact,
   writeDoctorArtifact
-} from "./index-1cb4wxnm.js";
-import"./index-q9h0wb04.js";
+} from "./index-819xp49y.js";
+import"./index-0asbrmdx.js";
 import"./index-5e4e2hvv.js";
 import"./index-p0arc26j.js";
 import"./index-zgwm4ryv.js";

package/dist/cli/{guardrail-explain-9fngqx80.js → guardrail-explain-sw5bjxtk.js}

@@ -1,14 +1,14 @@
 // @bun
 import {
   handleGuardrailExplain
-} from "./index-f41fa3f0.js";
-import"./index-6qkwgdsg.js";
-import"./index-5hvbw5xh.js";
+} from "./index-fwb5f2gr.js";
+import"./index-jch711dq.js";
+import"./index-g00qm2gf.js";
 import"./index-yhsmmv2z.js";
-import"./index-s8bj492g.js";
+import"./index-32axfg6h.js";
 import"./index-e8pk68cc.js";
-import"./index-1cb4wxnm.js";
-import"./index-q9h0wb04.js";
+import"./index-819xp49y.js";
+import"./index-0asbrmdx.js";
 import"./index-8y7qetpg.js";
 import"./index-adz3nk9b.js";
 import"./index-v4fcn4tr.js";