opencode-swarm 7.130.2 → 7.132.0

package/dist/services/trajectory-cluster.d.ts

@@ -16,6 +16,7 @@
  * Read-only over the knowledge store; writes only proposal markdown (never
  * active skills). Fail-open.
  */
+import { checkRecommendations, recordEmittedRecommendations } from './recommendation-ledger.js';
 /** Trajectories scanned per macro pass (the plan's N=200 window). */
 export declare const MACRO_TRAJECTORY_WINDOW = 200;
 /** A motif must recur across at least this many distinct tasks to propose. */
@@ -36,11 +37,31 @@ export declare function gatherFailureMotifs(directory: string, opts?: {
     window?: number;
     minTasks?: number;
 }): Promise<FailureMotif[]>;
+/**
+ * The recommendation a failure motif asserts, in cross-producer form
+ * (issue #1821 AC21).
+ *
+ * The agent role is folded into the *statement* rather than carried as a scope
+ * key so this statement can collide with an equivalent lesson proposed by the
+ * curator or the consensus miner — the whole point of a shared identity. The
+ * motif signature's constituents (tool, failure kind) are what actually vary
+ * between motifs, so two distinct motifs never produce the same statement.
+ */
+declare function motifStatement(motif: FailureMotif): string;
 /** Render a draft SKILL.md proposal body for a motif (with full provenance). */
-export declare function buildMotifProposal(motif: FailureMotif): string;
+export declare function buildMotifProposal(motif: FailureMotif, options?: {
+    fingerprint?: string;
+    producedAt?: string;
+}): string;
 export interface MotifProposalResult {
     motifs: number;
     proposalsWritten: string[];
+    /**
+     * #1821 AC21: motifs whose recommendation was already emitted — by an earlier
+     * improver run, the curator sweep, or the consensus miner — and were therefore
+     * not re-proposed.
+     */
+    duplicatesSuppressed: number;
 }
 /**
  * Run the macro motif pass and write one proposal per recurring motif. Returns
@@ -50,6 +71,8 @@ export declare function writeMotifProposals(directory: string, opts?: {
     window?: number;
     minTasks?: number;
     maxProposals?: number;
+    /** Recorded in the ledger entry's provenance write origin. */
+    sessionId?: string;
 }): Promise<MotifProposalResult>;
 /** Minimum number of steps in a trajectory for it to qualify as a workflow. */
 export declare const SUCCESS_SEQUENCE_MIN_STEPS = 3;
@@ -66,16 +89,56 @@ export interface SuccessMotif {
 export interface SuccessMotifProposalResult {
     motifs: number;
     proposalsWritten: string[];
+    /** #1821 AC21: see `MotifProposalResult.duplicatesSuppressed`. */
+    duplicatesSuppressed: number;
 }
 export declare function gatherSuccessMotifs(directory: string, opts?: {
     window?: number;
     minTasks?: number;
     minSteps?: number;
 }): Promise<SuccessMotif[]>;
-export declare function buildWorkflowProposal(motif: SuccessMotif): string;
+/**
+ * The recommendation a success motif asserts, in cross-producer form
+ * (issue #1821 AC21). Same agent-in-statement rationale as `motifStatement`.
+ *
+ * The rendered sequence MUST mirror `sequenceSignature` (`tool:action` per
+ * step), not just the tool names: two motifs that share a tool chain but differ
+ * in actions have different signatures, different slugs, and different proposal
+ * files, so a tool-only statement would collapse two genuinely different
+ * workflows onto one cross key and suppress the second.
+ */
+declare function workflowStatement(motif: SuccessMotif): string;
+export declare function buildWorkflowProposal(motif: SuccessMotif, options?: {
+    fingerprint?: string;
+    producedAt?: string;
+}): string;
 export declare function writeSuccessMotifProposals(directory: string, opts?: {
     window?: number;
     minTasks?: number;
     minSteps?: number;
     maxProposals?: number;
+    /** Recorded in the ledger entry's provenance write origin. */
+    sessionId?: string;
 }): Promise<SuccessMotifProposalResult>;
+/**
+ * DI seam (AGENTS.md invariant 7). `now` pins the shared `producedAt` that the
+ * ledger entry and the proposal frontmatter both carry; the two ledger functions
+ * let a test exercise the suppressed / degraded branches without touching the
+ * real ledger. Restore each entry in `afterEach`.
+ */
+export declare const _internals: {
+    now: () => Date;
+    checkRecommendations: typeof checkRecommendations;
+    recordEmittedRecommendations: typeof recordEmittedRecommendations;
+};
+/**
+ * Pure-function seam for tests (writing-tests SKILL.md, Tier 0). The two
+ * statement builders define the cross-producer identity of a motif, so a test
+ * asserting cross-producer suppression must derive the competing statement from
+ * them rather than hardcode a copy that can silently drift.
+ */
+export declare const _test_exports: {
+    motifStatement: typeof motifStatement;
+    workflowStatement: typeof workflowStatement;
+};
+export {};

package/dist/tools/consensus-mine.d.ts

@@ -0,0 +1,172 @@
+/**
+ * `consensus_mine` — run the consensus miner and persist its report.
+ *
+ * The tool is a thin, fully-wired shell around `src/consensus/`: it resolves the
+ * effective consensus config, assembles a `ConsensusMineRequest` from the
+ * caller's overrides, optionally supplies an LLM dispatcher, delegates to
+ * `mineAndStoreConsensusV1`, applies report retention, and renders a bounded
+ * summary.
+ *
+ * It is NOT write-minimal, and the description the model reads says so. The
+ * complete list of effects, none of which touches a project file:
+ *
+ * 1. **Its own report** under `.swarm/evolution/consensus/<reportId>.json`.
+ * 2. **Deletions of its own prior reports.** `pruneConsensusReports` runs
+ *    unconditionally after every mine and `consensus.report_retention` defaults
+ *    to 50, so the steady state of a long-lived project is that each run
+ *    `unlink`s the oldest report. Only `report_retention: 0` disables it.
+ * 3. **The shared dedup ledger** (issue #1821 AC21). It gains one entry per
+ *    emitted proposal EXCEPT where it already carries that recommendation's
+ *    cross key — those are counted as `duplicate_recommendation_count` instead.
+ *    The append is a whole-file rewrite with FIFO eviction at
+ *    `MAX_RECOMMENDATION_LEDGER_ENTRIES`, and eviction is by position, not by
+ *    producer: a miner append can evict the CURATOR's or the IMPROVER's oldest
+ *    entries. The ledger normally lives at
+ *    `.swarm/learning/recommendation-ledger.jsonl`, but its root is
+ *    `resolveKnowledgeStoreDir`, so under a knowledge-link pointer it lands in
+ *    the shared cohort root rather than this project's `.swarm/`.
+ * 4. **Lock sentinels.** The report goes through `withEvidenceLock`, whose
+ *    sentinel is an empty `<sha256>.lock` file under this project's
+ *    `.swarm/locks/`; `proper-lockfile` removes its own lock directory but
+ *    NOTHING removes that sentinel, so each distinct report id leaves one behind
+ *    permanently. The ledger goes through `transactFile`, which locks the
+ *    ledger's own containing directory and therefore produces
+ *    `<resolveKnowledgeStoreDir(directory)>/learning.lock` — outside this
+ *    project's `.swarm/` entirely whenever a knowledge link is active.
+ * 5. **A pending memory proposal per emitted proposal**, but only when
+ *    `memory.enabled` is `true` (it defaults to `false`,
+ *    `src/config/schema.ts`). This is issue #1821 AC22 — "use existing
+ *    proposal/MemoryRecord paths, not another inbox" — so the mirror goes
+ *    through the same `MemoryGateway.propose` path `swarm_memory_propose` uses,
+ *    which creates a *pending proposal* requiring curator review and never a
+ *    durable memory record.
+ * 6. **Up to `MAX_LLM_SUMMARIES` (20) `session.create` + `session.prompt`
+ *    calls** whenever `consensus.llm_summarization_enabled` (default `true`)
+ *    finds a wired OpenCode client.
+ *
+ * Effects 2-6 were absent from the tool description for four review rounds
+ * while it claimed "its only writes are its own immutable report and one entry
+ * in the shared recommendation dedup ledger". That string is read by a model as
+ * fact and was the premise of the Full-Auto auto-allow in
+ * `src/full-auto/policy.ts`; both now state the list above.
+ *
+ * What the tool does NOT do is mutate any of the evidence it reads. That is a
+ * chosen property, not a free one:
+ * `loadEvidence` upgrades a legacy flat retrospective in place by default, so
+ * `src/consensus/corpus.ts` binds it with `{ migrate: false }`. Without that, a
+ * mining run would rewrite evidence bundles — and remap their legacy
+ * `task_complexity` values — while advertising itself as read-only.
+ *
+ * It activates no skill, writes no knowledge entry, admits no durable memory
+ * record, and touches no project file — which is why it is classified as a
+ * **pathless write-like** tool in `src/full-auto/policy.ts` alongside
+ * `write_retro` and `knowledge_add`, and why it is absent from
+ * `WRITE_TOOL_NAMES` (`src/config/constants.ts`), whose members are the tools
+ * that write PROJECT FILE CONTENTS and are therefore subject to the scope guard.
+ * The knowledge-link redirection in effects 3 and 5 does not change that
+ * classification: `knowledge_add` and `knowledge_remove` are in the same
+ * auto-allow set and have the same redirection, and it comes from operator
+ * configuration rather than from anything the caller passed.
+ *
+ * `ctx.directory` is injected by `createSwarmTool`; there is no `process.cwd()`
+ * anywhere in this file (AGENTS.md invariant 4).
+ */
+import type { MemoryConfig } from '../config/schema';
+import type { ConsensusAttributeV1, ConsensusReportV1 } from '../consensus/contracts';
+import { createMemoryGateway } from '../memory';
+import { type RecommendationCandidate } from '../services/recommendation-ledger';
+import { createSwarmTool } from './create-tool';
+/**
+ * Reconcile the summary counters with what the inline echo actually shows.
+ *
+ * These are two different orderings and they do not line up. Restatements are
+ * spent on the top `MAX_LLM_SUMMARIES` attributes by CONFIDENCE
+ * (`src/consensus/miner.ts`), while the echo below is the first
+ * `MAX_INLINE_ATTRIBUTES` in canonical SIGNAL order. With confidence inverted
+ * relative to signal order, a report can print `summarized_count: 20` while zero
+ * `llm_summary` values are visible — which is exactly what "the count always
+ * agrees with the values echoed alongside it" used to claim was impossible.
+ * `hidden` is what makes the discrepancy legible instead of mysterious.
+ */
+declare function countSummaries(attributes: readonly ConsensusAttributeV1[], inlineLimit: number): {
+    total: number;
+    hidden: number;
+};
+/**
+ * Describe the miner's emissions to the cross-producer dedup ledger
+ * (issue #1821 AC21).
+ *
+ * The statement is the proposal's `intent` — the sentence the miner actually
+ * emits — not the internal attribute statement its own `lrec_` fingerprint is
+ * built from: only the intent survives onto the persisted report, and it is the
+ * text a human reads as "the recommendation". `scopeKeys` stays empty for the
+ * same reason the curator's new-knowledge recommendations carry none: content
+ * alone is the identity of a freshly-minted lesson, and that is exactly where
+ * another producer can legitimately be proposing the same thing.
+ */
+declare function buildMinerRecommendationCandidates(report: Pick<ConsensusReportV1, 'proposals' | 'generatedAt'>, sessionId?: string): RecommendationCandidate[];
+/**
+ * What the AC22 memory mirror actually did, reported rather than assumed.
+ *
+ * `attempted` is 0 whenever `enabled` is false, so a reader can tell "memory is
+ * off" from "memory is on and nothing was proposed". `failed` and `error` exist
+ * because the mirror is deliberately fail-open — the report is already durably
+ * written by the time it runs, and losing the whole mine to a memory-store
+ * problem would be worse than losing the mirror — but a fail-open path that
+ * reports nothing is exactly the defect `recommendation_ledger.degraded` was
+ * added to close.
+ */
+type MemoryMirrorResult = {
+    enabled: boolean;
+    attempted: number;
+    proposed: number;
+    rejected: number;
+    failed: number;
+    error?: string;
+};
+/**
+ * Issue #1821 AC22: mirror each emitted proposal into the EXISTING memory
+ * proposal path rather than leaving the consensus report as a write-only inbox.
+ *
+ * `MemoryGateway.propose` is the same entry point `swarm_memory_propose` uses
+ * (`src/tools/swarm-memory-propose.ts`), including its `dispose()` in a
+ * `finally`. It creates a PENDING proposal — curator review is still required,
+ * nothing durable is admitted — which is why the tool's proposals-only guarantee
+ * survives the mirror.
+ *
+ * Fail-open by design and per-proposal: one rejected or throwing proposal must
+ * not discard the ones that succeeded, and none of it can unwrite the report.
+ * Every outcome is counted and returned, so the tool's response says what
+ * happened instead of implying success.
+ */
+declare function mirrorProposalsToMemory(options: {
+    directory: string;
+    memoryConfig: MemoryConfig | undefined;
+    report: Pick<ConsensusReportV1, 'proposals' | 'reportId'>;
+    sessionId?: string;
+}): Promise<MemoryMirrorResult>;
+/**
+ * DI seam (AGENTS.md invariant 7). Lets a test drive the AC22 mirror's
+ * failure and rejection branches without a real provider and without
+ * `mock.module`. Restore each entry in `afterEach`.
+ */
+export declare const _internals: {
+    createMemoryGateway: typeof createMemoryGateway;
+};
+/**
+ * Pure-function seam for tests (writing-tests SKILL.md, Tier 0). Exported so a
+ * cross-producer dedup test can build the miner's ledger candidates through the
+ * same code the tool runs instead of restating the mapping, and so the
+ * summary-counter reconciliation can be asserted at the ordering that produces
+ * it — 20 summarized attributes with none visible — rather than only at the
+ * degenerate all-zero case a dispatcher-less run reaches.
+ */
+export declare const _test_exports: {
+    buildMinerRecommendationCandidates: typeof buildMinerRecommendationCandidates;
+    countSummaries: typeof countSummaries;
+    mirrorProposalsToMemory: typeof mirrorProposalsToMemory;
+    MAX_INLINE_ATTRIBUTES: number;
+    MIRRORED_PROPOSAL_KIND: "todo";
+};
+export declare const consensus_mine: ReturnType<typeof createSwarmTool>;
+export {};

package/dist/tools/index.d.ts

@@ -10,6 +10,7 @@ export { checkpoint } from './checkpoint';
 export { co_change_analyzer } from './co-change-analyzer';
 export { completion_verify } from './completion-verify';
 export { complexity_hotspots } from './complexity-hotspots';
+export { consensus_mine } from './consensus-mine';
 export { context_status } from './context-status';
 export { submit_council_verdicts } from './convene-council';
 export { convene_general_council } from './convene-general-council';
@@ -48,6 +49,7 @@ export { parse_lane_candidates } from './parse-lane-candidates';
 export { phase_complete } from './phase-complete';
 export { pkg_audit } from './pkg-audit';
 export { type PlaceholderFinding, type PlaceholderScanInput, type PlaceholderScanResult, placeholder_scan, placeholderScan, } from './placeholder-scan';
+export { plan_conflict_check } from './plan-conflict-check';
 export { pr_workflow_status } from './pr-workflow-status';
 export { type PreCheckBatchInput, type PreCheckBatchResult, pre_check_batch, runPreCheckBatch, type ToolResult, } from './pre-check-batch';
 export { executePreparePrFeedbackScope, prepare_pr_feedback_scope, } from './prepare-pr-feedback-scope';

package/dist/tools/knowledge-add.d.ts

@@ -1,2 +1,36 @@
 import { createSwarmTool } from './create-tool.js';
+/**
+ * Merge caller-supplied tags with the tags inferred from the lesson.
+ *
+ * Caller tags come FIRST so that when the combined list exceeds the cap,
+ * truncation drops inferred tags before it drops user intent. `dedupeCapped`
+ * is case-insensitive (first casing wins), so an inferred tag the caller
+ * already supplied collapses into the caller's casing instead of duplicating.
+ *
+ * Hoisted to module scope and exposed via `_test_exports` so this call site is
+ * observable on its own: the store write boundary normalizes the same fields,
+ * which would otherwise mask a regression here (issue #1821 Lane 0b).
+ */
+declare function mergeLessonTags(tagsInput: unknown, lesson: string): string[];
+/**
+ * Normalize one optional v3 actionability array from untrusted tool input.
+ *
+ * The `undefined` return is load-bearing: `validateActionableFields` and
+ * `validateActionability` distinguish an ABSENT field from an empty one, and
+ * JSON.stringify drops an `undefined` value so the persisted record keeps that
+ * distinction. Only the inner filter+cap is `dedupeCapped` (#1821 Lane 0b).
+ */
+declare function strArray(v: unknown): string[] | undefined;
 export declare const knowledge_add: ReturnType<typeof createSwarmTool>;
+/**
+ * Tier-0 test seam (issue #1821 Lane 0b). These are pure functions with no I/O.
+ * They are exported so the call-site normalization can be asserted directly:
+ * the store write boundary normalizes the same fields with the same semantics,
+ * so an assertion made against a PERSISTED entry cannot distinguish "call site
+ * fixed" from "call site reverted".
+ */
+export declare const _test_exports: {
+    mergeLessonTags: typeof mergeLessonTags;
+    strArray: typeof strArray;
+};
+export {};

package/dist/tools/lean-turbo-run-phase.d.ts

@@ -6,6 +6,7 @@ import type { ToolDefinition } from '@opencode-ai/plugin/tool';
 import { loadPluginConfigWithMeta as loadPluginConfigWithMeta_import } from '../config';
 import type { LaneResult, MergeBackFailureInfo } from '../turbo/lean/runner';
 import { LeanTurboRunner as LeanTurboRunner_import } from '../turbo/lean/runner';
+import type { LeanTurboDegradedTask } from '../turbo/lean/state';
 /**
  * Arguments for the lean_turbo_run_phase tool
  */
@@ -21,6 +22,12 @@ export interface LeanTurboRunPhaseResult {
     success: boolean;
     lanes?: LaneResult[];
     degradedTasks?: string[];
+    /**
+     * #1657: full degraded-task details (reason/files/requiredMode), additive
+     * alongside `degradedTasks`. Lets the architect see per-task degradation
+     * reasons in the tool result without reading /swarm status separately.
+     */
+    degradedDetails?: LeanTurboDegradedTask[];
     serializedTasks?: string[];
     mergeBackFailures?: MergeBackFailureInfo[];
     reason?: string;

package/dist/tools/manifest.d.ts

@@ -53,6 +53,7 @@ export declare const TOOL_MANIFEST: {
     checkpoint: () => ToolDefinition;
     pkg_audit: () => ToolDefinition;
     parse_lane_candidates: () => ToolDefinition;
+    plan_conflict_check: () => ToolDefinition;
     prepare_pr_feedback_scope: () => ToolDefinition;
     write_pr_review_artifact: () => ToolDefinition;
     write_pr_review_trigger_eval: () => ToolDefinition;
@@ -79,6 +80,7 @@ export declare const TOOL_MANIFEST: {
     doc_scan: () => ToolDefinition;
     doc_extract: () => ToolDefinition;
     curator_analyze: () => ToolDefinition;
+    consensus_mine: () => ToolDefinition;
     knowledge_add: () => ToolDefinition;
     knowledge_recall: () => ToolDefinition;
     knowledge_remove: () => ToolDefinition;

package/dist/tools/plan-conflict-check.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `plan_conflict_check` tool (#1656 — v8 parallel-first execution prerequisite).
+ *
+ * Read-only advisory: compute a pairwise file-conflict matrix for N proposed
+ * parallel task groups using declared scopes (and optional git co-change),
+ * returning a verdict and suggested serialization order.
+ *
+ * READ-ONLY CONTRACT (issue #1656 acceptance): this tool writes NOTHING — not
+ * to `.swarm/`, not to the source tree. It calls no other tools. The only I/O
+ * is reading `.swarm/plan.json` (via `loadPlanJsonOnly`) and
+ * `.swarm/scopes/scope-<taskId>.json` (via `readTaskScopes` inside
+ * `computeParallelVerdict`), plus an optional `git log` (only when the caller
+ * opts in via `use_cochange: true`).
+ *
+ * Why this tool exists alongside the gate: the gate (`delegation-gate.ts`)
+ * independently recomputes the verdict INLINE at coder-dispatch time via the
+ * same shared `computeParallelVerdict` helper. The tool gives the architect a
+ * way to inspect the conflict matrix BEFORE attempting parallel dispatch, so it
+ * can choose disjoint task groups and understand why the gate will (or won't)
+ * permit parallelism. Single source of truth (the helper), two call sites.
+ */
+import type { tool } from '@opencode-ai/plugin';
+import { z } from 'zod';
+export declare const plan_conflict_check_args: {
+    task_ids: z.ZodArray<z.ZodString>;
+    use_cochange: z.ZodOptional<z.ZodBoolean>;
+    phase_id: z.ZodOptional<z.ZodString>;
+};
+export interface PlanConflictCheckResult {
+    /** Summary verdict. `all_disjoint` ⇒ safe to parallelize. */
+    verdict: 'all_disjoint' | 'conflicts_present' | 'unknown_scopes';
+    /** Pairwise results. */
+    pairs: Array<{
+        a: string;
+        b: string;
+        verdict: 'conflict' | 'disjoint' | 'unknown';
+        evidence: string[];
+    }>;
+    /** Suggested serialization order (topological sort over the conflict graph). */
+    suggested_serial_order: string[];
+    /** Tasks whose declared scope could not be resolved. */
+    unknown_scope_tasks: string[];
+    /** Whether co-change signal was used. */
+    used_cochange: boolean;
+    /** Diagnostic: did plan.json load successfully? */
+    plan_loaded: boolean;
+    /** Task ids requested by the caller but absent from the loaded plan. */
+    unknown_to_plan?: string[];
+}
+/**
+ * Pure executor (no createSwarmTool wrapper) so it is directly unit-testable.
+ *
+ * Reads `.swarm/plan.json` (to confirm the task ids exist) and
+ * `.swarm/scopes/scope-*.json` (via `computeParallelVerdict`). Writes nothing.
+ */
+export declare function executePlanConflictCheck(args: {
+    task_ids: string[];
+    use_cochange?: boolean;
+    phase_id?: string;
+}, directory: string): Promise<PlanConflictCheckResult>;
+export declare const plan_conflict_check: ReturnType<typeof tool>;

package/dist/tools/tool-metadata.d.ts

@@ -196,6 +196,10 @@ export declare const TOOL_METADATA: {
         description: string;
         agents: "architect"[];
     };
+    plan_conflict_check: {
+        description: string;
+        agents: "architect"[];
+    };
     write_pr_review_trigger_eval: {
         description: string;
         agents: "architect"[];
@@ -320,6 +324,10 @@ export declare const TOOL_METADATA: {
         description: string;
         agents: "architect"[];
     };
+    consensus_mine: {
+        description: string;
+        agents: ("architect" | "curator_phase" | "curator_postmortem")[];
+    };
     knowledge_add: {
         description: string;
         agents: ("coder" | "architect")[];

package/dist/turbo/lean/recovery.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Durable merge-back conflict recovery records (#1657).
+ *
+ * When a lean-turbo lane's merge-back fails (conflict / partial / error), the
+ * runner preserves the lane's worktree + branch for manual recovery but —
+ * before this module — that information lived only in:
+ *   - the in-memory `LeanTurboLane` state (lost when the session ends), and
+ *   - a scrolled-away log line.
+ *
+ * Problem #1: `cleanupOrphanedBranches` (`src/worktree/merge.ts`) force-deletes
+ * any lane branch whose session isn't active, including a branch just preserved
+ * for recovery. The only copy of unmerged lane work could be deleted by routine
+ * init-time cleanup before a human ever sees the recovery message.
+ *
+ * Problem #2: `/swarm status` had no concept of preserved worktrees, so the
+ * architect was blind to pending recovery work unless it re-read the tool
+ * result inline.
+ *
+ * This module writes a durable record under `.swarm/recovery/` on every
+ * merge-back failure, lets `cleanupOrphanedBranches` EXEMPT recovery branches
+ * (fail-safe on read error), and lets `/swarm status` surface them. Records are
+ * auto-cleared when the lane later merges back successfully (no accumulation).
+ *
+ * Records live ONLY under `.swarm/recovery/` (AGENTS.md invariant 4 — `.swarm/`
+ * containment). They are intentionally NOT part of the plan ledger or
+ * turbo-state: recovery is a side-channel safety net, not authoritative plan
+ * or run state.
+ */
+/**
+ * A durable merge-back recovery record. Mirrors `MergeBackFailureInfo` plus
+ * the session/bookkeeping fields needed for orphan-cleanup exemption and
+ * status surfacing.
+ */
+export interface RecoveryRecord {
+    /** Lane identifier (e.g. "lane-1"). */
+    laneId: string;
+    /** Session that created the record (for scoping/status). */
+    sessionId: string;
+    /** Lane branch preserved for recovery (e.g. "swarm-lane/<sid>/<laneId>"). */
+    branchName?: string;
+    /** Lane worktree filesystem path preserved for recovery. */
+    worktreePath: string;
+    /** Merge-back failure class. */
+    status: 'failed' | 'partial' | 'conflict';
+    /** Human-readable reason for the merge-back failure. */
+    reason: string;
+    /** Conflict files (when status === 'conflict'). */
+    conflictFiles?: string[];
+    /** Epoch ms when the record was written. */
+    recordedAt: number;
+    /** Portable human guidance for inspecting the preserved worktree. */
+    replayHint: string;
+}
+/**
+ * Write a recovery record atomically (temp file + rename, mirroring the
+ * `turbo-state.json` pattern in `src/turbo/lean/state.ts`). Best-effort:
+ * swallows errors so a recovery-write failure can never break the merge-back
+ * path that called it.
+ */
+export declare function writeRecoveryRecord(directory: string, record: Omit<RecoveryRecord, 'recordedAt'> & {
+    recordedAt?: number;
+}): void;
+/**
+ * List all recovery records under `.swarm/recovery/`. Tolerates malformed
+ * files (skips + continues). Returns `[]` if the directory is absent or
+ * unreadable.
+ */
+export declare function listRecoveryRecords(directory: string): RecoveryRecord[];
+/**
+ * Fast check: does any recovery record reference the given branch name?
+ * Used by `cleanupOrphanedBranches` to exempt recovery branches. Returns
+ * `false` on any read error (the caller decides fail-open vs fail-safe —
+ * see `cleanupOrphanedBranches`).
+ */
+export declare function hasRecoveryRecordForBranch(directory: string, branchName: string): boolean;
+/**
+ * Remove the recovery record for a specific lane + session. Called on
+ * SUCCESSFUL merge-back so records don't accumulate (a record exists only
+ * while a lane is in a failed/preserved state). Best-effort.
+ */
+export declare function clearRecoveryRecord(directory: string, laneId: string, sessionId: string): void;
+/**
+ * Did the recovery-directory read itself throw (vs simply being empty)?
+ * `cleanupOrphanedBranches` uses this to decide fail-safe behavior: on a
+ * genuine read error it skips ALL lane-branch deletions for that pass
+ * (recovery safety trumps orphan cleanliness). Returns `true` if the
+ * directory exists but could not be read, OR if any record file exists but
+ * is unreadable.
+ */
+export declare function recoveryReadErrored(directory: string): boolean;

package/dist/turbo/lean/runner.d.ts

@@ -25,7 +25,7 @@ import { type ModelOverride } from '../../utils/model-dispatch-fallback';
 import { writeLaneEvidence, writePhaseEvidence } from './evidence';
 import { attemptMergeBackFromDirty, getMergeStrategy, mergeLaneBranch, postMergeCleanup, startupOrphanRecovery } from './merge-back';
 import { planLeanTurboLanes } from './planner';
-import type { LeanTurboLane } from './state';
+import type { LeanTurboDegradedTask, LeanTurboLane } from './state';
 import { loadLeanTurboRunState, saveLeanTurboRunState } from './state';
 import { assertCleanWorkingTree, provisionWorktree, removeLaneProfileFromDiskReal, removeWorktree } from './worktree';
 /**
@@ -152,6 +152,12 @@ export interface LeanTurboPhaseResult {
     lanes: LaneResult[];
     /** Task IDs that were degraded (risk conditions) */
     degradedTasks: string[];
+    /**
+     * #1657: full degraded-task details (reason/files/requiredMode) so the
+     * architect sees per-task degradation reasons in the tool result, not
+     * just task IDs. Additive alongside `degradedTasks` (kept for back-compat).
+     */
+    degradedDetails?: LeanTurboDegradedTask[];
     /**
      * Task IDs excluded from parallel lanes due to lock conflicts.
      * Caller must complete these via standard serial flow before phase can advance.
@@ -323,6 +329,15 @@ export declare class LeanTurboRunner {
      * the serialized tasks set for standard serial fallback.
      */
     private _processLane;
+    /**
+     * Persist a durable recovery record for a merge-back / dispatch failure (#1657).
+     *
+     * Wraps `writeRecoveryRecord` (best-effort, non-fatal) with this session's
+     * id and portable human recovery guidance. Called from every failure branch of
+     * `_sequentialWorktreeCleanup`. Records are auto-cleared on successful
+     * merge-back so they exist only while a lane is preserved.
+     */
+    private _persistRecovery;
     /**
      * Sequential worktree cleanup for completed and failed worktree lanes.
      *

package/dist/worktree/merge.d.ts

@@ -86,6 +86,11 @@ export interface OrphanCleanupResult {
         branch: string;
         error: string;
     }>;
+    /** #1657: lane branches skipped because a recovery record references them. */
+    skippedRecoveryBranches: string[];
+    /** #1657: set when the recovery-directory read errored and ALL lane-branch
+     * deletions were skipped this pass (fail-safe). */
+    recoveryReadError?: boolean;
 }
 export interface StartupRecoveryResult {
     prunedWorktrees: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.130.2",
+	"version": "7.132.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/dist/parallel/dependency-graph.d.ts

@@ -1,34 +0,0 @@
-export interface TaskNode {
-    id: string;
-    phase: number;
-    description: string;
-    depends: string[];
-    dependents: string[];
-    status: 'pending' | 'in_progress' | 'complete' | 'blocked';
-}
-export interface DependencyGraph {
-    tasks: Map<string, TaskNode>;
-    phases: Map<number, string[]>;
-    roots: string[];
-    leaves: string[];
-}
-/**
- * Parse plan.json and build dependency graph
- */
-export declare function parseDependencyGraph(planPath: string): DependencyGraph;
-/**
- * Get tasks that can run in parallel (no unresolved dependencies)
- */
-export declare function getRunnableTasks(graph: DependencyGraph): string[];
-/**
- * Check if a task is blocked (has incomplete dependencies)
- */
-export declare function isTaskBlocked(graph: DependencyGraph, taskId: string): boolean;
-/**
- * Get execution order (topological sort)
- */
-export declare function getExecutionOrder(graph: DependencyGraph): string[];
-/**
- * Find all paths from root to a task
- */
-export declare function getDependencyChain(graph: DependencyGraph, taskId: string): string[];