opencode-swarm 7.86.0 → 7.87.0

package/dist/memory/schema.d.ts

@@ -46,8 +46,8 @@ export declare const MemorySourceSchema: z.ZodObject<{
         manual: "manual";
         test: "test";
         tool: "tool";
-        user: "user";
         commit: "commit";
+        user: "user";
         repo: "repo";
         web: "web";
     }>;
@@ -105,8 +105,8 @@ export declare const MemoryRecordSchema: z.ZodObject<{
             manual: "manual";
             test: "test";
             tool: "tool";
-            user: "user";
             commit: "commit";
+            user: "user";
             repo: "repo";
             web: "web";
         }>;
@@ -183,8 +183,8 @@ export declare const MemoryProposalSchema: z.ZodObject<{
                 manual: "manual";
                 test: "test";
                 tool: "tool";
-                user: "user";
                 commit: "commit";
+                user: "user";
                 repo: "repo";
                 web: "web";
             }>;

package/dist/plan/manager.d.ts

@@ -39,6 +39,11 @@ export interface AcknowledgedRemovals {
     source: string;
 }
 import { type Plan, type RuntimePlan, type TaskStatus } from '../config/plan-schema';
+import { isGitRepo } from '../git/branch';
+import { getWorktreeMergeFailure } from '../hooks/delegation-gate/worktree-merge-status';
+import { isEpicModeActiveForProject } from '../turbo/epic/state.js';
+import { commitTaskCompletion } from '../turbo/epic/task-commit.js';
+import { readTaskScopes } from '../turbo/lean/conflicts.js';
 import { type LedgerEvent, type LedgerEventInput, takeSnapshotWithRetry } from './ledger';
 /** Reset the startup ledger check flag. For testing only. */
 export declare function resetStartupLedgerCheck(): void;
@@ -54,6 +59,11 @@ export declare const _internals: {
     loadPlan: typeof loadPlan;
     loadPlanJsonOnly: typeof loadPlanJsonOnly;
     regeneratePlanMarkdown: typeof regeneratePlanMarkdown;
+    isGitRepo: typeof isGitRepo;
+    isEpicModeActiveForProject: typeof isEpicModeActiveForProject;
+    readTaskScopes: typeof readTaskScopes;
+    commitTaskCompletion: typeof commitTaskCompletion;
+    getWorktreeMergeFailure: typeof getWorktreeMergeFailure;
 };
 /** @internal Test seam for snapshot retry helper */
 export declare const _snapshot_test_exports: {

package/dist/state.d.ts

@@ -188,6 +188,11 @@ export interface AgentSessionState {
      *  When set, overrides the plan's execution_profile.max_concurrent_tasks
      *  for delegation-gate guidance. Cleared on session reset. */
     maxConcurrencyOverride?: number;
+    /** Whether Epic Mode (additive overlay above Lean Turbo) is active for
+     *  this session. Durable mirror lives in `.swarm/epic-state.json`; this
+     *  in-memory flag matches what `src/turbo/epic/state.ts` persists and is
+     *  what `hasActiveEpicMode(sessionID)` reads on the hot path. */
+    epicModeActive?: boolean;
     /** Session-scoped override for execution_profile.auto_proceed.
      *  When set, overrides the plan's auto_proceed for this session.
      *  true = auto-advance, false = do not auto-advance. Cleared on session reset. */
@@ -616,6 +621,16 @@ export declare function hasActiveFullAuto(sessionID?: string): boolean;
  *          or if any session has that combination when no sessionID provided.
  */
 export declare function hasActiveLeanTurbo(sessionID?: string): boolean;
+/**
+ * Check if Epic Mode is active for a specific session or ANY session.
+ * Mirrors `hasActiveLeanTurbo` but reads `session.epicModeActive`. The flag
+ * is set by `enableEpicMode` (and by `/swarm turbo epic on`) and cleared by
+ * `disableEpicMode` (and `/swarm turbo epic off`). The durable mirror is
+ * `.swarm/epic-state.json` — see `src/turbo/epic/state.ts`. Epic Mode does
+ * NOT require `turboStrategy === 'lean'`; it composes Lean Turbo internally
+ * inside `epic_run_phase`.
+ */
+export declare function hasActiveEpicMode(sessionID?: string): boolean;
 /**
  * Resolves the effective auto_proceed value for a session.
  * Session override (autoProceedOverride) takes precedence over the plan default.
@@ -675,6 +690,7 @@ export declare const _internals: {
     hasActiveFullAuto: typeof hasActiveFullAuto;
     hasActiveTurboMode: typeof hasActiveTurboMode;
     hasActiveLeanTurbo: typeof hasActiveLeanTurbo;
+    hasActiveEpicMode: typeof hasActiveEpicMode;
     buildRehydrationCache: typeof buildRehydrationCache;
     applyRehydrationCache: typeof applyRehydrationCache;
     rehydrateSessionFromDisk: typeof rehydrateSessionFromDisk;

package/dist/tools/epic-plan-waves.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Epic Mode `epic_plan_waves` tool.
+ *
+ * Wraps `planEpicWaves` from `src/turbo/epic/wave-planner`. Partitions a
+ * phase's pending tasks into ordered concurrent waves and returns them in a
+ * shape the architect can iterate over for wave-by-wave Task dispatch.
+ *
+ * This is Epic Mode's replacement for `lean_turbo_plan_lanes`. The lane
+ * planner stays in place for non-Epic Lean Turbo callers; Epic flows route
+ * through this tool because the wave abstraction expresses branching DAGs
+ * (sibling fanout from a shared prefix) correctly, where lanes collapse them.
+ */
+import type { ToolDefinition } from '@opencode-ai/plugin/tool';
+import { loadPluginConfigWithMeta as loadPluginConfigWithMeta_import } from '../config';
+import { buildIsUpstreamCommittedWithStatus as buildIsUpstreamCommittedWithStatus_import } from '../turbo/epic/upstream-commits';
+import { type EpicWavePlan } from '../turbo/epic/wave-planner';
+import { readTaskScopes as readTaskScopes_import } from '../turbo/lean/conflicts';
+import type { PlanPhase } from '../turbo/lean/partition-common';
+/** Arguments for the `epic_plan_waves` tool. */
+export interface EpicPlanWavesArgs {
+    directory: string;
+    phase: number;
+    scopes?: Record<string, string[]>;
+}
+/** Result envelope. */
+export interface EpicPlanWavesResult {
+    success: boolean;
+    /** Set on success — the full wave plan from `planEpicWaves`. */
+    plan?: EpicWavePlan;
+    /** Set on success — shortcut alias for `plan.waves`. */
+    waves?: EpicWavePlan['waves'];
+    /** Set on success — shortcut alias for `plan.serializedTasks`. */
+    serializedTasks?: EpicWavePlan['serializedTasks'];
+    /** Set on success — shortcut alias for `plan.degradedTasks`. */
+    degradedTasks?: EpicWavePlan['degradedTasks'];
+    /**
+     * Set when `reason === 'scopes-missing'` — the task ids that have no
+     * declared scope and no `files_touched` fallback. The architect must
+     * call `declare_scope` for each of these and re-invoke this tool.
+     */
+    missingScopes?: string[];
+    /** Set on failure — categorical short code (machine-readable). */
+    reason?: 'no-plan' | 'no-phase' | 'phase-empty' | 'phase-already-complete' | 'scopes-missing' | 'git-failed' | 'planner-error';
+    /** Set on failure — long-form actionable error text. */
+    errors?: string[];
+}
+declare function readPlanJson(directory: string): {
+    phases: PlanPhase[];
+} | null;
+/**
+ * Execute the `epic_plan_waves` tool.
+ *
+ * Six possible outcomes:
+ *   1. `no-plan` — `.swarm/plan.json` missing / unparseable
+ *   2. `no-phase` — phase number not in `plan.json`
+ *   3. `phase-empty` — phase exists but has zero tasks
+ *   4. `phase-already-complete` — every task already completed
+ *   5. `scopes-missing` — one or more pending tasks have no declared scope
+ *      (preflight; identical to `epic_decide_phase` so the architect can't
+ *      bypass scope discipline by calling planner direct)
+ *   6. `git-failed` — git log scan failed (Rule 3 evidence unavailable;
+ *      we fail closed rather than implicitly satisfying cross-batch deps)
+ *   7. success — `plan` and aliased fields populated
+ */
+export declare function executeEpicPlanWaves(args: EpicPlanWavesArgs): Promise<EpicPlanWavesResult>;
+/**
+ * DI seam — same pattern as `lean-turbo-plan-lanes.ts` (AGENTS.md invariant 7).
+ * Tests substitute deterministic doubles via `_internals.*` rather than `mock.module`.
+ */
+export declare const _internals: {
+    readPlanJson: typeof readPlanJson;
+    readTaskScopes: typeof readTaskScopes_import;
+    isGitRepo: (cwd: string) => boolean;
+    buildIsUpstreamCommittedWithStatus: typeof buildIsUpstreamCommittedWithStatus_import;
+    loadPluginConfigWithMeta: typeof loadPluginConfigWithMeta_import;
+};
+/** Tool definition for `epic_plan_waves`. */
+export declare const epic_plan_waves: ToolDefinition;
+export {};

package/dist/tools/epic-record-divergence.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Epic Mode divergence-record tool (Capability D — capture leg).
+ *
+ * After the architect marks a task `completed` via `update_task_status`, it
+ * calls this tool with `{ directory, taskId, sessionID }`. The tool:
+ *
+ *   1. Reads the task's DECLARED scope from `.swarm/scopes/scope-{taskId}.json`
+ *      (the same on-disk record `readScopeFromDisk` consults).
+ *   2. Reads the ACTUAL files the coder modified from the session's
+ *      `modifiedFilesThisCoderTask` — populated by the guardrails write hook
+ *      and reset by Lean Turbo at task-boundaries, so it captures THIS
+ *      task's writes only.
+ *   3. Appends one record to `.swarm/epic/divergence.jsonl` via
+ *      `recordTaskDivergence`. The calibration engine reads that file on the
+ *      next `epic_decide_phase` invocation (the architect-facing decide
+ *      tool — `epic_run_phase` is the legacy unified path, retained as
+ *      `executeEpicRunPhase` for composition users only).
+ *
+ * Best-effort by design — failure to record divergence is logged but never
+ * surfaces as a task-blocking error. Worst case: a single observation is
+ * missed and the calibration loop sees one fewer data point.
+ *
+ * Composition contract: this tool does NOT modify `update_task_status` or
+ * any maintainer file. The architect is instructed to call it via the
+ * `EPIC_MODE_BANNER` system-enhancer injection. If the architect forgets,
+ * the only effect is missing calibration signal — Epic Mode keeps working.
+ */
+import type { ToolDefinition } from '@opencode-ai/plugin/tool';
+import { loadPlanJsonOnly as loadPlanJsonOnly_import } from '../plan/manager.js';
+import { readScopeFromDisk as readScopeFromDisk_import } from '../scope/scope-persistence.js';
+import { getAgentSession as getAgentSession_import, hasActiveEpicMode as hasActiveEpicMode_import } from '../state.js';
+import { recordTaskDivergence as recordTaskDivergence_import } from '../turbo/epic/divergence-recorder.js';
+export interface EpicRecordDivergenceArgs {
+    directory: string;
+    taskId: string;
+    sessionID: string;
+}
+export interface EpicRecordDivergenceResult {
+    success: boolean;
+    /**
+     * Either:
+     *  - `'recorded'` — a record was appended to divergence.jsonl.
+     *  - `'epic-mode-not-active'` — session has not toggled Epic Mode; no-op.
+     *  - `'no-scope'` — no declared scope on disk for this task (could be a
+     *    pure verification task that bypassed `declare_scope`). Skipped.
+     *  - `'no-session'` — no agent session for `sessionID`; skipped.
+     *  - `'persist-failed'` — write to JSONL failed (logged); skipped.
+     */
+    reason: string;
+    /** When `reason === 'recorded'`, summarises the record without the full file lists. */
+    summary?: {
+        declaredCount: number;
+        actualCount: number;
+        undeclaredCount: number;
+        unusedCount: number;
+        divergenceRatio: number;
+        isClean: boolean;
+    };
+}
+/**
+ * Test-only DI seam (AGENTS.md invariant 7). Mutating this object is
+ * file-scoped and trivially restorable via afterEach, avoiding Bun's
+ * cross-file `mock.module` leak.
+ */
+export declare const _internals: {
+    hasActiveEpicMode: typeof hasActiveEpicMode_import;
+    getAgentSession: typeof getAgentSession_import;
+    readScopeFromDisk: typeof readScopeFromDisk_import;
+    loadPlanJsonOnly: typeof loadPlanJsonOnly_import;
+    recordTaskDivergence: typeof recordTaskDivergence_import;
+};
+export declare function executeEpicRecordDivergence(args: EpicRecordDivergenceArgs): Promise<EpicRecordDivergenceResult>;
+export declare const epic_record_divergence: ToolDefinition;

package/dist/tools/epic-run-phase.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Epic Mode run-phase tool (Capability C).
+ *
+ * The architect invokes this tool — instead of `lean_turbo_run_phase` —
+ * when Epic Mode is active. It:
+ *
+ *   1. Verifies Epic Mode is on for the session (else fails closed).
+ *   2. Loads the plan, resolves task scopes the same way the coupling
+ *      report does, and queries the co-change signal.
+ *   3. Runs `decideEpicActivation` over the WHOLE PLAN (per-plan
+ *      activation per Q1) to get a `promote | demote` verdict.
+ *   4. Appends one record to `.swarm/evidence/epic-promotions.jsonl`
+ *      and updates `.swarm/epic-state.json` with the verdict.
+ *   5. If promoted: invokes `LeanTurboRunner` for the given phase by
+ *      composition (zero edits to `src/turbo/lean/`).
+ *   6. If demoted: returns a structured "epic recommends serial"
+ *      verdict so the caller can fall back to the standard serial
+ *      flow.
+ *
+ * Composition contract: this tool is the only architect-facing entry
+ * point Capability C adds. It does not modify `lean_turbo_run_phase`,
+ * `LeanTurboRunner`, or any Lean Turbo file. Decision happens above
+ * Lean Turbo; execution dispatches into Lean Turbo via import only.
+ */
+import type { ToolDefinition } from '@opencode-ai/plugin/tool';
+import { loadPluginConfigWithMeta as loadPluginConfigWithMeta_import } from '../config/index.js';
+import { isGitRepo as isGitRepo_import } from '../git/branch.js';
+import { loadPlanJsonOnly as loadPlanJsonOnly_import } from '../plan/manager.js';
+import type { EpicActivationVerdict } from '../turbo/epic/activation.js';
+import { decideEpicActivation as decideEpicActivation_import } from '../turbo/epic/activation.js';
+import { loadCalibrationState as loadCalibrationState_import, saveCalibrationState as saveCalibrationState_import } from '../turbo/epic/calibration.js';
+import { applyCalibration as applyCalibration_import, effectiveActivationThreshold as effectiveActivationThreshold_import, effectiveHotModules as effectiveHotModules_import } from '../turbo/epic/calibration-engine.js';
+import { getCoChangeData as getCoChangeData_import } from '../turbo/epic/cochange-source.js';
+import { readDivergenceHistory as readDivergenceHistory_import } from '../turbo/epic/divergence-recorder.js';
+import { appendPromotionEvidence as appendPromotionEvidence_import } from '../turbo/epic/promotion-evidence.js';
+import { isEpicModeActive as isEpicModeActive_import, recordEpicDecision as recordEpicDecision_import } from '../turbo/epic/state.js';
+import { buildIsUpstreamCommitted as buildIsUpstreamCommitted_import, buildIsUpstreamCommittedWithStatus as buildIsUpstreamCommittedWithStatus_import } from '../turbo/epic/upstream-commits.js';
+import { readTaskScopes as readTaskScopes_import } from '../turbo/lean/conflicts.js';
+import type { LaneResult } from '../turbo/lean/runner.js';
+import { LeanTurboRunner as LeanTurboRunner_import } from '../turbo/lean/runner.js';
+export interface EpicRunPhaseArgs {
+    directory: string;
+    phase: number;
+    sessionID: string;
+}
+export interface EpicRunPhaseResult {
+    success: boolean;
+    /** The verdict for this run, persisted to evidence. */
+    verdict?: EpicActivationVerdict;
+    /** Set when the verdict was `promote` and Lean Turbo ran. */
+    lanes?: LaneResult[];
+    degradedTasks?: string[];
+    serializedTasks?: string[];
+    /**
+     * Either:
+     *  - `'demoted'` — epic chose serial; the caller should fall back.
+     *  - `'promoted'` — epic chose parallel and Lean Turbo ran.
+     *  - `'epic-mode-not-active'` — the session has not toggled Epic Mode.
+     *  - `'no-plan'` — `.swarm/plan.json` is missing.
+     *  - `'no-phase'` — the requested phase number isn't present in the
+     *    plan. Phase 12 (B11): without this, an unknown phase silently
+     *    produced `currentPhaseTasks = []` and vacuously-passed the
+     *    activation gate — promoting a phase that doesn't exist.
+     *  - `'phase-already-complete'` — every task in the requested phase
+     *    is already `status: 'completed'`. Phase 15 (B35): without this,
+     *    re-running an already-completed phase silently produced a
+     *    vacuous-pass `promote` verdict; the architect then called the
+     *    wave planner and got an empty plan with no diagnostic.
+     *  - `'phase-empty'` — the requested phase exists but its `tasks`
+     *    array is empty (architect created a phase header but never
+     *    populated it, or a council edit removed every task). Phase 17
+     *    (E.1): the Phase 15 B35 guard only fired when at least one
+     *    completed task existed; an empty `tasks: []` slipped through to
+     *    the same vacuous-pass `promote` B35 was supposed to prevent.
+     *  - `'lean-runner-error'` — Lean Turbo threw during promoted execution.
+     *  - `'scopes-missing'` — one or more pending tasks in the phase have
+     *    neither a declared scope file on disk nor `files_touched` in
+     *    plan.json. Lean Turbo's lane planner needs scope data to compute
+     *    parallel lanes; without it the dispatch returns empty lanes and
+     *    the parallelization promise is silently broken. The architect
+     *    must call `declare_scope` for each missing task and then
+     *    re-invoke `epic_decide_phase`.
+     */
+    reason: string;
+    /** Set when `reason === 'lean-runner-error'`. */
+    errors?: string[];
+    /** Set when `reason === 'scopes-missing'` — the task ids with no scope. */
+    missingScopes?: string[];
+    /** Set when `reason === 'scopes-missing'` — actionable message for the architect. */
+    message?: string;
+}
+/**
+ * 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: {
+    loadPluginConfigWithMeta: typeof loadPluginConfigWithMeta_import;
+    loadPlanJsonOnly: typeof loadPlanJsonOnly_import;
+    getCoChangeData: typeof getCoChangeData_import;
+    decideEpicActivation: typeof decideEpicActivation_import;
+    isGitRepo: typeof isGitRepo_import;
+    appendPromotionEvidence: typeof appendPromotionEvidence_import;
+    recordEpicDecision: typeof recordEpicDecision_import;
+    isEpicModeActive: typeof isEpicModeActive_import;
+    readTaskScopes: typeof readTaskScopes_import;
+    loadCalibrationState: typeof loadCalibrationState_import;
+    saveCalibrationState: typeof saveCalibrationState_import;
+    applyCalibration: typeof applyCalibration_import;
+    effectiveActivationThreshold: typeof effectiveActivationThreshold_import;
+    effectiveHotModules: typeof effectiveHotModules_import;
+    readDivergenceHistory: typeof readDivergenceHistory_import;
+    LeanTurboRunner: typeof LeanTurboRunner_import;
+    buildIsUpstreamCommitted: typeof buildIsUpstreamCommitted_import;
+    buildIsUpstreamCommittedWithStatus: typeof buildIsUpstreamCommittedWithStatus_import;
+};
+/**
+ * Decide-only path: runs stages 1-9 of the phase flow (preflight + calibration
+ * + co-change + decision + evidence write + session state mirror) and returns
+ * the verdict WITHOUT dispatching Lean Turbo.
+ *
+ * This is the shared helper between:
+ *  - `epic_run_phase`: legacy unified tool (decide + dispatch in one call) —
+ *    calls this then continues with dispatch when verdict is promote.
+ *  - `epic_decide_phase`: transparent flow (decide only — architect then
+ *    calls `epic_plan_waves` and dispatches each wave via Task for visibility).
+ *
+ * Returns the same EpicRunPhaseResult shape with:
+ *  - reason: 'decided'  → verdict is promote, caller may dispatch.
+ *  - reason: 'demoted'  → verdict is demote, caller falls back to serial.
+ *
+ * Error / non-decision reasons (all set success: false):
+ *  - 'epic-mode-not-active' — the session has not toggled Epic Mode.
+ *  - 'no-plan' — `.swarm/plan.json` is missing.
+ *  - 'no-phase' (Phase 12 B11) — the requested phase number isn't in the plan.
+ *  - 'phase-empty' (Phase 17 E.1) — phase exists but has zero tasks.
+ *  - 'phase-already-complete' (Phase 15 B35) — every task already completed.
+ *  - 'scopes-missing' — one or more pending tasks lack declared scope.
+ *  - 'epic-state-unreadable' — `.swarm/epic-state.json` is corrupt.
+ */
+export declare function executeEpicDecidePhase(args: EpicRunPhaseArgs): Promise<EpicRunPhaseResult>;
+/**
+ * Full unified path: decide + dispatch in one call (legacy behavior).
+ *
+ * For transparent CLI-visible dispatch, prefer `epic_decide_phase` + lane
+ * dispatch via the architect's Task tool — see EPIC_MODE_BANNER. This unified
+ * path remains for back-compat and for callers that don't need visibility
+ * into the parallel coder agents.
+ */
+export declare function executeEpicRunPhase(args: EpicRunPhaseArgs): Promise<EpicRunPhaseResult>;
+/**
+ * NOTE: `epic_run_phase` is intentionally NOT exposed as a tool to the
+ * architect. The transparent decide-then-dispatch wave flow (`epic_decide_phase`
+ * → `epic_plan_waves` → Task dispatch per wave) is the ONLY supported flow,
+ * because it gives the user real-time visibility into each concurrent coder
+ * agent. The legacy unified-path function `executeEpicRunPhase` remains
+ * exported for tests and any composition users, but no ToolDefinition
+ * wraps it — so the architect cannot call it and accidentally fall back
+ * to the opaque path. This is a deliberate product decision: one flow,
+ * unambiguous, always-visible.
+ */
+/**
+ * Transparent decide-only tool. Returns the verdict (promote/demote/error)
+ * without dispatching coders. The architect should:
+ *  1. Call this after declaring scopes for all pending tasks.
+ *  2. Surface the verdict to the user.
+ *  3. If verdict is `promote`, call `epic_plan_waves` to get the wave plan,
+ *     then for each wave dispatch one `Task` per `taskId` in that wave —
+ *     ALL in one assistant message so the wave runs concurrently. Wait for
+ *     the wave to complete, then advance. Each Task is a visible subagent
+ *     the user can click into for live progress.
+ *  4. After each task completes (via `update_task_status`), call
+ *     `epic_record_divergence` to feed the calibration loop.
+ *
+ * This is the CLI-visibility flow. The legacy `epic_run_phase` bundles
+ * decide + dispatch into one opaque tool call where the user can't see
+ * the concurrent coder agents.
+ */
+export declare const epic_decide_phase: ToolDefinition;

package/dist/tools/index.d.ts

@@ -79,6 +79,9 @@ export type { ClassifiedFailure, FailureClassification, FailureCluster, } from '
 export { classifyAndCluster, classifyFailure, clusterFailures, } from '../test-impact/failure-classifier.js';
 export type { FlakyTestEntry } from '../test-impact/flaky-detector.js';
 export { computeFlakyScore, detectFlakyTests, isTestQuarantined, } from '../test-impact/flaky-detector.js';
+export { epic_plan_waves } from './epic-plan-waves';
+export { epic_record_divergence } from './epic-record-divergence';
+export { epic_decide_phase } from './epic-run-phase';
 export { generate_mutants } from './generate-mutants';
 export { lean_turbo_acquire_locks } from './lean-turbo-acquire-locks';
 export { lean_turbo_plan_lanes } from './lean-turbo-plan-lanes';

package/dist/tools/manifest.d.ts

@@ -119,4 +119,7 @@ export declare const TOOL_MANIFEST: {
     external_skill_reject: () => ToolDefinition;
     external_skill_delete: () => ToolDefinition;
     external_skill_revoke: () => ToolDefinition;
+    epic_decide_phase: () => ToolDefinition;
+    epic_plan_waves: () => ToolDefinition;
+    epic_record_divergence: () => ToolDefinition;
 };

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

@@ -407,6 +407,18 @@ export declare const TOOL_METADATA: {
         description: string;
         agents: never[];
     };
+    epic_decide_phase: {
+        description: string;
+        agents: "architect"[];
+    };
+    epic_plan_waves: {
+        description: string;
+        agents: "architect"[];
+    };
+    epic_record_divergence: {
+        description: string;
+        agents: "architect"[];
+    };
 };
 /** Union type of all valid tool names (the metadata keys). */
 export type ToolName = keyof typeof TOOL_METADATA;

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

@@ -0,0 +1,193 @@
+/**
+ * Epic Mode activation decision (Capability C).
+ *
+ * `decideEpicActivation(...)` is the pure heart of M3: given a plan, a
+ * co-change pair list, and the activation thresholds, it returns a
+ * structured `promote | demote` verdict with the rationale fields a
+ * caller can persist for audit. Pure function — no I/O.
+ *
+ * Three independent gates must all pass for promotion:
+ *
+ *   1. **p-threshold gate.** Compute the coupling coefficient `p` over
+ *      the plan's task graph using Capability A's `epicPairConflict` (via
+ *      Capability B's `computeCouplingReport`). Promote only when
+ *      `p <= activation_threshold`.
+ *
+ *   2. **Hot-module gate.** No task in scope may touch a Lean Turbo
+ *      "global" or "protected" path — these are the same lists Lean
+ *      Turbo already maintains (reused by import; not duplicated).
+ *      Touching a hot module forces serial regardless of `p`.
+ *
+ *   3. **Greenfield gate.** If the co-change history is sparse (fewer
+ *      than `min_commits_for_signal` distinct commits across the
+ *      analyzer output), the signal is too weak to trust per brief §4.2's
+ *      greenfield rule. Force serial.
+ *
+ * Default-serial-promote-on-proof (brief §4.2): when any gate fails or
+ * the data is missing, the decision is `demote`. Promotion requires
+ * positive evidence on every gate.
+ */
+import type { CoChangeEntry } from '../../tools/co-change-analyzer.js';
+import type { CouplingTask } from './coupling-report.js';
+/** Thresholds the caller supplies (typically derived from EpicConfigSchema). */
+export interface EpicActivationOptions {
+    /** Plan-wide p ceiling. Plans with p > activationThreshold are demoted. */
+    activationThreshold: number;
+    /** Greenfield floor on the analyzer's commit window. */
+    minCommitsForSignal: number;
+    /** NPMI floor for the co-change conflict signal — passed through to coupling. */
+    cochangeNpmiThreshold: number;
+    /** Minimum raw co-change count for the conflict signal. */
+    cochangeMinCoChanges: number;
+    /**
+     * Capability D (calibration) additions to the hot-module list. The static
+     * Lean Turbo predicates (`isGlobalFile` / `isProtectedPath`) always apply;
+     * these are normalised paths the calibration loop has promoted after
+     * observing divergent writes against the static set. Optional — falsy or
+     * empty means "no calibration overrides". Path matching is exact (post-
+     * `normalizePath`); callers compute that via `effectiveHotModules` in
+     * `./calibration-engine.ts`.
+     */
+    extraHotModules?: readonly string[];
+    /**
+     * Greenfield-smart Rule 1: whether the project is under git version control.
+     * The greenfield gate exists because co-change signals require git history
+     * to compute. When the project is not a git repo, there is no signal type
+     * to evaluate — the gate's premise is absent, so it passes trivially
+     * rather than fail-closed. Callers (typically `epic_run_phase`) resolve
+     * this via `isGitRepo(directory)` from `src/git/branch.ts`.
+     *
+     * Backward-compat: omitted or `undefined` reverts to legacy behavior
+     * (apply the `commitsObserved >= minCommitsForSignal` floor
+     * unconditionally). Callers should pass an explicit boolean.
+     */
+    isGitProject?: boolean;
+    /**
+     * Phase 13 (B20): task IDs the architect declared in `depends:` that
+     * don't resolve to ANY task in the plan. Typically an LLM typo. The
+     * gate fails closed with a dedicated `phantom dep` blocking reason so
+     * the architect sees the actual bad ID instead of being misled into
+     * hunting a non-existent cross-phase upstream. Pass alongside
+     * `crossPhaseUpstreams` (the two lists are disjoint).
+     */
+    phantomDeps?: readonly string[];
+    /**
+     * Phase 10 — predecessor-evidence gate redesign.
+     *
+     * Cross-phase upstream task IDs for the phase being decided: every
+     * task that lives in a strictly-prior phase AND is depended on by a
+     * task in the current phase. The gate verifies each one has a
+     * `swarm(task <id>):` marker in git log via `isUpstreamCommitted`.
+     *
+     * Empty array (the legacy default) ⇒ no cross-phase deps to check;
+     * predecessor evidence is vacuously satisfied. This is correct for
+     * Phase 1 (no prior phase), single-phase projects, and phases the
+     * architect explicitly declared as independent.
+     *
+     * Why this replaces the `commitsObserved >= minCommitsForSignal`
+     * floor: the floor was a statistical proxy for "do we have enough
+     * history to trust `p`?", but in small projects it permanently
+     * blocked parallelism (a 12-task project never reaches 20 commits).
+     * The structural check asks the actually-relevant question — "are
+     * the things this phase depends on actually in git?" — directly,
+     * regardless of project size. The architect's declared dep graph IS
+     * the parallelism specification (Lamport happens-before); Rule 2's
+     * commits ARE the synchronization point; this check ties them
+     * together.
+     *
+     * Callers (`epic_run_phase`) compute this from the plan's dep graph.
+     */
+    crossPhaseUpstreams?: readonly string[];
+    /**
+     * Predicate for the predecessor-evidence check above. Returns true
+     * when the given taskId has a `swarm(task <id>):` marker in git
+     * history. Same predicate Rule 3 uses at the lane planner — share
+     * one source of truth.
+     *
+     * Omitted ⇒ the gate treats every cross-phase upstream as
+     * uncommitted (fail-closed). Pair `crossPhaseUpstreams` with this
+     * predicate, or pass neither.
+     */
+    isUpstreamCommitted?: (taskId: string) => boolean;
+}
+/** Each gate's pass/fail outcome plus the evidence behind it. */
+export interface EpicActivationRationale {
+    pCheck: {
+        passed: boolean;
+        p: number;
+        threshold: number;
+    };
+    hotModuleCheck: {
+        passed: boolean;
+        touchedHotModules: string[];
+    };
+    greenfieldCheck: {
+        passed: boolean;
+        commitsObserved: number;
+        minCommits: number;
+        /**
+         * `true` when the caller flagged the project as non-git
+         * (`options.isGitProject === false`). In that case the gate is
+         * bypassed (`passed: true`) because the co-change signal does not
+         * apply — not because the history floor was met. Surfaced for audit
+         * so reviewers can distinguish "bypassed" from "satisfied".
+         */
+        bypassedNoGit?: boolean;
+        /**
+         * Phase 10: cross-phase upstream task IDs the gate consulted.
+         * Empty when the current phase has no cross-phase deps (Phase 1,
+         * single-phase plans, declared-independent phases).
+         *
+         * Phase 13 (B19): optional because pre-Phase-10 records on disk
+         * (`.swarm/evidence/epic-promotions.jsonl`) lack this field.
+         * Renderers MUST default to `[]` when reading historical records.
+         */
+        crossPhaseUpstreams?: string[];
+        /**
+         * Phase 10: cross-phase upstreams the predicate reported as NOT
+         * yet committed. Non-empty ⇒ the gate failed; the architect
+         * needs to wait for those tasks to commit before re-deciding.
+         *
+         * Phase 13 (B19): optional, same reason as above.
+         */
+        missingUpstreams?: string[];
+        /**
+         * Phase 13 (B20): dep IDs the architect declared that don't
+         * resolve to any task in the plan. Usually an LLM typo; the gate
+         * fails CLOSED so the architect can see the bad ID and fix the
+         * declaration. Distinct from `missingUpstreams` because phantom
+         * IDs aren't tasks that need to be "committed" — they don't
+         * exist at all, and the remediation is "fix the dep ID", not
+         * "wait for the upstream to land".
+         */
+        phantomDeps?: string[];
+    };
+}
+/** The verdict `decideEpicActivation` returns. */
+export interface EpicActivationVerdict {
+    decision: 'promote' | 'demote';
+    p: number;
+    rationale: EpicActivationRationale;
+    /** Plain-English reasons the verdict went the way it did — for logs and UI. */
+    blockingReasons: string[];
+}
+/**
+ * Decide whether the given tasks should be promoted to parallel execution
+ * via Lean Turbo's lane planner.
+ *
+ * Inputs are pre-resolved by the caller:
+ *  - `tasks`: every task in scope (typically the whole plan), with the
+ *    same `{ id, scope }` shape Capability B consumes. The caller
+ *    handles `readTaskScopes` / `files_touched` resolution and any
+ *    completed-task filtering.
+ *  - `cochangePairs`: the analyzer's output (unfiltered) plus the
+ *    `commitsObserved` count from `parseGitLog`. The greenfield gate
+ *    consults the count directly so the function stays pure.
+ *  - `options`: thresholds (typically read from
+ *    `turbo.epic.mode.*` + `turbo.epic.cochange.*`).
+ *
+ * Output: structured verdict the caller persists to
+ * `.swarm/evidence/epic-promotions.jsonl` and surfaces via
+ * `/swarm epic status`.
+ */
+export declare function decideEpicActivation(tasks: CouplingTask[], cochangePairs: CoChangeEntry[], commitsObserved: number, options: EpicActivationOptions): EpicActivationVerdict;