opencode-swarm 7.189.0 → 7.190.1

package/dist/epic/start.d.ts

@@ -0,0 +1,187 @@
+/**
+ * `/swarm epic start` orchestration (Epic v2 C1a).
+ *
+ * Refusals, checked in this order (the first one wins):
+ *   1. epic-disabled-by-config   `epic.mode.enabled !== true` (fail closed)
+ *   2. no-plan / plan-ledger-unreadable
+ *   3. epic-state-unreadable, then an existing epic: the same plan ⇒
+ *      `already-open` (idempotent success, not a refusal), another plan ⇒
+ *      epic-open-for-other-plan
+ *   4. turbo-active               config `turbo_mode: true`, any in-memory
+ *                                 session with Turbo on, or a running durable
+ *                                 Lean run (read without migrating Lean state)
+ *   5. dirty-baseline             git only: changes outside `.swarm/`
+ *      detached-head              git + epic-branch policy: HEAD is detached
+ *                                 (or the branch has no commit yet)
+ *      epic-branch-exists         git + epic-branch policy:
+ *                                 `swarm/epic/<epicKey>` already exists (left
+ *                                 by an earlier, abandoned epic of this plan)
+ *   6. in-flight-coders           project-wide (see `findInFlightCoderWork`)
+ *   7. not-epic-sized             sizing verdict (`--force` overrides; recorded)
+ *   8. branch-create-failed       `git checkout -b` failed after the row was
+ *                                 created — row and sentinel rolled back
+ *
+ * Learning (Epic v2 C6, `epic.learning.enabled` not false): before
+ * the sizing dry-run the Epic v1 calibration files are imported into the
+ * project prior once (`learning-store.ts`); the sizing plans with the
+ * prior's learned signals; the record keeps the prior's digest
+ * (`priorDigest`) and, once the epic is open, the epic's posterior starts
+ * as a copy of that prior.
+ *
+ * Commit policy (`epic.commit_policy`, default `epic-branch`): after
+ * the CAS create a git epic checks out `swarm/epic/<epicKey>` and records it
+ * (`git.epicBranch`) only once the checkout succeeded (M-e). Non-git
+ * projects (always `current-branch`) may open an epic but run it serially
+ * (maxParallel 1, M-i).
+ */
+import { readDelegationsDetailed } from '../background/pending-delegations.js';
+import { loadPluginConfigWithMeta } from '../config/index.js';
+import type { Plan } from '../config/plan-schema.js';
+import type { PluginConfig } from '../config/schema.js';
+import { scanWorktreeProvisioningOwnersForRecovery } from '../hooks/delegation-gate/worktree-provisioning-owner.js';
+import { scanWorktreeRecoveryAuthoritiesForRecovery } from '../hooks/delegation-gate/worktree-recovery-authority.js';
+import { readPlanEpochIdentity } from '../plan/ledger.js';
+import { loadPlanJsonOnly } from '../plan/manager.js';
+import { listRecoveryRecords, recoveryReadErrored } from '../turbo/lean/recovery.js';
+import { listCoderSettlementWalStates } from '../workflow/coder-settlement.js';
+import { getCoChangeData } from './cochange-source.js';
+import { resolveEpicDeclaredScopes } from './declared-scopes.js';
+import { checkoutNewEpicBranch, localBranchExists, readCurrentBranch, undoEpicBranchCreate } from './epic-branch.js';
+import { type EpicPriorRead, importLegacyEpicCalibrationOnce, initEpicPosterior, loadEpicLearningView, readEpicPrior } from './learning-store.js';
+import { createEpicRecord, deleteEpicState, type EpicRecordV1, inspectEpic, recordEpicBranch } from './lifecycle.js';
+import { syncEpicRefs } from './markers.js';
+import { type EpicPlanningSignals } from './planning-signals.js';
+import { type EpicShapingReport, shapeEpicPlan } from './shaping.js';
+import type { EpicSizingVerdict } from './sizing.js';
+export type EpicStartRefusal = 'epic-disabled-by-config' | 'host-unsupported' | 'no-plan' | 'plan-ledger-unreadable' | 'epic-open-for-other-plan' | 'epic-state-unreadable' | 'turbo-active' | 'dirty-baseline' | 'detached-head' | 'epic-branch-exists' | 'in-flight-coders' | 'not-epic-sized' | 'branch-create-failed';
+/** What the started epic inherited from the project prior. */
+export interface EpicStartLearning {
+    enabled: boolean;
+    prior: EpicPriorRead['status'];
+    /** Learned files / co-write edges / hot files in the inherited prior. */
+    files: number;
+    coWrites: number;
+    hotFiles: number;
+    /** The one-time Epic v1 import done by this start, if any. */
+    imported: {
+        calibrationHotModules: number;
+        divergenceRecords: number;
+    } | null;
+}
+export type EpicStartResult = {
+    status: 'started';
+    record: EpicRecordV1;
+    learning: EpicStartLearning;
+} | {
+    status: 'already-open';
+    record: EpicRecordV1;
+} | {
+    status: 'refused';
+    reason: EpicStartRefusal;
+    details: string[];
+    sizing?: EpicSizingVerdict;
+    /** Plan shaping advisory (`not-epic-sized` only; Epic v2 C7). */
+    shaping?: EpicShapingReport;
+};
+export interface EpicStartOptions {
+    directory: string;
+    sessionID: string;
+    force: boolean;
+}
+/**
+ * Why `/swarm epic start` refuses on a host without an OpenCode SDK client.
+ * Every git-epic coder needs worktree isolation and every phase needs the
+ * `epic_phase_review` dispatch, and both create sessions through that client
+ * (`worktree-isolation.ts` STANDARD_WORKTREE_ISOLATION_UNAVAILABLE,
+ * `src/review/contracts.ts`). The OpenCode 2 adapter initializes the plugin
+ * with `client: undefined` (`src/host/v2/setup.ts`), so an epic there could
+ * neither dispatch a coder nor complete a phase.
+ */
+export declare const EPIC_HOST_UNSUPPORTED_MESSAGE = "This OpenCode host gives the plugin no SDK client (OpenCode 2 does not yet, see docs/host/v2-hook-inventory.md). Epic needs it for worktree-isolated coders and for the epic_phase_review reviewer/critic, so an epic here could neither run its coders nor complete a phase. Run the plan in Balanced, or use an OpenCode 1.x host (1.18.29+).";
+/** Durable Lean run marked `running` — read without the migrating Lean reader. */
+declare function findRunningLeanRun(directory: string): string | null;
+/** Why Turbo blocks the start, or null (M-a). */
+export declare function findTurboActivity(directory: string, config: Pick<PluginConfig, 'turbo_mode'>): string[];
+/** Changes outside `.swarm/` (git only). Throws when git fails. */
+export declare function findDirtyBaseline(directory: string): string[];
+/**
+ * Project-wide in-flight coder work (MINOR 2), read-only:
+ *  - tracked standard worktree dispatches / lanes awaiting merge-back
+ *    (in-memory, this process);
+ *  - non-terminal durable background delegations;
+ *  - unsettled coder settlement WALs (DISPATCHED / PREPARED / unreadable);
+ *  - preserved Lean recovery lanes, preserved/claimed worktree recovery
+ *    authorities, and lanes being provisioned.
+ * Uncertain stores fail closed (reported as in flight).
+ */
+export declare function findInFlightCoderWork(directory: string): Promise<string[]>;
+/**
+ * Sizing inputs from the plan: pending tasks, scoped tasks, and the serial
+ * step count L of a dry run of the Epic component planner
+ * (`components.ts`, the planner `epic_next_wave` issues waves with) over
+ * every phase, under `maxParallel`, over the estimated scopes and the same
+ * planning signals (learned hot files and co-writes, co-change, density
+ * threshold). L = waves
+ * + tasks the planner can never schedule (a dependency cycle). Cross-phase
+ * dependencies count as satisfied (phases run in order). The computation
+ * is `sizeEpicPlan` (`shaping-sizing.ts`), shared with plan shaping, bounded
+ * by {@link MAX_START_SIZING_WORK} (beyond it the remaining tasks count as
+ * serial — a pessimistic L).
+ */
+export declare function computeEpicSizing(directory: string, plan: Plan, config: PluginConfig, maxParallel: number, signals: EpicPlanningSignals): EpicSizingVerdict;
+/**
+ * Phases already finished when the epic starts (every task completed or
+ * closed, or the phase closed) are recorded complete: `epic_next_wave`
+ * starts at the first unfinished phase. Later phases become complete only
+ * through `phase_complete` (phases are iterations).
+ */
+export declare function initialEpicPhases(plan: Plan): EpicRecordV1['phases'];
+export declare function startEpic(options: EpicStartOptions): Promise<EpicStartResult>;
+/**
+ * DI seam (AGENTS.md invariant 7) — tests replace collaborators without
+ * `mock.module`. Restore in `afterEach`.
+ */
+export declare const _internals: {
+    loadPluginConfigWithMeta: typeof loadPluginConfigWithMeta;
+    loadPlanJsonOnly: typeof loadPlanJsonOnly;
+    readPlanEpochIdentity: typeof readPlanEpochIdentity;
+    inspectEpic: typeof inspectEpic;
+    createEpicRecord: typeof createEpicRecord;
+    deleteEpicState: typeof deleteEpicState;
+    recordEpicBranch: typeof recordEpicBranch;
+    localBranchExists: typeof localBranchExists;
+    checkoutNewEpicBranch: typeof checkoutNewEpicBranch;
+    readCurrentBranch: typeof readCurrentBranch;
+    undoEpicBranchCreate: typeof undoEpicBranchCreate;
+    resolveEpicDeclaredScopes: typeof resolveEpicDeclaredScopes;
+    loadEpicLearningView: typeof loadEpicLearningView;
+    readEpicPrior: typeof readEpicPrior;
+    importLegacyEpicCalibrationOnce: typeof importLegacyEpicCalibrationOnce;
+    initEpicPosterior: typeof initEpicPosterior;
+    getCoChangeData: typeof getCoChangeData;
+    shapeEpicPlan: typeof shapeEpicPlan;
+    hasActiveTurboMode: () => boolean;
+    /**
+     * False only when the plugin was initialized on a host that supplies no
+     * SDK client: the v1 init stores the host client, the OpenCode 2 adapter
+     * stores `undefined`, and an uninitialized process (tests, scripts) keeps
+     * the initial `null` — which is not a host verdict, so it is allowed.
+     * Capability-based: once a v2 client is wired, Epic starts there too.
+     */
+    hostProvidesClient: () => boolean;
+    findRunningLeanRun: typeof findRunningLeanRun;
+    gitExec: (args: string[], cwd: string) => string;
+    getGitRepositoryStatus: (cwd: string) => import("../git/branch.js").GitRepositoryStatus;
+    /** In-memory worktree dispatches (lazy: the maps live in an import cycle). */
+    countTrackedWorktreeDispatches: () => number;
+    readDelegationsDetailed: typeof readDelegationsDetailed;
+    listCoderSettlementWalStates: typeof listCoderSettlementWalStates;
+    listRecoveryRecords: typeof listRecoveryRecords;
+    recoveryReadErrored: typeof recoveryReadErrored;
+    scanWorktreeRecoveryAuthoritiesForRecovery: typeof scanWorktreeRecoveryAuthoritiesForRecovery;
+    scanWorktreeProvisioningOwnersForRecovery: typeof scanWorktreeProvisioningOwnersForRecovery;
+    syncEpicRefs: typeof syncEpicRefs;
+    now: () => number;
+    newToken: () => string;
+};
+export {};

package/dist/epic/task-landing.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Epic v2 C3 — how an epic task's coder work reaches the epic branch.
+ *
+ * Two seams in shared code rely on this module, both Epic-gated and both
+ * costing exactly one `existsSync` (the epic sentinel) when no epic is open:
+ *
+ *   - `finishStandardWorktreeDispatch` (worktree-isolation.ts) asks
+ *     {@link epicCommitLandingFor}: for a task of the open epic, on the epic
+ *     branch, the lane lands as a real merge commit
+ *     (`git merge --no-ff --no-edit -m <message>`, see `src/worktree/merge.ts`)
+ *     whose message is `swarm(task <id>): <description>` + the plan's
+ *     `Swarm-Plan:` trailer — instead of the default squash-unstaged landing.
+ *     The work is therefore COMMITTED before `update_task_status(completed)`,
+ *     so a rework coder (whose worktree is cut from HEAD) starts from it and
+ *     its own landing no longer overlaps uncommitted bytes (critic B2).
+ *   - the delegation gate's Epic dispatch policy (`gate-policy.ts`, C4)
+ *     isolates every coder of an open git epic in a worktree (policy treated
+ *     as `required`), whatever `parallelization_enabled`, the session's
+ *     concurrency override or the preset say; when isolation cannot be
+ *     provided the dispatch is refused with
+ *     {@link epicIsolationDegradedMessage} instead of running un-isolated in
+ *     the main tree (M-b).
+ *
+ * Non-git epics run serially in the main tree (one task per wave, M-i) and
+ * never reach the landing seam's Epic branch.
+ */
+import { checkEpicBranch as checkEpicBranch_import } from './epic-branch.js';
+import { gitExecOnce as gitExecOnce_import } from './git-once.js';
+import { type EpicPlanTaskRef, type EpicRecordV1, epicSentinelExists as epicSentinelExists_import, getOpenEpic as getOpenEpic_import, readPlanTaskRef as readPlanTaskRef_import } from './lifecycle.js';
+/** DI seam (AGENTS.md invariant 7). Restore in `afterEach`. */
+export declare const _internals: {
+    epicSentinelExists: typeof epicSentinelExists_import;
+    getOpenEpic: typeof getOpenEpic_import;
+    readPlanTaskRef: typeof readPlanTaskRef_import;
+    checkEpicBranch: typeof checkEpicBranch_import;
+    gitExecOnce: typeof gitExecOnce_import;
+};
+/** An open epic and one of its plan's tasks. */
+export interface EpicTaskContext {
+    epic: EpicRecordV1;
+    task: EpicPlanTaskRef;
+}
+/**
+ * The open epic and the task, when `taskId` is a task of the plan the open
+ * epic is bound to; otherwise null. Sentinel first: one `existsSync` and
+ * nothing else when no epic is open. Unreadable lifecycle state counts as
+ * "no epic" here (Epic behaviour is off until repaired; `/swarm epic
+ * status` reports it).
+ */
+export declare function resolveEpicTaskContext(directory: string, taskId: string | null | undefined): EpicTaskContext | null;
+/** The landing options an epic task's worktree merge-back uses. */
+export interface EpicLandingOptions {
+    commitLanding: true;
+    landingCommitMessage: string;
+}
+/**
+ * The epic task must NOT be landed now: a committed merge requires the
+ * primary index to match HEAD, so unrelated staged entries would make it
+ * fail (and could be swept into the merge). `message` starts with
+ * `EPIC_LANDING_INDEX_DIRTY` and carries the remedy.
+ */
+export interface EpicLandingRefusal {
+    refused: true;
+    stage: typeof EPIC_LANDING_INDEX_STAGE;
+    message: string;
+}
+/** Merge-failure stage recorded for an {@link EpicLandingRefusal}. */
+export declare const EPIC_LANDING_INDEX_STAGE = "epic-landing-index";
+/**
+ * Landing override for a worktree coder of `planTaskId`: a committed landing
+ * with the Epic task message when the task belongs to the open git epic and
+ * HEAD is on the epic's branch. Undefined otherwise — the caller keeps its
+ * own (default) landing. A branch mismatch also yields undefined: the work
+ * must never be COMMITTED onto a foreign branch; `epic_next_wave` blocks
+ * `epic-branch-mismatch` until HEAD is back.
+ */
+export declare function epicCommitLandingFor(directory: string, planTaskId: string | null | undefined): EpicLandingOptions | EpicLandingRefusal | undefined;
+/**
+ * Refusal text for an epic coder whose worktree dispatch could not be set
+ * up. It wraps ANY error of that setup (isolation, provisioning, lifecycle
+ * lock, …), so the original error is quoted verbatim.
+ */
+export declare function epicIsolationDegradedMessage(taskId: string, reason: string): string;

package/dist/epic/wave-close.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Epic v2 C2 — closing a wave.
+ *
+ * `epic_next_wave` closes the active wave once every task in it is resolved
+ * (plan status completed / closed, or removed from the plan) and none has a
+ * relevant worktree merge-back failure. Closing records, in the epic record:
+ *
+ *   - `closeHead` (HEAD at close — every task's work is already committed:
+ *     its coder's worktree landing is a merge commit and non-coder writes
+ *     are residue commits, see `task-landing.ts` / `residue-commit.ts`);
+ *   - one {@link EpicTaskOutcome} per wave task: resolution and time (plan
+ *     ledger), evidence workflow generation, Stage A/B failure LOWER BOUNDS
+ *     (the evidence `retryHistory` keeps only its last 3 entries), the merge
+ *     failure snapshot observed while the wave was blocked, reopen count
+ *     (ledger transitions out of `completed`), declared (frozen) and
+ *     undeclared files, and the task's commit (`marker`: its newest
+ *     `swarm(task <id>):` commit for this plan inside the wave, else the
+ *     close HEAD) that `markers.ts` mirrors to `refs/swarm/epics/…/tasks/<id>`;
+ *   - undeclared files (divergence), computed automatically: a task's actual files are its
+ *     write attribution unioned across every same-project session (coder
+ *     writes are attributed on the coder's CHILD session). When no session
+ *     holds attribution the git fallback applies: files changed since the
+ *     wave's `baseHead` (committed or not), attributed to the task only when it was the wave's single
+ *     member, and otherwise kept at WAVE level (`wave.undeclared`) minus
+ *     every declared and attributed file.
+ *
+ * After the close is committed, the epic's learning posterior applies the
+ * closed wave's outcomes once ({@link recordEpicWaveLearning},
+ * `learning-store.ts`): undeclared writes teach learned co-writes and,
+ * with merge conflicts, rework, Stage B failures and reopens, the decaying
+ * hot set the planner uses for later waves (`components.ts`). A failed
+ * update never blocks the wave flow; the next close (or the epic close)
+ * catches it up from the record.
+ */
+import type { Plan } from '../config/plan-schema.js';
+import type { PluginConfig } from '../config/schema.js';
+import { readTaskEvidence as readTaskEvidence_import } from '../gate-evidence.js';
+import { readLedgerEvents as readLedgerEvents_import } from '../plan/ledger.js';
+import { hydrationProjectKey as hydrationProjectKey_import } from '../session/hydration-ownership.js';
+import { type AgentSessionState, getAgentSession as getAgentSession_import, getModifiedFilesForTask as getModifiedFilesForTask_import, resetModifiedFilesForTask as resetModifiedFilesForTask_import } from '../state.js';
+import { applyClosedWavesToPosterior as applyClosedWavesToPosterior_import } from './learning-store.js';
+import type { EpicRecordV1, EpicTaskOutcome, EpicWaveRecord } from './lifecycle.js';
+import { findTaskCommits as findTaskCommits_import } from './markers.js';
+/** DI seam (AGENTS.md invariant 7). Restore in `afterEach`. */
+export declare const _internals: {
+    gitExec: (args: string[], cwd: string) => string;
+    readTaskEvidence: typeof readTaskEvidence_import;
+    readLedgerEvents: typeof readLedgerEvents_import;
+    listAgentSessions: () => Iterable<[string, AgentSessionState]>;
+    getAgentSession: typeof getAgentSession_import;
+    getModifiedFilesForTask: typeof getModifiedFilesForTask_import;
+    resetModifiedFilesForTask: typeof resetModifiedFilesForTask_import;
+    hydrationProjectKey: typeof hydrationProjectKey_import;
+    applyClosedWavesToPosterior: typeof applyClosedWavesToPosterior_import;
+    findTaskCommits: typeof findTaskCommits_import;
+};
+export interface EpicWaveCloseComputation {
+    closeHead: string | null;
+    outcomes: EpicTaskOutcome[];
+    waveUndeclared: string[];
+}
+/**
+ * Files changed since `baseHead` — committed (`git diff baseHead HEAD`) or
+ * not (`git status`, untracked included) — outside `.swarm/`. Null when git
+ * fails or there is no base.
+ */
+export declare function changedFilesSinceBase(directory: string, baseHead: string | null): string[] | null;
+/**
+ * The task's write attribution unioned across the calling session and every
+ * session owned by the same project (read-only), canonicalized
+ * repo-relative. Sessions without an owning project key are never read
+ * (cross-project safety), except the calling session itself.
+ */
+export declare function collectTaskAttribution(directory: string, callerSessionID: string | undefined, taskId: string): string[];
+/**
+ * Compute everything a wave close records. Reads only (git, ledger,
+ * evidence, in-memory attribution); the caller CASes the result into the
+ * record with {@link applyWaveClose}.
+ */
+export declare function computeWaveClose(args: {
+    directory: string;
+    epic: EpicRecordV1;
+    wave: EpicWaveRecord;
+    plan: Plan;
+    sessionID: string | undefined;
+    nowIso: string;
+}): Promise<EpicWaveCloseComputation>;
+/**
+ * Pure record mutation for a wave close. Returns the record unchanged when
+ * the wave is no longer the issued active wave (a concurrent close won).
+ */
+export declare function applyWaveClose(record: EpicRecordV1, seq: number, computation: EpicWaveCloseComputation, nowIso: string): EpicRecordV1;
+/**
+ * After a committed close (by the call that closed the wave): apply every
+ * closed wave's outcomes not applied yet to the epic's learning posterior
+ * (idempotent per wave seq, `learning-store.ts`) unless
+ * `epic.learning.enabled` is false. Never throws: a failure is a
+ * critical warning and the next update (or the epic close) catches it up.
+ */
+export declare function recordEpicWaveLearning(args: {
+    directory: string;
+    config: PluginConfig;
+    record: EpicRecordV1;
+}): number[];
+/**
+ * Release the closed wave's retained write attribution (Epic retains
+ * completed-task attribution until its wave closes — see
+ * `completeModifiedFilesForTask`) in the calling session and in EVERY
+ * session owned by the same project (coder child sessions hold it too).
+ * Sessions of other projects are never touched. Best-effort.
+ */
+export declare function releaseWaveAttribution(directory: string, sessionID: string | undefined, taskIds: readonly string[]): void;

package/dist/epic/wave-select.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Epic v2 C2/C5 — choose the NEXT wave of the current phase.
+ *
+ * `epic_next_wave` issues one wave at a time. This module decides which
+ * tasks that wave contains with the Epic component planner
+ * (`components.ts`: conflict graph → components → modes → greedy wave). It
+ * never writes: the caller freezes the result into the epic record.
+ *
+ * Inputs and rules:
+ *   - batch = the phase's tasks that are not completed / closed / blocked;
+ *   - a dependency OUTSIDE the batch is satisfied only when that task is
+ *     `completed` in the plan AND (under git) its commit is on the epic
+ *     branch (`isCommitted`: its epic task ref is an ancestor of HEAD, see
+ *     `markers.ts`, or it was completed before the epic started); a
+ *     dependency on a closed or removed task, on a later-phase task, or a
+ *     completed task without that evidence makes the dependent
+ *     `predecessor-missing` (the plan must be fixed — it can never run);
+ *   - scopes: the live `declare_scope` binding, else `files_touched` (an
+ *     estimate); the chosen members must all have a live binding, otherwise
+ *     the result is `declare-scopes` (suggested files = `files_touched`);
+ *   - components over the batch: a task touching a global file, a
+ *     protected path or a learned hot file (`learning.ts`), or with no
+ *     usable scope, is exclusive and runs ALONE first; other tasks are
+ *     grouped into conflict components (path ∪ co-change, the wave
+ *     verdict's predicate, with each scope expanded by learned co-writes
+ *     for the path half — stricter than the verdict, never looser) and a
+ *     densely coupled component
+ *     (`serial-component`) contributes at most one task per wave;
+ *   - the wave records every batch task's component and each component's
+ *     mode (`components`), shown by `/swarm epic status`; past waves'
+ *     records age components so none starves.
+ */
+import type { Plan } from '../config/plan-schema.js';
+import type { LeanTurboConfig } from '../config/schema.js';
+import { type EpicCochangeSignal, type EpicWaveComponents, type EpicWaveHistoryEntry } from './components.js';
+import type { EpicCoWriteIndex } from './learning.js';
+import type { EpicCochangePair } from './lifecycle.js';
+/** Max co-change pairs frozen into one wave record. */
+export declare const MAX_WAVE_COCHANGE_PAIRS = 256;
+export interface EpicWaveSelectionInput {
+    directory: string;
+    plan: Plan;
+    phaseId: number;
+    /** Live declared scope per task (`[]` = no live binding). */
+    liveScopes: Record<string, string[]>;
+    maxParallel: number;
+    leanConfig: LeanTurboConfig;
+    /**
+     * Predecessor evidence for a completed out-of-batch task (git: its task
+     * ref is an ancestor of HEAD; non-git: always true). Precomputed by the
+     * caller, which maps a git failure to `git-failed`.
+     */
+    isCommitted: (taskId: string) => boolean;
+    /** Learned hot files (`learning.ts`); tasks declaring them run alone. */
+    hotFiles: readonly string[];
+    /** Learned co-writes expanding scopes in the conflict graph (null: none). */
+    coWrites: EpicCoWriteIndex | null;
+    /** Co-change signal (null = disabled by config). */
+    cochange: EpicCochangeSignal | null;
+    /** Intra-component density above which a component runs serially. */
+    densityThreshold: number;
+    /** This phase's earlier waves, oldest first (component ages). */
+    waveHistory: readonly EpicWaveHistoryEntry[];
+}
+export interface EpicPredecessorProblem {
+    taskId: string;
+    dependency: string;
+    why: 'removed' | 'closed' | 'later-phase' | 'not-committed' | 'cycle';
+}
+export type EpicWaveSelection = {
+    kind: 'wave';
+    waveKind: 'parallel' | 'exclusive' | 'serial-component';
+    taskIds: string[];
+    files: Record<string, string[]>;
+    cochangePairs: EpicCochangePair[];
+    components: EpicWaveComponents;
+} | {
+    kind: 'declare-scopes';
+    tasks: {
+        taskId: string;
+        suggestedFiles: string[];
+    }[];
+} | {
+    kind: 'task-blocked';
+    taskIds: string[];
+} | {
+    kind: 'predecessor-missing';
+    problems: EpicPredecessorProblem[];
+} | {
+    kind: 'none';
+};
+/** Threshold-passing pairs whose both files lie within `files`. */
+export declare function cochangePairsWithin(files: readonly string[], cochange: EpicCochangeSignal): EpicCochangePair[];
+/** Choose the next wave of `phaseId` (see the module header). */
+export declare function selectNextEpicWave(input: EpicWaveSelectionInput): EpicWaveSelection;

package/dist/evaluation/contracts.d.ts

@@ -279,8 +279,8 @@ export declare const PromotionDecisionV1Schema: z.ZodObject<{
     decidedAt: z.ZodISODateTime;
     status: z.ZodEnum<{
         inconclusive: "inconclusive";
-        accept: "accept";
         reject: "reject";
+        accept: "accept";
     }>;
     reasons: z.ZodArray<z.ZodString>;
     baseline: z.ZodObject<{

package/dist/evaluation/public-api.d.ts

@@ -33,7 +33,7 @@ export declare const evaluationV1: ((options: EvaluateCandidateV1Options) => Pro
         decisionId: string;
         runId: string;
         decidedAt: string;
-        status: "inconclusive" | "accept" | "reject";
+        status: "inconclusive" | "reject" | "accept";
         reasons: string[];
         baseline: {
             baselineRunId: string;

package/dist/full-auto/policy.d.ts

@@ -65,7 +65,18 @@ export interface FullAutoClassifierInput {
                 enabled?: boolean;
             };
         };
-        turbo?: unknown;
+        turbo?: {
+            epic?: {
+                mode?: {
+                    enabled?: boolean;
+                };
+            };
+        };
+        epic?: {
+            mode?: {
+                enabled?: boolean;
+            };
+        };
         skills?: {
             enabled?: boolean;
         };

package/dist/hooks/delegation-gate/worktree-isolation.d.ts

@@ -9,6 +9,7 @@
  * The _internals seam allows test injection of worktree operations.
  */
 import type { PluginConfig, WorktreeIsolationConfig } from '../../config';
+import { epicCommitLandingFor } from '../../epic/task-landing.js';
 import { tryAcquireLock } from '../../parallel/file-locks';
 import { bunSpawn } from '../../utils/bun-compat';
 import { resolveGitExecutable } from '../../utils/git-executable.js';
@@ -252,6 +253,13 @@ export declare function precreateStandardWorktreeSession(args: {
         taskId: string;
         files: string[];
     };
+    /**
+     * Epic v2 C3 (M-b): the coder belongs to the open epic, so an `auto`
+     * policy is treated as `required` — an isolation failure throws instead
+     * of degrading (serializing) the session to the main tree. Absent ⇒ the
+     * configured policy, unchanged.
+     */
+    isolationRequired?: boolean;
 }): Promise<void>;
 /**
  * Create a durable ownership tag without touching an in-flight background
@@ -338,6 +346,12 @@ options?: {
  * @param directory - The project root (required for git worktree/branch commands).
  */
 export declare function abortStandardWorktreeDispatch(callID: string, reason: 'denied' | 'cancelled', directory: string): Promise<void>;
+/**
+ * Epic v2 C3: run `task` on the standard merge-back queue, so it never
+ * writes to the primary checkout's index concurrently with a worktree
+ * merge-back (Epic residue commits). Only Epic calls it.
+ */
+export declare function runSerializedWithMergeBacks<T>(task: () => T | Promise<T>): Promise<T>;
 export declare function finishStandardWorktreeDispatch(directory: string, dispatch: StandardWorktreeDispatch, config?: PluginConfig, 
 /**
  * Optional callID for cleanup of awaitingMergeByCallID. When omitted,
@@ -368,6 +382,8 @@ export declare function readLaneEnvFileFromDisk(worktreePath: string, laneIndex:
  * here via getters/setters) to mock worktree provisioning, merge-back, etc.
  */
 export declare const _internals: {
+    /** Epic v2 C3: committed landing for a task of the open epic. */
+    epicCommitLandingFor: typeof epicCommitLandingFor;
     provisionWorktree: typeof provisionWorktree;
     removeWorktree: typeof removeWorktree;
     attemptMergeBackFromDirty: typeof attemptMergeBackFromDirty;

package/dist/hooks/delegation-gate.d.ts

@@ -9,6 +9,9 @@ import { deleteStageBDispatchBindings, readStageBDispatchBindings, recordStageBD
 import type { PluginConfig } from '../config';
 import { type Plan } from '../config/plan-schema';
 import { type QaGates } from '../db/qa-gate-profile.js';
+import { resolveEpicDispatchPolicy, resolveEpicPrFeedbackConflict } from '../epic/gate-policy.js';
+import { epicSentinelExists, isEpicOpenForProject } from '../epic/lifecycle.js';
+import { commitEpicResidueAfterDelegation } from '../epic/residue-commit.js';
 import { loadPlanJsonOnly } from '../plan/manager';
 import type { AgentSessionState } from '../state';
 import type { DelegationEnvelope, EnvelopeValidationResult } from '../types/delegation.js';
@@ -518,6 +521,14 @@ declare function resolveEvidenceTaskId(args: Record<string, unknown> | undefined
  * that test mutations on this object propagate to the extracted module.
  */
 export declare const _internals: {
+    isEpicOpenForProject: typeof isEpicOpenForProject;
+    /** Epic v2 C4: wave-only coder admission + the wave's parallel/isolation policy. */
+    resolveEpicDispatchPolicy: typeof resolveEpicDispatchPolicy;
+    resolveEpicPrFeedbackConflict: typeof resolveEpicPrFeedbackConflict;
+    /** Epic v2 C3 (X1): commit a non-coder writer's residue for an epic task. */
+    commitEpicResidueAfterDelegation: typeof commitEpicResidueAfterDelegation;
+    /** Epic sentinel probe (one existsSync) gating the residue seam. */
+    epicSentinelExists: typeof epicSentinelExists;
     recordStageBDispatchBindings: typeof recordStageBDispatchBindings;
     readStageBDispatchBindings: typeof readStageBDispatchBindings;
     deleteStageBDispatchBindings: typeof deleteStageBDispatchBindings;

package/dist/hooks/guardrails/index.d.ts

@@ -8,6 +8,7 @@
  */
 import { extractSwarmIdFromAgentName, getSwarmAgents, resolveFallbackModel } from '../../agents/index';
 import { type AuthorityConfig, type GuardrailsConfig } from '../../config/schema';
+import { resolveEpicGateTaskAttribution } from '../../epic/gate-policy';
 import { assessSandboxEnforcement, getExecutor } from '../../sandbox/executor';
 import { dcCheckJunctionCreation } from './destructive-command';
 import { getMostRecentAssistantText, getProviderFailureFingerprint, isTransientProviderFailureText } from './messages-transform';
@@ -22,6 +23,12 @@ export declare const _internals: {
     extractErrorSignal: typeof extractErrorSignal;
     getSandboxExecutor: typeof getExecutor;
     assessSandboxEnforcement: typeof assessSandboxEnforcement;
+    /**
+     * Epic seam (sentinel-first: one existsSync when Epic is off): while an
+     * epic runs a multi-task wave, the wave task whose frozen scope owns the
+     * gate run's files. See `resolveEpicGateTaskAttribution`.
+     */
+    resolveEpicGateTaskAttribution: typeof resolveEpicGateTaskAttribution;
     /** Test-only compatibility for legacy direct-after hook tests. */
     allowUncorrelatedGateReceipts: boolean;
     MAX_PENDING_GATE_RECEIPTS_PER_SESSION: number;

package/dist/hooks/promotion-evidence-store.d.ts

@@ -10,8 +10,8 @@
  *
  * Per-worktree by design: promotion evidence records THIS worktree's observed
  * applications. It is intentionally NOT a member of `KNOWLEDGE_FAMILY` (the
- * linked-cohort shared-artifact manifest), matching the precedent set by
- * `src/turbo/epic/promotion-evidence.ts`. It lives under the project-root
+ * linked-cohort shared-artifact manifest), matching the precedent set by the
+ * former Epic promotion-evidence log. It lives under the project-root
  * `.swarm/` (via {@link validateSwarmPath}), NOT the link-aware shared store
  * dir, so it stays per-worktree.
  */