opencode-swarm 7.86.0 → 7.87.0

package/dist/turbo/epic/calibration-engine.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Calibration engine for Epic Mode Capability D.
+ *
+ * `applyCalibration(state, newRecords, options) → newState` is a pure
+ * function that walks fresh divergence records (those not yet processed)
+ * and produces an updated calibration state. The wiring code is responsible
+ * for: (a) reading the prior state, (b) filtering history to the
+ * unprocessed tail, (c) writing the new state.
+ *
+ * Hard design rules (brief §4.5-D + the user's ratified §20.3 defaults):
+ *
+ *   1. **Auto-tighten only on threshold.** A divergent task tightens
+ *      `activationThresholdOverride` toward zero by `tightenStep`,
+ *      bounded by `floorThreshold` (we never tighten below the floor —
+ *      a value too small makes Epic Mode never promote anything).
+ *
+ *   2. **Hot-module list monotonically grows.** Files in a divergent
+ *      task's `undeclared` set are added to `hotModuleAdditions`. The
+ *      list is NEVER auto-shrunk; loosening a hot-module promotion
+ *      requires manual intervention. This is a one-way ratchet.
+ *
+ *   3. **Loosen only after `loosenWindow` consecutive clean tasks.**
+ *      Every clean (divergenceRatio === 0) task increments
+ *      `consecutiveCleanCount`; every divergent task resets it to zero.
+ *      When the counter reaches `loosenWindow`, the threshold is loosened
+ *      by `loosenStep` toward the static config value (never past it) and
+ *      the counter resets to zero. The hot-module list is NOT shrunk by
+ *      loosening — only the threshold relaxes.
+ *
+ *   4. **No oscillation.** A clean-then-divergent-then-clean sequence
+ *      cannot swing the threshold back and forth: every divergent task
+ *      resets the clean-counter and tightens by `tightenStep`, so the
+ *      threshold only moves toward zero in the divergent direction and
+ *      toward the static value (with the clean-window gate) in the
+ *      clean direction. Tests assert this invariant.
+ */
+import type { CalibrationState } from './calibration.js';
+import type { DivergenceRecord } from './divergence-recorder.js';
+export interface ApplyCalibrationOptions {
+    /** Static config value — the absolute ceiling for the threshold. */
+    staticThreshold: number;
+    /**
+     * Floor for the threshold — calibration never tightens past this.
+     * Default 0.05 — below that, Epic Mode effectively never promotes
+     * even on highly-decoupled plans.
+     */
+    floorThreshold?: number;
+    /** Per-divergent-task tightening step. Default 0.02. */
+    tightenStep?: number;
+    /** Per-loosening-event step (toward static). Default 0.01. */
+    loosenStep?: number;
+    /** Consecutive-clean-tasks required before any loosening. Default 10. */
+    loosenWindow?: number;
+}
+/**
+ * Apply the calibration rules to a chronological list of NEW divergence
+ * records. Pure — no I/O, no side effects, deterministic for a given
+ * (state, newRecords, options) triple.
+ *
+ * The caller is responsible for tracking which records are "new" (typically
+ * by reading the full divergence history and slicing past the
+ * `processedRecords` count from the current state). This function does
+ * not deduplicate — feeding the same record twice will double-count its
+ * effect.
+ */
+export declare function applyCalibration(state: CalibrationState, newRecords: readonly DivergenceRecord[], options: ApplyCalibrationOptions): CalibrationState;
+/**
+ * Resolve the effective activation threshold by combining the static config
+ * value with the calibration override (if any). The override is always a
+ * tighter or equal value to the static — calibration can never relax past
+ * static. Returns the static value when calibration state is null
+ * (fail-closed mode) or when no override is set.
+ *
+ * Belt-and-braces clamps:
+ *  - upper bound: static ceiling (calibration never relaxes past it)
+ *  - lower bound: 0 (a negative or absurdly small override — e.g. from a
+ *    hand-edited calibration.json — would make Epic Mode never promote
+ *    anything; treat 0 as the absolute floor here; callers that pass a
+ *    higher `floor_threshold` to the engine get that bound at WRITE time,
+ *    so this clamp only matters for corrupt on-disk values)
+ */
+export declare function effectiveActivationThreshold(staticThreshold: number, state: CalibrationState | null): number;
+/**
+ * Union the static hot-module list (Lean Turbo's globals + protected) with
+ * the calibration's learned additions. Returns a fresh array; callers can
+ * pass this to `decideEpicActivation`'s effective-hot-module check.
+ */
+export declare function effectiveHotModules(staticHotModules: readonly string[], state: CalibrationState | null): string[];

package/dist/turbo/epic/calibration.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Durable calibration state for Epic Mode Capability D.
+ *
+ * Persists the LEARNED knob overrides that `decideEpicActivation` consults
+ * at runtime — the activation-threshold override (tighter than the static
+ * config when divergence has been observed) and the auto-added hot-module
+ * list (monotonically grows; never auto-shrinks per design).
+ *
+ * Lives at `<projectRoot>/.swarm/epic/calibration.json`. Pattern mirrors
+ * `src/turbo/epic/state.ts` exactly — atomic `tmp + rename`, per-directory
+ * fail-closed marker on malformed file, repair seam.
+ *
+ * No imports from `src/turbo/lean/` — purely additive to the Epic namespace.
+ */
+/** Persisted shape of `.swarm/epic/calibration.json`. */
+export interface CalibrationState {
+    version: 1;
+    updatedAt: string;
+    /**
+     * Effective activation threshold override. When set, supersedes the
+     * static `turbo.epic.mode.activation_threshold` config value (which is
+     * always the absolute ceiling — calibration can tighten, never loosen
+     * past, the static value). Range: same as the static config — [0, 1].
+     */
+    activationThresholdOverride?: number;
+    /**
+     * Modules promoted to the hot-module list by observed divergence.
+     * Monotonically grows — never auto-shrinks (loosening the hot-module
+     * list requires manual intervention; the calibration loop only adds).
+     * Sorted lexicographically for stable diffs.
+     */
+    hotModuleAdditions: string[];
+    /**
+     * Running counter of consecutive clean (divergenceRatio === 0) task
+     * outcomes since the last divergent task or the last loosening event.
+     * Drives the loosen-rule (loosen only after `loosenWindow` consecutive
+     * clean tasks). Cleared by the engine after any loosening or divergence.
+     */
+    consecutiveCleanCount: number;
+    /** ISO 8601 timestamp of the most recent calibration-engine invocation. */
+    lastCalibrationAt?: string;
+    /** Number of divergence records processed by the engine so far. */
+    processedRecords: number;
+}
+export declare function emptyCalibrationState(): CalibrationState;
+export declare function isCalibrationStateUnreadable(directory: string): boolean;
+export declare function repairCalibrationUnreadable(directory: string): void;
+/**
+ * Read calibration state from disk. Seeds an empty file on first access so
+ * subsequent writes do not race on directory creation. Returns null when
+ * the file is malformed (fail-closed via `stateUnreadableMap`).
+ *
+ * Self-healing: when the in-memory unreadable marker is set, this function
+ * first attempts to re-validate the on-disk file. If a user (or another
+ * process) has repaired the file out-of-band, the marker auto-clears and the
+ * normal read proceeds. Without this, a long-lived plugin process would keep
+ * returning null until manually told to repair (adversarial review H2).
+ */
+export declare function loadCalibrationState(directory: string): CalibrationState | null;
+/**
+ * Atomic write of calibration state. `tmp + rename` pattern with random
+ * suffix to avoid concurrent-collision; tmp file is best-effort cleaned up
+ * on rename failure so a failed write does not leave orphans.
+ */
+export declare function saveCalibrationState(directory: string, state: CalibrationState): void;

package/dist/turbo/epic/cochange-conflict.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Co-change-aware pair conflict predicate for Epic mode.
+ *
+ * Combines Lean Turbo's existing path-based conflict signal (imported from
+ * `../lean/conflicts`) with a git co-change signal (from the
+ * `co_change_analyzer` output, sourced via `./cochange-source`).
+ *
+ * Conservative combination rule (design notes §15.2 step 4):
+ *  - The co-change signal may only ESCALATE a verdict, never DOWNGRADE it.
+ *  - `conflict = pathConflict || cochangeConflict`.
+ *  - This module never modifies Lean Turbo's behavior — when its caller does
+ *    not invoke it, nothing changes anywhere.
+ *
+ * Path / co-change name reconciliation:
+ *  - Scope paths may arrive normalized but absolute (`{projectRoot}/src/x.ts`)
+ *    because `src/turbo/lean/planner.ts:getValidatedFiles` prepends `directory`
+ *    to relative scopes.
+ *  - Co-change paths come from `git log --name-only` and are always
+ *    repo-relative (e.g. `src/x.ts`).
+ *  - We bridge with a boundary-aware suffix match: a scope path matches a
+ *    co-change path if they are equal OR the scope ends with `'/' + cochange`.
+ *    This handles both absolute and relative scope paths without needing the
+ *    project root.
+ */
+import type { CoChangeEntry } from '../../tools/co-change-analyzer.js';
+/**
+ * Threshold for treating a co-change pair as a conflict signal.
+ *
+ * `npmi` and `minCoChanges` directly correspond to fields on
+ * `CoChangeEntry`. Both must be satisfied for a pair to contribute a signal.
+ * Defaults live in `EpicConfigSchema` (`src/config/schema.ts`) and are
+ * deliberately stricter than `co_change_analyzer`'s discovery defaults.
+ */
+export interface CoChangeThreshold {
+    /** Minimum NPMI in [-1, 1]. */
+    npmi: number;
+    /** Minimum raw co-change count, to suppress small-sample noise. */
+    minCoChanges: number;
+}
+/** Detailed verdict from `epicPairConflict`. */
+export interface EpicPairVerdict {
+    /** True iff the two scopes conflict under the combined signal. */
+    conflict: boolean;
+    /** Which signal(s) fired. `'none'` only when `conflict === false`. */
+    reason: 'path' | 'cochange' | 'both' | 'none';
+    /** Concrete pairs that drove the verdict. Empty arrays when no signal fired. */
+    evidence: {
+        /** Path-overlapping pairs (each entry: `[scopeApath, scopeBpath]`). */
+        pathPairs: Array<[string, string]>;
+        /** Co-change pairs (each entry references files as they appear in CoChangeEntry). */
+        cochangePairs: Array<{
+            a: string;
+            b: string;
+            npmi: number;
+            coChangeCount: number;
+        }>;
+    };
+}
+/**
+ * Decide whether two task scopes conflict, combining path-based and co-change
+ * signals. Pure function — no I/O, no side effects.
+ *
+ * @param scopeA       Files task 1 declares. Paths may be absolute or relative.
+ * @param scopeB       Files task 2 declares.
+ * @param cochangePairs Unfiltered co-change entries from `./cochange-source`.
+ *                     This function applies the threshold internally so callers
+ *                     can pass the analyzer's output verbatim.
+ * @param threshold    NPMI floor + min co-change count.
+ *
+ * Behavioral invariants verified by tests:
+ *  - Empty `cochangePairs` (greenfield / signal absent) → verdict is exactly
+ *    the path-only result. This is the "feature disabled" guarantee from
+ *    design notes §15.6.
+ *  - Co-change-only conflict promotes `'none'` to `'cochange'`.
+ *  - Path-only conflict is unaffected by co-change input.
+ *  - Both signals present → reason `'both'`.
+ *  - Empty scopes (either side) → no conflict (no pairs to evaluate).
+ */
+export declare function epicPairConflict(scopeA: string[], scopeB: string[], cochangePairs: CoChangeEntry[], threshold: CoChangeThreshold): EpicPairVerdict;

package/dist/turbo/epic/cochange-source.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Co-change pair source for Epic mode.
+ *
+ * Composes the existing `co_change_analyzer` primitives (`parseGitLog`,
+ * `buildCoChangeMatrix`) to produce a full, unfiltered list of file-pair
+ * co-change entries the Epic conflict module can threshold itself.
+ *
+ * Why not call `detectDarkMatter` directly?
+ *  - `detectDarkMatter` caps output at the top 20 pairs by NPMI and excludes
+ *    pairs that already have a static import edge. That filter is correct for
+ *    *dark-matter discovery* (its purpose) but wrong for lane-conflict signal:
+ *    a high-NPMI pair with a static edge is still a real coupling signal the
+ *    lane planner should know about.
+ *
+ * Caching:
+ *  - One entry per project directory, keyed on `git rev-parse HEAD`.
+ *  - Same HEAD → cache hit, no git re-scan.
+ *  - Different HEAD or different directory → recompute.
+ *  - FIFO eviction at `MAX_TRACKED_DIRS` so multi-project usage stays bounded
+ *    (AGENTS.md invariant 8: module-level state needs explicit eviction).
+ *
+ * Reuse vs reimplementation:
+ *  - This module never copies analyzer logic. It only orchestrates calls to
+ *    the analyzer's existing exported `_internals` (per AGENTS.md invariant
+ *    on composition).
+ *  - The git HEAD read is a separate bounded subprocess, exposed via the
+ *    `_internals` DI seam so tests can stub it without `mock.module`.
+ */
+import * as child_process from 'node:child_process';
+import { type CoChangeEntry, _internals as coChangeAnalyzer } from '../../tools/co-change-analyzer.js';
+declare const execFileAsync: typeof child_process.execFile.__promisify__;
+export interface GetCoChangePairsOptions {
+    /** Maximum commits the analyzer scans. Defaults to 500. */
+    maxCommitsToAnalyze?: number;
+}
+/**
+ * Output of `getCoChangeData`. Carries the same `pairs` returned by
+ * `getCoChangePairs`, plus the commit count the analyzer actually observed
+ * — which Capability C's greenfield gate needs to decide whether the
+ * signal is dense enough to trust.
+ */
+export interface CoChangeData {
+    pairs: CoChangeEntry[];
+    commitsObserved: number;
+}
+/**
+ * Return the full co-change data for the given directory at the current
+ * git HEAD. The returned `pairs` are unfiltered (every pair the analyzer
+ * recorded, with NPMI / lift / counts / static-edge fields); `commitsObserved`
+ * is the number of distinct commits the analyzer scanned. Capability A
+ * applies the NPMI threshold to `pairs`; Capability C's greenfield gate
+ * inspects `commitsObserved`.
+ *
+ * Returns `{ pairs: [], commitsObserved: 0 }` when:
+ *  - Directory is not a git repo, or `git` is unavailable / times out.
+ *  - The analyzer's commit map is empty (greenfield repo).
+ * Both cases are signal-absent.
+ */
+export declare function getCoChangeData(directory: string, options?: GetCoChangePairsOptions): Promise<CoChangeData>;
+/**
+ * Back-compat wrapper kept for the M2 path (`/swarm coupling` only needs
+ * `pairs`). Capability C uses `getCoChangeData` directly for the
+ * greenfield gate.
+ */
+export declare function getCoChangePairs(directory: string, options?: GetCoChangePairsOptions): Promise<CoChangeEntry[]>;
+/** Test-only: drop all cache entries. */
+export declare function _clearCache(): void;
+/** Test-only: cache size, for asserting eviction behavior. */
+export declare function _cacheSize(): number;
+/**
+ * Test-only DI seam. Mutating this object is file-scoped and trivially
+ * restorable via afterEach, avoiding Bun's cross-file `mock.module` leak
+ * (AGENTS.md invariant 7).
+ */
+export declare const _internals: {
+    execFile: typeof execFileAsync;
+    parseGitLog: typeof coChangeAnalyzer.parseGitLog;
+    buildCoChangeMatrix: typeof coChangeAnalyzer.buildCoChangeMatrix;
+};
+export {};

package/dist/turbo/epic/coupling-report.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Coupling report computation for Epic mode (Capability B).
+ *
+ * Given a plan, computes:
+ *  - `p` — the coupling coefficient (fraction of task pairs that conflict
+ *          under the combined path + co-change signal from Capability A).
+ *  - `perModule` — for each file/module that caused at least one conflict,
+ *          the count of conflicting pairs it appeared in.
+ *  - `roadmap` — the modules ranked by conflict-contribution, with each
+ *          one's share of total detected conflicts. The team can use this
+ *          as a decoupling priority order.
+ *
+ * Read-only — this module changes no execution behavior. It composes
+ * Capability A's `epicPairConflict` (the same predicate the future epic
+ * mode will use when scheduling), so the report answers exactly the
+ * question "what would Capability A say about this plan if I asked it
+ * about every task pair?".
+ */
+import type { CoChangeEntry } from '../../tools/co-change-analyzer.js';
+import { type CoChangeThreshold, type EpicPairVerdict } from './cochange-conflict.js';
+/** A task as `epic` mode sees it: identifier + declared file scope. */
+export interface CouplingTask {
+    id: string;
+    scope: string[];
+}
+/** One conflicting pair in the report. */
+export interface ConflictingPair {
+    a: string;
+    b: string;
+    reason: EpicPairVerdict['reason'];
+    cochangeMatches: number;
+    pathMatches: number;
+}
+/** Per-module conflict contribution. */
+export interface ModuleContention {
+    module: string;
+    conflicts: number;
+    share: number;
+}
+/** Output of `computeCouplingReport`. */
+export interface CouplingReport {
+    /** Number of tasks considered. */
+    taskCount: number;
+    /** Number of unordered task pairs evaluated (`n*(n-1)/2`). */
+    totalPairs: number;
+    /** Pairs the combined signal flagged as conflicting. */
+    conflictingPairCount: number;
+    /** Coupling coefficient `p` = conflictingPairCount / totalPairs (0 when totalPairs == 0). */
+    p: number;
+    /** Each conflicting pair, with the per-pair verdict reason and evidence counts. */
+    conflictingPairs: ConflictingPair[];
+    /** Per-module contention table, sorted by `conflicts` descending. */
+    perModule: ModuleContention[];
+    /** Top-N modules with a human-readable rank line for each. */
+    roadmap: string[];
+}
+export interface ComputeCouplingReportOptions {
+    /** Cap on roadmap rank entries. Default 5. */
+    roadmapTop?: number;
+}
+/**
+ * Compute the coupling report over a set of tasks.
+ *
+ * Inputs:
+ *  - `tasks`: the tasks to consider. The caller decides scoping (whole
+ *    plan vs a single phase) and any filtering (pending vs all). Empty
+ *    array is valid and produces `p = 0`.
+ *  - `cochangePairs`: typically the output of
+ *    `getCoChangePairs(directory)` — passed in so this function stays
+ *    pure (no I/O) and trivially testable. Empty array is valid (the
+ *    Capability A predicate falls back to path-only verdicts).
+ *  - `threshold`: NPMI + min-co-changes floor, same shape Capability A
+ *    consumes.
+ *  - `options.roadmapTop`: how many modules to list in the roadmap
+ *    (default 5).
+ *
+ * Pure function — no file I/O, no side effects.
+ */
+export declare function computeCouplingReport(tasks: CouplingTask[], cochangePairs: CoChangeEntry[], threshold: CoChangeThreshold, options?: ComputeCouplingReportOptions): CouplingReport;
+/**
+ * Render a `CouplingReport` as a markdown document. Output shape is
+ * stable so downstream tools can parse it; the JSON form (via
+ * `JSON.stringify(report)`) is the better target for programmatic use.
+ */
+export declare function formatCouplingReportMarkdown(report: CouplingReport): string;

package/dist/turbo/epic/divergence-recorder.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Divergence recorder for Epic Mode Capability D (self-calibration).
+ *
+ * After every task transitions to `completed`, this module:
+ *   1. Compares the task's DECLARED scope (from
+ *      `.swarm/scopes/scope-{taskId}.json` — what the coder said it would
+ *      touch) against the ACTUAL files modified during the task
+ *      (`session.modifiedFilesThisCoderTask` — what the guardrails hook
+ *      observed the coder writing to).
+ *   2. Computes divergence — undeclared writes (actual − declared), unused
+ *      declarations (declared − actual), and a per-task divergence ratio
+ *      (undeclared / max(1, actual)).
+ *   3. Appends one record to `.swarm/epic/divergence.jsonl`.
+ *
+ * The calibration engine (`./calibration-engine.ts`) reads this history on
+ * the next `epic_decide_phase` invocation and uses it to adjust the
+ * activation threshold and hot-module list. This module just records.
+ *
+ * Pure I/O: never throws to the caller. Failures are logged and swallowed
+ * so the task-completion path is never blocked by an audit write.
+ */
+/** One record per task completion. */
+export interface DivergenceRecord {
+    /** ISO 8601. */
+    timestamp: string;
+    sessionID: string;
+    taskId: string;
+    /** Phase the task belonged to, when known. */
+    phaseNumber?: number;
+    /** Normalised paths declared via `declare_scope` or files_touched fallback. */
+    declaredScope: string[];
+    /** Normalised paths the guardrails hook observed the coder write to. */
+    actualFiles: string[];
+    /** Files in `actualFiles` not present in `declaredScope`. */
+    undeclared: string[];
+    /** Files in `declaredScope` not present in `actualFiles`. */
+    unused: string[];
+    /** undeclared.length / max(1, actualFiles.length). 0 ⇒ fully declared. */
+    divergenceRatio: number;
+    /** True when divergenceRatio === 0 (no undeclared writes). */
+    isClean: boolean;
+}
+/**
+ * Compute the divergence between a declared scope and the files actually
+ * modified. Pure — no I/O, no side effects. Returns the diff sets plus the
+ * ratio used by the calibration engine.
+ *
+ * Path comparison uses `normalizePath` (POSIX-style, no trailing slash,
+ * Windows-lowercased) from Lean Turbo's conflicts module so the comparison
+ * is consistent with everything else in the lane planner.
+ */
+export declare function computeDivergence(declaredScope: readonly string[], actualFiles: readonly string[]): {
+    declared: string[];
+    actual: string[];
+    undeclared: string[];
+    unused: string[];
+    divergenceRatio: number;
+};
+interface RecordTaskDivergenceArgs {
+    directory: string;
+    sessionID: string;
+    taskId: string;
+    phaseNumber?: number;
+    declaredScope: readonly string[];
+    actualFiles: readonly string[];
+}
+/**
+ * Append one divergence record to the JSONL audit file.
+ *
+ * Append-only, line-delimited so partial writes are tolerable (the calibration
+ * reader skips malformed lines). Best-effort — never throws to caller:
+ *   - Directory-creation failure → log and return null.
+ *   - Append write failure → log and return null.
+ * Either keeps the task-completion path moving even if the audit subsystem
+ * is broken (audit miss is not a correctness issue; blocking task completion
+ * would be).
+ */
+export declare function recordTaskDivergence(args: RecordTaskDivergenceArgs): {
+    path: string;
+    record: DivergenceRecord;
+} | null;
+export interface ReadDivergenceHistoryOptions {
+    /** Read at most this many of the most recent records. */
+    limit?: number;
+    /** Filter to this session (default: all sessions). */
+    sessionID?: string;
+    /**
+     * Maximum bytes to read from the tail of the file. Defaults to
+     * `MAX_TAIL_BYTES` (16 MiB) — large enough to hold thousands of
+     * records, small enough to avoid OOMing on a runaway audit log.
+     * Pass `Infinity` to disable the bound (callers that truly need the
+     * whole history — adversarial review H3).
+     */
+    maxBytes?: number;
+}
+/**
+ * Read divergence records from disk, oldest-to-newest within the read
+ * window. Malformed lines (rare — could occur on partial write) are
+ * silently skipped — they do not corrupt the well-formed records before or
+ * after them. Returns `[]` when the file does not exist.
+ *
+ * Tail-bounded: by default reads at most the last `MAX_TAIL_BYTES`. When
+ * the file is larger, the read starts mid-file and the FIRST encountered
+ * line (which is almost certainly a partial record split by the byte
+ * boundary) is discarded. This means very old records are not returned by
+ * a default-bounded read — the calibration engine consumes the tail
+ * incrementally via `processedRecords`, so it never needs the full history
+ * in memory at once. For full-history audit reads (tests, ad-hoc tooling),
+ * pass `maxBytes: Infinity`.
+ */
+export declare function readDivergenceHistory(directory: string, options?: ReadDivergenceHistoryOptions): DivergenceRecord[];
+export {};

package/dist/turbo/epic/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Epic mode — barrel export.
+ *
+ * Epic mode is a new, additive execution mode that composes Lean Turbo without
+ * modifying it. Capabilities:
+ *  - A: co-change-aware pair conflict (`epicPairConflict`).
+ *  - B: coupling KPI + decoupling roadmap (`computeCouplingReport`).
+ *  - C: per-plan activation decision (`decideEpicActivation`).
+ *
+ * Dependency direction is one-way: `epic` depends on `lean`; `lean` never
+ * depends on `epic`. All Lean Turbo files stay byte-for-byte untouched.
+ */
+export type { EpicActivationOptions, EpicActivationRationale, EpicActivationVerdict, } from './activation.js';
+export { decideEpicActivation } from './activation.js';
+export type { CoChangeThreshold, EpicPairVerdict, } from './cochange-conflict.js';
+export { epicPairConflict } from './cochange-conflict.js';
+export type { CoChangeData, GetCoChangePairsOptions, } from './cochange-source.js';
+export { getCoChangeData, getCoChangePairs } from './cochange-source.js';
+export type { ComputeCouplingReportOptions, ConflictingPair, CouplingReport, CouplingTask, ModuleContention, } from './coupling-report.js';
+export { computeCouplingReport, formatCouplingReportMarkdown, } from './coupling-report.js';
+export type { PromotionEvidenceRecord } from './promotion-evidence.js';
+export { appendPromotionEvidence, readPromotionEvidence, } from './promotion-evidence.js';
+export type { EpicLastDecision, EpicPersistedState, EpicSessionState, } from './state.js';
+export { disableEpicMode, emptyPersisted as emptyEpicPersisted, emptySessionState as emptyEpicSessionState, enableEpicMode, isEpicModeActive, isStateUnreadable as isEpicStateUnreadable, loadEpicSessionState, recordEpicDecision, repairStateUnreadable as repairEpicStateUnreadable, resetEpicSession, saveEpicSessionState, } from './state.js';

package/dist/turbo/epic/promotion-evidence.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Promotion-evidence writer for Epic Mode (Capability C).
+ *
+ * Each activation decision (one per phase per session) appends a single
+ * JSON line to `.swarm/evidence/epic-promotions.jsonl`. The file is
+ * line-delimited so partial writes are tolerable — readers can skip a
+ * truncated trailing line and continue.
+ *
+ * The write is intentionally append-mode (not atomic-rename) because
+ * each line is a self-contained record and the file is monotonically
+ * growing. Per AGENTS.md invariant 4, writes go under `ctx.directory`,
+ * never `process.cwd()`.
+ */
+import type { EpicActivationVerdict } from './activation.js';
+/** What `appendPromotionEvidence` writes per decision. */
+export interface PromotionEvidenceRecord {
+    /** ISO 8601 timestamp of the decision. */
+    timestamp: string;
+    /** Session that made the decision (so multi-session usage stays auditable). */
+    sessionID: string;
+    /** Phase the decision applied to (Capability C operates per-plan but each
+     *  phase invokes the runner; we record per phase for granular telemetry). */
+    phase?: number;
+    /** The decision and the rationale, copied from the activation verdict. */
+    verdict: EpicActivationVerdict;
+}
+/**
+ * Append one decision record to `.swarm/evidence/epic-promotions.jsonl`.
+ *
+ * Returns the absolute path of the file written. On any I/O failure the
+ * error is rethrown — the caller decides whether to surface a warning to
+ * the user or fail closed. Returns null when the directory itself cannot
+ * be created (best-effort fail-soft so a missing `.swarm/` does not break
+ * the activation flow's primary verdict).
+ */
+export declare function appendPromotionEvidence(directory: string, record: PromotionEvidenceRecord): string | null;
+/**
+ * Read all evidence records from the JSONL file. Convenience for
+ * `/swarm epic status` and tests. Skips malformed lines (best-effort
+ * tolerance for the rare partial-write case).
+ */
+export declare function readPromotionEvidence(directory: string): PromotionEvidenceRecord[];

package/dist/turbo/epic/state.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Durable Epic Mode session state (Capability C).
+ *
+ * Persists per-session Epic Mode activation state under
+ * `<projectRoot>/.swarm/epic-state.json` so toggling survives process
+ * restarts. Mirrors the pattern in `src/turbo/lean/state.ts` (atomic
+ * `tmp + rename`, per-directory `stateUnreadableMap` for fail-closed
+ * semantics, sessions-keyed shape) — without modifying that file.
+ *
+ * Dependency direction is one-way: this module imports nothing from
+ * `src/turbo/lean/`. The shape is parallel but independent.
+ */
+/** Top-level state for a single session. */
+export interface EpicSessionState {
+    sessionID: string;
+    /** When epic mode was last enabled for this session (ISO 8601). */
+    enabledAt?: string;
+    /** When epic mode was last disabled for this session (ISO 8601). */
+    disabledAt?: string;
+    /** Most recent activation decision recorded for this session, if any. */
+    lastDecision?: EpicLastDecision;
+    /** Whether epic mode is currently active for this session. */
+    active: boolean;
+}
+/** Minimal snapshot of the last activation decision. */
+export interface EpicLastDecision {
+    decidedAt: string;
+    phase?: number;
+    decision: 'promote' | 'demote';
+    p: number;
+    blockingReasons: string[];
+}
+/** Persisted shape of `.swarm/epic-state.json`. */
+export interface EpicPersistedState {
+    version: 1;
+    updatedAt: string;
+    sessions: Record<string, EpicSessionState>;
+}
+export declare function emptyPersisted(): EpicPersistedState;
+export declare function emptySessionState(sessionID: string): EpicSessionState;
+export declare function isStateUnreadable(directory: string): boolean;
+export declare function repairStateUnreadable(directory: string): void;
+/** Read this session's state, or null if not yet recorded. */
+export declare function loadEpicSessionState(directory: string, sessionID: string): EpicSessionState | null;
+/** Write the given session state, replacing any prior entry for that sessionID. */
+export declare function saveEpicSessionState(directory: string, state: EpicSessionState): void;
+/** True iff epic mode is currently active for the given session. */
+export declare function isEpicModeActive(directory: string, sessionID: string): boolean;
+/**
+ * True iff epic mode is currently active for ANY session in the project.
+ *
+ * Use this when a code path needs to know "is the project running under
+ * Epic Mode right now" without caring which session toggled it. The
+ * session-scoped `isEpicModeActive` answers "did THIS session toggle it" —
+ * a different question with a different answer.
+ *
+ * The architect's session enables Epic via `/swarm epic on`; sub-agents
+ * (coders, reviewers) dispatched through the `Task` tool run in their own
+ * sessions and have no record of that toggle. Asking the project-scoped
+ * check is the only correct way to honor Epic Mode from those flows.
+ * Rule 2's auto-commit (centralized in Phase 5) is the canonical caller.
+ *
+ * Fail-closed: returns `false` on unreadable state, matching the rest of
+ * this module's defaults.
+ */
+export declare function isEpicModeActiveForProject(directory: string): boolean;
+/** Enable epic mode for the session; records `enabledAt`. */
+export declare function enableEpicMode(directory: string, sessionID: string): void;
+/** Disable epic mode for the session; records `disabledAt`. */
+export declare function disableEpicMode(directory: string, sessionID: string): void;
+/** Reset the session's state entry entirely. */
+export declare function resetEpicSession(directory: string, sessionID: string): void;
+/**
+ * Update the session's `lastDecision` field. Used by the runner after each
+ * activation evaluation so `/swarm epic status` can show the most recent
+ * decision rationale without re-reading the evidence JSONL.
+ *
+ * Precondition: the session must already have an entry (i.e. the caller has
+ * called `enableEpicMode` previously). This is intentional — recording a
+ * decision for a never-toggled session would produce phantom state that
+ * `/swarm epic status` could not distinguish from a legitimately-active
+ * session. Callers that reach this function should have already verified
+ * `isEpicModeActive(...)` returned `true`. Throws if no session entry exists.
+ */
+export declare function recordEpicDecision(directory: string, sessionID: string, decision: EpicLastDecision): void;