opencode-swarm 7.189.0 → 7.190.1

package/dist/epic/learning.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Epic v2 C6 — what an epic learns from its own outcomes (pure).
+ *
+ * Two signals, both learned from the per-task outcomes `epic_next_wave`
+ * records when it closes a wave (`EpicTaskOutcome`, see `wave-close.ts`),
+ * and both used ONLY by the component planner (`components.ts`) — they are
+ * analysis, never write authorization:
+ *
+ *  1. Learned scope expansion. A task that declared D and wrote f without
+ *     declaring it is evidence that work on D also touches f:
+ *     w(d → f) += 1 for every d ∈ D. The planner's conflict graph uses
+ *       scope*(t) = scope(t) ∪ { f : Σ_{d ∈ scope(t)} w(d → f) ≥ 1 }.
+ *     scope* only ADDS path-conflict edges; the wave still freezes the
+ *     DECLARED scopes, which the dispatch gate checks for drift and its
+ *     parallel verdict reads. Because the planner is stricter than the
+ *     verdict (a superset of its edges), every multi-task wave it picks
+ *     stays `all_disjoint` under the verdict (property-tested). Co-change
+ *     coupling keeps using the declared scopes: its "exclusively owns one
+ *     side" rule is not monotone in the scope, so expanding it could REMOVE
+ *     a verdict conflict.
+ *
+ *  2. Decaying hot set. Per file, incidents α_f and exposures β_f:
+ *       incidents — undeclared write 1.0 (the written file); merge-back
+ *       failure 0.5, Stage B failure 0.25 per failure, rework
+ *       0.25 × min(generation − 1, 4) and reopen 0.5 per reopen, each
+ *       charged to every declared FILE entry of the task (the merge-status
+ *       registry records no conflict files, so a merge failure is charged
+ *       to the declared files);
+ *       exposures — β += 1 per declared FILE entry of every resolved task.
+ *     A declared entry that is a directory (on disk, or covering another
+ *     path of the same outcome) is never charged or exposed: one troubled
+ *     `src`-scoped task must not make everything under `src/` hot.
+ *     A task run again after a reopen is charged only the DELTA of its
+ *     counters over its previous outcome (`previous`), when that previous
+ *     outcome was already learned.
+ *     Beta prior with mean m0 = 0.1 and strength 2 (a0 = 0.2, b0 = 1.8):
+ *       r(f) = (a0 + α_f) / (a0 + b0 + α_f + β_f).
+ *     Strongest-co-writer discount: α'_f = α_f − m_f when the strongest
+ *     learned co-writer m_f = max_d w(d → f) ≥ 1 (an active expansion edge
+ *     already keeps that declarer apart from f's owners), else α'_f = α_f.
+ *     f is HOT ⇔ α'_f ≥ 1 ∧ r(α'_f, β_f) − m0 > hot_excess (default 0.25). A task
+ *     whose declared scope lists a hot file (exact normalized path) runs
+ *     alone (exclusive). Hot
+ *     needs EXCESS evidence: an empty or clean history has no hot file and
+ *     no expansion, so the cold start is neutral (no R_C product).
+ *
+ * Decay keeps both bounded and current: × `decay_per_epic` (0.7) of the
+ * project prior at every epic close that learned something, and age decay
+ * in WHOLE half-lives — × 0.5^floor(Δdays / `half_life_days` (60)) since
+ * the state was last written — so an observation keeps its full weight for
+ * a whole half-life; entries below 0.05 are dropped and at most
+ * {@link MAX_EPIC_LEARNING_FILES} files (lowest α + β evicted) and
+ * {@link MAX_EPIC_LEARNING_EDGES} co-write edges (lowest weight evicted) are
+ * kept. Persistence (project prior + epic posterior) is `learning-store.ts`.
+ */
+import { type EpicConfigSource } from './config.js';
+import type { EpicTaskOutcome } from './lifecycle.js';
+/** Files with learned statistics kept (lowest α + β evicted first). */
+export declare const MAX_EPIC_LEARNING_FILES = 2000;
+/** Learned co-write edges kept (lowest weight evicted first). */
+export declare const MAX_EPIC_LEARNING_EDGES = 2000;
+/** Entries whose mass falls below this after decay are dropped. */
+export declare const EPIC_LEARNING_DROP_BELOW = 0.05;
+/** Prior mean incident rate m0 and its strength (a0 + b0). */
+export declare const EPIC_LEARNING_PRIOR_MEAN = 0.1;
+export declare const EPIC_LEARNING_PRIOR_STRENGTH = 2;
+/** Minimum incident mass before a file can be hot. */
+export declare const EPIC_HOT_MIN_ALPHA = 1;
+/** Summed co-write weight at which a learned file joins scope*. */
+export declare const EPIC_EXPANSION_MIN_WEIGHT = 1;
+export declare const EPIC_LEARNING_INCIDENT_WEIGHTS: Readonly<{
+    undeclared: 1;
+    mergeFailurePerDeclared: 0.5;
+    stageBFailure: 0.25;
+    reworkPerGeneration: 0.25;
+    reworkMaxGenerations: 4;
+    reopen: 0.5;
+}>;
+/** Resolved `epic.learning.*` settings. */
+export interface EpicLearningSettings {
+    enabled: boolean;
+    decayPerEpic: number;
+    halfLifeDays: number;
+    hotExcess: number;
+}
+export declare const DEFAULT_EPIC_LEARNING_SETTINGS: EpicLearningSettings;
+export declare function resolveEpicLearningSettings(config: EpicConfigSource): EpicLearningSettings;
+export interface EpicFileStats {
+    /** Incident mass α_f. */
+    alpha: number;
+    /** Exposure mass β_f. */
+    beta: number;
+}
+/** In-memory learning statistics (paths normalized, never `.swarm/`). */
+export interface EpicLearningStats {
+    files: Map<string, EpicFileStats>;
+    /** from (declared) → to (co-written undeclared) → weight. */
+    edges: Map<string, Map<string, number>>;
+}
+/** Learned co-write weights, read-only (the planner's view). */
+export type EpicCoWriteIndex = ReadonlyMap<string, ReadonlyMap<string, number>>;
+export declare function emptyEpicLearning(): EpicLearningStats;
+export declare function isEpicLearningEmpty(stats: EpicLearningStats): boolean;
+export declare function cloneEpicLearning(stats: EpicLearningStats): EpicLearningStats;
+/** Normalized, unique paths learning may keep (never `.swarm/` or absolute). */
+export declare function learnablePaths(files: readonly string[]): string[];
+/**
+ * Files written that the declared scope does not cover (a declared
+ * directory covers every file beneath it, segment-aware). Sorted, unique,
+ * normalized.
+ */
+export declare function undeclaredFiles(declaredScope: readonly string[], actualFiles: readonly string[]): string[];
+export interface EpicLearningOptions {
+    /**
+     * Whether a declared entry is a directory on disk (never charged or
+     * exposed). Absent ⇒ only entries covering another path of the same
+     * outcome count as directories.
+     */
+    isDirectory?: (path: string) => boolean;
+    /**
+     * Waves up to this seq were already learned: a re-run task whose
+     * `previous` outcome is among them is charged only the delta of its
+     * counters. Absent ⇒ every outcome is charged in full (the record
+     * fallback, where the earlier outcome was never learned separately).
+     */
+    learnedThroughWaveSeq?: number;
+}
+/**
+ * The learning increments of resolved task outcomes (removed tasks never
+ * ran and teach nothing). Pure (the directory probe is injected); the
+ * caller merges the result.
+ */
+export declare function epicLearningFromOutcomes(outcomes: readonly EpicTaskOutcome[], options?: EpicLearningOptions): EpicLearningStats;
+/** a ⊕ b (new object; inputs untouched). */
+export declare function mergeEpicLearning(a: EpicLearningStats, b: EpicLearningStats): EpicLearningStats;
+/** Every mass × factor (new object). */
+export declare function scaleEpicLearning(stats: EpicLearningStats, factor: number): EpicLearningStats;
+/**
+ * Age decay in WHOLE half-lives: 0.5^floor(Δdays / halfLifeDays) — an
+ * observation keeps its full weight for a whole half-life (a single
+ * co-write keeps expanding scopes until then). 1 for a future or unknown
+ * timestamp.
+ */
+export declare function epicTimeDecayFactor(updatedAtIso: string | null | undefined, nowMs: number, halfLifeDays: number): number;
+/**
+ * Drop entries below {@link EPIC_LEARNING_DROP_BELOW} and keep at most the
+ * file / edge caps (lowest mass evicted; ties by path). New object.
+ */
+export declare function boundEpicLearning(stats: EpicLearningStats): EpicLearningStats;
+/** r(f) = (a0 + α) / (a0 + b0 + α + β). */
+export declare function epicIncidentRate(stats: EpicFileStats): number;
+export declare function isEpicHotFile(stats: EpicFileStats, hotExcess: number): boolean;
+/**
+ * The incident mass the hot predicate judges (the strongest-co-writer
+ * discount): α' = max(0, α − m) when the file's strongest learned co-writer
+ * m = max_d w(d → f) is an ACTIVE scope-expansion edge (m ≥
+ * {@link EPIC_EXPANSION_MIN_WEIGHT}), else α. Undeclared writes that one
+ * declared file keeps explaining are already handled by scope expansion
+ * (the declarer now conflicts with the file's owners), so they must not
+ * ALSO make the file hot and serialize everyone declaring it; writes from
+ * several different declarers (a file that attracts undeclared writes
+ * from all over) and the other incidents still count.
+ */
+export declare function epicHotIncidentMass(stats: EpicFileStats, strongestCoWriter: number): number;
+/** The hot predicate's evidence for one file (`/swarm epic learning`). */
+export interface EpicHotEvidence {
+    /** Raw incident mass α. */
+    alpha: number;
+    /** α' after the strongest-co-writer discount. */
+    countedAlpha: number;
+    beta: number;
+    /** r(α', β). */
+    rate: number;
+}
+export declare function epicHotEvidence(stats: EpicLearningStats, file: string): EpicHotEvidence;
+/**
+ * Hot files, hottest first (ties by path) — THE hot predicate (planner,
+ * sizing, shaping, report and commands all use it): {@link isEpicHotFile}
+ * over the discounted incident mass ({@link epicHotIncidentMass}).
+ */
+export declare function epicHotFiles(stats: EpicLearningStats, hotExcess: number): string[];
+/**
+ * scope*(t) = scope(t) ∪ { f : Σ_{d ∈ scope(t)} w(d → f) ≥ 1 } (normalized;
+ * declared entries first, learned files appended sorted). Analysis only.
+ */
+export declare function expandEpicScope(scope: readonly string[], coWrites: EpicCoWriteIndex | null): string[];
+export interface EpicLearningSummary {
+    files: number;
+    edges: number;
+    hotFiles: string[];
+    topCoWrites: Array<{
+        from: string;
+        to: string;
+        weight: number;
+    }>;
+}
+/** A bounded human summary (status / commands). */
+export declare function summarizeEpicLearning(stats: EpicLearningStats, hotExcess: number, limit?: number): EpicLearningSummary;

package/dist/epic/legacy-migration.d.ts

@@ -0,0 +1,26 @@
+/**
+ * One-time retirement of Epic v1 session state (Epic v2 C1a).
+ *
+ * Epic v1 kept a per-session "Epic on" flag in the coordination namespace
+ * `turbo.epic.session` with `.swarm/epic-state.json` as its projection. v2
+ * epics are plan-scoped and opened only by `/swarm epic start`, so v1 state
+ * is never imported as an open epic: it is retired here — rows deleted, the
+ * projection renamed to `.imported` — and any session that was still "on"
+ * yields an advisory to run `/swarm epic start`.
+ *
+ * Runs only inside `/swarm epic status` (never on a probe/hot path). Opens
+ * swarm.db only when it already exists. Idempotent: once retired there is
+ * nothing left to find.
+ */
+/** The retired v1 coordination namespace. */
+export declare const LEGACY_EPIC_SESSION_NAMESPACE = "turbo.epic.session";
+export interface LegacyEpicMigrationResult {
+    rowsRemoved: number;
+    /** Sessions that still had Epic v1 switched on. */
+    activeSessions: number;
+    fileArchivedTo: string | null;
+    errors: string[];
+}
+export declare function retireLegacyEpicSessionState(directory: string): LegacyEpicMigrationResult;
+/** Status lines for a non-empty migration result (empty otherwise). */
+export declare function describeLegacyEpicMigration(result: LegacyEpicMigrationResult): string[];

package/dist/epic/lifecycle.d.ts

@@ -0,0 +1,437 @@
+/**
+ * Epic v2 lifecycle (C1a): one open epic per project, bound to one plan.
+ *
+ * Authority: the coordination row in namespace {@link EPIC_LIFECYCLE_NAMESPACE}
+ * (entity key = epicKey). The sentinel `.swarm/epic/epic.json` is a JSON
+ * projection of that row whose only job is to make "Epic is off" cost exactly
+ * ONE `existsSync` on every hot-path seam: a project that never opened an
+ * epic has no sentinel, so no probe ever opens swarm.db, reads config, or
+ * reads the plan.
+ *
+ * Probe order (`getOpenEpic`): sentinel → row → config → identity. No memo,
+ * no migration, no writes. A row whose plan identity no longer matches the
+ * current plan (plan renamed or replaced — a new ledger root) is ORPHANED:
+ * the probe answers "no open epic"; `/swarm epic status` explains and
+ * `/swarm epic close --abandon` repairs.
+ *
+ * Lifecycle lock (M-d): every sentinel mutation runs INSIDE the coordination
+ * store's `BEGIN IMMEDIATE` transaction (`withCoordinationTransaction`), so
+ * the row write and the sentinel write/delete are serialized against every
+ * other lifecycle writer in every process:
+ *   - start: only the CAS winner (row created with expectedRevision null)
+ *     writes the sentinel; a sentinel-write failure rolls the row back.
+ *   - close/repair: the row is deleted (revision CAS) and the sentinel is
+ *     removed only when it still names the same epicKey + token
+ *     (compare-and-delete), so a late close can never delete a newer epic's
+ *     sentinel.
+ */
+import type { EpicWaveComponents } from './components.js';
+import { isEpicModeConfigEnabledForDirectory } from './config-gate.js';
+import type { EpicSizingVerdict } from './sizing.js';
+/** Coordination namespace of the authoritative epic row. */
+export declare const EPIC_LIFECYCLE_NAMESPACE = "turbo.epic.lifecycle";
+/** Project-relative path of the sentinel projection. */
+export declare const EPIC_SENTINEL_RELATIVE_PATH: string;
+export type EpicLifecycleStatus = 'open' | 'closing';
+/** One co-change pair recorded with a wave (threshold-passing, in-wave). */
+export interface EpicCochangePair {
+    fileA: string;
+    fileB: string;
+    npmi: number;
+    coChangeCount: number;
+}
+/** Snapshot of a worktree merge-back failure observed for a wave task. */
+export interface EpicMergeFailureSnapshot {
+    outcome: string;
+    stage: string;
+    message: string;
+    at: number | null;
+}
+/**
+ * One wave issued by `epic_next_wave` (Epic v2 C2). `files` are the FROZEN
+ * declared scopes of the wave's tasks at issue time; later commits compare
+ * against them (divergence now, the dispatch gate in C4).
+ */
+export interface EpicWaveRecord {
+    seq: number;
+    phase: number;
+    /**
+     * `parallel` (tasks of conflict-free components), `exclusive` (a task
+     * that runs alone), or `serial-component` (one task of a densely coupled
+     * component; no other ready task could join it). See `components.ts`.
+     */
+    kind: 'parallel' | 'exclusive' | 'serial-component';
+    taskIds: string[];
+    files: Record<string, string[]>;
+    /** ≤ 256 threshold-passing pairs within the wave's files; null = co-change off. */
+    cochange: {
+        pairs: EpicCochangePair[];
+        threshold: {
+            npmi: number;
+            minCoChanges: number;
+        };
+    } | null;
+    /**
+     * Epic v2 C5: the phase's components when the wave was issued (pending
+     * task → component, component modes/densities). Absent on waves issued
+     * before C5.
+     */
+    components?: EpicWaveComponents;
+    /** HEAD when the wave was issued (null: non-git / unborn). */
+    baseHead: string | null;
+    issuedAt: string;
+    closedAt?: string;
+    closeHead?: string | null;
+    status: 'issued' | 'closed' | 'aborted';
+    abortReason?: string;
+    /** Merge-back failures observed while the wave was blocked (snapshots). */
+    mergeFailures?: Record<string, EpicMergeFailureSnapshot>;
+    /**
+     * Wave-level undeclared files from the git fallback (changed since
+     * `baseHead`, not declared by any wave task, not attributed to a task).
+     */
+    undeclared?: string[];
+}
+/** How one wave task was resolved, recorded when its wave closes. */
+export interface EpicTaskOutcome {
+    taskId: string;
+    phase: number;
+    waveSeq: number;
+    resolution: 'completed' | 'closed' | 'removed';
+    resolvedAt: string;
+    /** Evidence workflow generation (uncapped; 0 = no evidence). */
+    generation: number;
+    /**
+     * LOWER BOUNDS: `stage_a_failed` / `stage_b_failed` entries in the
+     * evidence workflow `retryHistory`, which keeps only the last 3 entries.
+     */
+    stageAFailures: number;
+    stageBFailures: number;
+    /** Merge-back failure snapshot observed while the wave was blocked. */
+    mergeFailure: {
+        outcome: string;
+        stage: string;
+    } | null;
+    declared: string[];
+    undeclared: string[];
+    /** Where `undeclared` came from. */
+    attribution: 'session' | 'git-single-task' | 'unavailable' | 'no-git';
+    /** Ledger transitions out of `completed` for this task since the epic started. */
+    reopened: number;
+    /**
+     * Epic v2 C6: the counters of this task's earlier outcome when it ran
+     * again (reopened) — learning charges only the delta.
+     */
+    previous?: {
+        waveSeq: number;
+        generation: number;
+        stageBFailures: number;
+        reopened: number;
+    };
+    /**
+     * The commit proving the task's work is on the epic branch (Epic v2 C3),
+     * mirrored to `ref` (`refs/swarm/epics/<epicKey>/tasks/<id>`, see
+     * `markers.ts`): the task's newest `swarm(task <id>):` commit for this
+     * plan inside the wave (`landing-commit` — its coder's landing merge or a
+     * residue commit), else HEAD at wave close (`wave-close-head`), or a
+     * commit re-adopted by `/swarm epic status --repair-refs` (`repaired`).
+     * Completed tasks only; `no-git` epics record no commit.
+     */
+    marker: {
+        ref: string | null;
+        sha: string | null;
+        provenance: EpicTaskMarkerProvenance;
+    } | null;
+}
+export type EpicTaskMarkerProvenance = 'landing-commit' | 'wave-close-head' | 'repaired' | 'no-git';
+/** Per-phase lifecycle as seen by `epic_next_wave` / `epic_phase_review`. */
+export interface EpicPhaseRecord {
+    status: 'active' | 'review' | 'complete';
+    /** True when the phase was already finished when the epic started. */
+    completeAtStart?: boolean;
+    reviewRuns: number;
+    /** Newest last; at most {@link EPIC_PHASE_VERDICTS_KEEP}. */
+    verdicts: string[];
+}
+/** Phase-review verdict strings kept per phase in the record. */
+export declare const EPIC_PHASE_VERDICTS_KEEP = 20;
+/**
+ * Where an epic's commits go (`epic.commit_policy`, default
+ * `epic-branch`): a dedicated `swarm/epic/<epicKey>` branch checked out at
+ * start and landed at close, or the branch that was current at start.
+ */
+export type EpicCommitPolicy = 'epic-branch' | 'current-branch';
+/** How `/swarm epic close` lands the epic branch (default `squash`). */
+export type EpicLandMode = 'squash' | 'merge' | 'none';
+export interface EpicRecordConfig {
+    /** Non-git epics always record 'current-branch' (nothing to branch). */
+    commitPolicy: EpicCommitPolicy;
+    isolation: 'worktree' | 'main-tree-nogit';
+    /** Wave width cap honoured by `epic_next_wave` (1 for non-git, M-i). */
+    maxParallel: number;
+}
+export interface EpicRecordGit {
+    isRepo: boolean;
+    baseCommit: string | null;
+    originalBranch: string | null;
+    /**
+     * `swarm/epic/<epicKey>` — written ONLY after `git checkout -b` succeeded
+     * (M-e); null for current-branch / non-git epics.
+     */
+    epicBranch: string | null;
+}
+/** A landing attempt that did not land (close stays resumable). */
+export interface EpicLandingAttempt {
+    mode: EpicLandMode;
+    status: 'conflict' | 'failed';
+    at: string;
+    conflictFiles: string[];
+    detail: string;
+}
+export interface EpicClosingInfo {
+    requestedAt: string;
+    outcome: EpicCloseOutcome;
+    /** Landing mode of the latest close request (null: abandon / no branch). */
+    land: EpicLandMode | null;
+    /** Last landing attempt that failed; null until one fails. */
+    lastLandingAttempt: EpicLandingAttempt | null;
+}
+export type EpicCloseOutcome = 'completed' | 'abandoned' | 'abandoned-by-swarm-close';
+export interface EpicRecordV1 {
+    schema: 'epic-record-v1';
+    epicKey: string;
+    /** Per-start nonce; the sentinel compare-and-delete matches it too. */
+    token: string;
+    planId: string;
+    planIdentityHash: string;
+    planEpoch: string | null;
+    planKey: string;
+    /** sha256 of the plan ledger's root line (sync epoch proxy); null = no ledger. */
+    ledgerRootDigest: string | null;
+    status: EpicLifecycleStatus;
+    startedAt: string;
+    startedBySession: string;
+    forced: boolean;
+    structureHashAtStart: string;
+    config: EpicRecordConfig;
+    git: EpicRecordGit;
+    sizing: EpicSizingVerdict;
+    /**
+     * Epic v2 C6: sha256 of the project prior (`.swarm/epic-prior/
+     * learning.json`) the epic's posterior was copied from at start; null
+     * when there was no readable prior or learning is disabled.
+     */
+    priorDigest: string | null;
+    closing: EpicClosingInfo | null;
+    /** Waves issued by `epic_next_wave`, in issue order (Epic v2 C2). */
+    waves: EpicWaveRecord[];
+    /** Seq of the wave currently issued and not yet closed. */
+    activeWaveSeq: number | null;
+    /** Outcome of every task resolved through a closed wave, by task id. */
+    tasks: Record<string, EpicTaskOutcome>;
+    /** Phase lifecycle keyed by phase id (string). */
+    phases: Record<string, EpicPhaseRecord>;
+}
+/** Sentinel projection: enough to identify the row it mirrors. */
+export interface EpicSentinel {
+    schema: 'epic-sentinel-v1';
+    epicKey: string;
+    token: string;
+    planId: string;
+    startedAt: string;
+}
+/** Raised when the lifecycle row exists but cannot be trusted. */
+export declare class EpicStateUnreadableError extends Error {
+    constructor(message: string);
+}
+/**
+ * DI seam (AGENTS.md invariant 7). Restore in `afterEach`.
+ */
+export declare const _internals: {
+    isEpicModeConfigEnabledForDirectory: typeof isEpicModeConfigEnabledForDirectory;
+    now: () => number;
+    /** Bounded warn-once set so a corrupt row does not spam every probe. */
+    warnedDirectories: Set<string>;
+};
+export declare function epicSentinelPath(directory: string): string;
+/**
+ * The one hot-path check: does the sentinel exist? Exactly one `existsSync`.
+ * Never follows raw `..` segments into an ancestor's `.swarm/`.
+ */
+export declare function epicSentinelExists(directory: string): boolean;
+/** Ref-safe, filename-safe epic key: `<planId≤40>-<planKey≤12>`. */
+export declare function computeEpicKey(planId: string, planKey: string): string;
+/** Identity fields of the current plan used for the orphan check. */
+export interface EpicPlanIdentity {
+    planId: string;
+    planIdentityHash: string;
+}
+export declare function planIdentityOf(plan: {
+    swarm: string;
+    title: string;
+}): EpicPlanIdentity;
+/**
+ * sha256 of the plan ledger's first line. The ledger is append-only and a
+ * new plan (save_plan of a different plan, reset, recovery re-root) starts a
+ * new root line, so the digest is a synchronous proxy for the plan epoch.
+ * Returns null when there is no ledger.
+ */
+export declare function readLedgerRootDigest(directory: string): string | null;
+/** Synchronous, bounded read of the current plan identity from plan.json. */
+export declare function readCurrentPlanIdentity(directory: string): EpicPlanIdentity | null;
+export declare function parseEpicRecord(payload: string): EpicRecordV1;
+/** Read and validate the sentinel; null when absent, invalid, or oversized. */
+export declare function readEpicSentinel(directory: string): EpicSentinel | null;
+/** Why a row-backed epic is not usable for the current plan. */
+export type EpicOrphanReason = 'plan-missing' | 'plan-renamed-or-replaced' | 'plan-ledger-replaced';
+/** Pure identity comparison (exported for tests and status). */
+export declare function evaluateEpicIdentity(record: EpicRecordV1, current: EpicPlanIdentity | null, ledgerRootDigest: string | null): EpicOrphanReason | null;
+/** Full diagnostic view used by `/swarm epic status` / close / repair. */
+export interface EpicInspection {
+    sentinelPresent: boolean;
+    sentinel: EpicSentinel | null;
+    /** Validated record (null when no row, or when `unreadable` is set). */
+    record: EpicRecordV1 | null;
+    /** Row entity keys present (even when unparseable). */
+    rowKeys: string[];
+    unreadable: string | null;
+    orphanReason: EpicOrphanReason | null;
+    configEnabled: boolean;
+}
+/**
+ * Inspect every piece of lifecycle state without writing. Unlike the probe
+ * it reads rows even when the sentinel is absent (repair needs that), so it
+ * is only for `/swarm epic *` and `/swarm close` finalization. Opens the DB
+ * only when swarm.db already exists.
+ */
+export declare function inspectEpic(directory: string, plan?: {
+    swarm: string;
+    title: string;
+} | null): EpicInspection;
+/**
+ * The open epic for the current plan, or null. Probe order: sentinel → row →
+ * config → identity; no memo, no writes. Throws {@link EpicStateUnreadableError}
+ * when the sentinel exists and the row is present but untrustworthy.
+ *
+ * @param plan - when supplied, its identity is used instead of reading
+ *        `.swarm/plan.json`.
+ */
+export declare function getOpenEpic(directory: string, plan?: {
+    swarm: string;
+    title: string;
+} | null): EpicRecordV1 | null;
+/**
+ * Boolean probe for hot-path seams. Sentinel-first (one `existsSync` when
+ * Epic is off); corrupt state ⇒ false + one critical warning per directory.
+ */
+export declare function isEpicOpenForProject(directory: string): boolean;
+export type EpicCreateOutcome = {
+    outcome: 'created';
+    record: EpicRecordV1;
+} | {
+    outcome: 'exists';
+    existingKeys: string[];
+};
+/**
+ * CAS-create the epic row and (as the winner only) write the sentinel, both
+ * under the lifecycle lock. A sentinel-write failure rolls the row back.
+ */
+export declare function createEpicRecord(directory: string, record: EpicRecordV1): EpicCreateOutcome;
+/**
+ * The epic row would outgrow the store payload cap. Distinct from a generic
+ * store failure so callers can surface the remedy instead of the raw
+ * `payload must contain 1..1048576 characters`.
+ */
+export declare class EpicRecordTooLargeError extends Error {
+    constructor(epicKey: string);
+}
+/** True when `record` would serialize past {@link MAX_EPIC_RECORD_PAYLOAD_CHARS}. */
+export declare function epicRecordPayloadTooLarge(record: EpicRecordV1): boolean;
+/**
+ * Revision-checked read-modify-write of the epic row. Returns the updated
+ * record, or null when the row vanished or (with `expectedToken`) belongs to
+ * a different start of the same epicKey. Throws on contention/corruption, and
+ * throws {@link EpicRecordTooLargeError} when the row would outgrow the store
+ * payload cap.
+ */
+export declare function updateEpicRecord(directory: string, epicKey: string, mutate: (record: EpicRecordV1) => EpicRecordV1, expectedToken?: string | null): EpicRecordV1 | null;
+/** A phase as the Epic phase order sees it (id + plan status). */
+export interface EpicPhaseRef {
+    id: number;
+    status?: string;
+}
+/**
+ * Whether `phase` is done for Epic: recorded complete on the epic (by
+ * `phase_complete`, or finished before the epic started), or closed in the
+ * plan. The plan's own `complete` status is NOT used: it turns `complete`
+ * as soon as every task completes, before the phase review ran.
+ */
+export declare function isEpicPhaseDone(record: Pick<EpicRecordV1, 'phases'>, phase: EpicPhaseRef): boolean;
+/** The epic's current phase: the first phase (plan order) not done. */
+export declare function epicCurrentPhase(record: Pick<EpicRecordV1, 'phases'>, phases: readonly EpicPhaseRef[]): number | null;
+/** Bounded read of the plan's phase order from `.swarm/plan.json`. */
+export declare function readPlanPhaseRefs(directory: string): EpicPhaseRef[] | null;
+/** A plan task as Epic's hot-path seams see it. */
+export interface EpicPlanTaskRef {
+    id: string;
+    phase: number;
+    description: string | undefined;
+    files: string[];
+}
+/**
+ * Bounded synchronous lookup of one task in `.swarm/plan.json` (the derived
+ * projection — enough for membership and the commit subject). Null when the
+ * plan is unreadable or the task is not in it.
+ */
+export declare function readPlanTaskRef(directory: string, taskId: string): EpicPlanTaskRef | null;
+export type EpicPhaseCompleteOutcome = {
+    outcome: 'recorded' | 'already-complete';
+    record: EpicRecordV1;
+} | {
+    outcome: 'no-open-epic';
+} | {
+    outcome: 'not-current-phase';
+    currentPhase: number | null;
+};
+/**
+ * Record `phase` complete on the open epic (Epic v2 C2; called by
+ * `phase_complete` on success while an epic is open). Phases are
+ * iterations: only the epic's CURRENT phase can be completed — completing
+ * another phase out of order is refused (`not-current-phase`) so it cannot
+ * skip the current phase's waves. Idempotent for an already-complete phase.
+ * Throws on unreadable state / contention.
+ */
+export declare function markEpicPhaseComplete(directory: string, phase: number, planPhases?: readonly EpicPhaseRef[]): EpicPhaseCompleteOutcome;
+/**
+ * CAS the row to `closing` (first close step; idempotent). A resumed close
+ * keeps the original request time and outcome — except that an explicit
+ * abandon upgrades a `completed` close whose landing never finished — and
+ * records the landing mode of the latest request.
+ */
+export declare function markEpicClosing(directory: string, epicKey: string, outcome: EpicCloseOutcome, expectedToken?: string | null, land?: EpicLandMode | null): EpicRecordV1 | null;
+/**
+ * Record the epic branch once `git checkout -b` succeeded (M-e). Returns the
+ * updated record, or null when the row vanished / belongs to another start.
+ */
+export declare function recordEpicBranch(directory: string, epicKey: string, expectedToken: string, epicBranch: string): EpicRecordV1 | null;
+/** Record a failed landing attempt on a `closing` row (close stays resumable). */
+export declare function recordEpicLandingAttempt(directory: string, epicKey: string, expectedToken: string, attempt: EpicLandingAttempt): EpicRecordV1 | null;
+export interface EpicDeleteResult {
+    rowsDeleted: string[];
+    sentinelDeleted: boolean;
+}
+/**
+ * Delete the epic row(s) then the sentinel (compare-and-delete), under the
+ * lifecycle lock. `epicKey` null deletes every lifecycle row WITHOUT parsing
+ * payloads (corrupt-state repair for `close --abandon`).
+ */
+export declare function deleteEpicState(directory: string, epicKey: string | null, token: string | null): EpicDeleteResult;
+export type EpicSentinelRepair = 'none' | 'removed-stale-sentinel' | 'restored-sentinel' | 'rewrote-mismatched-sentinel';
+/**
+ * Reconcile the sentinel with the authoritative row under the lifecycle lock:
+ *  - sentinel without any row  → remove the sentinel (row confirmed absent);
+ *  - open row without sentinel → restore the sentinel from the row;
+ *  - sentinel naming another epic than the row → rewrite it from the row.
+ * Corrupt rows are left alone (repair is `close --abandon`).
+ */
+export declare function repairEpicSentinel(directory: string): EpicSentinelRepair;