/**
 * Context-switch (pivot) primitive for the orchestrate domain.
 *
 * A `pivot` is a first-class, audited verb for switching the active task in a
 * session away from one task (the `from` task) to another (the `to` task).
 * It exists to replace silent reframes — situations where an agent quietly
 * abandons one line of work and starts another without recording why. Pivots
 * leave a forensic trail consisting of:
 *
 * 1. an audit JSONL line in `.cleo/audit/pivots.jsonl`
 * 2. a memory observation persisted via {@link memoryObserve}
 * 3. an optional dependency edge (`addDepends: [toTaskId]` on the from task)
 *    so the from task cannot complete until the to task resolves.
 *
 * Project-agnostic — pivots are a CLEO-level concept and do not depend on any
 * particular language, build system, or testing framework.
 *
 * @task T1596
 * @epic T-FOUNDATION-LOCKDOWN
 */
import type { DataAccessor } from '../store/data-accessor.js';
/** Relative path to the pivot audit log inside a project root. */
export declare const PIVOT_AUDIT_FILE = ".cleo/audit/pivots.jsonl";
/**
 * Options accepted by {@link pivotTask}.
 */
export interface PivotOptions {
    /** Free-form, human-readable explanation of why the pivot is happening. REQUIRED. */
    reason: string;
    /**
     * When `true` (the default), `addDepends: [toTaskId]` is recorded on the
     * `from` task so it cannot be marked complete until the `to` task resolves.
     * Set to `false` for "advisory" pivots that leave the from task free to
     * complete independently.
     */
    blocksFrom?: boolean;
    /** Optional override for project root — defaults to {@link getProjectRoot}. */
    projectRoot?: string;
    /** Optional override for the data accessor (used by tests). */
    accessor?: DataAccessor;
}
/**
 * Result returned by {@link pivotTask}.
 */
export interface PivotResult {
    /** Stable, opaque id for this pivot — used to correlate audit + memory entries. */
    pivotId: string;
    /** Serialized JSON line written to {@link PIVOT_AUDIT_FILE}. */
    auditEntry: string;
    /** ID of the task that was paused. */
    fromTaskId: string;
    /** ID of the task that became active. */
    toTaskId: string;
    /** Free-form pivot rationale (echoed back for caller convenience). */
    reason: string;
    /** ISO 8601 timestamp of the pivot. */
    timestamp: string;
    /** Active session id at the time of pivot, or null when no session was active. */
    sessionId: string | null;
    /** Agent identifier resolved from `CLEO_AGENT_ID` (or `'local'`). */
    agentId: string;
    /** Whether `addDepends: [toTaskId]` was applied to the from task. */
    blockedFrom: boolean;
    /** Memory observation entry id (if a memory write succeeded). */
    memoryObservationId: string | null;
}
/**
 * Pivot from one task to another, recording a forensic trail.
 *
 * @param fromTaskId - The currently-active task ID being paused.
 * @param toTaskId   - The task ID becoming active in the current session.
 * @param opts       - Options bag (see {@link PivotOptions}).
 * @returns A {@link PivotResult} with the pivot id, audit line, and metadata.
 *
 * @throws {@link CleoError} when validation fails. Mapping:
 *  - missing/empty `reason` → `ExitCode.VALIDATION_ERROR` (E_VALIDATION)
 *  - missing/empty task ids → `ExitCode.INVALID_INPUT` (E_INVALID_INPUT)
 *  - either task does not exist → `ExitCode.NOT_FOUND` (E_NOT_FOUND)
 *  - from task is not active   → `ExitCode.ACTIVE_TASK_REQUIRED` (E_NOT_ACTIVE)
 *
 * @example
 * ```ts
 * await pivotTask('T1596', 'T1597', {
 *   reason: 'audit -> layering -> engine sidetrack discovered',
 * });
 * ```
 */
export declare function pivotTask(fromTaskId: string, toTaskId: string, opts: PivotOptions): Promise<PivotResult>;
//# sourceMappingURL=pivot.d.ts.map