/**
 * IVTR `ivtr_state` record — read + cantbook-mirror surface.
 *
 * The Implement → Validate → Audit → Test → Release phase loop now runs on the
 * cantbook runtime (the survivor state machine after the T11764 collapse). The
 * hand-rolled phase-walk functions (`startIvtr`/`advanceIvtr`/`loopBackIvtr`/
 * `releaseIvtr`) plus the per-phase prompt/auto-gate helpers were deleted in
 * T11896 once `cleo go` (default) drives `executePlaybook(ivtr.cantbook)` and
 * the manual `cleo orchestrate ivtr` mutate ops were deprecated.
 *
 * This module now owns the RETAINED `ivtr_state` surface (one deprecation
 * cycle):
 *  - {@link IvtrState} / {@link IvtrPhase} / {@link IvtrPhaseEntry} — the JSON
 *    shape persisted in the `ivtr_state` column on `tasks`.
 *  - {@link getIvtrState} — the read path backing `cleo show --ivtr-history`
 *    and the strict `E_IVTR_INCOMPLETE` completion gate (`tasks/complete.ts`).
 *  - {@link seedIvtrForPlaybook} / {@link finalizeIvtrFromPlaybook} — the
 *    `cleo go` cantbook seam (T11805): seed the column at `implement` and
 *    mirror the run's terminal status back so the completion gate stays
 *    load-bearing.
 *  - {@link MAX_LOOP_BACKS_PER_PHASE} — read by `classify-readiness.ts`.
 *  - {@link validateSpawnRequest} — Lead authorship-bypass guard (ADR-070).
 *
 * Evidence refs are sha256 hashes of attachment blobs stored under
 * .cleo/attachments (see ADR T796 attachment store).
 *
 * @epic T810
 * @task T811
 * @task T813
 * @task T11805 — cantbook seam (seed + finalize mirror)
 * @task T11896 — phase-walk functions deleted; this is the read/mirror surface
 */
/** The four canonical IVTR phases. */
/** @task T9216 — added 'audit' phase between validate and test */
export type IvtrPhase = 'implement' | 'validate' | 'audit' | 'test' | 'released';
/**
 * A single phase entry in the IVTR phase history.
 * Loop-back entries have `passed: false` and a non-null `reason`.
 */
export interface IvtrPhaseEntry {
    /** Phase name. */
    phase: IvtrPhase;
    /** Agent identity string (from session/agent registry), or null if unknown. */
    agentIdentity: string | null;
    /** ISO timestamp when this phase was started. */
    startedAt: string;
    /** ISO timestamp when this phase was completed, or null if still active. */
    completedAt: string | null;
    /** Whether this phase passed. null = in-progress. */
    passed: boolean | null;
    /** sha256 hashes of attachments produced as evidence for this phase. */
    evidenceRefs: string[];
    /** Populated on loop-back entries to explain the failure. */
    reason?: string;
}
/** Complete IVTR state for a task. */
export interface IvtrState {
    /** Task ID (e.g. 'T811'). */
    taskId: string;
    /**
     * Schema version for forward-only migration.
     *
     * Version 2 adds the `audit` phase. Legacy rows (version absent or 1)
     * continue to work — `audit` counts default to 0 on read.
     *
     * @task T9216
     */
    schemaVersion?: number;
    /** Current active phase. */
    currentPhase: IvtrPhase;
    /** Full ordered history of all phase entries (including loop-backs). */
    phaseHistory: IvtrPhaseEntry[];
    /** ISO timestamp when the IVTR loop was first started. */
    startedAt: string;
    /**
     * Running count of loop-backs per target phase.
     *
     * Incremented each time `loopBackIvtr` targets that phase.
     * After `MAX_LOOP_BACKS_PER_PHASE` loop-backs to the same phase, the next
     * attempt throws `E_IVTR_MAX_RETRIES` and requires HITL escalation.
     *
     * Missing on legacy states — treated as all-zeros on read.
     */
    loopBackCount: Record<IvtrPhase, number>;
}
/**
 * Seed the `tasks.ivtr_state` mirror for a task whose IVTR loop is now driven
 * by `executePlaybook(ivtr.cantbook)` rather than the hand-rolled phase walk
 * (T11805 · collapse-plan §3 item 4).
 *
 * The strict completion gate `E_IVTR_INCOMPLETE` (`tasks/complete.ts`) fires
 * **only when `ivtr_state !== null`**. The `cleo go` seam removed `startIvtr`
 * — the historical sole writer of that column — from the autopilot path; this
 * helper restores the writer so the gate stays load-bearing while the column
 * is retained for one deprecation cycle. It is intentionally **not**
 * `startIvtr`: AC4 of T11805 requires the go path to no longer call
 * `startIvtr`, but the seeded state must remain identical, so both share
 * {@link buildInitialIvtrState}.
 *
 * Idempotent: a task that already has IVTR state is left untouched and its
 * existing state is returned.
 *
 * @param taskId - Task to seed `ivtr_state` for.
 * @param options - Optional cwd and agent identity for the first phase entry.
 * @returns The current (possibly newly seeded) {@link IvtrState}.
 */
export declare function seedIvtrForPlaybook(taskId: string, options?: {
    cwd?: string;
    agentIdentity?: string;
}): Promise<IvtrState>;
/**
 * Terminal status reported by the cantbook runtime (`executePlaybook`) for an
 * IVTR run. Mirrors `PlaybookTerminalStatus` in `@cleocode/playbooks` but is
 * declared locally so `@cleocode/core` never imports the runtime package
 * (the dependency runs the other way — collapse-plan §3).
 */
export type IvtrPlaybookTerminalStatus = 'completed' | 'failed' | 'pending_approval' | 'exceeded_iteration_cap';
/**
 * Outcome of {@link finalizeIvtrFromPlaybook}.
 */
export interface FinalizeIvtrResult {
    /** The IVTR state after the terminal mirror, or `null` if no state existed. */
    state: IvtrState | null;
    /**
     * sha256 of the content-addressed provenance blob written when the run
     * `completed` (reproduces the legacy walk's attachment-store evidence
     * write — collapse-plan §3 mapping row "evidence refs"). Absent when the run
     * did not complete or no state was present.
     */
    evidenceRef?: string;
}
/**
 * Mirror the terminal status of a cantbook-driven IVTR run back into
 * `tasks.ivtr_state` (T11805 · collapse-plan §3 item 4 + Risk #2).
 *
 * The `cleo go` seam seeds `ivtr_state` at the `implement` phase via
 * {@link seedIvtrForPlaybook} but the cantbook runtime (`executePlaybook`)
 * only writes `playbook_runs` — it never touches `ivtr_state`. Without this
 * mirror a fully-successful autonomous run leaves `ivtr_state.currentPhase`
 * frozen at `'implement'`, so the strict `E_IVTR_INCOMPLETE` completion gate
 * (`tasks/complete.ts`) permanently rejects `cleo complete`. This function
 * closes that gap by translating the runtime's terminal status into the
 * equivalent `ivtr_state` transition:
 *
 *  - **`completed`** → walk every required phase to a passing
 *    {@link IvtrPhaseEntry} and set `currentPhase = 'released'`, so the gate
 *    passes exactly as the legacy `advanceIvtr`→`releaseIvtr` walk did. A
 *    content-addressed provenance blob (runId + terminalStatus + a bounded
 *    `finalContext` snapshot) is written to the attachment store and its
 *    sha256 recorded on the released entry's `evidenceRefs`, reproducing the
 *    per-phase evidence write the old walk produced (collapse-plan §3
 *    "evidence refs (sha256 attachments)").
 *  - **`failed` / `exceeded_iteration_cap`** → mark the active phase entry
 *    `passed: false` with the runtime error as the `reason`, leaving
 *    `currentPhase` un-advanced so the gate correctly blocks completion.
 *  - **`pending_approval`** → no-op (the run is awaiting a HITL gate; a later
 *    resume turn finalizes it).
 *
 * Idempotent: a state already at `'released'` is returned untouched.
 *
 * @param taskId - Task whose `ivtr_state` mirror is being finalized.
 * @param terminalStatus - Terminal status from the cantbook run.
 * @param options - Optional cwd, agent identity, runId, error reason, and a
 *   bounded `finalContext` snapshot for the provenance blob.
 * @returns The finalized state + optional provenance evidence ref.
 *
 * @task T11805 — E-ORCH-STATE-MACHINE-COLLAPSE / T11764
 */
export declare function finalizeIvtrFromPlaybook(taskId: string, terminalStatus: IvtrPlaybookTerminalStatus, options?: {
    cwd?: string;
    agentIdentity?: string;
    runId?: string;
    error?: string;
    finalContext?: Record<string, unknown>;
}): Promise<FinalizeIvtrResult>;
/**
 * Maximum number of loop-backs allowed per phase before HITL escalation.
 *
 * The hand-rolled loop-back walk (`loopBackIvtr`) that enforced this cap was
 * deleted in T11896 (the IVTR loop now runs on the cantbook runtime). The
 * constant is RETAINED because {@link classifyReadiness} still reads it to
 * detect tasks whose `ivtr_state.loopBackCount` has reached the monotonic
 * per-target cap (the audit's "Gap A" parity check) and must escalate to HITL.
 *
 * @see packages/core/src/orchestration/classify-readiness.ts
 */
export declare const MAX_LOOP_BACKS_PER_PHASE = 2;
/**
 * Retrieve the current IVTR state for a task, or null if the loop has not
 * been started.
 *
 * @param taskId  - Task ID to inspect.
 * @param options - Optional cwd.
 * @returns IvtrState or null.
 */
export declare function getIvtrState(taskId: string, options?: {
    cwd?: string;
}): Promise<IvtrState | null>;
/**
 * Result of {@link validateSpawnRequest}.
 * @task T9231
 */
export interface SpawnRequestValidationResult {
    allowed: boolean;
    /** Populated when `allowed=false`. */
    code?: string;
    message?: string;
}
/**
 * Validate whether a Lead agent is permitted to write the `implemented` gate
 * for a task.
 *
 * A Lead MUST have produced at least one downstream delegate_task spawn event
 * for the target task in the current session before claiming authorship of
 * the `implemented` gate. If no such event exists, the write is blocked with
 * `E_LEAD_AUTHORSHIP_BYPASS`.
 *
 * Provider-neutral: detection uses the CLEO audit log (SQLite-backed) and the
 * `CLEO_AGENT_ROLE` environment variable — no adapter-specific API required.
 *
 * Override: `CLEO_OWNER_OVERRIDE=1` is not effective here because T1118 L4b
 * already silently blocks overrides for `lead` role — owners must use
 * `CLEO_AGENT_ROLE` unset or set to a non-restricted role to override.
 *
 * @param taskId - Task being verified.
 * @param gate - Gate being written (only `implemented` triggers this check).
 * @param sessionId - Active session ID for audit log lookup.
 * @param cwd - Project root (defaults to `process.cwd()`).
 *
 * @task T9231
 * @adr ADR-070
 */
export declare function validateSpawnRequest(taskId: string, gate: string, sessionId: string | null | undefined): Promise<SpawnRequestValidationResult>;
//# sourceMappingURL=ivtr-loop.d.ts.map