/**
 * MentorOnboardingTick — the structural core of one mentor heartbeat tick
 * (FRAMEWORK-ONBOARDING-MENTOR-SPEC §3, §4, §6, §19.4).
 *
 * This is PURE orchestration logic with every side-effect injected as a
 * callback, so the whole tick is unit-testable without tmux, an LLM, or a
 * server. The structural guarantees the spec demands live HERE (in code), not
 * in a prompt:
 *
 *   - The leak canary runs FIRST every tick; a dead detector halts the tick and
 *     self-reports (§4.3) — the detector can't silently rot.
 *   - The budget check is a fail-closed PRE-tick gate: under budget pressure the
 *     ENTIRE tick is skipped before any spend or any contact (§6) — never a
 *     partial Stage A without Stage B.
 *   - The safe-window check gates on a durable mentee state, not a clock (§12 Q3).
 *   - Stage A is driven via the injected `spawnStageA` (the §19.4 runner passes
 *     the empty-tool-grant spawn); its transcript is run through the leakage
 *     detector and any leak is captured as an instar-integration-gap (§4.3).
 *   - Stage B forensics + capture run via injected callbacks; the ledger's
 *     captureRun logs the run to the funnel even when nothing is found (§19.2).
 */
import { type ConversationSurface } from '../monitoring/MentorStageA.js';
import type { CaptureRunInput, CaptureRunResult, ForensicFinding } from '../monitoring/FrameworkIssueLedger.js';
/** Mentor run modes (spec §16). `off` never reaches the tick; `dry-run` does
 *  everything except deliver a message to the mentee; `live` is the full loop. */
export type MentorMode = 'dry-run' | 'live';
/**
 * One mentor↔mentee differential cycle captured from a tick — the raw materials
 * for an ApprenticeshipCycleStore `mentor-mentee-differential` record. The tick
 * produces these; the host's injected `recordCycle` decides whether/where to
 * persist them (it no-ops unless an apprenticeship instance is configured). This
 * is what makes the AUTOMATED mentor loop fire the keystone differential axis,
 * the structural fix for the program's #1 drift failure.
 */
export interface MentorCycleCapture {
    framework: string;
    /** Short descriptor of the work the mentee was driven through this tick. */
    task: string;
    /** The mentee's Stage-A transcript (its output). */
    menteeOutput: string;
    /** The overseer/forensics differential — one string per finding. */
    differential: string[];
}
export interface MentorTickDeps {
    framework: string;
    mode: MentorMode;
    /** The user-visible conversation surface (Stage A's only input). */
    surface: ConversationSurface;
    /** Durable safe-window: true when the mentee is at a stable point (task-complete /
     *  waiting / blocked / quiet-after-user-msg) AND the min-interval floor has elapsed. */
    safeWindowOpen: boolean;
    /** Fail-closed budget gate (the GET /autonomous/can-start precedent). */
    budgetOk: boolean;
    /** LLM-availability gate: false when the shared LlmCircuitBreaker is open/half-open
     *  (the provider is rate-limited). The tick's Stage A (spawn) and Stage B (`claude -p`
     *  forensics) are both LLM-backed, so running while rate-limited just fails and
     *  RE-TRIPS the circuit (which pauses ALL LLM-backed work). Skip instead. */
    llmAvailable: boolean;
    /** Spawn Stage A (empty tool grant) and return its transcript. Injected so the
     *  pure tick has no SessionManager/tmux dependency. */
    spawnStageA: (prompt: string) => Promise<string>;
    /** Stage-B forensics: read the mentee's logs/rollouts/diff and return findings.
     *  Injected so the pure tick has no LLM dependency. */
    runStageBForensics: () => Promise<ForensicFinding[]>;
    /** Write findings + log the run to the ledger funnel (§19.2). */
    capture: (input: CaptureRunInput) => CaptureRunResult;
    /**
     * Record one mentor↔mentee differential CYCLE (in addition to the per-finding
     * ledger capture above). Injected + optional: the host wires it to the
     * ApprenticeshipCycleStore only when a `mentor.apprenticeshipInstanceId` is
     * configured, so by default it no-ops. This is the keystone-axis hook — the
     * automated loop records `mentor-mentee-differential` cycles, not just findings.
     */
    recordCycle?: (input: MentorCycleCapture) => void;
    /**
     * Deliver the Stage-A message to the mentee — called ONLY in `live` mode (§6).
     * The host's implementation MUST be persist-only (queue to a durable outbox the
     * mentee's already-running session picks up), never spawn-on-receive — that's
     * the structural fix for the cross-agent spawn loop. Omitted/undefined ⇒ no
     * delivery (the dormant + dry-run default).
     */
    deliverToMentee?: (framework: string, message: string) => void;
    /** Tick id for provenance/episode keying. */
    tickId?: string;
    now?: () => number;
    /** Leak-detector liveness check; defaults to the real canary. Injected for tests. */
    canaryCheck?: () => boolean;
}
export type MentorTickReason = 'canary-failed' | 'budget' | 'llm-rate-limited' | 'unsafe-window' | 'stage-a-failed' | 'ran';
export interface MentorTickResult {
    ran: boolean;
    reason: MentorTickReason;
    mode?: MentorMode;
    /** True when the Stage-A message was delivered to the mentee (live mode only). */
    delivered?: boolean;
    leakDetected?: boolean;
    observationsWritten?: number;
    findingsCount?: number;
    /** The Stage-A message the mentor produced (delivered only in `live` mode by the runner). */
    stageAMessage?: string;
    /**
     * When a tick throws (e.g. the Stage-A compose-session spawn/capture fails),
     * the underlying error message — surfaced in GET /mentor/status.lastResult so
     * the real cause is visible instead of being swallowed into the opaque
     * `reason: 'stage-a-failed'`. Diagnosability for the mentor failure class.
     */
    error?: string;
}
/**
 * Run one mentor tick. Returns a structured result; the only side effects are
 * via the injected callbacks. Order is load-bearing (canary → budget →
 * safe-window → Stage A → leak → Stage B → capture).
 */
export declare function runMentorTick(deps: MentorTickDeps): Promise<MentorTickResult>;
//# sourceMappingURL=MentorOnboardingTick.d.ts.map