opencode-swarm 7.85.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/repo-graph/builder.d.ts

@@ -26,6 +26,8 @@ export declare const _internals: {
     extractPythonSymbols: typeof extractPythonSymbols;
     parseFileImports: typeof parseFileImports;
     extractFileOntology: typeof extractFileOntology;
+    stripComments: typeof stripComments;
+    computeUsedSymbols: typeof computeUsedSymbols;
 };
 /**
  * Add or update a node in the graph.
@@ -66,6 +68,16 @@ export declare function resolveModuleSpecifier(workspaceRoot: string, sourceFile
 /**
  * A parsed import with its specifier and type.
  */
+/**
+ * A single imported binding: the symbol's *exported* name in the target file
+ * and the *local* name it is bound to in the importing file (differs when an
+ * `as` alias or default import is used). Used to attribute call-site usage back
+ * to the correct exported symbol.
+ */
+interface ImportBinding {
+    imported: string;
+    local: string;
+}
 interface ParsedImport {
     /** The module specifier (e.g., './foo', 'lodash') */
     specifier: string;
@@ -73,8 +85,42 @@ interface ParsedImport {
     importType: 'default' | 'named' | 'namespace' | 'require' | 'sideeffect';
     /** Named imported symbols when statically detectable */
     importedSymbols: string[];
+    /** Alias-aware imported→local bindings for usage attribution */
+    bindings: ImportBinding[];
+    /** True for `export { x } from '...'` re-exports (symbols are re-exposed). */
+    reExport: boolean;
 }
+/**
+ * Strip line (`//…`) and block (`/* … *\/`) comments from JS/TS source while
+ * preserving string, template-literal, and regex-literal contents (DD-C010).
+ * Import specifiers live inside string literals, so strings must be kept
+ * intact; only comment spans are removed. This is a bounded single-pass scanner
+ * — not a full parser (AST parsing in the repo-graph init path would violate
+ * AGENTS.md invariant 1) — and it eliminates the most common source of false
+ * import edges: import-like text inside comments (`// import x from "y"`).
+ *
+ * It is string-aware (a `//` inside `"http://…"` is not a comment) and
+ * regex-aware (a regex literal such as `/[/*]/` must not be mistaken for the
+ * start of a block comment, which would otherwise run to EOF and delete real
+ * imports). Regex-vs-division is disambiguated by the previous significant
+ * character (REGEX_ALLOWED_AFTER).
+ */
+declare function stripComments(content: string): string;
 declare function parseFileImports(rawContent: string): ParsedImport[];
+/**
+ * Conservatively determine which imported bindings are actually referenced in
+ * the importing file's body.
+ *
+ * Heuristic: in a well-formed import statement, each local binding name appears
+ * exactly once. Counting occurrences of the local name across the
+ * comment-stripped file content, a count > 1 means at least one body reference.
+ * Strings are intentionally *not* stripped, so the bias is toward "used" — a
+ * conservative direction that avoids false dead-export positives. Bindings whose
+ * local name cannot be safely word-boundary matched are assumed used.
+ *
+ * @returns the *exported* names (binding.imported) judged to be used.
+ */
+declare function computeUsedSymbols(strippedContent: string, bindings: readonly ImportBinding[]): string[];
 /**
  * Result of scanning a single file for graph updates.
  */

package/dist/tools/repo-graph/query.d.ts

@@ -1,10 +1,35 @@
-import type { BlastRadiusResult, FileOntology, FileReference, GraphNode, LocalizationBlock, PackageBoundarySummary, RepoGraph, SymbolReference } from './types';
+import type { BlastRadiusResult, CallerReference, DeadExportsResult, FileOntology, FileReference, GraphNode, LocalizationBlock, PackageBoundarySummary, RepoGraph, SymbolReference } from './types';
 export declare function getGraphNode(graph: RepoGraph, input: string): GraphNode | undefined;
 export declare function resetQueryCache(): void;
 export declare function isGraphFresh(graph: RepoGraph | null, maxAgeMs?: number): boolean;
 export declare function getImporters(graph: RepoGraph, filePath: string): FileReference[];
 export declare function getDependencies(graph: RepoGraph, filePath: string): FileReference[];
 export declare function getSymbolConsumers(graph: RepoGraph, filePath: string, symbolName: string): SymbolReference[];
+/**
+ * Files that actually *reference* an exported symbol of `filePath` — call-site
+ * granularity, not just "imports the file". On schema >= 1.1.0 graphs this uses
+ * per-edge `usedSymbols`; on older graphs (or namespace imports) it falls back
+ * to import-level matching, flagged via `resolution: 'imported'`.
+ */
+export declare function getCallers(graph: RepoGraph, filePath: string, symbolName: string): CallerReference[];
+export interface DeadExportsOptions {
+    /** Max candidates returned (default 100). */
+    maxCandidates?: number;
+}
+/**
+ * Conservatively detect exported symbols with no detected in-repo reference.
+ *
+ * Scoping for precision (advisory "candidate" output, never a delete directive):
+ *   - Requires schema >= 1.1.0 (per-edge usedSymbols); otherwise returns
+ *     schemaSupported=false so the caller can prompt a rebuild.
+ *   - Only considers files imported by >= 1 other file — a file with no
+ *     importers is a likely public-API entry / CLI / test, not dead code.
+ *   - Skips files imported anywhere via namespace/side-effect/require/dynamic
+ *     imports, where per-symbol usage is unresolvable.
+ *   - Excludes framework-invoked roles (routes, CLIs, tests, agents, hooks,
+ *     middleware) and the synthetic 'default' export.
+ */
+export declare function getDeadExports(graph: RepoGraph, options?: DeadExportsOptions): DeadExportsResult;
 export declare function getBlastRadius(graph: RepoGraph, filePaths: string[], maxDepth?: number): BlastRadiusResult;
 export declare function getKeyFiles(graph: RepoGraph, topN?: number): GraphNode[];
 export declare function getFileOntology(graph: RepoGraph, filePath: string): FileOntology | null;

package/dist/tools/repo-graph/types.d.ts

@@ -7,7 +7,23 @@
  * Every other submodule imports from here.
  */
 export declare const REPO_GRAPH_FILENAME = "repo-graph.json";
-export declare const GRAPH_SCHEMA_VERSION = "1.0.0";
+/**
+ * Graph schema version.
+ *
+ * 1.1.0 added per-edge `usedSymbols` (imported symbols actually referenced in
+ * the importing file) and per-node `exportLines`, enabling the `callers` and
+ * `dead_exports` queries. Both fields are optional, so graphs written by older
+ * versions (1.0.0) still load — but `dead_exports` requires >= 1.1.0 data and
+ * self-gates via {@link isSchemaVersionAtLeast} rather than relying on the
+ * loader (which only checks that a version string is present, not its value).
+ */
+export declare const GRAPH_SCHEMA_VERSION = "1.1.0";
+/**
+ * Compare dotted numeric version strings (e.g. '1.1.0' >= '1.1.0').
+ * Missing/non-numeric segments are treated as 0. Returns true when `version`
+ * is greater than or equal to `minimum`.
+ */
+export declare function isSchemaVersionAtLeast(version: string | undefined, minimum: string): boolean;
 export declare const FILE_ROLE_VALUES: readonly ["api_route", "middleware", "service_module", "data_module", "swarm_tool", "agent", "hook", "config", "schema", "test_file", "cli_command", "documentation", "source_module"];
 export type FileRole = (typeof FILE_ROLE_VALUES)[number];
 export declare const ROUTE_METHOD_VALUES: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "ALL"];
@@ -73,6 +89,13 @@ export interface GraphNode {
     moduleName: string;
     /** Exported symbols from this file */
     exports: string[];
+    /**
+     * Definition line for each exported symbol, keyed by symbol name (1-based).
+     * Optional and best-effort: present on graphs built at schema >= 1.1.0,
+     * absent for symbols whose line could not be determined. Used to point
+     * `dead_exports` candidates at a location.
+     */
+    exportLines?: Record<string, number>;
     /** Imported module specifiers */
     imports: string[];
     /** Language/extension of the file */
@@ -98,6 +121,14 @@ export interface GraphEdge {
     importType: ImportType;
     /** Named symbols imported from the target, when statically detectable */
     importedSymbols?: string[];
+    /**
+     * The subset of the target's exported symbols (by their *exported* name)
+     * that are actually referenced in the source file's body — not merely
+     * imported. Computed at build time via a conservative, alias-aware textual
+     * scan (schema >= 1.1.0). Absent on namespace/side-effect/require/dynamic
+     * imports, where individual symbol usage is not statically resolvable.
+     */
+    usedSymbols?: string[];
 }
 export interface FileReference {
     file: string;
@@ -109,6 +140,47 @@ export interface SymbolReference {
     line?: number;
     importedAs: string;
 }
+/**
+ * A file that references a specific exported symbol of a target file.
+ * `resolution` records how confidently the usage was attributed:
+ *   - 'used'     → the symbol was found referenced in the source body
+ *   - 'imported' → fallback for graphs predating usedSymbols (schema < 1.1.0);
+ *                  the symbol is imported but body usage was not analyzed
+ */
+export interface CallerReference {
+    file: string;
+    resolution: 'used' | 'imported';
+}
+/**
+ * An exported symbol with no detected in-repo reference. Advisory only —
+ * regex-based analysis cannot see dynamic dispatch, string-keyed access, or
+ * usage through namespace/barrel re-exports, so this is a *candidate* for
+ * review, never a directive to delete.
+ */
+export interface DeadExportCandidate {
+    /** Module name (workspace-relative) of the file that owns the export */
+    file: string;
+    /** The exported symbol name */
+    symbol: string;
+    /** Definition line, when known (from exportLines) */
+    line?: number;
+    /** How many other in-repo files import this file at all */
+    importerCount: number;
+}
+export interface DeadExportsResult {
+    /** False when the graph predates schema 1.1.0 (rebuild required). */
+    schemaSupported: boolean;
+    /** Files whose exports were analyzed (imported by >= 1 other file). */
+    analyzedFiles: number;
+    /**
+     * Files skipped because at least one importer used a namespace/side-effect/
+     * require/dynamic import, making per-symbol usage unresolvable.
+     */
+    skippedUnresolvable: number;
+    candidates: DeadExportCandidate[];
+    /** Human-readable note describing scope and limitations of the result. */
+    note: string;
+}
 export interface BlastRadiusResult {
     target: string[];
     directDependents: string[];