opencode-swarm 7.86.0 → 7.87.1

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/memory/scoring.d.ts

@@ -7,6 +7,24 @@ export interface RecallScoringDiagnostics {
     noSignalCount: number;
     belowThresholdCount: number;
 }
+/**
+ * Recall scoring weight coefficients. Sum is 1.13 (scores are an unnormalised
+ * weighted sum; may exceed 1.0). minScore thresholds in DEFAULT_MEMORY_CONFIG
+ * are calibrated against these weights.
+ *
+ * Pinned by tests/unit/memory/scoring.test.ts to detect drift.
+ */
+export declare const SCORING_WEIGHTS: {
+    readonly textOverlap: 0.38;
+    readonly tagOverlap: 0.16;
+    readonly fileOverlap: 0.12;
+    readonly symbolOverlap: 0.08;
+    readonly taskTermOverlap: 0.08;
+    readonly scopeSpecificityBoost: 0.12;
+    readonly kindProfileBoost: 0.06;
+    readonly roleBoost: 0.05;
+    readonly confidence: 0.08;
+};
 export declare function sameScope(a: MemoryScopeRef, b: MemoryScopeRef): boolean;
 export declare function scopeAllowed(recordScope: MemoryScopeRef, allowedScopes: MemoryScopeRef[]): boolean;
 export declare function scoreMemoryRecord(record: MemoryRecord, request: RecallRequest): RecallResultItem | null;

package/dist/memory/sqlite-provider.d.ts

@@ -3,6 +3,12 @@ import { type JsonlMigrationReport } from './jsonl-migration';
 import type { MemoryCompactOptions, MemoryCompactResult, MemoryProposalStore, MemoryProvider, MemoryRecallUsageEvent, MemoryRecallUsageFilter } from './provider';
 import type { RecallScoringDiagnostics } from './scoring';
 import type { AppliedMemoryChange, MemoryListFilter, MemoryProposal, MemoryRecord, RecallRequest, RecallResultItem, ResolvedCuratorMemoryDecision } from './types';
+interface Migration {
+    version: number;
+    name: string;
+    sql: string;
+}
+export declare const MIGRATIONS: Migration[];
 export interface SQLiteJsonlImportResult {
     importedMemories: number;
     importedProposals: number;
@@ -14,6 +20,7 @@ export declare class SQLiteMemoryProvider implements MemoryProvider, MemoryPropo
     private readonly rootDirectory;
     private readonly config;
     private initialized;
+    private initPromise;
     private db;
     private ftsAvailable;
     private memories;
@@ -22,6 +29,7 @@ export declare class SQLiteMemoryProvider implements MemoryProvider, MemoryPropo
     constructor(rootDirectory: string, config?: Partial<MemoryConfig>);
     private databasePath;
     initialize(): Promise<void>;
+    private doInitialize;
     upsert(record: MemoryRecord): Promise<MemoryRecord>;
     get(id: string): Promise<MemoryRecord | null>;
     delete(id: string, reason?: string): Promise<void>;
@@ -75,9 +83,11 @@ export declare class SQLiteMemoryProvider implements MemoryProvider, MemoryPropo
     private insertEvent;
     private requireDb;
 }
+declare function splitSql(sql: string): string[];
 declare function buildFtsQuery(request: RecallRequest): string | null;
 declare function extractFtsTerms(text: string): Set<string>;
 export declare const _test_exports: {
+    splitSql: typeof splitSql;
     buildFtsQuery: typeof buildFtsQuery;
     extractFtsTerms: typeof extractFtsTerms;
     FTS_SCHEMA_MIGRATION_NAME: string;

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;