opencode-swarm 7.189.0 → 7.190.1

package/dist/epic/markers.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Epic v2 C3 — git refs as the epic's durable markers.
+ *
+ * Under `refs/swarm/epics/<epicKey>/` an open git epic keeps:
+ *
+ *   - `base`         → the commit the epic started from (written at start);
+ *   - `waves/<seq>`  → HEAD when wave `<seq>` closed;
+ *   - `tasks/<id>`   → the commit proving task `<id>`'s work is on the epic
+ *                      branch (its newest `swarm(task <id>):` landing or
+ *                      residue commit for this plan inside its wave, else
+ *                      the wave's close HEAD).
+ *
+ * The epic record is the source of truth (`EpicTaskOutcome.marker`,
+ * `EpicWaveRecord.closeHead`, `git.baseCommit`); the refs mirror it
+ * ({@link syncEpicRefs}): a missing ref is created with the create-only form
+ * `git update-ref <ref> <sha> ""`, an existing ref with the recorded value is
+ * left alone (idempotent), and a ref with another value (left over by an
+ * earlier epic of the same key with `retain_refs`, or a raced write) is
+ * compare-and-swapped to the recorded value. The refs are gc roots for the
+ * epic's commits while it is open, survive in every linked worktree (refs
+ * are shared), and are never pushed or fetched by default (`git push` /
+ * `git clone` carry only branches and tags; `--mirror` copies them).
+ *
+ * Predecessor evidence ({@link isCommitAncestorOfHead}): a dependency
+ * completed in an earlier wave is satisfied only when its task ref exists
+ * and is an ancestor of HEAD — a rebase or amend that dropped the commit
+ * makes the dependent `predecessor-missing` until `/swarm epic status
+ * --repair-refs` ({@link repairEpicTaskRefs}) re-adopts the task's commit.
+ *
+ * At `/swarm epic close` the report captures every ref and the refs are
+ * deleted ({@link deleteEpicRefs}) unless `epic.retain_refs: true`.
+ *
+ * Subprocess discipline (AGENTS.md #3): reads use `gitExec`
+ * (`src/git/branch.ts`); every ref write/delete is ONE attempt
+ * (`git-once.ts`) — a timed-out `update-ref` is judged by re-reading the ref.
+ */
+import { gitExecOnce, gitProbeExitCode } from './git-once.js';
+import type { EpicRecordV1 } from './lifecycle.js';
+/** Root namespace of every epic's refs. */
+export declare const EPIC_REFS_ROOT = "refs/swarm/epics";
+/** Bound on the commits a marker lookup or repair walks. */
+export declare const MARKER_LOOKUP_MAX_COMMITS = 2000;
+/** DI seam (AGENTS.md invariant 7). Restore in `afterEach`. */
+export declare const _internals: {
+    gitExec: (args: string[], cwd: string) => string;
+    gitExecOnce: typeof gitExecOnce;
+    gitProbeExitCode: typeof gitProbeExitCode;
+};
+export declare function isFullSha(value: unknown): value is string;
+/**
+ * A task id as one ref path component: strict-looking ids (`1.2`, `2.10.3`,
+ * `setup-db`) verbatim; anything else (or a `.lock` suffix) hex-encoded
+ * behind `_x`, which no verbatim component can start with.
+ */
+export declare function taskRefComponent(taskId: string): string;
+export declare function epicRefPrefix(epicKey: string): string;
+export declare function epicBaseRef(epicKey: string): string;
+export declare function epicWaveRef(epicKey: string, seq: number): string;
+export declare function epicTaskRef(epicKey: string, taskId: string): string;
+/**
+ * Every ref under the epic's namespace (full name → sha). One bounded
+ * `git for-each-ref`. Throws when git fails.
+ */
+export declare function readEpicRefs(directory: string, epicKey: string): Map<string, string>;
+/**
+ * Point `ref` at `sha`: create-only when missing (`update-ref <ref> <sha> ""`),
+ * no-op when already there, compare-and-swap from `existing` otherwise. One
+ * attempt; on failure the ref is re-read and the call succeeds only when it
+ * now holds `sha`. Throws otherwise.
+ */
+export declare function writeEpicRef(directory: string, ref: string, sha: string, existing: string | null): 'created' | 'unchanged' | 'updated';
+/** The refs the epic record says should exist (full name → sha). */
+export declare function desiredEpicRefs(record: EpicRecordV1): Map<string, string>;
+/**
+ * Make the epic's refs mirror its record (see the module header). Returns
+ * the refs after the sync. Throws when git fails.
+ */
+export declare function syncEpicRefs(directory: string, record: EpicRecordV1): Map<string, string>;
+/** `git merge-base --is-ancestor <sha> HEAD`. Throws when git fails. */
+export declare function isCommitAncestorOfHead(directory: string, sha: string): boolean;
+/**
+ * Delete every ref under the epic's namespace (each `update-ref -d` guarded
+ * by its current value, one attempt each). Never throws; failures are
+ * returned for the close report.
+ */
+export declare function deleteEpicRefs(directory: string, epicKey: string): {
+    deleted: string[];
+    failed: string[];
+};
+/**
+ * The newest `swarm(task <id>):` commit of each task in `taskIds` whose
+ * `Swarm-Plan:` trailer is `planKey`, among `range` (e.g. `<base>..HEAD`).
+ * One bounded `git log` (merge commits included — a landing is a merge).
+ * Throws when git fails.
+ */
+export declare function findTaskCommits(directory: string, range: string, planKey: string, taskIds: readonly string[]): Map<string, string>;
+/** The range an epic's own commits live in: `<base>..HEAD`, or all of HEAD. */
+export declare function epicCommitRange(record: EpicRecordV1): string;
+/** One task's repair verdict (`/swarm epic status --repair-refs`). */
+export interface EpicRefRepair {
+    taskId: string;
+    status: 'ok' | 'repaired' | 'needs-attention';
+    sha: string | null;
+    detail: string;
+}
+/**
+ * Plan `/swarm epic status --repair-refs` (MINOR 11). For every completed
+ * task the epic recorded, and every task in `unrecorded` (completed in the
+ * plan during the epic but outside a wave), the task's commit must be
+ * reachable from HEAD. When it is not (a rebase or amend rewrote it, or no
+ * ref was ever written) the task's commit is re-adopted: its newest
+ * `swarm(task <id>):` commit for this plan in the epic's range, else (a
+ * recorded task) the newest commit in that range touching its declared
+ * files; neither ⇒ `needs-attention`. Returns the verdicts and the adopted
+ * commits — `recorded` ones the caller CASes into the epic record (then
+ * {@link syncEpicRefs}), `unrecorded` ones it writes as refs directly.
+ * Throws when git fails.
+ */
+export declare function planEpicTaskRefRepair(directory: string, record: EpicRecordV1, unrecorded: readonly string[]): {
+    repairs: EpicRefRepair[];
+    recorded: Map<string, string>;
+    unrecorded: Map<string, string>;
+};

package/dist/epic/merge-epoch.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Plan-epoch filter over the shared worktree merge-back status registry
+ * (Epic v2 C0).
+ *
+ * `.swarm/worktree-merge-status.json` is keyed by bare task id and is never
+ * cleaned automatically (it also serves `/swarm lanes` and orphan recovery,
+ * so it is NOT re-keyed here). Epic consults it where a task's work never
+ * landing matters: `epic_next_wave` does not close a wave while one of its
+ * completed tasks has a failure recorded since the wave was issued, and
+ * `update_task_status` skips the #2582 auto-checkpoint for such a task
+ * ({@link epicMergeFailureSkipsCheckpoint}). Without an epoch filter, a
+ * failure recorded for task `1.1` of a PREVIOUS plan would block the current
+ * plan's `1.1` forever.
+ *
+ * Most writers stamp `completedAt` and/or `queuedAt`, but NOT all: the
+ * delegation-gate `task-result` failure (a cancelled/denied task) records no
+ * timestamp. A failure recorded before the current plan's root timestamp
+ * belongs to an earlier plan and is ignored. A failure with NO timestamp
+ * cannot be dated, so it is treated as relevant (fail closed), surfaced by
+ * `/swarm epic status`, and can be cleared explicitly with
+ * `/swarm epic clear-merge-failure <taskId> --confirm` (which calls the
+ * registry's own `clearWorktreeMergeStatus`, the same function a clean
+ * re-dispatch merge-back uses).
+ */
+import { clearWorktreeMergeStatus as clearWorktreeMergeStatus_import, getWorktreeMergeFailure as getWorktreeMergeFailure_import, initDurableStatusPath as initDurableStatusPath_import, scanWorktreeMergeFailuresForRecovery as scanWorktreeMergeFailuresForRecovery_import, type WorktreeMergeFailure } from '../hooks/delegation-gate/worktree-merge-status.js';
+import { epicSentinelExists as epicSentinelExists_import, getOpenEpic as getOpenEpic_import } from './lifecycle.js';
+/** How a recorded merge failure relates to the current plan. */
+export type MergeFailureRelevance = 'current' | 'undated' | 'stale';
+/** Classify one failure against the plan root time (`sinceMs`). */
+export declare function classifyMergeFailure(failure: WorktreeMergeFailure, sinceMs: number): MergeFailureRelevance;
+/**
+ * The recorded merge-back failure for `taskId` iff it is relevant to the
+ * plan that started at `sinceMs`: recorded at/after `sinceMs`
+ * (`completedAt ?? queuedAt`), or undated (fail closed). Pass `sinceMs = 0`
+ * when the plan root is unknown — every failure is then relevant.
+ */
+export declare function relevantMergeFailure(taskId: string, sinceMs: number): WorktreeMergeFailure | undefined;
+/**
+ * {@link relevantMergeFailure} for one project, used by `epic_next_wave`
+ * (wave advance rule). The shared registry is process-global and keyed by
+ * bare task id, so its in-memory map is trusted only while it is bound to
+ * THIS project's durable file (then every record/clear is persisted to that
+ * file synchronously). Bound to another project, or unbound, the in-memory
+ * map may hold another project's `1.1`: only this project's durable file is
+ * read (read-only scan). An unreadable durable file adds nothing; `/swarm
+ * epic status` reports it.
+ */
+export declare function relevantMergeFailureForProject(directory: string, taskId: string, sinceMs: number): WorktreeMergeFailure | undefined;
+/**
+ * Epic v2 C3 seam before the #2582 auto-checkpoint in `updateTaskStatus`
+ * (MINOR 3): true — skip the checkpoint, with a critical warning — when an
+ * epic is open and `taskId` has a merge-back failure recorded since the epic
+ * started (or undated): its work is not on the epic branch, so a checkpoint
+ * of HEAD would exclude it. One `existsSync` and `false` when no epic is
+ * open; unreadable lifecycle state counts as no epic. Never throws.
+ */
+export declare function epicMergeFailureSkipsCheckpoint(directory: string, taskId: string): boolean;
+/**
+ * `/swarm epic status` lines for recorded merge failures (read-only scan of
+ * the durable file). Empty when there are none. `sinceMs` null ⇒ plan root
+ * unknown, every failure is reported as blocking.
+ */
+export declare function describeMergeFailuresForStatus(directory: string, sinceMs: number | null): string[];
+/**
+ * `/swarm epic clear-merge-failure <taskId> [--confirm]` — Epic-owned escape
+ * hatch for a merge failure that blocks an epic wave but no longer reflects
+ * reality (work landed by hand, undated record from an earlier plan).
+ *
+ * Only a task id that currently HAS a recorded failure (durable file or
+ * in-memory registry) can be cleared. Without `--confirm` the call is
+ * read-only and prints what would be cleared. With it, the registry's own
+ * `clearWorktreeMergeStatus` removes the record (in memory + durable file),
+ * after `initDurableStatusPath(directory)` binds the registry to this
+ * project (a no-op when the delegation gate already did).
+ */
+export declare function clearMergeFailureCommand(directory: string, args: string[]): string;
+/**
+ * DI seam (AGENTS.md invariant 7). The shared registry module is consumed
+ * through its exported API only, never modified.
+ */
+export declare const _internals: {
+    epicSentinelExists: typeof epicSentinelExists_import;
+    getOpenEpic: typeof getOpenEpic_import;
+    clearWorktreeMergeStatus: typeof clearWorktreeMergeStatus_import;
+    initDurableStatusPath: typeof initDurableStatusPath_import;
+    getWorktreeMergeFailure: typeof getWorktreeMergeFailure_import;
+    scanWorktreeMergeFailuresForRecovery: typeof scanWorktreeMergeFailuresForRecovery_import;
+    /** Throws when the shared registry is unbound (no project path given). */
+    getBoundStatusPath: () => string;
+};

package/dist/epic/next-wave-format.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Result shapes and architect-facing text of `epic_next_wave` (Epic v2 C2).
+ * Pure: no I/O. The procedure lives in these responses (the banner only
+ * says "call epic_next_wave and do exactly what its status says").
+ */
+import type { Plan } from '../config/plan-schema.js';
+import type { EpicPhaseRecord, EpicTaskOutcome, EpicWaveRecord } from './lifecycle.js';
+import type { EpicPredecessorProblem } from './wave-select.js';
+export interface EpicWaveView {
+    seq: number;
+    phase: number;
+    kind: EpicWaveRecord['kind'];
+    taskIds: string[];
+    files: Record<string, string[]>;
+    tasks: {
+        taskId: string;
+        description: string;
+        files: string[];
+    }[];
+    issuedAt: string;
+}
+/** What the call just closed (present on results that follow a close). */
+export interface EpicClosedWaveSummary {
+    seq: number;
+    phase: number;
+    taskIds: string[];
+    resolutions: Record<string, EpicTaskOutcome['resolution']>;
+    closeHead: string | null;
+    /** Tasks with undeclared writes (session or single-task git attribution). */
+    divergence: {
+        taskId: string;
+        undeclared: string[];
+    }[];
+    /** Wave-level undeclared files no task's attribution explains. */
+    waveUndeclared: string[];
+}
+export type EpicNextWaveRefusal = 'no-open-epic' | 'epic-orphaned' | 'epic-state-unreadable' | 'epic-disabled-by-config';
+export type EpicNextWaveBlockReason = 'task-blocked' | 'merge-failed' | 'landing-index-dirty' | 'git-failed' | 'dirty-baseline' | 'predecessor-missing' | 'plan-revised' | 'task-reopened' | 'epic-branch-mismatch';
+type WithClosed = {
+    closedWave?: EpicClosedWaveSummary;
+};
+export type EpicNextWaveResult = ({
+    status: 'dispatch';
+    wave: EpicWaveView;
+    instructions: string;
+} & WithClosed) | ({
+    status: 'declare-scopes';
+    phase: number;
+    tasks: {
+        taskId: string;
+        suggestedFiles: string[];
+    }[];
+    message: string;
+} & WithClosed) | ({
+    status: 'in-progress';
+    wave: EpicWaveView;
+    waitingOn: {
+        taskId: string;
+        state: string;
+    }[];
+    message: string;
+} & WithClosed) | ({
+    status: 'blocked';
+    reason: EpicNextWaveBlockReason;
+    details: Record<string, unknown>;
+    message: string;
+} & WithClosed) | ({
+    status: 'phase-ready-for-review';
+    phase: number;
+    message: string;
+} & WithClosed) | ({
+    status: 'epic-complete';
+    message: string;
+} & WithClosed) | {
+    status: 'refused';
+    reason: EpicNextWaveRefusal;
+    message: string;
+};
+/**
+ * How review findings are fixed while an epic is open (C4): coders run only
+ * through waves, so a fix is a NEW pending task of the phase — `epic_next_wave`
+ * then runs it as a fix wave (scopes, landing commit, refs, outcomes) and
+ * returns `phase-ready-for-review` again.
+ */
+export declare function epicPhaseFixPath(phase: number): string;
+/** The fix-task steps of {@link epicPhaseFixPath} on their own. */
+export declare function epicPhaseFixSteps(phase: number): string;
+export declare function refused(reason: EpicNextWaveRefusal, message: string): EpicNextWaveResult;
+export declare function toWaveView(wave: EpicWaveRecord, plan: Plan): EpicWaveView;
+/** The step-by-step text returned with every `dispatch`. */
+export declare function buildDispatchInstructions(wave: EpicWaveView): string;
+export declare function summarizeClosedWave(wave: EpicWaveRecord, outcomes: EpicTaskOutcome[]): EpicClosedWaveSummary;
+export declare function predecessorMessage(problems: EpicPredecessorProblem[], planKey: string): string;
+/**
+ * Phase bookkeeping: the current phase takes `currentStatus` (`active` while
+ * waves run, `review` once every task is resolved). A phase recorded
+ * `complete` (by `phase_complete`) is never downgraded. Returns the SAME
+ * object when nothing changes (callers skip the write).
+ */
+export declare function syncPhaseRecords(phases: Record<string, EpicPhaseRecord>, currentPhase: number, currentStatus: 'active' | 'review'): Record<string, EpicPhaseRecord>;
+export {};

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

@@ -0,0 +1,102 @@
+/**
+ * Epic v2 C2 — `epic_next_wave`: the single, idempotent way forward while an
+ * epic is open. It replaces `epic_decide_phase`, `epic_plan_waves` and
+ * `epic_record_divergence`.
+ *
+ * Each call, in order:
+ *   1. refuses unless Epic is enabled by config and an epic is open for the
+ *      current plan (`epic-disabled-by-config`, `epic-state-unreadable`,
+ *      `epic-orphaned`, `no-open-epic`);
+ *   2. blocks `epic-branch-mismatch` when HEAD left the epic branch (M-e);
+ *   3. with a wave active — advance rule: the wave closes when every task is
+ *      resolved (plan status completed — already gated by
+ *      `update_task_status` — or closed, or removed from the plan) and none
+ *      has a merge-back failure recorded since the wave was issued.
+ *      Otherwise: `blocked` (`task-blocked`, `merge-failed`, `plan-revised`
+ *      when an unresolved task moved to another phase — the wave is aborted)
+ *      or `in-progress` (the same wave; idempotent). A closable wave is
+ *      closed (`wave-close.ts`) and the call continues to the next wave;
+ *   4. phases are iterations: the current phase is the first phase not
+ *      recorded complete by `phase_complete`; a pending task in a complete
+ *      phase
+ *      blocks (`task-reopened` when the epic had resolved it, else
+ *      `plan-revised`);
+ *   5. every current-phase task resolved → `phase-ready-for-review` (then
+ *      `epic_phase_review` → `phase_complete`); every phase complete →
+ *      `epic-complete`;
+ *   6. otherwise selects the next wave (`wave-select.ts` over the component
+ *      planner `components.ts`, with the planning signals of
+ *      `planning-signals.ts`; past waves of the phase age its components):
+ *      `declare-scopes`,
+ *      `blocked` (`predecessor-missing`, `task-blocked`, `git-failed`,
+ *      `dirty-baseline`), or `dispatch` — a multi-task wave must pass THE
+ *      wave verdict (`gate-policy.ts`, the call the delegation gate repeats
+ *      at dispatch); the wave (frozen declared scopes, base HEAD) is
+ *      CAS-written into the epic record (token-guarded) and returned with
+ *      dispatch instructions.
+ *
+ * Git epics (Epic v2 C3): every task's work is committed before the task
+ * completes (its coder's worktree lands as a merge commit; non-coder writes
+ * become residue commits). Closing a wave first commits any residue still
+ * attributed to its tasks, then records each task's commit and mirrors it to
+ * `refs/swarm/epics/<epicKey>/tasks/<id>` (`markers.ts`). A completed
+ * dependency outside the batch is satisfied by that ref being an ancestor of
+ * HEAD (or by having been completed before the epic started). Before a new
+ * wave, TRACKED changes block `dirty-baseline`; untracked files are only
+ * reported.
+ */
+import { loadPluginConfigWithMeta as loadPluginConfigWithMeta_import } from '../config/index.js';
+import type { Plan } from '../config/plan-schema.js';
+import { readLedgerEvents as readLedgerEvents_import } from '../plan/ledger.js';
+import { loadPlanJsonOnly as loadPlanJsonOnly_import } from '../plan/manager.js';
+import { getCoChangeData as getCoChangeData_import } from './cochange-source.js';
+import { resolveEpicDeclaredScopes as resolveEpicDeclaredScopes_import } from './declared-scopes.js';
+import { checkEpicBranch as checkEpicBranch_import } from './epic-branch.js';
+import { computeEpicWaveVerdict as computeEpicWaveVerdict_import } from './gate-policy.js';
+import { loadEpicLearningView as loadEpicLearningView_import } from './learning-store.js';
+import { type EpicRecordV1, getOpenEpic as getOpenEpic_import, inspectEpic as inspectEpic_import, updateEpicRecord as updateEpicRecord_import } from './lifecycle.js';
+import { isCommitAncestorOfHead as isCommitAncestorOfHead_import, syncEpicRefs as syncEpicRefs_import } from './markers.js';
+import { relevantMergeFailureForProject as relevantMergeFailureForProject_import } from './merge-epoch.js';
+import { type EpicNextWaveResult } from './next-wave-format.js';
+import { commitTaskResidue as commitTaskResidue_import, listDirtyEntries as listDirtyEntries_import } from './residue-commit.js';
+import { collectTaskAttribution as collectTaskAttribution_import, computeWaveClose as computeWaveClose_import, recordEpicWaveLearning as recordEpicWaveLearning_import, releaseWaveAttribution as releaseWaveAttribution_import } from './wave-close.js';
+export type { EpicNextWaveResult } from './next-wave-format.js';
+/** DI seam (AGENTS.md invariant 7). Restore in `afterEach`. */
+export declare const _internals: {
+    loadPluginConfigWithMeta: typeof loadPluginConfigWithMeta_import;
+    loadPlanJsonOnly: typeof loadPlanJsonOnly_import;
+    readLedgerEvents: typeof readLedgerEvents_import;
+    getOpenEpic: typeof getOpenEpic_import;
+    inspectEpic: typeof inspectEpic_import;
+    updateEpicRecord: typeof updateEpicRecord_import;
+    checkEpicBranch: typeof checkEpicBranch_import;
+    listDirtyEntries: typeof listDirtyEntries_import;
+    commitTaskResidue: typeof commitTaskResidue_import;
+    collectTaskAttribution: typeof collectTaskAttribution_import;
+    syncEpicRefs: typeof syncEpicRefs_import;
+    isCommitAncestorOfHead: typeof isCommitAncestorOfHead_import;
+    /** One writer of the primary checkout's index at a time (merge-back queue). */
+    serializeWithMergeBacks: <T>(task: () => T | Promise<T>) => Promise<T>;
+    readHead: (directory: string) => string | null;
+    resolveEpicDeclaredScopes: typeof resolveEpicDeclaredScopes_import;
+    relevantMergeFailureForProject: typeof relevantMergeFailureForProject_import;
+    loadEpicLearningView: typeof loadEpicLearningView_import;
+    getCoChangeData: typeof getCoChangeData_import;
+    computeWaveClose: typeof computeWaveClose_import;
+    recordEpicWaveLearning: typeof recordEpicWaveLearning_import;
+    releaseWaveAttribution: typeof releaseWaveAttribution_import;
+    computeEpicWaveVerdict: typeof computeEpicWaveVerdict_import;
+    now: () => number;
+};
+/** Run one `epic_next_wave` step for `directory` (see the module header). */
+export declare function runEpicNextWave(directory: string, sessionID: string | undefined): Promise<EpicNextWaveResult>;
+/**
+ * Tasks completed BEFORE the epic started. `/swarm epic start` refuses a
+ * dirty tree, so their work is in HEAD even though the epic recorded no
+ * commit (task ref) for them — they need none as predecessor evidence. A task
+ * counts when the epic never resolved it in a wave and either its phase was
+ * already finished at start, or its last transition to `completed` in the
+ * plan ledger predates the start (or it was saved completed, with no
+ * transition at all).
+ */
+export declare function completedBeforeEpic(directory: string, epic: EpicRecordV1, plan: Plan): Promise<Set<string>>;

package/dist/epic/phase-readiness.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Epic Mode phase readiness — phase reviewer + phase critic gate.
+ *
+ * Epic Mode replaces Lean Turbo's `lean_turbo_readiness` gate in
+ * `phase_complete` (Lean readiness is keyed on Lean lane state, which Epic's
+ * visible-`Task` wave flow never produces). This module is the Epic-owned
+ * replacement: before an Epic phase may close, an integrated phase reviewer
+ * AND a phase critic must both have APPROVED the phase's combined result.
+ *
+ * ## Evidence integrity
+ *
+ * Verdicts are never self-reported by the architect. `runEpicPhaseReview`
+ * dispatches the reviewer and then the critic itself, through the plugin's
+ * read-only ephemeral review dispatcher (the same pattern `lean_turbo_review` /
+ * `lean_turbo_critic` use), parses each verdict from the agent's own response
+ * text, and persists the result to
+ * `.swarm/evidence/{phase}/epic-phase-review.json`. An agent therefore cannot
+ * obtain an APPROVED record without a real reviewer and critic dispatch.
+ *
+ * ## Freshness binding
+ *
+ * The evidence binds to:
+ *   - the epic instance (`epic_key`), so a review recorded under one epic can
+ *     never satisfy phase_complete under another — e.g. after the epic was
+ *     closed and a new one started on the same plan,
+ *   - the plan identity (`plan_id`) and status-free plan structure hash,
+ *   - the phase's task ids + statuses (`phase_tasks_digest`), and
+ *   - the byte content of every phase task's `.swarm/evidence/{taskId}.json`
+ *     (`task_evidence_digest`), so any post-review rework that re-records
+ *     reviewer/test_engineer gate evidence invalidates the approval,
+ * plus a 24h TTL with a bounded forward-skew rejection (the Full-Auto phase
+ * approval precedent). Any mismatch blocks with a STALE code and the
+ * architect re-runs `epic_phase_review`.
+ */
+import type { RuntimePlan } from '../config/plan-schema';
+import { type ReadOnlyToolDenials } from '../evaluation/ephemeral-agent-dispatcher';
+import type { ReviewModelDispatcher } from '../review/contracts';
+import { type ReviewAgentModelRegistry } from '../review/runtime';
+import { type EpicRecordV1, getOpenEpic } from './lifecycle';
+/** Evidence filename under `.swarm/evidence/{phase}/`. */
+export declare const EPIC_PHASE_REVIEW_FILENAME = "epic-phase-review.json";
+/** Approval lifetime; older evidence is stale (Full-Auto phase-approval precedent). */
+export declare const EPIC_PHASE_REVIEW_TTL_MS: number;
+/** Tolerated forward clock skew before a timestamp is treated as forged. */
+export declare const EPIC_PHASE_REVIEW_FORWARD_SKEW_MS: number;
+/** Default per-role dispatch timeout (`epic.phase_review.timeout_ms`). */
+export declare const EPIC_PHASE_REVIEW_DISPATCH_TIMEOUT_MS = 300000;
+/**
+ * The configured per-role timeout (`epic.phase_review.timeout_ms`), or the
+ * default when it is unset or the config cannot be read (fail-open to the
+ * default: a timeout is a budget, not a safety gate).
+ */
+export declare function resolveEpicPhaseReviewTimeoutMs(directory: string): number;
+/** Recovery tool name advertised in every block message. */
+export declare const EPIC_PHASE_REVIEW_TOOL = "epic_phase_review";
+/**
+ * Tool map for the one empty-response retry: the shared read-only map with
+ * only `bash` left enabled. OpenCode Zen's free tier answers a request that
+ * disables `bash` with HTTP 403 ("free tier can only be used from within
+ * OpenCode"), and the shared dispatcher (which disables `bash` along with
+ * every mutating and plugin tool) surfaces ANY provider-side error as a
+ * `completed` response with no text (or, where it reads the assistant
+ * message's `info.error`, as an `error` with a `providerError`) — so the
+ * retry fires on every empty completion and every structured provider
+ * refusal, not only the Zen 403; a second refusal stays a fail-closed
+ * REJECTED. Every other tool stays denied, so this profile is
+ * still narrower than the standard per-task reviewer/critic agents (whose
+ * own config denies only write/edit/patch among the built-ins). Their shell
+ * commands pass the same guardrails, which for a scope-less non-coder role
+ * block unresolvable, inline-eval and deny-listed (none by default) writes;
+ * that is not a read-only sandbox, so the retry also tells the model not to
+ * change anything ({@link EPIC_PHASE_REVIEW_BASH_RETRY_NOTE}).
+ */
+export declare const EPIC_PHASE_REVIEW_BASH_RETRY_NOTE = "You have a `bash` tool for this review. Use it only to read and inspect (for example cat, ls, grep, git log, git diff, git show). Never run a command that creates, modifies or deletes files, changes git state (checkout, stash, reset, commit), installs packages, or runs tests.";
+export declare const EPIC_PHASE_REVIEW_BASH_RETRY_TOOLS: ReadOnlyToolDenials;
+export type EpicPhaseVerdict = 'APPROVED' | 'NEEDS_REVISION' | 'REJECTED';
+export type EpicReviewToolProfile = 'read-only' | 'read-only-with-bash';
+export interface EpicRoleVerdict {
+    role: 'reviewer' | 'critic';
+    /** Resolved agent name that was dispatched (e.g. `reviewer`, `mega_critic`). */
+    agent: string;
+    verdict: EpicPhaseVerdict;
+    reason: string | null;
+    /**
+     * `completed` — the agent responded and a single verdict was parsed;
+     * `unparseable` — the agent responded without one unambiguous verdict;
+     * `failed` — dispatch failed after fallbacks. Both non-`completed`
+     * outcomes are recorded fail-closed as REJECTED.
+     */
+    dispatch: 'completed' | 'unparseable' | 'failed';
+    /**
+     * Tool profile of the dispatch that produced this verdict: `read-only`
+     * (the shared map) or `read-only-with-bash` (the provider-refusal retry,
+     * see {@link EPIC_PHASE_REVIEW_BASH_RETRY_TOOLS}). Absent on evidence
+     * written before the retry existed.
+     */
+    tool_profile?: EpicReviewToolProfile;
+    model?: string;
+    duration_ms?: number;
+    dispatched_at: string;
+}
+export interface EpicPhaseBinding {
+    /**
+     * Key of the open epic the review ran under (null if none was readable).
+     * Absent on evidence written before the field existed, which is then
+     * treated as stale rather than malformed.
+     */
+    epic_key?: string | null;
+    plan_id: string;
+    plan_structure_hash: string;
+    phase_task_ids: string[];
+    phase_tasks_digest: string;
+    task_evidence_digest: string;
+}
+export interface EpicPhaseReviewEvidence {
+    schema_version: 1;
+    kind: 'epic_phase_review';
+    phase: number;
+    reviewed_at: string;
+    /** Architect session that ran `epic_phase_review` (dispatch parent). */
+    parent_session_id: string;
+    binding: EpicPhaseBinding;
+    reviewer: EpicRoleVerdict;
+    /** null when the critic was not dispatched because the reviewer did not approve. */
+    critic: EpicRoleVerdict | null;
+}
+export type EpicPhaseReadinessCode = 'EPIC_PHASE_REVIEW_MISSING' | 'EPIC_PHASE_REVIEW_INVALID' | 'EPIC_PHASE_REVIEWER_NOT_APPROVED' | 'EPIC_PHASE_CRITIC_MISSING' | 'EPIC_PHASE_CRITIC_NOT_APPROVED' | 'EPIC_PHASE_REVIEW_STALE' | 'EPIC_PHASE_PLAN_UNREADABLE' | 'EPIC_PHASE_WAVES_OPEN';
+export type EpicPhaseReadinessResult = {
+    ok: true;
+    evidence: EpicPhaseReviewEvidence;
+} | {
+    ok: false;
+    code: EpicPhaseReadinessCode;
+    reason: string;
+};
+declare function taskEvidenceFingerprint(directory: string, taskId: string): string;
+/**
+ * Compute the freshness binding for `phase` of `plan`. Returns the ids of
+ * tasks that are not yet `completed`/`closed` so the review tool can refuse a
+ * premature review.
+ */
+export declare function computeEpicPhaseBinding(directory: string, plan: RuntimePlan, phase: number): {
+    ok: true;
+    binding: EpicPhaseBinding;
+    incompleteTaskIds: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** Strict shape check for persisted evidence (fail-closed on any drift). */
+export declare function parseEpicPhaseReviewEvidence(raw: unknown): EpicPhaseReviewEvidence | null;
+type EvidenceRead = {
+    status: 'missing';
+} | {
+    status: 'invalid';
+    detail: string;
+} | {
+    status: 'found';
+    evidence: EpicPhaseReviewEvidence;
+};
+declare function readEpicPhaseReviewEvidence(directory: string, phase: number): EvidenceRead;
+/** Seqs of the epic's waves for `phase` that are issued and not closed. */
+export declare function openEpicWavesForPhase(record: Pick<EpicRecordV1, 'waves'>, phase: number): number[];
+/**
+ * Epic v2 C2: a phase is reviewable / completable only when every wave
+ * `epic_next_wave` issued for it is closed. Null when that holds (or no
+ * epic is open); otherwise the blocking reason. An unreadable epic record
+ * fails closed.
+ */
+export declare function describeOpenEpicWaves(directory: string, phase: number): string | null;
+/**
+ * Verify that `phase` has fresh, APPROVED phase-reviewer and phase-critic
+ * evidence and (Epic v2 C2) no open wave. Observational only: never
+ * dispatches or writes.
+ */
+export declare function verifyEpicPhaseReadiness(directory: string, phase: number, nowMs: number): Promise<EpicPhaseReadinessResult>;
+/**
+ * Parse exactly one verdict from agent response text. Every `VERDICT:` line
+ * is collected; zero or conflicting verdicts are unparseable (fail-closed),
+ * so a template echo such as `VERDICT: APPROVED | REJECTED` cannot count.
+ */
+export declare function parseEpicPhaseVerdict(text: string): {
+    verdict: EpicPhaseVerdict;
+    reason: string | null;
+} | null;
+export interface EpicPhaseReviewOptions {
+    dispatcher?: ReviewModelDispatcher;
+    generatedAgentNames?: readonly string[];
+    activeAgentName?: string;
+    agentModelRegistry?: ReviewAgentModelRegistry;
+    timeoutMs?: number;
+}
+export type EpicPhaseReviewRunResult = {
+    success: true;
+    phase: number;
+    ready: boolean;
+    reviewer: EpicRoleVerdict;
+    critic: EpicRoleVerdict | null;
+    evidencePath: string;
+    message: string;
+} | {
+    success: false;
+    phase: number;
+    reason: 'dispatcher-unavailable' | 'no-plan' | 'no-phase' | 'tasks-incomplete' | 'agent-resolution-failed' | 'persist-failed';
+    message: string;
+};
+/**
+ * Dispatch the phase reviewer, then (only when it APPROVES) the phase critic,
+ * and persist the bound verdicts for the phase_complete Epic readiness gate.
+ */
+export declare function runEpicPhaseReview(directory: string, phase: number, parentSessionId: string, options?: EpicPhaseReviewOptions): Promise<EpicPhaseReviewRunResult>;
+/** Dependency-injection seam (AGENTS.md invariant 7); restore in afterEach. */
+export declare const _internals: {
+    loadPlan: (directory: string) => Promise<RuntimePlan | null>;
+    readEvidence: typeof readEpicPhaseReviewEvidence;
+    taskEvidenceFingerprint: typeof taskEvidenceFingerprint;
+    writeEvidence: (target: string, content: string) => Promise<void>;
+    now: () => number;
+    getOpenEpic: typeof getOpenEpic;
+};
+export {};