opencode-swarm 7.130.2 → 7.132.0

package/dist/learning/provenance.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Learning provenance records (issue #1821, Lane 0a).
+ *
+ * Every durable learning write — a curator sweep decision, a micro-reflection,
+ * a PRM pattern, a consensus-mined lesson, a skill-improver edit — must be able
+ * to say *where it came from*. `LearningProvenanceV1` is the shared envelope:
+ * which mechanism produced it, which knowledge/task/evidence/run/model ids fed
+ * it, and which session/agent physically wrote it.
+ *
+ * Every reference class is deduplicated, sorted, and hard-capped at
+ * `MAX_REFS_PER_CLASS` so a long-running session cannot grow a provenance record
+ * without bound (AGENTS.md invariant 8 — global/persisted state must be
+ * bounded).
+ *
+ * This module is pure: no filesystem, no network, no module-level mutable state.
+ * The only ambient input is the wall clock, and only when the caller does not
+ * supply `producedAt` — callers that need determinism pass it explicitly.
+ */
+import { z } from 'zod';
+/**
+ * Hard cap on entries retained per reference class. Sorting happens before the
+ * cap so truncation is deterministic rather than insertion-order dependent.
+ */
+export declare const MAX_REFS_PER_CLASS = 50;
+/** The learning mechanism that produced a record. */
+export type LearningMechanism = 'curator_sweep' | 'micro_reflection' | 'prm_pattern' | 'consensus_mine' | 'skill_improver';
+export declare const LearningProvenanceV1Schema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    mechanism: z.ZodEnum<{
+        skill_improver: "skill_improver";
+        consensus_mine: "consensus_mine";
+        curator_sweep: "curator_sweep";
+        micro_reflection: "micro_reflection";
+        prm_pattern: "prm_pattern";
+    }>;
+    sourceKnowledgeIds: z.ZodArray<z.ZodString>;
+    sourceTaskIds: z.ZodArray<z.ZodString>;
+    sourceEvidenceRefs: z.ZodArray<z.ZodString>;
+    sourceRunIds: z.ZodArray<z.ZodString>;
+    sourceModelIds: z.ZodArray<z.ZodString>;
+    writeOrigin: z.ZodObject<{
+        sessionId: z.ZodOptional<z.ZodString>;
+        agentRole: z.ZodOptional<z.ZodString>;
+        producedAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export interface LearningProvenanceV1 {
+    v: 1;
+    mechanism: LearningMechanism;
+    sourceKnowledgeIds: string[];
+    sourceTaskIds: string[];
+    sourceEvidenceRefs: string[];
+    sourceRunIds: string[];
+    sourceModelIds: string[];
+    /** See `LearningWriteOriginSchema` for why there is no `agentId` here. */
+    writeOrigin: {
+        sessionId?: string;
+        agentRole?: string;
+        producedAt: string;
+    };
+}
+/** Caller-supplied provenance body. Every reference class is optional. */
+export interface LearningProvenanceInput {
+    mechanism: LearningMechanism;
+    sourceKnowledgeIds?: string[];
+    sourceTaskIds?: string[];
+    sourceEvidenceRefs?: string[];
+    sourceRunIds?: string[];
+    sourceModelIds?: string[];
+}
+/** Caller-supplied write origin. `producedAt` defaults to now when omitted. */
+export interface LearningWriteOriginInput {
+    sessionId?: string;
+    agentRole?: string;
+    producedAt?: string;
+}
+/**
+ * Build a validated `LearningProvenanceV1` from a partial body and a write
+ * origin. Fills `v`, missing reference classes, and `producedAt`; deduplicates,
+ * sorts, and caps every reference class; then parses through
+ * `LearningProvenanceV1Schema` so the returned value is guaranteed valid.
+ *
+ * Throws (via Zod) on an unknown mechanism or an unparseable `producedAt` —
+ * a malformed provenance record must never be persisted silently.
+ */
+export declare function stampLearningProvenance(partial: LearningProvenanceInput, origin?: LearningWriteOriginInput): LearningProvenanceV1;

package/dist/parallel/index.d.ts

@@ -1,5 +1,3 @@
 export { EvidenceLockTimeoutError, withEvidenceLock, } from '../evidence/lock.js';
-export { type DependencyGraph, getDependencyChain, getExecutionOrder, getRunnableTasks, isTaskBlocked, parseDependencyGraph, type TaskNode, } from './dependency-graph.js';
 export { cleanupExpiredLocks, type FileLock, isLocked, listActiveLocks, releaseLock, tryAcquireLock, } from './file-locks.js';
-export { extractMetaSummaries, getLatestTaskSummary, indexMetaSummaries, type MetaSummaryEntry, querySummaries, } from './meta-indexer.js';
 export { type ComplexityMetrics, computeComplexity, type ReviewDepth, type ReviewRouting, routeReview, routeReviewForChanges, shouldParallelizeReview, } from './review-router.js';

package/dist/plan/parallel-verdict.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Plan-time parallel-execution verdict helper (#1656 / #1674 v8 flagship).
+ *
+ * Pure, synchronous, side-effect-free pairwise conflict analysis for N proposed
+ * parallel task groups. Used by BOTH:
+ *   - the `plan_conflict_check` tool (architect-facing advisory — see
+ *     `src/tools/plan-conflict-check.ts`), and
+ *   - the delegation gate (`src/hooks/delegation-gate.ts`) which recomputes the
+ *     verdict INLINE at coder-dispatch time to enforce the v8 "serial fallback
+ *     when scopes overlap or are unknown" contract (acceptance criterion 4).
+ *
+ * Single source of truth: one helper, two call sites, so the architect's
+ * advisory and the gate's enforcement can never disagree on what "disjoint"
+ * means.
+ *
+ * Design notes:
+ *  - Sync by design: it reads only `.swarm/scopes/scope-<taskId>.json` via
+ *    the hardened persisted-scope reader (sync + fail-closed). The gate runs in
+ *    `toolBefore` on every tool call and must stay bounded; an async/gitten
+ *    helper would violate the bounded-gate spirit.
+ *  - The helper itself NEVER calls `getCoChangePairs` (async + `git log`).
+ *    Co-change signal is opt-in and supplied by the caller (the tool) via
+ *    `options.cochangePairs`. The gate never supplies it, keeping the
+ *    enforcement path git-free and fast.
+ *  - Fail-closed: a missing/malformed scope → `unknown_scope`, which conflicts
+ *    with everything, so `verdict` can never be `all_disjoint` while any task
+ *    lacks a declared scope. This is the v8 safety guarantee.
+ *  - Writes nothing. Honors issue #1656's "read-only (writes nothing)" tool
+ *    acceptance criterion.
+ */
+import type { CoChangeEntry } from '../tools/co-change-analyzer.js';
+import { type CoChangeThreshold } from '../turbo/epic/cochange-conflict.js';
+import { normalizePath, pathsConflict, readTaskScopes } from '../turbo/lean/conflicts.js';
+/**
+ * Per-pair conflict classification. Mirrors `EpicPairVerdict`'s signal
+ * decomposition but flattens `none` into `disjoint` for the plan-level view.
+ */
+export interface ParallelVerdictPair {
+    /** First task id (input order). */
+    a: string;
+    /** Second task id (input order). */
+    b: string;
+    /** `conflict` = path or co-change overlap; `disjoint` = provably no overlap; `unknown` = ≥1 task has no usable scope. */
+    verdict: 'conflict' | 'disjoint' | 'unknown';
+    /** Human-readable evidence lines (path pairs, co-change pairs). Empty for `disjoint`/`unknown`. */
+    evidence: string[];
+}
+/**
+ * Whole-plan verdict. The gate keys off `verdict === 'all_disjoint'` to allow
+ * parallel execution; anything else forces serial.
+ */
+export interface ParallelVerdict {
+    /** `all_disjoint` iff every pair is `disjoint` (no conflicts, no unknowns). */
+    verdict: 'all_disjoint' | 'conflicts_present' | 'unknown_scopes';
+    /** Pairwise results, one per input task pair (i < j). */
+    pairs: ParallelVerdictPair[];
+    /** Suggested serialization order (topological sort over the conflict graph). Input order preserved when no conflicts. */
+    suggestedSerialOrder: string[];
+    /** Task ids whose scope could not be resolved (missing/malformed). */
+    unknownScopeTasks: string[];
+}
+/** Default co-change threshold when the caller opts into co-change but omits one. */
+export declare const DEFAULT_PARALLEL_COCHANGE_THRESHOLD: CoChangeThreshold;
+/** Hard cap for the synchronous O(N²) verdict path (F-005). */
+export declare const MAX_PARALLEL_VERDICT_TASKS = 64;
+export interface ComputeParallelVerdictOptions {
+    /** When true AND `cochangePairs` is supplied, fold co-change signal into each pair. Off by default. */
+    useCochange?: boolean;
+    /** Caller-supplied co-change data (e.g. from `getCoChangePairs`). The helper never fetches it. */
+    cochangePairs?: CoChangeEntry[];
+    /** Override the co-change threshold. Defaults to `DEFAULT_PARALLEL_COCHANGE_THRESHOLD`. */
+    cochangeThreshold?: CoChangeThreshold;
+}
+/**
+ * Compute a pairwise conflict verdict for the given task ids.
+ *
+ * Pure + synchronous. Reads only `.swarm/scopes/`. Writes nothing. Fail-closed
+ * on any read/parse error (treats the task as `unknown`).
+ *
+ * @param directory  Project root (for `.swarm/scopes/` reads).
+ * @param taskIds    Task ids to analyze. Caller is responsible for min-length
+ *                   validation (the tool requires ≥2; the gate only calls this
+ *                   with ≥2 pending tasks).
+ * @param options    Optional co-change signal + threshold.
+ */
+export declare function computeParallelVerdict(directory: string, taskIds: string[], options?: ComputeParallelVerdictOptions): ParallelVerdict;
+/**
+ * Quick pairwise check used by the gate: are these task ids provably disjoint?
+ *
+ * Equivalent to `computeParallelVerdict(...).verdict === 'all_disjoint'` but
+ * exposed as a named predicate so the gate reads as intent.
+ */
+export declare function isProvablyDisjoint(directory: string, taskIds: string[]): boolean;
+export { normalizePath, pathsConflict, readTaskScopes };

package/dist/prm/index.d.ts

@@ -16,6 +16,10 @@ export { formatCourseCorrectionForInjection, generateCourseCorrection, } from '.
 export { createDefaultEscalationState, EscalationTracker } from './escalation';
 export { detectContextThrash, detectExpansionDrift, detectPatterns, detectPingPong, detectRepetitionLoop, detectStuckOnTest, } from './pattern-detector';
 export type { CourseCorrection, EscalationState, PatternDetectionResult, PatternMatch, PatternSeverity, PatternType, PrmConfig, TaxonomyCategory, TrajectoryEntry, } from './types';
+import type { LearningConfig } from '../config/schema.js';
+import { appendInsightCandidates } from '../hooks/micro-reflector.js';
+import { enqueueCandidate } from '../learning/candidate-queue.js';
+import { recordPatternObservation } from '../learning/prm-pattern-support.js';
 import { getAgentSession } from '../state';
 import { telemetry } from '../telemetry';
 import { formatCourseCorrectionForInjection, generateCourseCorrection } from './course-correction';
@@ -44,6 +48,9 @@ export declare const _internals: {
     recordReplayEntry: typeof recordReplayEntry;
     startReplayRecording: typeof startReplayRecording;
     telemetry: typeof telemetry;
+    recordPatternObservation: typeof recordPatternObservation;
+    enqueueCandidate: typeof enqueueCandidate;
+    appendInsightCandidates: typeof appendInsightCandidates;
 };
 /**
  * Context passed to toolAfter handler
@@ -94,4 +101,42 @@ export declare function resetPrmSessionState(session: ResettablePrmSessionState,
  * // Wire prmHook.toolAfter into your tool.execute.after hook
  * ```
  */
-export declare function createPrmHook(config: PrmConfig, directory: string): PrmHook;
+/**
+ * Knobs the PRM hook needs to hand supported patterns to the real-time
+ * admission queue (issue #1821, AC10). Optional so existing callers and tests
+ * keep working unchanged; when absent, pattern persistence is simply off.
+ */
+export interface PrmPatternPersistenceOptions {
+    /**
+     * `learning.prm_persistence.enabled`. Governs the WHOLE producer, durable
+     * append included.
+     */
+    enabled: boolean;
+    min_support: number;
+    cooldown_ms: number;
+    /**
+     * `learning.realtime_admission.enabled`. Governs ONLY the in-memory enqueue.
+     *
+     * It must never gate the durable append (issue #1821 F3): AC8 says disabled
+     * or crashed real-time work loses nothing, and the phase-boundary backstop
+     * can only see candidates that reached `.swarm/insight-candidates.jsonl`.
+     * ANDing the two flags at the call site made `realtime_admission.enabled=false`
+     * silently discard every PRM candidate. Mirrors `micro-reflector.ts`, which
+     * appends unconditionally and gates only its enqueue.
+     */
+    admission_enabled: boolean;
+    /** `learning.realtime_admission.max_queue_size` — bounds the shared queue. */
+    max_queue_size: number;
+}
+/**
+ * Map a parsed `learning` config onto the PRM producer's knobs (issue #1821 F3).
+ *
+ * The mapping lives here, beside the interface that documents which flag governs
+ * what, and `src/index.ts` is its only production caller — so the AC8 coupling
+ * ("durable persistence is gated by `prm_persistence.enabled` ALONE") is
+ * expressed once and can be asserted directly by a test instead of being
+ * re-derived from an object literal at the plugin's wiring site, where the two
+ * flags were previously ANDed together.
+ */
+export declare function resolvePrmPatternPersistenceOptions(learning: LearningConfig): PrmPatternPersistenceOptions;
+export declare function createPrmHook(config: PrmConfig, directory: string, patternPersistence?: PrmPatternPersistenceOptions): PrmHook;

package/dist/services/recommendation-ledger.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Cross-producer recommendation dedup ledger (issue #1821, AC21).
+ *
+ * Three mechanisms propose learning recommendations: the curator sweep
+ * (`src/hooks/curator.ts`), the skill improver's macro-reflector
+ * (`src/services/trajectory-cluster.ts`), and the consensus miner
+ * (`src/consensus/miner.ts`). `src/learning/fingerprint.ts` gave them a shared
+ * identity function, but a fingerprint alone dedups nothing: somebody has to
+ * remember what was already emitted. This module is that memory.
+ *
+ * ## Why a second key
+ *
+ * `computeRecommendationFingerprint` deliberately folds `kind` into the digest —
+ * its own doc says "dedup across mechanisms is a policy decision made by the
+ * caller, not baked into the identity". This module *is* that caller, and the
+ * policy it implements is: **two recommendations are the same recommendation
+ * when they say the same thing about the same scope, regardless of which
+ * mechanism noticed it first.** So every ledger entry carries two ids:
+ *
+ * - `fingerprint` — the producer-scoped `lrec_…` id, kept verbatim for audit.
+ * - `crossKey` — an `lxk_…` id over `{ normalizedStatement, sortedScopeKeys }`.
+ *
+ * `crossKey` drops both `kind` and `target`. Dropping `kind` is the whole point.
+ * Dropping `target` is a redundancy call, not a necessity: each producer already
+ * interpolates its target into the statement it emits (the miner's `intent`
+ * names its `proposedTarget`; the improver's statement names the tool and
+ * failure kind its slug is built from; the curator's `entry_id` travels in
+ * `scopeKeys`), so keeping `target` would add no discriminating power while
+ * splitting identity on producer-local vocabulary.
+ *
+ * Disambiguation that genuinely must survive therefore travels in `scopeKeys`,
+ * which is order- and duplicate-insensitive (`normalizeScopeKeys`). The curator
+ * uses that to keep `archive entry-X` and `rewrite entry-X` distinct even when
+ * both carry the same lesson text; recommendations that mint *new* knowledge
+ * carry no scope keys, because content alone is their identity.
+ *
+ * ## What this does and does not achieve today
+ *
+ * The key is an EXACT hash of normalized text. Two producers dedup against each
+ * other only when they emit the same sentence. In the current codebase the
+ * improver and the miner build their statements from fixed templates
+ * (`Avoid the recurring … failure in …`, `Investigate the smallest … change …`)
+ * while the curator's statement is a free-form LLM lesson, so a cross-producer
+ * collision is possible but uncommon. The concrete, everyday win is therefore:
+ * (a) WITHIN-producer dedup, which the curator and the improver had none of, and
+ * (b) one shared, provenance-stamped record of every emitted recommendation that
+ * any producer can consult. Making cross-producer suppression routine would need
+ * near-duplicate matching (see `findNearDuplicate` / the knowledge dedup sweep)
+ * rather than an exact fingerprint, which is a different mechanism than the one
+ * `src/learning/fingerprint.ts` defines.
+ *
+ * ## Check, emit, then record — never "reserve"
+ *
+ * The two phases are deliberately separate:
+ *
+ * - `checkRecommendations` is read-only. It answers "has this been emitted
+ *   before?" and writes nothing.
+ * - `recordEmittedRecommendations` is the locked write, and callers run it only
+ *   for recommendations that **actually took effect**.
+ *
+ * An earlier design claimed the key up-front, before the caller emitted. That is
+ * wrong here: the curator legitimately *defers* recommendations (cohort-safe
+ * authorization not yet granted, target entry temporarily inactive, CAS revision
+ * drift, fair-scan generation already curated, actionability quarantine pending
+ * the hardening loop). Every one of those paths expects a later sweep to retry,
+ * and a key claimed before the emit would suppress that retry permanently.
+ * Recording after the fact costs a small race — two producers can both pass
+ * `check` and both emit — whose worst case is one duplicate, exactly the
+ * pre-#1821 behaviour. A burned key, by contrast, loses a lesson forever. The
+ * record step re-checks under the lock, so the ledger itself never grows a
+ * duplicate.
+ *
+ * ## Boundedness and containment
+ *
+ * The ledger is a JSONL file at `.swarm/learning/recommendation-ledger.jsonl`,
+ * hard-capped at `MAX_RECOMMENDATION_LEDGER_ENTRIES` entries with oldest-first
+ * FIFO eviction, and every entry is capped at `MAX_ENTRY_BYTES` (provenance is
+ * dropped rather than allowed to blow the bound), so the file has a hard ceiling
+ * of roughly 2 MB (AGENTS.md invariant 8). It never touches `process.cwd()`
+ * (invariant 4). Its own subdirectory is deliberate: `transactFile` locks the
+ * *containing directory*, so living under `learning/` keeps this lock disjoint
+ * from the `.swarm/` root lock that `transactKnowledge` takes.
+ *
+ * The root is `resolveKnowledgeStoreDir`, NOT a hardcoded `<directory>/.swarm`.
+ * That is the same link-aware resolution `resolveSwarmKnowledgePath` uses, so in
+ * a linked cohort the ledger lives beside the knowledge store it guards instead
+ * of being stranded per-worktree — a lane worktree would otherwise discard its
+ * ledger while the lessons it recorded persisted in the shared store.
+ *
+ * Eviction means a recommendation older than the last 500 emissions can surface
+ * again. That is the intended trade: bounded state beats perfect recall. Note
+ * this cap is independent of `knowledge.swarm_max_entries` (default 100): a
+ * lesson the knowledge store has already FIFO-evicted can still be suppressed
+ * here until its own entry ages out.
+ *
+ * ## Fail-open
+ *
+ * Every failure mode — unreadable ledger, lock timeout, corrupt lines, a
+ * provenance record the schema rejects — resolves to "emit everything", i.e.
+ * exactly the behaviour that existed before this module. A broken dedup ledger
+ * must never silence the learning loops.
+ */
+import { transactFile } from '../hooks/knowledge-store.js';
+import { type RecommendationKind } from '../learning/fingerprint.js';
+import { type LearningProvenanceInput, type LearningProvenanceV1, type LearningWriteOriginInput } from '../learning/provenance.js';
+/**
+ * Hard cap on retained ledger entries (AGENTS.md invariant 8). Sized to match
+ * `INSIGHT_CANDIDATES_MAX_ENTRIES` in `src/hooks/micro-reflector.ts`, the
+ * closest sibling queue: the same order of magnitude of learning artifacts flows
+ * through both, and one shared number is easier to reason about than two.
+ */
+export declare const MAX_RECOMMENDATION_LEDGER_ENTRIES = 500;
+/**
+ * Hard cap on one serialized entry. Provenance reference lists are individually
+ * bounded by `stampLearningProvenance`, but 5 classes x 50 refs x 512 chars is
+ * still ~128 KB, which would put the file's ceiling in the tens of megabytes.
+ * An entry over this budget keeps its identity fields and drops provenance —
+ * dedup is the contract, provenance is the bonus.
+ */
+export declare const MAX_ENTRY_BYTES = 4096;
+/** A recommendation a producer is about to emit, or has just emitted. */
+export interface RecommendationCandidate {
+    /** Producing mechanism. Recorded on the entry; excluded from `crossKey`. */
+    kind: RecommendationKind;
+    /** Producer-local target (knowledge id, proposal slug, subsystem name). */
+    target: string;
+    /** The recommendation body. Normalized before hashing. */
+    statement: string;
+    /** Scope disambiguators. Order- and duplicate-insensitive. */
+    scopeKeys?: string[];
+    /** Learning provenance stamped onto the ledger entry when recorded. */
+    provenance?: LearningProvenanceInput;
+    /** Write origin for the provenance stamp. */
+    origin?: LearningWriteOriginInput;
+}
+/** The two ids a candidate resolves to. */
+export interface RecommendationIdentity {
+    /** Producer-scoped `lrec_…` id from `src/learning/fingerprint.ts`. */
+    fingerprint: string;
+    /** Kind- and target-independent `lxk_…` id used for dedup. */
+    crossKey: string;
+}
+/** One durable record of an emitted recommendation. */
+export interface RecommendationLedgerEntry extends RecommendationIdentity {
+    v: 1;
+    kind: RecommendationKind;
+    target: string;
+    /** ISO-8601 timestamp of the record call that appended this entry. */
+    emittedAt: string;
+    provenance?: LearningProvenanceV1;
+}
+/**
+ * Why a candidate was not accepted for emission.
+ *
+ * Module-private: consumers reach this set through
+ * `RecommendationDecision['suppressedBy']`, which is exported and narrows to the
+ * same two literals. Exporting the alias as well gave it a name no importer ever
+ * used.
+ */
+type RecommendationSuppressionSource = 'ledger' | 'batch';
+/** Per-candidate outcome, in input order. */
+export interface RecommendationDecision extends RecommendationIdentity {
+    /** Index into the candidate array this decision belongs to. */
+    index: number;
+    /** True when the caller should emit this recommendation. */
+    emit: boolean;
+    /**
+     * `'ledger'` — a previous emission (possibly by another producer) already
+     * claimed this `crossKey`. `'batch'` — an earlier candidate in this same call
+     * claimed it. Absent when `emit` is true.
+     */
+    suppressedBy?: RecommendationSuppressionSource;
+}
+export interface CheckRecommendationsResult {
+    decisions: RecommendationDecision[];
+    /** Count of `emit === true` decisions. */
+    accepted: number;
+    /** Count of `emit === false` decisions. */
+    suppressed: number;
+    /**
+     * True when the ledger could not be read and every candidate was accepted by
+     * fail-open default rather than by an actual dedup check.
+     */
+    degraded: boolean;
+}
+export interface RecordRecommendationsResult {
+    /** Entries actually appended. */
+    recorded: number;
+    /** Candidates skipped because the ledger already carried their cross key. */
+    suppressed: number;
+    /** Entries dropped by the FIFO cap during this record. */
+    evicted: number;
+    /** True when the ledger could not be written. */
+    degraded: boolean;
+}
+/**
+ * Absolute path of the ledger, link-aware.
+ *
+ * Byte-identical to `<directory>/.swarm/learning/recommendation-ledger.jsonl`
+ * for an unlinked worktree; redirects to the shared cohort store when
+ * `.swarm/link.json` is active, exactly as `resolveSwarmKnowledgePath` does for
+ * the knowledge file this ledger shadows.
+ */
+export declare function resolveRecommendationLedgerPath(directory: string): string;
+/** Shape check for a value that claims to be a cross-producer key. */
+export declare function isRecommendationCrossKey(value: string): boolean;
+/**
+ * Compute the kind- and target-independent dedup key.
+ *
+ * Built from the same normalizers the `lrec_` fingerprint uses, so whitespace
+ * runs, surrounding space, letter case, trailing sentence punctuation, scope-key
+ * order, and scope-key duplicates all collapse to one identity.
+ */
+export declare function computeCrossProducerKey(input: {
+    statement: string;
+    scopeKeys?: string[];
+}): string;
+/** Compute both ids for a candidate. Pure. */
+export declare function computeRecommendationIdentity(candidate: RecommendationCandidate): RecommendationIdentity;
+/**
+ * Read every retained ledger entry, propagating a real read failure.
+ *
+ * A missing ledger is the first-run case and yields `[]`; anything else throws
+ * so `checkRecommendations` can report `degraded` truthfully instead of treating
+ * an unreadable ledger as an empty one and silently claiming it deduped.
+ */
+declare function readLedgerStrict(directory: string): Promise<RecommendationLedgerEntry[]>;
+/**
+ * Read every retained ledger entry. Fail-open: returns `[]` when the ledger is
+ * absent or unreadable. This is the inspection entry point — the dedup decision
+ * itself goes through `readLedgerStrict` so a failure is visible rather than
+ * disguised as an empty ledger.
+ */
+export declare function readRecommendationLedger(directory: string): Promise<RecommendationLedgerEntry[]>;
+/**
+ * Answer "has this been emitted before?" without writing anything.
+ *
+ * Suppression is decided against the ledger's existing cross keys plus the keys
+ * claimed by earlier candidates in this same batch. Fail-open: an unreadable
+ * ledger yields `degraded: true` and accepts everything.
+ */
+export declare function checkRecommendations(directory: string, candidates: readonly RecommendationCandidate[]): Promise<CheckRecommendationsResult>;
+/**
+ * Append the recommendations a producer actually emitted.
+ *
+ * Runs one locked read-modify-write and re-checks every cross key under that
+ * lock, so a candidate another producer recorded between `checkRecommendations`
+ * and here is counted as `suppressed` rather than duplicated into the ledger.
+ * Candidates whose statement normalizes to nothing are never recorded.
+ */
+export declare function recordEmittedRecommendations(directory: string, candidates: readonly RecommendationCandidate[], options?: {
+    producedAt?: string;
+}): Promise<RecordRecommendationsResult>;
+/**
+ * DI seam (AGENTS.md invariant 7). `now` lets tests pin `emittedAt`;
+ * `transactFile`, `readRecommendationLedger`, and
+ * `resolveRecommendationLedgerPath` let them exercise the fail-open paths
+ * without `mock.module`. Restore each entry in `afterEach`.
+ */
+export declare const _internals: {
+    now: () => Date;
+    transactFile: typeof transactFile;
+    readLedgerStrict: typeof readLedgerStrict;
+    resolveRecommendationLedgerPath: typeof resolveRecommendationLedgerPath;
+};
+export {};

package/dist/services/skill-improver.d.ts

@@ -83,11 +83,15 @@ export interface SkillImproveResult {
     macroMotifs?: {
         motifs: number;
         proposalsWritten: number;
+        /** #1821 AC21: motifs suppressed by the cross-producer dedup ledger. */
+        duplicatesSuppressed?: number;
     };
     /** #1234 Part 4: success workflow-motif proposals written this run. */
     successMotifs?: {
         motifs: number;
         proposalsWritten: number;
+        /** #1821 AC21: motifs suppressed by the cross-producer dedup ledger. */
+        duplicatesSuppressed?: number;
     };
     /** Issue #1477: self-healing reconciliation of stale active generated skills
      *  (regenerate-or-retire). In proposal-only runs this is a dry run (the

package/dist/services/status-service.d.ts

@@ -40,6 +40,20 @@ export interface StatusData {
     leanDegradedTasks?: number;
     /** Human-readable degradation summary */
     leanDegradationSummary?: string;
+    /**
+     * #1657: merge-back conflict recovery worktrees preserved for manual
+     * recovery (durable records under `.swarm/recovery/`). Surfaced so the
+     * architect/operator can see pending recovery work in `/swarm status`
+     * rather than having to re-read a prior tool result. `undefined`/empty when
+     * no lanes are preserved.
+     */
+    leanPreservedRecoveryWorktrees?: Array<{
+        laneId: string;
+        status: string;
+        worktreePath: string;
+        reason: string;
+        replayHint: string;
+    }>;
     /** Whether Full-Auto mode is currently active */
     fullAutoActive?: boolean;
     /**
@@ -78,6 +92,19 @@ export interface StatusData {
     unactionableQueueDepth?: number;
     /** #1234 Part 3: pending insight candidates awaiting phase boundary consumption */
     insightCandidatesPending?: number;
+    /**
+     * #1821 AC22: consensus report FILES stored under
+     * `.swarm/evolution/consensus/`.
+     *
+     * The reader half of the consensus store. Without it the miner's reports were
+     * a write-only directory — nothing in the product enumerated them, so a user
+     * had no way to learn they existed. A file count, deliberately: it is one
+     * `readdir` with no JSON parse and no integrity recomputation, so it costs the
+     * same whether the store holds one report or fifty. It therefore includes any
+     * corrupt report, because what it counts is files whose name is a well-formed
+     * report id.
+     */
+    consensusReports?: number;
     /**
      * Cohort/link status (issue #1846). Makes the linked knowledge store and its
      * health obvious in `/swarm status`. `undefined` when link state is absent.