/**
 * `cleo go` autopilot driver — the thin orchestration sequencer.
 *
 * This is the canonical entry point for `cleo go` (SG-AUTOPILOT / T11492).
 * It is PURE GLUE: it sequences existing core engines without adding new
 * orchestration math.
 *
 * ## Pipeline (AC1)
 *
 * ```
 * briefing (optional context anchor)
 *   → sagaNext() — pick highest-priority non-terminal saga
 *   → orchestrateReady(sagaId) — fetch readyFrontier
 *   → branch on pipelineStage of the active epic:
 *       AC-only (no children, research stage)
 *         → { action: 'needsDecomposition', sagaId, epicId }
 *       research | specification | decomposition
 *         → { action: 'lifecycleHop', sagaId, epicId, currentStage }
 *       implementation | validation | testing | release | contribution
 *         → fan-out the injected IVTR runner over readyFrontier tasks
 *         → { action: 'ivtrFanOut', sagaId, epicId, tasks: string[], runIds: string[] }
 *   → return ONE LAFS-compatible EngineResult envelope
 * ```
 *
 * ## IVTR seam (T11805 · T11896 · E-ORCH-STATE-MACHINE-COLLAPSE / T11764)
 *
 * The implementation+ branch is gated by {@link CLEO_GO_VIA_PLAYBOOK_ENV}, which
 * now defaults **ON** (T11896): the cantbook runtime is the shipped survivor
 * state machine and `cleo go` drives IVTR through it. The flag is retained for
 * **one deprecation cycle** as an opt-OUT kill-switch — set
 * `CLEO_GO_VIA_PLAYBOOK=0` (or `false`/`no`/`off`) to restore the legacy
 * `ivtr_state` seed (`seedIvtrForPlaybook`, byte-identical to the retired
 * `startIvtr`) for a single release if a cantbook-path regression surfaces.
 *
 * - **Flag ON (default)** — fan out an injected {@link IvtrRunner} — supplied
 *   by the CLI `cleo go` handler — that drives each task through
 *   `executePlaybook(ivtr.cantbook)` (the cantbook runtime, the survivor state
 *   machine) AND mirrors the run's terminal status back into `ivtr_state`
 *   (`finalizeIvtrFromPlaybook`) so the strict `E_IVTR_INCOMPLETE` completion
 *   gate reflects the cantbook run. The runtime's
 *   `on_failure.inject_into: implement` edge reproduces the IVTR loop-back walk.
 * - **Flag OFF (opt-out kill-switch)** OR **no runner injected** — seed each
 *   ready task's `ivtr_state` via `seedIvtrForPlaybook` (byte-identical to the
 *   retired `startIvtr` seed); the seam is a no-op. This fallback is retained
 *   for one release so a cantbook-path regression can never strand autopilot.
 *
 * The driver stays in `@cleocode/core` and must NOT import `@cleocode/playbooks`
 * (that would invert the package dependency), so the runtime call is injected
 * as a callback rather than referenced directly.
 *
 * ## Design constraints
 *
 * - AC2: ONE LAFS envelope per call — all branching produces a single return.
 * - AC3: empty ready-set + zero children → `needsDecomposition` (typed, not silent []).
 * - No new orchestration math — only sequences ops from `sagas`, `orchestrate`,
 *   and `lifecycle` modules.
 * - CORE-FIRST: all logic here in `packages/core/src/go/`; CLI is a thin dispatch.
 *
 * @module @cleocode/core/go
 *
 * @task T11494 — E2-CLEO-GO
 * @saga T11492 — SG-AUTOPILOT
 */
import type { TaskViewPipelineStage } from '@cleocode/contracts';
import { type EngineResult } from '../engine-result.js';
/**
 * Feature-flag env var gating the cantbook IVTR seam (T11805 · T11896 ·
 * collapse-plan Risk Register §7 row #1).
 *
 * As of T11896 the cantbook runtime is the **shipped default** — the flag now
 * defaults **ON** and is retained for one deprecation cycle purely as an
 * opt-OUT kill-switch. When unset (or any truthy value) the implementation-stage
 * branch drives the injected {@link IvtrRunner}
 * (`executePlaybook(ivtr.cantbook)`). Set `CLEO_GO_VIA_PLAYBOOK=0` (or
 * `false`/`no`/`off`) to restore the legacy `seedIvtrForPlaybook` seed
 * (byte-identical to the retired `startIvtr`) for a single release if a
 * cantbook-path regression surfaces. The kill-switch is removed in a follow-up
 * once the cantbook path has baked.
 */
export declare const CLEO_GO_VIA_PLAYBOOK_ENV: "CLEO_GO_VIA_PLAYBOOK";
/**
 * Outcome of a single IVTR playbook run started by the seam (T11805).
 *
 * Returned by {@link IvtrRunner} so the driver can both report the started
 * task and surface the `playbook_runs.run_id` for resume-on-next-turn.
 *
 * @task T11805 — E-ORCH-STATE-MACHINE-COLLAPSE / T11764
 */
export interface IvtrRunResult {
    /** The task whose `ivtr.cantbook` run was started. */
    taskId: string;
    /**
     * The `playbook_runs.run_id` of the started run, when the runtime created
     * one. Absent only when the runner cannot reach a run id (e.g. a pre-flight
     * failure before the run row is written).
     */
    runId?: string;
    /**
     * Terminal status reported by the cantbook runtime for this turn, when the
     * run reached a terminal node (`completed | failed | pending_approval |
     * exceeded_iteration_cap`). Absent when the runner only seeded the run.
     */
    terminalStatus?: string;
}
/**
 * Options handed to an {@link IvtrRunner} for a single task.
 *
 * @task T11805
 */
export interface IvtrRunnerOptions {
    /** Resolved project root for playbook resolution + audit writes. */
    projectRoot: string;
    /**
     * Session id persisted onto `playbook_runs.session_id` (evidence/provenance
     * gate parameter). Absent when no session is active.
     */
    sessionId?: string;
    /** Parent epic id persisted onto `playbook_runs.epic_id` for dashboards. */
    epicId?: string;
}
/**
 * Injected callback that drives one task's IVTR loop through the cantbook
 * runtime (`executePlaybook(ivtr.cantbook)`).
 *
 * The driver lives in `@cleocode/core`, which must not depend on
 * `@cleocode/playbooks`; the runtime call is therefore injected by the CLI
 * `cleo go` handler (which already imports `@cleocode/playbooks`). The runner
 * is responsible for:
 *   - resolving + parsing `ivtr.cantbook`,
 *   - seeding `initialContext = { taskId }`,
 *   - calling `executePlaybook` with `taskId` (via context) + `sessionId` +
 *     the evidence-gate parameters the cantbook encodes,
 *   - keeping `tasks.ivtr_state` populated so the strict `E_IVTR_INCOMPLETE`
 *     completion gate stays load-bearing (collapse-plan §3 item 4).
 *
 * @task T11805
 */
export type IvtrRunner = (taskId: string, options: IvtrRunnerOptions) => Promise<IvtrRunResult>;
/**
 * Input parameters for {@link cleoGo}.
 *
 * @task T11494
 */
export interface CleoGoParams {
    /**
     * Optional saga ID to scope the autopilot run. When omitted, `sagaNext`
     * auto-selects the highest-priority non-terminal Saga in canonical order.
     */
    sagaId?: string;
    /**
     * When true, suppress any interactive output suitable for daemon / unattended
     * runs. The result shape is identical; only side-channel logging is affected.
     */
    headless?: boolean;
    /** Override project root (useful in tests). */
    projectRoot?: string;
    /**
     * Drives each ready task through `executePlaybook(ivtr.cantbook)` — the
     * shipped default path (T11896) gated by {@link CLEO_GO_VIA_PLAYBOOK_ENV}.
     * Injected by the CLI handler so the core driver never imports the playbooks
     * runtime. When the kill-switch is set (`CLEO_GO_VIA_PLAYBOOK=0`) or this is
     * omitted, the driver falls back to the legacy `seedIvtrForPlaybook` seed for
     * the implementation+ branch (no behaviour is silently skipped).
     */
    ivtrRunner?: IvtrRunner;
    /**
     * Session id forwarded to {@link IvtrRunner} for `playbook_runs.session_id`
     * provenance. Best-effort; absent when no session is active.
     */
    sessionId?: string;
}
/**
 * Discriminated union of the four action outcomes `cleoGo` can produce.
 *
 * Consumers pattern-match on `action` to route further processing.
 *
 * @task T11494
 */
export type CleoGoAction = {
    /** No children + research stage — the epic needs decomposition before IVTR. */
    action: 'needsDecomposition';
    sagaId: string;
    /** The AC-only epic that needs task children added. */
    epicId: string;
    /** Current pipelineStage (always `'research'` for AC-only epics). */
    currentStage: TaskViewPipelineStage;
} | {
    /** Pre-implementation stage — lifecycle must hop before IVTR is valid. */
    action: 'lifecycleHop';
    sagaId: string;
    epicId: string;
    currentStage: TaskViewPipelineStage;
    /** All ready-frontier task IDs (may be empty while lifecycle hops). */
    readyFrontier: string[];
} | {
    /**
     * Fan-out: an IVTR cantbook run was started for each task on the ready
     * frontier (T11805 — `executePlaybook(ivtr.cantbook)`, no longer
     * `startIvtr`).
     */
    action: 'ivtrFanOut';
    sagaId: string;
    epicId: string;
    currentStage: TaskViewPipelineStage;
    /** Task IDs for which an IVTR playbook run was initiated. */
    tasks: string[];
    /**
     * `playbook_runs.run_id` for each started run, positionally aligned to
     * the tasks that produced one. Lets the autopilot resume paused runs on
     * the next turn.
     *
     * @task T11805
     */
    runIds: string[];
} | {
    /** No non-terminal sagas remain — the workgraph is complete. */
    action: 'complete';
};
/**
 * Result payload for {@link cleoGo}.
 *
 * @task T11494
 * @task T11496 E4-GOAL-LOOP
 */
export interface CleoGoResult {
    /** The action taken by the driver in this turn. */
    outcome: CleoGoAction;
    /**
     * Structured diagnostics for display / logging. Always present; may be empty.
     */
    diagnostics: string[];
    /**
     * The id of the goal that was armed (or reused) for the Stop-hook loop.
     *
     * `null` when no saga was selected (workgraph `complete` action) — there is
     * nothing to arm when the workgraph is already done.
     *
     * @task T11496
     */
    armedGoalId: string | null;
}
/**
 * Run one turn of the `cleo go` autopilot pipeline.
 *
 * Returns a single LAFS-compatible {@link EngineResult} wrapping a
 * {@link CleoGoResult}. Each call is stateless (side effects — IVTR cantbook
 * runs via the injected {@link IvtrRunner}, lifecycle progression — happen
 * inside the called engines); the driver itself carries no mutable state.
 *
 * @param params - Input parameters controlling the saga scope and mode.
 * @returns EngineResult with {@link CleoGoResult}.
 *
 * @task T11494
 * @saga T11492
 */
export declare function cleoGo(params?: CleoGoParams): Promise<EngineResult<CleoGoResult>>;
//# sourceMappingURL=driver.d.ts.map