opencode-swarm 7.189.0 → 7.190.1

package/dist/epic/close.d.ts

@@ -0,0 +1,209 @@
+/**
+ * `/swarm epic close` and `/swarm close` finalization (Epic v2 C1a + C1b).
+ *
+ *   1. refuse `epic-incomplete` (pending tasks) / `epic-orphaned` /
+ *      `epic-state-unreadable` unless `--abandon`;
+ *   2. epic-branch epics (C1b), not abandoning: landing preflight BEFORE any
+ *      mutation (M-f) — refuse `dirty-worktree` (changes outside `.swarm/`),
+ *      `original-branch-missing`, `detached-head` (a detached commit that
+ *      switching would orphan),
+ *      `epic-branch-missing`, `landing-git-failed`; detect an
+ *      already-landed state so a resumed close is idempotent;
+ *   3. CAS the row to `closing` (an interrupted close resumes from here);
+ *   4. write the close report (`epic-report-v2`: lifecycle facts + the
+ *      epic's scorecard, `scorecard.ts`) to
+ *      `.swarm/epic/reports/<reportKey>.json` and
+ *      `.swarm/epic-prior/reports/<reportKey>.json` (newest 50 kept —
+ *      `epic-prior/` survives `/swarm close`; `/swarm epic report` reads
+ *      them);
+ *   5. land (`--land squash|merge|none`, default squash; see
+ *      `epic-branch.ts`). A conflict or failure is rolled back, recorded on
+ *      the row, and the close STOPS with the row still `closing` — rerunning
+ *      `/swarm epic close` resumes. `--abandon` never lands: it switches back
+ *      to the original branch when the tree is clean and keeps the branch;
+ *   6. delete the epic's refs `refs/swarm/epics/<epicKey>/*` (Epic v2 C3;
+ *      the report captured their values in step 4) unless
+ *      `epic.retain_refs: true`; merge the epic's learning posterior
+ *      into the project prior `.swarm/epic-prior/learning.json` (Epic v2 C6,
+ *      any outcome, once per epic instance — the prior survives
+ *      `/swarm close`); rewrite the report with the landing, ref and
+ *      learning outcome, delete the row, then compare-and-delete the
+ *      sentinel, under the lifecycle lock. A failed landing keeps the refs
+ *      and merges nothing (the close resumes).
+ * `--abandon` on unreadable state deletes every lifecycle row without
+ * parsing it, then the sentinel.
+ */
+import type { Plan } from '../config/plan-schema.js';
+import { loadPlanJsonOnly } from '../plan/manager.js';
+import { listCoderSettlementWalStates } from '../workflow/coder-settlement.js';
+import { type EpicConfigSource } from './config.js';
+import { type EpicLandingAfterState, leaveEpicBranchOnAbandon, performEpicLanding, preflightEpicLanding } from './epic-branch.js';
+import { type EpicLearningSettings } from './learning.js';
+import { type EpicPriorMergeResult, loadEpicLearningView, mergeEpicPosteriorIntoPrior } from './learning-store.js';
+import { deleteEpicState, type EpicCloseOutcome, type EpicLandMode, type EpicRecordV1, inspectEpic, markEpicClosing, recordEpicLandingAttempt } from './lifecycle.js';
+import { deleteEpicRefs, readEpicRefs } from './markers.js';
+import { completedBeforeEpic } from './next-wave.js';
+import { type EpicScorecardV1 } from './scorecard.js';
+/** Newest close reports kept under `.swarm/epic-prior/reports/`. */
+export declare const EPIC_PRIOR_REPORTS_KEEP = 50;
+export declare const EPIC_REPORTS_RELATIVE_DIR: string;
+export declare const EPIC_PRIOR_REPORTS_RELATIVE_DIR: string;
+/** File names of close reports (`<reportKey>.json`). */
+export declare const EPIC_REPORT_NAME_RE: RegExp;
+/** Close-report schema (`report.ts` reads only this version). */
+export declare const EPIC_REPORT_SCHEMA = "epic-report-v2";
+export interface EpicTaskSummary {
+    total: number;
+    completed: number;
+    closed: number;
+    pending: string[];
+}
+/** What close did with the epic branch. */
+export interface EpicLandingSummary {
+    /** Requested mode; null when abandoning (never lands). */
+    mode: EpicLandMode | null;
+    status: 'not-applicable' | 'pending' | 'landed' | 'already-landed' | 'nothing-to-land' | 'checked-out-original' | 'left-in-place' | 'conflict' | 'failed';
+    epicBranch: string | null;
+    originalBranch: string | null;
+    conflictFiles: string[];
+    detail: string;
+    /**
+     * Where the repository actually ended up after a landing attempt (null
+     * when no landing git command ran).
+     */
+    after: EpicLandingAfterState | null;
+}
+/**
+ * The close report (`epic-report-v2`): lifecycle facts, the raw waves /
+ * outcomes / phases, the landing, refs and learning outcome, and the
+ * epic's {@link EpicScorecardV1} (which carries `forced`, `sizingAtStart`
+ * and the inherited `priorDigest`). Epic v2 C8 superseded the C1 report of
+ * this unreleased branch in place; no earlier version was ever shipped.
+ */
+export interface EpicCloseReport {
+    schema: typeof EPIC_REPORT_SCHEMA;
+    reportKey: string;
+    epicKey: string;
+    planId: string;
+    planKey: string;
+    outcome: EpicCloseOutcome;
+    startedAt: string;
+    closedAt: string;
+    startedBySession: string;
+    /** The epic's scorecard at close (`scorecard.ts`). */
+    scorecard: EpicScorecardV1;
+    config: EpicRecordV1['config'];
+    git: EpicRecordV1['git'] & {
+        headAtClose: string | null;
+    };
+    /** Null when the plan is gone or no longer the epic's plan (orphaned). */
+    tasks: EpicTaskSummary | null;
+    /** Waves issued by `epic_next_wave` (frozen scopes, heads, status). */
+    waves: EpicRecordV1['waves'];
+    /** Per-task outcomes recorded at wave close. */
+    taskOutcomes: EpicRecordV1['tasks'];
+    /** Phase lifecycle (review runs, verdicts). */
+    phases: EpicRecordV1['phases'];
+    landing: EpicLandingSummary;
+    /**
+     * The epic's refs (`refs/swarm/epics/<epicKey>/*`, name → sha) captured
+     * at close, and what close did with them. Null for non-git epics.
+     */
+    refs: {
+        entries: Record<string, string>;
+        retained: boolean;
+        /** Refs that could not be deleted (or listed); empty when clean. */
+        deleteFailures: string[];
+        /** Why the refs could not be captured, when they could not. */
+        captureError?: string;
+    } | null;
+    /**
+     * Epic v2 C6: what the epic's learning contributed to the project prior
+     * (`priorPath`, kept across `/swarm close`); null until the close
+     * completes the merge step.
+     */
+    learning: (EpicPriorMergeResult & {
+        priorPath: string;
+    }) | null;
+}
+export type EpicCloseResult = {
+    status: 'no-epic';
+    repairedSentinel: boolean;
+} | {
+    status: 'refused';
+    reason: 'epic-incomplete' | 'epic-orphaned' | 'epic-state-unreadable' | 'coders-live' | 'dirty-worktree' | 'epic-branch-missing' | 'original-branch-missing' | 'detached-head' | 'landing-git-failed';
+    details: string[];
+} | {
+    /** Landing conflicted / failed: rolled back, row stays `closing`. */
+    status: 'landing-failed';
+    report: EpicCloseReport;
+    reportPaths: string[];
+    landing: EpicLandingSummary;
+} | {
+    status: 'repaired-unreadable';
+    rowsDeleted: string[];
+    sentinelDeleted: boolean;
+} | {
+    status: 'closed';
+    report: EpicCloseReport;
+    reportPaths: string[];
+    sentinelDeleted: boolean;
+};
+export interface EpicCloseOptions {
+    directory: string;
+    abandon: boolean;
+    /**
+     * `--land` (epic-branch epics). Absent ⇒ the mode a resumed close
+     * recorded, else `squash`. Ignored with `abandon`.
+     */
+    land?: EpicLandMode;
+    /** Overrides the outcome label (swarm-close finalization). */
+    outcome?: EpicCloseOutcome;
+    /** `epic.retain_refs`: keep the epic's refs after close. */
+    retainRefs?: boolean;
+    /** `epic.learning.*` (absent ⇒ the schema defaults). */
+    learning?: EpicLearningSettings;
+}
+/** Unique per epic instance: `<epicKey>-<startedAt compact UTC>`. */
+export declare function epicReportKey(record: EpicRecordV1): string;
+export declare function summarizePlanTasks(plan: Plan): EpicTaskSummary;
+/** Keep the newest {@link EPIC_PRIOR_REPORTS_KEEP} reports (by mtime). */
+export declare function pruneEpicPriorReports(directory: string): number;
+declare function writeReport(directory: string, report: EpicCloseReport): string[];
+export declare function closeEpic(options: EpicCloseOptions): Promise<EpicCloseResult>;
+/**
+ * `/swarm close` hook, run BEFORE the archive stage (MINOR 1): an open epic
+ * is closed as `abandoned-by-swarm-close` so its report lands in
+ * `.swarm/epic/` (archived) and `.swarm/epic-prior/reports/` (kept).
+ *
+ * Epic-gated on the config close already loaded: with
+ * `epic.mode.enabled !== true` it returns null with NO I/O, so a
+ * non-Epic close is byte-identical (leftover state is left for
+ * `/swarm epic close --abandon`, which works regardless of config). With the
+ * gate on it acts when the sentinel exists, or — sentinel lost — when a
+ * lifecycle row exists in an existing swarm.db. Never throws.
+ */
+export declare function finalizeOpenEpicOnSwarmClose(directory: string, config: EpicConfigSource): Promise<string | null>;
+/**
+ * DI seam (AGENTS.md invariant 7). Restore in `afterEach`.
+ */
+export declare const _internals: {
+    loadPlanJsonOnly: typeof loadPlanJsonOnly;
+    inspectEpic: typeof inspectEpic;
+    markEpicClosing: typeof markEpicClosing;
+    recordEpicLandingAttempt: typeof recordEpicLandingAttempt;
+    deleteEpicState: typeof deleteEpicState;
+    preflightEpicLanding: typeof preflightEpicLanding;
+    performEpicLanding: typeof performEpicLanding;
+    leaveEpicBranchOnAbandon: typeof leaveEpicBranchOnAbandon;
+    writeReport: typeof writeReport;
+    readEpicRefs: typeof readEpicRefs;
+    deleteEpicRefs: typeof deleteEpicRefs;
+    mergeEpicPosteriorIntoPrior: typeof mergeEpicPosteriorIntoPrior;
+    loadEpicLearningView: typeof loadEpicLearningView;
+    listCoderSettlementWalStates: typeof listCoderSettlementWalStates;
+    completedBeforeEpic: typeof completedBeforeEpic;
+    gitExec: (args: string[], cwd: string) => string;
+    now: () => number;
+};
+export {};

package/dist/{turbo/epic → epic}/cochange-conflict.d.ts

@@ -12,9 +12,10 @@
  *    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.
+ *  - Planner scope paths are repo-relative (`getValidatedFiles` in
+ *    `src/turbo/lean/partition-common.ts` normalizes them relative to the
+ *    project root), but other callers may still pass normalized absolute
+ *    paths (`{projectRoot}/src/x.ts`).
  *  - 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
@@ -22,7 +23,7 @@
  *    This handles both absolute and relative scope paths without needing the
  *    project root.
  */
-import type { CoChangeEntry } from '../../tools/co-change-analyzer.js';
+import type { CoChangeEntry } from '../tools/co-change-analyzer.js';
 /**
  * Threshold for treating a co-change pair as a conflict signal.
  *

package/dist/{turbo/epic → epic}/cochange-source.d.ts

@@ -27,7 +27,7 @@
  *    `_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';
+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. */
@@ -57,6 +57,15 @@ export interface CoChangeData {
  * Both cases are signal-absent.
  */
 export declare function getCoChangeData(directory: string, options?: GetCoChangePairsOptions): Promise<CoChangeData>;
+/**
+ * The co-change data last computed for `directory` (any HEAD), WITHOUT git:
+ * no subprocess, no scan — a read of the in-memory cache `getCoChangeData`
+ * fills. Null when nothing is cached (cold: the caller plans path-only and
+ * says so). The entry may be for an older HEAD; it is a planning estimate.
+ * Used by the `save_plan` plan-shaping seam (Epic v2 C7), which must not
+ * spawn git on a plan save.
+ */
+export declare function peekCoChangeData(directory: string): CoChangeData | null;
 /**
  * Back-compat wrapper kept for the M2 path (`/swarm coupling` only needs
  * `pairs`). Capability C uses `getCoChangeData` directly for the

package/dist/epic/components.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Epic v2 C5 — per-component parallelism (pure).
+ *
+ * The Epic wave planner. Over the pending tasks of ONE phase it builds the
+ * conflict graph, splits it into connected components, gives every
+ * component a mode, and picks the next wave ({@link planNextEpicWave}).
+ * `epic_next_wave` (`wave-select.ts`) issues the wave it picks;
+ * `/swarm epic start`'s sizing dry-run ({@link dryRunEpicPhase}) repeats
+ * that same step over the tasks still pending, wave after wave, so it
+ * replays exactly the waves `epic_next_wave` would issue while every live
+ * scope equals the planning scope (`files_touched` until declared).
+ *
+ * ONE conflict predicate — `epicPairConflict(...).conflict` (path ∪
+ * co-change, `cochange-conflict.ts`) — is the edge relation here (computed
+ * through a pair index that is the same relation, see `cochangePartners`)
+ * and the pair relation of THE wave verdict (`computeEpicWaveVerdict`
+ * in `gate-policy.ts` → `computeParallelVerdict`, which the delegation gate
+ * repeats at dispatch). Both are `epicPairConflict(scopeA, scopeB, pairs,
+ * threshold).conflict` over the tasks' scopes:
+ *   - the scopes are the same strings: a task enters a multi-task wave only
+ *     with a live declared scope, and that live scope is what the wave
+ *     freezes and the verdict reads;
+ *   - the co-change pairs the wave freezes (`cochangePairsWithin`) are a
+ *     SUBSET of the pairs used here, and `epicPairConflict` is monotone in
+ *     its pairs (fewer pairs ⇒ fewer conflicts), so no edge here ⇒ no
+ *     conflict in the verdict;
+ *   - a task with no usable scope (the verdict's `unknown`) is exclusive
+ *     here, so it never shares a wave.
+ *   - learned scope expansion (Epic v2 C6, `learning.ts`) only ADDS edges:
+ *     the path half runs over scope*(t) = scope(t) ∪ the files tasks
+ *     declaring scope(t) were learned to co-write, a superset of the
+ *     declared scope the verdict reads (path overlap is monotone in the
+ *     scopes); the co-change half keeps the declared scopes (its rule is
+ *     not monotone in the scope). The planner is stricter than the verdict.
+ * Hence every wave of ≥ 2 tasks picked here is `all_disjoint` under the
+ * verdict (`epic_next_wave` still asserts it before issuing).
+ *
+ * Model:
+ *   - exclusive task: its scope touches a global file or a protected path
+ *     (`isGlobalFile` / `isProtectedPath`, classified by the shared
+ *     partition preflight), has no usable scope, or its declared scope
+ *     lists a learned hot file (`learning.ts`; exact normalized path). It is its own component
+ *     (mode `exclusive`) and
+ *     always runs ALONE, before any other ready task;
+ *   - every other task is a vertex; E = pairs that conflict (above, over
+ *     the learned scope* for the path half);
+ *     C = connected components of (vertices, E) (union-find);
+ *   - density d_C = |E_C| / (|C| choose 2) (0 for a single task);
+ *   - mode(C) = `serial-component` when d_C > `epic.mode.
+ *     activation_threshold` (default 0.3): a densely coupled cluster — a hub
+ *     file most of its tasks touch — runs ONE task per wave; otherwise
+ *     `parallel`: its tasks share a wave whenever they have no edge (a
+ *     sparse chain is one component whose non-adjacent tasks still run
+ *     together).
+ * A hub file therefore costs one serial cluster, never the whole phase:
+ * tasks outside the cluster keep filling waves in parallel.
+ *
+ * Next wave (readiness via the shared partition preflight + `getReadyTasks`,
+ * cycle-safe topological order):
+ *   1. a ready exclusive task, alone;
+ *   2. otherwise greedy over the ready tasks — oldest component first
+ *      (waves since the component last had a task issued: no component
+ *      starves), then topological order: add t when it has no edge to a
+ *      chosen task, its component has no chosen task yet if the component
+ *      is `serial-component`, and the wave is below `maxParallel`.
+ */
+import type { LeanTurboConfig } from '../config/schema.js';
+import type { CoChangeEntry } from '../tools/co-change-analyzer.js';
+import { type PartitionPreflight, type PlanTask as PartitionTask } from '../turbo/lean/partition-common.js';
+import type { CoChangeThreshold } from './cochange-conflict.js';
+import { type EpicCoWriteIndex } from './learning.js';
+/** Default intra-component density threshold (`mode.activation_threshold`). */
+export declare const DEFAULT_EPIC_DENSITY_THRESHOLD = 0.3;
+/** Max task → component entries recorded per wave (wave tasks always kept). */
+export declare const MAX_WAVE_COMPONENT_TASKS = 256;
+export type EpicComponentMode = 'exclusive' | 'serial-component' | 'parallel';
+export type EpicExclusiveReason = 'global-file' | 'protected-path' | 'no-scope' | 'hot-file';
+/** Co-change signal (null = disabled by config ⇒ path-only conflicts). */
+export interface EpicCochangeSignal {
+    pairs: CoChangeEntry[];
+    threshold: CoChangeThreshold;
+}
+/** The components recorded with a wave (`EpicWaveRecord.components`). */
+export interface EpicWaveComponents {
+    /** Pending task of the phase at issue time → its component id. */
+    byTask: Record<string, string>;
+    /** Component id → mode. */
+    modes: Record<string, EpicComponentMode>;
+    /** Component id → intra-component density d_C. */
+    density: Record<string, number>;
+    /** Component id → why its (single) task is exclusive. */
+    exclusive: Record<string, EpicExclusiveReason>;
+    /** The density threshold in force. */
+    threshold: number;
+    /** True when `byTask` was capped at {@link MAX_WAVE_COMPONENT_TASKS}. */
+    truncated: boolean;
+}
+/** What a past wave contributes to component ages. */
+export interface EpicWaveHistoryEntry {
+    taskIds: readonly string[];
+    components?: Pick<EpicWaveComponents, 'byTask'>;
+}
+export interface EpicConflictGraphInput {
+    /** Project root (scope paths are validated relative to it; no I/O). */
+    directory: string;
+    /** The phase's pending tasks. */
+    tasks: readonly PartitionTask[];
+    /** Scope per task: the live declared scope, else `files_touched`. */
+    scopes: Record<string, string[]>;
+    /** Lean config (risk policy of the shared preflight). */
+    leanConfig: LeanTurboConfig;
+    /** Learned hot files (`learning.ts`): tasks declaring them are exclusive. */
+    hotFiles: readonly string[];
+    /**
+     * Learned co-writes (`learning.ts`): the path half of the conflict graph
+     * runs over each task's expanded scope*. Null ⇒ no expansion.
+     */
+    coWrites: EpicCoWriteIndex | null;
+    cochange: EpicCochangeSignal | null;
+}
+export interface EpicConflictGraph {
+    /** Shared preflight: classification + cycle-safe topological order. */
+    preflight: PartitionPreflight;
+    /** Exclusive tasks and why. */
+    exclusive: Map<string, EpicExclusiveReason>;
+    /** Conflict edges among the non-exclusive tasks (symmetric). */
+    adjacency: Map<string, Set<string>>;
+    /** Task id → position in the topological order. */
+    topoIndex: Map<string, number>;
+}
+/** Build the conflict graph of one phase's pending tasks. */
+export declare function buildEpicConflictGraph(input: EpicConflictGraphInput): EpicConflictGraph;
+export interface EpicComponent {
+    /** Smallest member task id. */
+    id: string;
+    /** Member task ids, sorted. */
+    members: string[];
+    mode: EpicComponentMode;
+    /** Conflict edges inside the component. */
+    edgeCount: number;
+    /** d_C = edgeCount / (|C| choose 2); 0 for a single task. */
+    density: number;
+    exclusiveReason?: EpicExclusiveReason;
+}
+export interface EpicComponentPartition {
+    components: EpicComponent[];
+    /** Task id → component id. */
+    componentOf: Map<string, string>;
+    threshold: number;
+}
+/**
+ * Components (union-find) of `taskIds` — a subset of the graph's tasks —
+ * with their modes under `densityThreshold`.
+ */
+export declare function partitionEpicComponents(graph: EpicConflictGraph, taskIds: Iterable<string>, densityThreshold: number): EpicComponentPartition;
+/**
+ * Waves since each component last had a task issued (`history` oldest
+ * first). A wave served component C when one of its issued tasks shared a
+ * recorded component with a current member of C (or was a member). Never
+ * served ⇒ `history.length`.
+ */
+export declare function componentAges(partition: EpicComponentPartition, history: readonly EpicWaveHistoryEntry[]): Map<string, number>;
+export interface EpicWaveChoice {
+    taskIds: string[];
+    kind: 'parallel' | 'exclusive' | 'serial-component';
+}
+/**
+ * The next wave among `readyIds` (see the module header); null when none is
+ * ready.
+ */
+export declare function chooseEpicWave(graph: EpicConflictGraph, partition: EpicComponentPartition, readyIds: readonly string[], maxParallel: number, ages: Map<string, number>): EpicWaveChoice | null;
+/** Ready task ids: every dependency in `done` or satisfied outside. */
+export declare function readyEpicTasks(graph: EpicConflictGraph, done: ReadonlySet<string>, satisfiedOutside: (taskId: string) => boolean): string[];
+/** The recorded form of a partition (wave tasks always kept when capped). */
+export declare function toWaveComponents(partition: EpicComponentPartition, waveTaskIds: readonly string[]): EpicWaveComponents;
+export interface EpicNextWaveInput extends EpicConflictGraphInput {
+    maxParallel: number;
+    densityThreshold: number;
+    /** A dependency outside `tasks` is satisfied (completed + evidence). */
+    satisfiedOutside: (taskId: string) => boolean;
+    /** This phase's earlier waves, oldest first (component ages). */
+    history: readonly EpicWaveHistoryEntry[];
+}
+/**
+ * THE next-wave step over `tasks` (the phase's runnable pending tasks):
+ * graph → components → ready tasks → wave. `epic_next_wave`
+ * (`wave-select.ts`) issues its choice; {@link dryRunEpicPhase} repeats it.
+ */
+export declare function planNextEpicWave(input: EpicNextWaveInput): {
+    partition: EpicComponentPartition;
+    choice: EpicWaveChoice | null;
+};
+export interface EpicPhaseDryRun {
+    /** Waves in issue order. */
+    waves: EpicWaveChoice[];
+    /**
+     * Tasks never scheduled: `blocked` tasks, a dependency cycle, tasks
+     * downstream of either — and, when the run stopped at its work budget,
+     * every task still pending (each then counts as one serial step: a
+     * pessimistic L).
+     */
+    unscheduled: string[];
+    /** Work units spent ({@link epicWaveWork} summed over the waves). */
+    work: number;
+    /** True when `maxWork` stopped the run before every task was planned. */
+    aborted: boolean;
+}
+/** Work units per scope path per wave (the shared preflight resolves each). */
+export declare const EPIC_WORK_PER_SCOPE_PATH = 8;
+/** Work units per task pair per wave (graph + component bookkeeping). */
+export declare const EPIC_WORK_PER_TASK_PAIR = 6;
+/**
+ * Deterministic cost estimate (work units ≈ path comparisons) of ONE
+ * planning step over `remaining` tasks with these scope sizes, `history`
+ * waves old: per-path preflight + per-pair graph work + the pairwise path
+ * comparisons (Σ_{i<j} |a_i|·|a_j|) + component aging. Callers that must
+ * stay bounded (start sizing, plan shaping) spend a budget of these.
+ */
+export declare function epicWaveWork(scopeSizes: readonly number[], history: number): number;
+/**
+ * Replay `epic_next_wave` over one phase as if every issued wave completed
+ * (the `/swarm epic start` sizing dry-run): each step is
+ * {@link planNextEpicWave} over the tasks still pending — the graph and
+ * components rebuilt, the recorded components aging them — exactly the
+ * sequence `epic_next_wave` issues when every live scope equals the
+ * planning scope. `blocked` tasks never run (as in `epic_next_wave`), so
+ * they and their dependents are unscheduled. Dependencies outside the
+ * phase count as satisfied (phases run in order).
+ *
+ * `maxWork` bounds the run: before each step its {@link epicWaveWork} is
+ * charged; a step that would exceed the budget is not run (`aborted`, the
+ * rest unscheduled). Without it the run is unbounded (and identical).
+ */
+export declare function dryRunEpicPhase(input: EpicConflictGraphInput & {
+    maxParallel: number;
+    densityThreshold: number;
+    maxWork?: number;
+}): EpicPhaseDryRun;

package/dist/epic/config-gate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Epic Mode config master gates.
+ *
+ * `epic.mode.enabled` and `epic.cochange.enabled` are documented as opt-in
+ * master gates (both default `false`). This module is the single source of
+ * truth for reading them so every Epic entry point (slash commands, architect
+ * tools, agent tool maps, the hot-path seams, phase-complete readiness)
+ * agrees. Both read the effective Epic block via `resolveEpicConfig`
+ * (`./config.ts`: top-level `epic`, legacy `turbo.epic` fallback).
+ *
+ * Pure predicates take an already-loaded `PluginConfig`; callers that only
+ * have a directory use the `*ForDirectory` variants, which load config via
+ * `loadPluginConfigWithMeta` and fail closed (return `false`) if loading
+ * throws.
+ */
+import { loadPluginConfigWithMeta } from '../config/loader.js';
+/** The pure gates live in `./config.ts`; re-exported here for gate callers. */
+export { isEpicCochangeConfigEnabled, isEpicModeConfigEnabled, } from './config.js';
+/** Remediation text shown when Epic Mode is used without the config opt-in. */
+export declare const EPIC_MODE_CONFIG_DISABLED_MESSAGE: string;
+export declare const _internals: {
+    loadPluginConfigWithMeta: typeof loadPluginConfigWithMeta;
+};
+/** Directory-keyed variant of {@link isEpicModeConfigEnabled}; fails closed. */
+export declare function isEpicModeConfigEnabledForDirectory(directory: string): boolean;

package/dist/epic/config.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Epic Mode config — the ONE place that knows where Epic settings live.
+ *
+ * Canonical path: the top-level `epic` block of `opencode-swarm.json`
+ * (`{ "epic": { "mode": { "enabled": true } } }`). It needs no `turbo` block:
+ * Epic Mode is its own mode, not a Turbo overlay.
+ *
+ * Legacy path: `turbo.epic` (Epic v1 and Epic v2 before C9). It is accepted
+ * PERMANENTLY — there is no removal date — and handled in two layers:
+ *
+ *  1. Raw config (the loader, `src/config/loader.ts` step 0, and the raw
+ *     re-reads in `/swarm config doctor`): {@link migrateLegacyEpicConfig}
+ *     moves `turbo.epic` to top-level `epic` in EACH config file BEFORE the
+ *     user + project files are merged and before Zod parsing. Within one
+ *     file the move is a per-key deep merge in which that file's top-level
+ *     `epic` wins every key both set; across files the normal precedence
+ *     applies afterwards (project over user), whichever path each file used.
+ *     Doing it on the raw object is what makes the merge exact (after
+ *     parsing, schema defaults are indistinguishable from keys the user
+ *     wrote). The `turbo` block left behind is unchanged apart from losing
+ *     `epic`, and is dropped when nothing else was in it — so a legacy
+ *     `turbo.epic` no longer needs `turbo.strategy`. The loader warns once
+ *     when any file carries `turbo.epic` ({@link LEGACY_EPIC_CONFIG_WARNING}),
+ *     names recovered keys that came from it `… (from turbo.epic)`
+ *     ({@link annotateLegacyEpicKeys}), and `/swarm config doctor` reports
+ *     `legacy-epic-config-path` per file (report-only), naming validation
+ *     issues at the path the user wrote ({@link legacyEpicIssuePath}).
+ *  2. Parsed config: {@link resolveEpicConfig} returns `config.epic`, falling
+ *     back to `config.turbo.epic` for a config parsed WITHOUT the loader
+ *     (direct `PluginConfigSchema.parse`, tests). When a parsed config carries
+ *     both, the top-level block wins whole — the per-key merge needs the raw
+ *     config and is the loader's job.
+ *
+ * Every Epic config reader goes through {@link resolveEpicConfig} (directly or
+ * via `config-gate.ts`). This module has no runtime imports, so the loader and
+ * shared files can use it without pulling in Epic code.
+ */
+import type { EpicConfig } from '../config/schema.js';
+/** Advisory printed once per config-advisory dedup window (process / session start). */
+export declare const LEGACY_EPIC_CONFIG_WARNING: string;
+/**
+ * The parts of a parsed config Epic settings can live in. Generic over the
+ * Epic block's shape so structural mini-configs (e.g. the Full-Auto
+ * classifier input) resolve through the same function as `PluginConfig`.
+ */
+export type EpicConfigSource<E = EpicConfig> = {
+    epic?: E | null;
+    turbo?: {
+        epic?: E | null;
+    } | null;
+} | null | undefined;
+/**
+ * The effective Epic settings of a parsed config: top-level `epic`, else the
+ * legacy `turbo.epic` (see the module doc for the per-key merge). `undefined`
+ * when neither is set — every Epic gate then reads as off.
+ */
+export declare function resolveEpicConfig<E = EpicConfig>(config: EpicConfigSource<E>): E | undefined;
+/**
+ * Master gate: `epic.mode.enabled === true` (absent block ⇒ false). Pure; the
+ * directory-keyed variant and the disabled message live in `config-gate.ts`,
+ * which re-exports this.
+ */
+export declare function isEpicModeConfigEnabled(config: EpicConfigSource<{
+    mode?: {
+        enabled?: boolean;
+    } | null;
+}>): boolean;
+/** Co-change gate: `epic.cochange.enabled === true` (absent block ⇒ false). */
+export declare function isEpicCochangeConfigEnabled(config: EpicConfigSource<{
+    cochange?: {
+        enabled?: boolean;
+    } | null;
+}>): boolean;
+/** True when a raw (pre-parse) config carries the legacy `turbo.epic` key. */
+export declare function hasLegacyEpicConfig(raw: unknown): boolean;
+/**
+ * Move a raw config's legacy `turbo.epic` to top-level `epic` (module doc,
+ * layer 1). Returns the SAME object when there is no legacy key — a non-Epic
+ * config is never copied or changed. A non-object legacy value is moved as-is
+ * when top-level `epic` is absent (so validation reports it at `epic`), and
+ * dropped when top-level `epic` is set (top-level wins). Applied per config
+ * FILE, before the user and project files are merged.
+ */
+export declare function migrateLegacyEpicConfig(raw: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The path a validation issue of a MIGRATED raw config file should be reported
+ * at, given the file as the user wrote it: an `epic.*` path maps back to
+ * `turbo.epic.*` when the file set only the legacy path (no top-level `epic`).
+ * Every other path — and every path of a file without `turbo.epic` — is
+ * returned unchanged.
+ */
+export declare function legacyEpicIssuePath(raw: unknown, path: readonly PropertyKey[]): PropertyKey[];
+/**
+ * Label recovered config keys that came from a legacy `turbo.epic` block:
+ * `epic.<k>` becomes `epic.<k> (from turbo.epic)` when `<k>` was written under
+ * `turbo.epic` in one of `rawFiles` (as the user wrote them, before
+ * migration) and under no top-level `epic`; the whole `epic` section gets
+ * the label when some file had `turbo.epic` and none had top-level `epic`.
+ * Returns `keys` itself when no file carries `turbo.epic`.
+ */
+export declare function annotateLegacyEpicKeys(keys: string[], rawFiles: readonly unknown[]): string[];

package/dist/{turbo/epic → epic}/coupling-report.d.ts

@@ -16,7 +16,7 @@
  * 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 { 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 {
@@ -54,6 +54,8 @@ export interface CouplingReport {
     /** Top-N modules with a human-readable rank line for each. */
     roadmap: string[];
 }
+/** Whether the co-change conflict signal contributed to `p` (`/swarm coupling`). */
+export type EpicCochangeSignalState = 'enabled' | 'disabled-by-config';
 export interface ComputeCouplingReportOptions {
     /** Cap on roadmap rank entries. Default 5. */
     roadmapTop?: number;