@glrs-dev/cli 2.3.0 → 2.4.1

package/dist/node_modules/@glrs-dev/autopilot/dist/index.d.ts

@@ -0,0 +1,1765 @@
+import { EventEmitter } from 'node:events';
+import { execFile } from 'node:child_process';
+import { Logger } from 'pino';
+
+/**
+ * AgentAdapter — abstract interface for driving an AI agent programmatically.
+ *
+ * Decouples the autopilot loop engine from any specific agent implementation
+ * (OpenCode, Claude Code, etc.). The concrete adapter is injected at runtime
+ * by the CLI command.
+ */
+interface AgentHandle {
+    readonly id: string;
+}
+interface SessionResult$1 {
+    kind: "idle" | "error" | "stall" | "abort" | "question_rejected";
+    message?: string;
+    stallMs?: number;
+    title?: string;
+}
+interface AgentAdapter {
+    readonly name: string;
+    start(opts: {
+        cwd: string;
+    }): Promise<AgentHandle>;
+    createSession(handle: AgentHandle, opts: {
+        agentName?: string;
+    }): Promise<string>;
+    sendAndWait(handle: AgentHandle, opts: {
+        sessionId: string;
+        message: string;
+        stallMs?: number;
+        abortSignal?: AbortSignal;
+        onToolCall?: (name: string, arg?: string) => void;
+        onTextDelta?: (chars: number) => void;
+        onCostUpdate?: (cost: number, tokens: {
+            input: number;
+            output: number;
+        }) => void;
+    }): Promise<SessionResult$1>;
+    getLastResponse(handle: AgentHandle, sessionId: string): Promise<string>;
+    getSessionCost(handle: AgentHandle, sessionId: string): Promise<number>;
+    /** Return cost + token totals for a session. Optional — callers fall back to getSessionCost when absent. */
+    getSessionStats?(handle: AgentHandle, sessionId: string): Promise<{
+        cost: number;
+        tokensIn: number;
+        tokensOut: number;
+    }>;
+    shutdown(handle: AgentHandle): Promise<void>;
+    enhanceError?(message: string): Promise<string>;
+}
+
+/**
+ * Typed SessionEvent discriminated union for the autopilot event stream.
+ *
+ * Every event has `type` (the discriminant) and `timestamp` (ISO 8601 string).
+ * Consumers narrow to a specific variant via the exported type guards.
+ *
+ * Channel 1: EventEmitter (in-process, consumed by CLI renderer)
+ * Channel 2: NDJSON file at .agent/autopilot-events.jsonl (consumed by TUI / --status)
+ */
+interface SessionStartEvent {
+    type: "session:start";
+    timestamp: string;
+    planPath: string;
+    cwd: string;
+    fast: boolean;
+    resume: boolean;
+    enrichModel?: string;
+    executeModel?: string;
+}
+interface SessionDoneEvent {
+    type: "session:done";
+    timestamp: string;
+    exitReason: string;
+    iterations: number;
+    cumulativeCostUsd?: number;
+    message: string;
+}
+interface EnrichStartEvent {
+    type: "enrich:start";
+    timestamp: string;
+    planPath: string;
+    fileCount: number;
+}
+interface EnrichFileStartEvent {
+    type: "enrich:file:start";
+    timestamp: string;
+    file: string;
+}
+interface EnrichFileDoneEvent {
+    type: "enrich:file:done";
+    timestamp: string;
+    file: string;
+    toolCalls: number;
+    specFile?: string;
+}
+interface EnrichFileSkipEvent {
+    type: "enrich:file:skip";
+    timestamp: string;
+    file: string;
+    reason: string;
+}
+interface EnrichFileErrorEvent {
+    type: "enrich:file:error";
+    timestamp: string;
+    file: string;
+    error: string;
+}
+interface EnrichDoneEvent {
+    type: "enrich:done";
+    timestamp: string;
+    filesProcessed: number;
+}
+interface PhaseStartEvent {
+    type: "phase:start";
+    timestamp: string;
+    phase: string;
+    laneId: string;
+    current: number;
+    total: number;
+}
+interface PhaseDoneEvent {
+    type: "phase:done";
+    timestamp: string;
+    phase: string;
+    laneId: string;
+    completed: boolean;
+    iterations: number;
+    costUsd: number;
+}
+interface IterationStartEvent {
+    type: "iteration:start";
+    timestamp: string;
+    iteration: number;
+    maxIterations: number;
+    laneId?: string;
+}
+interface IterationDoneEvent {
+    type: "iteration:done";
+    timestamp: string;
+    iteration: number;
+    durationMs: number;
+    madeProgress: boolean;
+    filesChanged?: number;
+    commitSubject?: string;
+    costUsd?: number;
+    cumulativeCostUsd?: number;
+    laneId?: string;
+}
+interface ToolCallEvent {
+    type: "tool:call";
+    timestamp: string;
+    toolName: string;
+    firstArg?: string;
+    iteration: number;
+    laneId?: string;
+}
+interface CostUpdateEvent {
+    type: "cost:update";
+    timestamp: string;
+    cumulativeCostUsd: number;
+    isEstimated: boolean;
+    iteration: number;
+    tokensIn?: number;
+    tokensOut?: number;
+}
+interface ThinkingEvent {
+    type: "thinking";
+    timestamp: string;
+    iteration: number;
+    /** Cumulative characters streamed in the current reasoning block. */
+    chars: number;
+    /** Seconds since the last tool call (or iteration start). */
+    elapsedSec: number;
+    laneId?: string;
+}
+interface ErrorEvent {
+    type: "error";
+    timestamp: string;
+    message: string;
+    iteration?: number;
+    phase?: string;
+}
+interface CredentialExpiredEvent {
+    type: "credential:expired";
+    timestamp: string;
+    provider: string;
+    message: string;
+    iteration: number;
+}
+interface VerifyStartEvent {
+    type: "verify:start";
+    timestamp: string;
+    phase: string;
+    itemCount: number;
+}
+interface VerifyResultEvent {
+    type: "verify:result";
+    timestamp: string;
+    phase: string;
+    itemId: string;
+    command: string;
+    passed: boolean;
+    stderr?: string;
+}
+interface VerifyDoneEvent {
+    type: "verify:done";
+    timestamp: string;
+    phase: string;
+    passed: number;
+    failed: number;
+}
+type SessionEvent = SessionStartEvent | SessionDoneEvent | EnrichStartEvent | EnrichFileStartEvent | EnrichFileDoneEvent | EnrichFileSkipEvent | EnrichFileErrorEvent | EnrichDoneEvent | PhaseStartEvent | PhaseDoneEvent | IterationStartEvent | IterationDoneEvent | ToolCallEvent | CostUpdateEvent | ThinkingEvent | ErrorEvent | CredentialExpiredEvent | VerifyStartEvent | VerifyResultEvent | VerifyDoneEvent;
+
+/**
+ * NDJSON event stream writer and reader for the autopilot event stream.
+ *
+ * Channel 2: .agent/autopilot-events.jsonl
+ *
+ * Writer: append-only, sync writes (crash-safe).
+ * Reader: full read or tail mode (byte offset).
+ */
+
+/**
+ * Append-only NDJSON writer. Opens the file for append on construction,
+ * writes each event as a JSON line synchronously (crash-safe), and closes
+ * the file descriptor on `close()`.
+ */
+declare class EventStreamWriter {
+    private fd;
+    constructor(filePath: string);
+    /**
+     * Serialize `event` as a JSON line and write it synchronously.
+     * Sync write ensures the line is on disk even if the process crashes
+     * immediately after.
+     */
+    emit(event: SessionEvent): void;
+    /**
+     * Close the underlying file descriptor. Safe to call multiple times
+     * (subsequent calls are no-ops).
+     */
+    close(): void;
+}
+/**
+ * NDJSON reader for the autopilot event stream.
+ *
+ * Supports full reads and tail mode (byte offset). Truncated or malformed
+ * last lines are silently skipped — they indicate a crash mid-write.
+ */
+declare class EventStreamReader {
+    private readonly filePath;
+    constructor(filePath: string);
+    /**
+     * Read all events from the file. Returns an empty array if the file
+     * does not exist or is empty.
+     */
+    readAll(): SessionEvent[];
+    /**
+     * Read events starting at `byteOffset`. Returns the parsed events and
+     * the new byte offset (= file size after reading). Useful for polling
+     * (tail mode): pass the returned `newOffset` on the next call to read
+     * only new events.
+     *
+     * Truncated or malformed last lines are skipped.
+     */
+    readFrom(byteOffset: number): {
+        events: SessionEvent[];
+        newOffset: number;
+    };
+}
+
+/**
+ * Plan-parser module for the autopilot engine.
+ *
+ * Parses both single-file plans (one .md file with checkboxes or a
+ * plan-state fence) and multi-file plans (a directory containing
+ * main.md + phase_N.md files). Returns structured progress data.
+ *
+ * Never throws — all errors degrade to zero-count results so the
+ * loop's heartbeat can fall back to plan-blind mode safely.
+ */
+interface PlanPhase {
+    file: string;
+    totalItems: number;
+    checkedItems: number;
+}
+interface PlanState {
+    type: "single" | "multi";
+    totalItems: number;
+    checkedItems: number;
+    phaseCount: number;
+    phasesCompleted: number;
+    phases: PlanPhase[];
+}
+interface PlanFileEntry {
+    path: string;
+    isNew: boolean;
+    change: string;
+}
+interface PlanItem {
+    id: string;
+    intent: string;
+    files: PlanFileEntry[];
+    tests: string[];
+    verify: string;
+    checked: boolean;
+}
+/**
+ * Parse a plan at the given path and return structured progress data.
+ *
+ * - If `planPath` is a directory containing `main.md`, it's treated as
+ *   a multi-file plan.
+ * - If `planPath` is a `.md` file, it's treated as a single-file plan.
+ * - Any error (missing file, parse failure, etc.) returns a degraded
+ *   result with zero counts — never throws.
+ */
+declare function parsePlanState(planPath: string): PlanState;
+/**
+ * Parse individual plan items from a plan-state fence block.
+ *
+ * Each item starts with `- [ ] id:` or `- [x] id:` and contains
+ * optional `intent:`, `files:`, `tests:`, and `verify:` fields.
+ *
+ * Returns an empty array if no fence is found or the content is malformed.
+ * Never throws.
+ */
+declare function parseItems(content: string): PlanItem[];
+
+/**
+ * Verify-command runner for the post-phase test gate (item 4.1).
+ *
+ * After a phase reports `phaseComplete === true` (every checkbox checked),
+ * the orchestrator runs each plan-state item's `verify:` command in a
+ * child process and reports pass/fail. Phases whose verify commands
+ * fail are treated as incomplete — the failure is fed back into the
+ * next iteration's prompt so the agent can fix it.
+ *
+ * Each command runs via `/bin/sh -c` so users can write shell features
+ * (pipes, redirects, env vars) into a `verify:` field. Per-command
+ * timeout = 5 minutes; on timeout we synthesize a stderr message and
+ * return `passed: false` rather than throwing — `runVerifyCommands`
+ * always returns a `VerifyResult[]` so callers can build a result table
+ * without wrapping every call in try/catch.
+ */
+
+declare const execFileDefault$3: typeof execFile.__promisify__;
+/** Result of running a single `verify:` command. */
+interface VerifyResult {
+    /** Plan-state item id (e.g. "4.1"). */
+    itemId: string;
+    /** The exact command string that was run. */
+    command: string;
+    /** True iff the child process exited with code 0 within the timeout. */
+    passed: boolean;
+    stdout: string;
+    stderr: string;
+    /** Wall-clock duration of the command in milliseconds. */
+    durationMs: number;
+}
+interface RunVerifyCommandsOptions {
+    /** Per-command timeout in milliseconds (default: 5 minutes). */
+    timeoutMs?: number;
+    /**
+     * Test-only: inject execFile replacement.
+     * @internal
+     */
+    _deps?: {
+        execFile?: typeof execFileDefault$3;
+    };
+}
+/**
+ * Run each item's `verify:` command in `cwd` and return the results.
+ *
+ * Items without a `verify:` field are skipped (no result emitted). The
+ * function never throws — every executed command yields exactly one
+ * `VerifyResult`, including timeouts and spawn failures.
+ */
+declare function runVerifyCommands(items: PlanItem[], cwd: string, opts?: RunVerifyCommandsOptions): Promise<VerifyResult[]>;
+
+/**
+ * Structured logger for the autopilot CLI.
+ *
+ * Single sink: **file** at trace level (captures everything, always).
+ *   JSON — files are for grep/telemetry/debugging, not eyes.
+ *   Default path: `<cwd>/.agent/autopilot-logs/<ISO-timestamp>.log`.
+ *   Override via GLRS_AUTOPILOT_LOG_FILE=<path> or "off" to disable.
+ *
+ * User-facing output goes to stderr via plain `process.stderr.write`
+ * in the calling code (TUI-style). Pino does NOT write to stderr —
+ * the two channels are separate by design.
+ *
+ * Environment variables:
+ *   - GLRS_AUTOPILOT_LOG_FILE: explicit path, or "off" to disable file sink
+ */
+
+/**
+ * Per-run logger state. Created once per autopilot invocation.
+ */
+interface AutopilotLogger {
+    /** The pino root logger. Call .child({ component }) for module-level loggers. */
+    root: Logger;
+    /** Path to the file log sink, if enabled. */
+    logFilePath: string | null;
+    /** Flush all streams. Call before process exit. */
+    flush: () => Promise<void>;
+}
+/**
+ * Create the autopilot logger with file sink only.
+ * Call ONCE per autopilot run. Pass `cwd` so the default file path
+ * resolves relative to the user's project.
+ *
+ * User-facing output goes to stderr via process.stderr.write in the
+ * calling code. Pino is for structured file logging only.
+ *
+ * @deprecated The autopilot code path now uses the typed SessionEvent stream
+ * (session-events.ts + event-stream.ts) instead of pino for user-visible output.
+ * This function is kept for non-autopilot consumers and as a verbose debug
+ * channel inside the loop engine. New code should use SessionRunner + EventStreamWriter.
+ */
+declare function createAutopilotLogger(opts: {
+    cwd: string;
+}): AutopilotLogger;
+/**
+ * Convenience factory for module-level loggers when the root logger is
+ * already created. Use this inside modules that receive a root logger
+ * from the caller:
+ *
+ *   const log = childLogger(root, "autopilot.loop");
+ *   log.info("hello");  // emits with component: "autopilot.loop"
+ */
+declare function childLogger(root: Logger, component: string): Logger;
+
+type LoopExitReason = "sentinel" | "max-iterations" | "timeout" | "struggle" | "kill-switch" | "stall" | "error" | "aborted";
+interface LoopResult {
+    exitReason: LoopExitReason;
+    iterations: number;
+    message: string;
+    /** The OpenCode session ID for the loop session. Used by the debrief module. */
+    sessionId?: string;
+    /** Cumulative cost in USD for the loop session. Used by the debrief module. */
+    cumulativeCostUsd?: number;
+    /**
+     * Per-phase cost breakdown for multi-phase plans.
+     * Populated by the multi-phase runner (loop-session.ts) when available.
+     */
+    phaseBreakdown?: Array<{
+        phaseFile: string;
+        iterations: number;
+        costUsd: number;
+    }>;
+    /**
+     * Per-lane cost breakdown for parallel-lane runs (item 3.5).
+     * Populated by `loop-session.ts` only when `--parallel > 1` produced
+     * a real parallel run. `Map<laneId, costUsd>`. Optional to preserve
+     * backward compatibility for callers that never enabled parallelism.
+     */
+    laneCosts?: Map<string, number>;
+    /**
+     * Surviving worktree paths from a partially-failed parallel run
+     * (item 3.6). When a lane's merge failed, its worktree is left on
+     * disk and the path is reported here so the user can manually
+     * `git worktree remove --force <path>`. Empty/undefined on clean runs.
+     */
+    orphanedWorktrees?: string[];
+    /**
+     * Per-phase verify-command results from the post-phase test gate
+     * (item 4.1). Populated by `loop-session.ts` after each phase runs
+     * its `verify:` commands (one per plan-state item). When any verify
+     * command fails the phase is treated as incomplete (its main.md
+     * checkbox is NOT marked) and the failures are surfaced here so the
+     * debrief can render a results table. Optional to preserve back-
+     * compat for callers that never enabled verify gating.
+     */
+    verifyResults?: Array<{
+        phaseFile: string;
+        results: VerifyResult[];
+    }>;
+    /**
+     * Path to the changeset file generated after all phases passed
+     * (item 4.6). Absent when generation was skipped (test deps in
+     * use, no phases run, or a prior failure short-circuited the run).
+     */
+    changesetPath?: string;
+    /**
+     * URL of the PR opened by --ship (item 4.7). Absent when --ship was
+     * not passed or auto-ship failed. The hard-rule guards (no force-
+     * push, no main/master push, no merge) live inside `auto-ship.ts`.
+     */
+    prUrl?: string;
+    /**
+     * The agent adapter + handle, kept alive for the caller to reuse
+     * (e.g., for the debrief). The caller is responsible for calling
+     * `adapter.shutdown(handle)` when done. Present only when `keepAlive` is
+     * true in RalphLoopOptions (default: false — adapter is shut down
+     * in the finally block).
+     */
+    agentHandle?: {
+        adapter: AgentAdapter;
+        handle: AgentHandle;
+    };
+}
+interface RalphLoopOptions {
+    /** The prompt to send to PRIME each iteration. */
+    prompt: string;
+    /** Working directory for the OpenCode server. */
+    cwd: string;
+    /** Agent name for the session (default: "autopilot-prime"). */
+    agentName?: string;
+    /** Maximum number of iterations (default: MAX_ITERATIONS). */
+    maxIterations?: number;
+    /** Total wall-clock timeout in ms (default: TIMEOUT_MS). */
+    timeoutMs?: number;
+    /** Per-iteration stall timeout in ms (default: STALL_MS). */
+    stallMs?: number;
+    /** Struggle threshold — consecutive zero-progress iterations (default: STRUGGLE_THRESHOLD). */
+    struggleThreshold?: number;
+    /**
+     * Optional lane id for parallel-lane execution (item 3.4). When set,
+     * all childLogger names are scoped under `autopilot.loop.lane.<id>`
+     * (and tool/stream/status equivalents) so pino emits a `name` field
+     * the user-facing formatter can prefix as `[lane-N]`. Status snapshots
+     * also include this id so status.ts can render multi-lane state.
+     * When unset (default), logging is scoped at `autopilot.loop` as before.
+     */
+    laneId?: string;
+    /**
+     * Webhook URL to POST lifecycle events to (optional).
+     * Supports plain webhooks and Slack incoming webhooks (auto-detected).
+     */
+    notifyUrl?: string;
+    /**
+     * When true, the agent adapter is NOT shut down in the finally block.
+     * Instead, the adapter + handle are exposed on the LoopResult so the
+     * caller can reuse them (e.g., for the debrief). The caller is
+     * responsible for calling `adapter.shutdown(handle)`.
+     * Default: false.
+     */
+    keepAlive?: boolean;
+    /**
+     * Pre-created logger to reuse. When provided, the loop skips creating
+     * its own `createAutopilotLogger` and uses this one instead. This lets
+     * the entire autopilot session (enrichment + loop + debrief) share a
+     * single log file.
+     */
+    logger?: AutopilotLogger;
+    /**
+     * Optional event emitter for typed SessionEvents (Channel 1).
+     * When provided, the loop emits iteration:start, iteration:done,
+     * tool:call, cost:update, error, and credential:expired events.
+     * The pino logger is kept as a verbose debug channel.
+     */
+    emitter?: SessionEventEmitter;
+    /**
+     * Agent adapter to use for driving the AI agent.
+     * Required in production — the CLI injects the OpenCode adapter.
+     * Optional only when _deps.startServer is provided (legacy test path).
+     */
+    adapter?: AgentAdapter;
+}
+/**
+ * Run the Ralph loop: send prompt → wait for idle → inspect response →
+ * retry or exit.
+ */
+declare function runRalphLoop(opts: RalphLoopOptions): Promise<LoopResult>;
+
+/**
+ * Shared type definitions for the loop session orchestrator and plan session.
+ * Defined here so both loop-session.ts, plan-session.ts (in autopilot) and
+ * the CLI interactive command can import them without circular dependencies.
+ */
+
+interface PlanSessionOptions {
+    scopePath: string;
+    planDir: string;
+    slug: string;
+}
+interface PlanSessionResult {
+    planPath: string;
+}
+interface LoopSessionOptions {
+    planPath: string;
+    cwd: string;
+    /** When true, use the fast executor agent (mid-execute tier). */
+    fast?: boolean;
+    /**
+     * When true, read `<cwd>/.agent/autopilot-checkpoint.json` and skip
+     * phases already listed in `completedPhases` (provided the checkpoint's
+     * `planPath` matches the current `--plan`). On full completion the
+     * checkpoint is deleted.
+     */
+    resume?: boolean;
+    /**
+     * Per-phase iteration budget override. When unset, defaults are
+     * picked by tier (see MAX_ITERATIONS_PER_PHASE_BY_TIER):
+     *   - deep: 5
+     *   - mid-execute / autopilot-execute: 10
+     *   - fast: 10
+     * A phase that hits `max-iterations` is treated as a soft failure:
+     * checkpoint is written, a warning is logged, and the run continues
+     * to the next phase rather than terminating.
+     */
+    maxIterationsPerPhase?: number;
+    /**
+     * Maximum number of retry attempts per phase when verify fails.
+     * Default: 3. Set to 1 to disable retries (single attempt per phase).
+     */
+    maxPhaseRetries?: number;
+    /**
+     * Number of parallel lanes for phase execution (item 3.3).
+     * Default: 1 (sequential — preserves the original semantics exactly).
+     * When > 1 AND the conflict graph reveals at least one independent
+     * pair, phases are dispatched to per-lane git worktrees and merged
+     * back on completion (items 3.2 + 3.6). When ≤ 1 OR no parallelism
+     * is possible (every phase conflicts with every other), the runner
+     * falls back to the sequential path (item 3.7) — no worktree overhead.
+     */
+    parallel?: number;
+    /**
+     * Auto-ship after all phases pass (item 4.7). When true, the runner
+     * pushes the current branch and opens a PR via `gh pr create` after
+     * verify passes and a changeset has been generated. When false (the
+     * default), the runner stops at "all phases complete, run `/ship` to
+     * finalize." Push targets and the no-force/no-merge invariants are
+     * enforced inside `auto-ship.ts`.
+     */
+    ship?: boolean;
+    /**
+     * Pre-created logger shared across the entire autopilot session
+     * (enrichment + loop + debrief). When provided, the loop reuses
+     * this logger instead of creating its own.
+     */
+    logger?: AutopilotLogger;
+    /**
+     * Optional event emitter for typed SessionEvents (Channel 1).
+     * When provided, loop-session.ts emits phase:start, phase:done,
+     * verify:*, and error events. The emitter is also forwarded to
+     * runRalphLoop so iteration-level events flow through.
+     */
+    emitter?: SessionEventEmitter;
+    /**
+     * Agent adapter to use for driving the AI agent.
+     * Required in production — the CLI injects the OpenCode adapter.
+     */
+    adapter?: AgentAdapter;
+    /**
+     * Optional abort signal for graceful shutdown. When the signal fires,
+     * the loop writes a checkpoint and returns with exitReason: "aborted"
+     * at the next phase boundary. Mid-tool-call iterations are not
+     * interrupted — the abort is checked between phases only.
+     */
+    signal?: AbortSignal;
+}
+
+interface SessionRunnerOptions {
+    planPath: string;
+    cwd: string;
+    fast?: boolean;
+    resume?: boolean;
+    parallel?: number;
+    ship?: boolean;
+    maxIterationsPerPhase?: number;
+    /**
+     * The agent adapter (e.g. OpenCodeAdapter). Required for production use.
+     * The adapter drives the actual agent CLI — start server, create session,
+     * send prompts, wait for idle.
+     */
+    adapter?: AgentAdapter;
+    /**
+     * Path for the NDJSON event stream file.
+     * Defaults to `<cwd>/.agent/autopilot-events.jsonl`.
+     */
+    eventStreamPath?: string;
+    /**
+     * Injectable dependencies for testing.
+     * @internal
+     */
+    _deps?: SessionRunnerDeps;
+}
+interface SessionResult {
+    planPath: string;
+    loopResult: LoopResult;
+}
+/**
+ * Injectable dependencies for testing.
+ * @internal
+ */
+interface SessionRunnerDeps {
+    /** Override enrichPlanForFastModel for testing. */
+    enrichPlan?: (cwd: string, planPath: string, logger?: AutopilotLogger) => Promise<void>;
+    /** Override runLoopSession for testing. */
+    runLoopSession?: (opts: LoopSessionOptions & {
+        _deps?: unknown;
+    }) => Promise<LoopResult>;
+    /** Override createAutopilotLogger for testing. */
+    createLogger?: (opts: {
+        cwd: string;
+    }) => AutopilotLogger;
+    /** Override EventStreamWriter constructor for testing. */
+    createWriter?: (filePath: string) => EventStreamWriter;
+}
+/**
+ * Typed EventEmitter for SessionEvents. Wraps Node's EventEmitter with a
+ * typed `emit` method so callers get type-checked event payloads.
+ */
+declare class SessionEventEmitter extends EventEmitter {
+    emitEvent(event: SessionEvent): void;
+}
+declare class SessionRunner {
+    /** Channel 1: in-process event emitter. Subscribe to event types or "event" for all. */
+    readonly events: SessionEventEmitter;
+    private readonly opts;
+    private _abortController;
+    private _abortCount;
+    constructor(opts: SessionRunnerOptions);
+    /**
+     * Request graceful shutdown. First call signals the running loop session
+     * to stop at the next phase boundary (checkpoint is written). Second call
+     * force-exits via process.exit(1).
+     */
+    abort(): void;
+    /**
+     * Run the autopilot session:
+     * 1. Emit session:start
+     * 2. If --fast, run enrichment (emitting enrich:* events)
+     * 3. Run the loop session (emitting phase:* events via loop-session.ts)
+     * 4. Emit session:done
+     *
+     * Returns a SessionResult with the final LoopResult.
+     */
+    run(): Promise<SessionResult>;
+}
+
+/**
+ * Loop session runner for the interactive autopilot orchestrator.
+ *
+ * For multi-file plans (directory with main.md + phase_N.md files):
+ *   - Reads main.md to extract Goal and Constraints sections
+ *   - Detects unchecked phase files from the ## Phases section
+ *   - Creates a fresh runRalphLoop session per phase with a prompt
+ *     containing Goal + Constraints + full phase file contents
+ *   - After each successful phase, updates main.md's phase checkbox
+ *   - Stops early if a phase exits with struggle/stall/error/timeout
+ *
+ * For single-file plans (.md file):
+ *   - Unchanged behavior: single runRalphLoop call with a direct prompt
+ */
+
+/**
+ * Injectable dependencies for testing.
+ * @internal
+ */
+interface LoopSessionDeps {
+    runRalphLoop?: (opts: RalphLoopOptions) => Promise<LoopResult>;
+    /** Override filesystem stat check for testing. */
+    isDirectory?: (p: string) => boolean;
+    /** Override fs.readFileSync for testing. */
+    readFileSync?: (p: string) => string;
+    /** Override fs.writeFileSync for testing. */
+    writeFileSync?: (p: string, content: string) => void;
+    /**
+     * Override the post-phase verify-command runner (item 4.1) for tests
+     * that don't want to actually shell out. Default: real implementation
+     * from `verify-runner.ts`.
+     */
+    runVerifyCommands?: typeof runVerifyCommands;
+}
+/**
+ * Run a headless loop session against a plan.
+ *
+ * Detects whether planPath is a directory (multi-file plan) or a file
+ * (single-file plan) and shapes the prompt accordingly, then delegates
+ * to runRalphLoop.
+ */
+declare function runLoopSession(opts: LoopSessionOptions & {
+    _deps?: LoopSessionDeps;
+}): Promise<LoopResult>;
+
+/**
+ * Plan enrichment for fast-model execution.
+ *
+ * When --fast is used, this module reads the markdown plan files and
+ * generates `spec/*.yaml` files from them. The spec IS the enriched
+ * artifact — one LLM pass per file that reads the markdown + codebase
+ * and produces structured YAML with enrichment context included:
+ *   - mirror: references to similar existing files (pattern-match targets)
+ *   - context: key function signatures, 10-20 lines of code for modified files
+ *   - conventions: import style, export pattern, test framework, naming
+ *
+ * Per-file iteration: each plan file gets its own fresh session and its
+ * own short-context prompt. This keeps each enrichment call's context
+ * small and lets a SIGINT halfway through preserve the already-generated
+ * spec files. Whole-plan single-pass enrichment is gone — the cost
+ * savings of context-locality more than compensate for the per-file
+ * session overhead.
+ *
+ * Idempotency (item 4.3): before opening any session, check whether
+ * spec/ already exists with all items enriched (100% threshold). If so,
+ * skip the entire pass. This saves an Opus call on re-runs of `--fast`
+ * against an already-enriched plan.
+ */
+
+/**
+ * Enrich a plan for fast-model execution by generating spec/*.yaml files.
+ *
+ * For multi-file plans (directory with main.md), generates a spec YAML file
+ * for each markdown plan file in its own session. For single-file plans,
+ * generates a spec file for that file. Each per-file session is independent —
+ * failures in one file are logged and skipped, the loop moves to the next.
+ *
+ * Idempotency: if spec/ already exists with all items fully enriched,
+ * enriched, the entire pass is skipped. Per-file: if a spec YAML already
+ * exists and is sufficiently enriched, that file is skipped.
+ */
+declare function enrichPlanForFastModel(cwd: string, planPath: string, logger?: AutopilotLogger, emitter?: SessionEventEmitter, adapter?: AgentAdapter): Promise<void>;
+
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validate a parsed main spec object. Returns structured errors rather
+ * than throwing so callers can surface clear messages.
+ */
+declare function validateMainSpec(raw: unknown): ValidationResult;
+/**
+ * Validate a parsed phase spec object. Returns structured errors rather
+ * than throwing so callers can surface clear messages.
+ */
+declare function validatePhaseSpec(raw: unknown): ValidationResult;
+
+/**
+ * YAML spec parser for the autopilot engine.
+ *
+ * Reads spec/main.yaml and spec/<phase>.yaml files, validates them
+ * against the schema, and converts to the canonical PlanState/PlanItem
+ * types used throughout the autopilot.
+ *
+ * Never throws — all errors degrade to zero-count results or empty
+ * arrays so callers can fall back gracefully.
+ */
+
+/**
+ * Check whether a plan directory has a YAML spec (spec/main.yaml exists).
+ * This is the gate that determines whether to use the YAML path or fall
+ * back to the markdown parser.
+ */
+declare function hasSpec(planDir: string): boolean;
+/**
+ * Parse a phase YAML file and return PlanItem[].
+ * Returns [] on any error (missing file, invalid YAML, schema failure).
+ */
+declare function parseSpecItems(phasePath: string): Array<PlanItem & {
+    mirror?: string;
+    context?: string;
+    conventions?: string;
+}>;
+/**
+ * Detect phase files from spec/main.yaml. Returns sorted list of phase
+ * filenames (e.g., ["wave_0.yaml", "wave_1.yaml"]).
+ */
+declare function detectSpecPhases(planDir: string): string[];
+/**
+ * Read the goal field from spec/main.yaml. Returns "" on failure.
+ */
+declare function readSpecGoal(planDir: string): string;
+/**
+ * Read the constraints field from spec/main.yaml. Returns "" on failure.
+ */
+declare function readSpecConstraints(planDir: string): string;
+/**
+ * Filter a list of phase filenames to only those not yet completed.
+ * Uses yaml.parse() on spec/main.yaml to read the `completed` field
+ * on each phase entry — no hand-rolled regex.
+ *
+ * Returns `phaseFiles` unchanged on any error (fail-open so the caller
+ * can still attempt all phases rather than silently skipping them).
+ */
+declare function filterUncheckedSpecPhases(phaseFiles: string[], planDir: string): string[];
+
+/**
+ * Mark a phase as completed in spec/main.yaml.
+ *
+ * @param planDir - The plan directory (parent of spec/)
+ * @param phaseFile - The phase filename to mark completed (e.g., "wave_0.yaml")
+ */
+declare function markPhaseCompleted(planDir: string, phaseFile: string): void;
+
+/**
+ * Autopilot run checkpoint persistence.
+ *
+ * After each phase completes, the multi-phase loop writes a checkpoint
+ * to `<cwd>/.agent/autopilot-checkpoint.json`. On startup with
+ * `--resume` (or whenever the checkpoint matches the current `--plan`),
+ * the loop skips already-completed phases and continues from the next
+ * unchecked one.
+ *
+ * On successful run completion (all phases done), the checkpoint is
+ * deleted.
+ *
+ * Design notes:
+ *   - Atomic write via tmp-file + rename (mirrors cost-tracker's rollup
+ *     pattern at src/plugins/cost-tracker.ts lines 280-305).
+ *   - Read failures (corrupt JSON, missing file, perm denial) return
+ *     `null`. This module never throws — failure modes are silent.
+ *   - The checkpoint is purely advisory: callers must validate the
+ *     `planPath` matches the current run's plan before trusting any
+ *     `completedPhases` list.
+ */
+interface Checkpoint {
+    /**
+     * Absolute path to the plan (file or directory) that this checkpoint
+     * was created for. Resume only valid when the current --plan matches.
+     */
+    planPath: string;
+    /** Phase filenames that have completed (e.g. ["wave_1.md"]). */
+    completedPhases: string[];
+    /** Cumulative cost across completed phases, in USD. */
+    totalCostUsd: number;
+    /** Cumulative iteration count across completed phases. */
+    totalIterations: number;
+    /** ISO 8601 timestamp of the last write. */
+    timestamp: string;
+}
+/**
+ * Injectable filesystem deps for testing. Production code should call
+ * the exported functions without `_deps`; tests inject mocks.
+ *
+ * @internal
+ */
+interface CheckpointDeps {
+    readFileSync?: (p: string) => string;
+    writeFileSync?: (p: string, content: string) => void;
+    unlinkSync?: (p: string) => void;
+    renameSync?: (from: string, to: string) => void;
+    existsSync?: (p: string) => boolean;
+    mkdirSync?: (p: string, opts: {
+        recursive: boolean;
+    }) => void;
+}
+/**
+ * Atomically write the checkpoint file. Never throws — write errors
+ * are swallowed (best-effort persistence; the run continues even if
+ * the checkpoint can't be persisted).
+ */
+declare function writeCheckpoint(cwd: string, state: Checkpoint, deps?: CheckpointDeps): void;
+/**
+ * Read and parse the checkpoint file. Returns `null` if the file is
+ * missing, unreadable, or contains corrupt JSON / wrong shape.
+ */
+declare function readCheckpoint(cwd: string, deps?: CheckpointDeps): Checkpoint | null;
+/**
+ * Delete the checkpoint file. Silent on missing / permission errors.
+ */
+declare function deleteCheckpoint(cwd: string, deps?: CheckpointDeps): void;
+
+/**
+ * Default budgets and constants for the Ralph loop autopilot engine.
+ */
+/** Maximum number of loop iterations before giving up. */
+declare const MAX_ITERATIONS = 50;
+/**
+ * Number of consecutive zero-progress iterations before the loop
+ * declares the agent is struggling and exits.
+ */
+declare const STRUGGLE_THRESHOLD = 3;
+/** Total wall-clock timeout for one `glrs oc autopilot` invocation (4 hours). */
+declare const TIMEOUT_MS: number;
+/**
+ * Per-iteration stall timeout, keyed by model tier. If a single
+ * iteration produces no idle signal within the tier's window,
+ * something is broken.
+ *
+ * Deep models (Opus, Sonnet thinking) get the longest window — they're
+ * permitted to chew on a hard problem for a while. Mid-tier executors
+ * are faster and a long stall there is much more likely to be a stuck
+ * call than a productive think. Fast models are the most responsive
+ * and warrant the shortest window.
+ *
+ * The CLI accepts `--stall-timeout <ms>` to override the tier-default.
+ */
+declare const STALL_MS_BY_TIER: {
+    readonly deep: number;
+    readonly mid: number;
+    readonly "mid-execute": number;
+    readonly "autopilot-execute": number;
+    readonly fast: number;
+};
+/** Backwards-compatible default (used when no tier is resolved). */
+declare const STALL_MS: number;
+/** Phase-level iteration budgets, keyed by model tier (item 2.7). */
+declare const MAX_ITERATIONS_PER_PHASE_BY_TIER: {
+    readonly deep: 5;
+    readonly mid: 8;
+    readonly "mid-execute": 10;
+    readonly "autopilot-execute": 10;
+    readonly fast: 10;
+};
+/**
+ * Status-heartbeat interval. Every N milliseconds the loop emits an
+ * info-level "working" log line summarizing elapsed time, iteration
+ * count, and cumulative cost. Default: 5 minutes.
+ * Override via GLRS_AUTOPILOT_STATUS_INTERVAL_MS (parsed as integer,
+ * clamped to [1000, 1h]).
+ */
+declare const STATUS_INTERVAL_MS: number;
+
+/**
+ * Status-heartbeat helper for the autopilot loop.
+ *
+ * Fires a periodic "still working" summary log at info level every N
+ * milliseconds (see STATUS_INTERVAL_MS in config.ts). The summary
+ * reports:
+ *
+ *   - elapsed wall time since loop start
+ *   - iteration count (completed iterations, not current)
+ *   - cumulative session cost in USD (sampled via session.get().data.cost)
+ *   - a 1-line "working successfully" signal (or a warning if the last
+ *     iteration hit an error)
+ *
+ * Decoupled from the Ralph loop's iteration accounting — the heartbeat
+ * reads a shared state snapshot that the loop updates between iterations.
+ * Fires on a setInterval timer, not per-iteration, so the user sees
+ * activity even during long single-iteration sessions (PRIME streaming
+ * text / running a slow test suite / waiting on an LLM response).
+ */
+
+interface StatusState {
+    /** Wall-clock timestamp when the loop started. */
+    startedAt: number;
+    /** Completed iteration count (not the current in-flight iteration). */
+    iterationsCompleted: number;
+    /** Latest cumulative session cost in USD, sampled at iteration boundaries. */
+    cumulativeCostUsd: number;
+    /** Whether the most recent iteration made filesystem progress. */
+    lastIterationProgress: boolean;
+    /** Whether the most recent iteration errored. */
+    lastIterationErrored: boolean;
+    /**
+     * When true, `cumulativeCostUsd` is an estimate from token counts
+     * (not API-reported). Displayed as "~$X.XXX est".
+     */
+    costIsEstimated?: boolean;
+    /** Total number of phases in the plan (multi-file plans only). */
+    phaseCount?: number;
+    /** Number of phases completed so far. */
+    phasesCompleted?: number;
+    /** Total checkbox items in main.md (multi-file plans only). */
+    mainCheckboxesTotal?: number;
+    /** Checked checkbox items in main.md. */
+    mainCheckboxesCompleted?: number;
+    /**
+     * Active parallel lanes (item 3.4). Only set when the orchestrator is
+     * running > 1 lane; the sequential path leaves this undefined and
+     * `composeStatusMessage` falls back to the single-stream output.
+     */
+    lanes?: Record<string, LaneState>;
+}
+interface LaneState {
+    /** Phase filename currently running on this lane. */
+    phaseFile: string;
+    /** Iteration number within the lane's current phase (1-based). */
+    iteration: number;
+    /** Most-recent tool name observed on the lane (optional). */
+    lastTool?: string;
+}
+interface StatusHeartbeat {
+    /** Start the heartbeat timer. Idempotent — safe to call multiple times. */
+    start(): void;
+    /** Stop the timer. Safe to call if not started. */
+    stop(): void;
+    /** Update the shared state. Call between iterations. */
+    update(patch: Partial<StatusState>): void;
+    /** Read the current state snapshot (for testing). */
+    getState(): StatusState;
+}
+interface StatusHeartbeatOptions {
+    logger: Logger;
+    intervalMs: number;
+    /** Optional async function to poll current session cost. Called on
+     *  each heartbeat tick. If provided, the returned cost replaces
+     *  the heartbeat's cumulativeCostUsd on each tick. */
+    pollCost?: () => Promise<number>;
+    /**
+     * Optional path to write the status snapshot as JSON on each tick.
+     * Written atomically via tmp-file-then-rename. Non-fatal on error.
+     * Default: undefined (no file write).
+     */
+    statusFilePath?: string;
+    /** Test-only: inject clock and timer functions. */
+    _deps?: {
+        now?: () => number;
+        setInterval?: (handler: () => void, ms: number) => ReturnType<typeof setInterval>;
+        clearInterval?: (id: ReturnType<typeof setInterval>) => void;
+    };
+}
+/**
+ * Format elapsed milliseconds as "Xh Ym Zs" (Xh is omitted when 0).
+ * Public for testing.
+ */
+declare function formatElapsed(ms: number): string;
+/**
+ * Format cost as USD with 3 decimal places, or "$0.00" for zero.
+ * When `estimated` is true, prepends "~" and appends " est" to indicate
+ * the cost is an estimate (e.g., from token counts when API cost is unavailable).
+ * Public for testing.
+ */
+declare function formatCost(usd: number, estimated?: boolean): string;
+declare function createStatusHeartbeat(opts: StatusHeartbeatOptions): StatusHeartbeat;
+
+/**
+ * Sentinel detection for the Ralph loop autopilot engine.
+ *
+ * The agent emits `<autopilot-done>` as a standalone tag (not inside a
+ * code fence or inline backtick) to signal that all work is complete.
+ */
+/**
+ * Returns true if the text contains the `<autopilot-done>` sentinel tag
+ * outside of any code fence (``` ... ```) or inline backtick span.
+ *
+ * Detection rules:
+ *   - Case-sensitive: `<AUTOPILOT-DONE>` does NOT match.
+ *   - Tag inside a fenced code block (``` ... ```) does NOT match.
+ *   - Tag inside an inline backtick span (` ... `) does NOT match.
+ *   - Partial tags (`<autopilot-done` or `autopilot-done>`) do NOT match.
+ */
+declare function detectSentinel(text: string): boolean;
+
+/**
+ * Struggle detection for the Ralph loop autopilot engine.
+ *
+ * Tracks consecutive zero-progress iterations. "Progress" is defined as
+ * at least one filesystem write (non-empty `git diff --stat` output)
+ * during the iteration.
+ */
+/**
+ * Tracks consecutive zero-progress iterations and signals when the
+ * agent is struggling (no progress for `threshold` consecutive iterations).
+ */
+declare class StruggleDetector {
+    private _consecutiveStalls;
+    private readonly _threshold;
+    constructor(threshold: number);
+    /** Number of consecutive stall iterations recorded so far. */
+    get consecutiveStalls(): number;
+    /**
+     * Record the result of one iteration.
+     * @param madeProgress - true if the agent made filesystem changes this iteration.
+     */
+    record(madeProgress: boolean): void;
+    /**
+     * Returns true if the agent has stalled for `threshold` consecutive
+     * iterations without making progress.
+     */
+    isStruggling(): boolean;
+}
+/**
+ * Returns true if the kill-switch file exists at `.agent/autopilot-disable`
+ * relative to `cwd`. The loop should exit immediately when this returns true.
+ */
+declare function checkKillSwitch(cwd: string): boolean;
+
+/**
+ * Phase-level git safety: record-and-soft-reset helpers.
+ *
+ * Used by the multi-phase loop runner (loop-session.ts) to capture
+ * HEAD before each phase. If a phase fails (struggle / stall / error)
+ * and the user requested it (or running in --fast mode where there's
+ * no human to ask), `resetSoft` rolls the worktree back to that SHA,
+ * preserving any changes in the index so nothing is lost.
+ *
+ * Safety invariants (per AGENTS.md and Wave 2 plan):
+ *   - NEVER use `git reset --hard`. Soft reset only.
+ *   - Any git failure here is non-fatal — log and continue.
+ *   - Helpers use `execFile` from node:child_process via promisify.
+ */
+/**
+ * Injectable execFile for testing.
+ * @internal
+ */
+interface GitSafetyDeps {
+    /**
+     * Mock the git invocation. Receives the args array; returns
+     * { stdout, stderr } or throws to simulate a git failure.
+     */
+    execGit?: (args: string[], cwd: string) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+}
+/**
+ * Record the current HEAD SHA. Returns "HEAD" on any failure
+ * (matches the existing getHeadSha shape in loop.ts so callers can
+ * pass the result to git operations without crashing).
+ */
+declare function recordHead(cwd: string, deps?: GitSafetyDeps): Promise<string>;
+/**
+ * Soft-reset the worktree to the given SHA. Changes since `sha` move
+ * to the staging area; nothing is destroyed. Any failure is logged
+ * via the optional `onWarn` callback and swallowed.
+ *
+ * Returns true on success, false on failure.
+ */
+declare function resetSoft(cwd: string, sha: string, opts?: GitSafetyDeps & {
+    onWarn?: (msg: string) => void;
+}): Promise<boolean>;
+
+/**
+ * Conflict-graph builder for parallel phase scheduling.
+ *
+ * Two phases conflict if they share any file path in their `files:` lists
+ * (parsed via `plan-parser`'s `parseItems` from each phase's plan-state
+ * fence). Phases with no shared files are independent and can run in
+ * parallel lanes.
+ *
+ * Conservative fallback: when a phase yields zero parsed items (e.g., no
+ * fenced plan-state block, or the phase is written as plain markdown
+ * checkboxes with `mirror:` / `files:` as prose) it is treated as
+ * conflicting with EVERY other phase. The runtime then collapses to
+ * sequential execution for that phase — which preserves correctness at
+ * the cost of opportunistic parallelism. Explicit, machine-parseable
+ * `files:` entries inside a plan-state fence are required to unlock
+ * parallel scheduling.
+ *
+ * Pure module — no I/O, no logging. Inputs are already-parsed PlanItems.
+ */
+
+interface PhaseInput {
+    /** Phase filename (e.g., "wave_1.md"). */
+    file: string;
+    /** Items parsed from this phase's plan-state fence. */
+    items: PlanItem[];
+}
+interface ConflictGraph {
+    /** Phase filenames in input order. */
+    phases: string[];
+    /** Map: phase -> set of phases it conflicts with. */
+    conflicts: Map<string, Set<string>>;
+}
+/**
+ * Build a conflict graph from a list of phases.
+ *
+ * Two phases A and B conflict iff:
+ *   - either phase has unknown file footprint (null from collectPhaseFiles), OR
+ *   - their file sets share at least one path.
+ *
+ * Self-conflicts are not recorded (a phase doesn't conflict with itself).
+ */
+declare function buildConflictGraph(phases: PhaseInput[]): ConflictGraph;
+/**
+ * Convenience: returns true if the graph has any independent pair —
+ * i.e., at least one group from `findIndependentPhases` has size > 1.
+ * Used by the orchestrator to decide whether parallel scheduling can
+ * yield any speedup, vs. falling back to sequential to skip overhead.
+ */
+declare function hasParallelism(graph: ConflictGraph): boolean;
+
+/**
+ * Parallel-lane orchestrator (item 3.3).
+ *
+ * Replaces the sequential per-phase loop in `loop-session.ts` with an
+ * N-lane scheduler. Each lane runs one phase at a time. When a lane
+ * finishes, it picks up the next phase in the queue that does NOT
+ * conflict (per the conflict graph from item 3.1) with any currently-
+ * running phase. Phases that conflict with all currently-running phases
+ * wait in the queue.
+ *
+ * Pure scheduler — no I/O, no git, no worktree creation. The caller
+ * provides a `runPhase` callback that takes a phase filename plus a
+ * lane id and returns a `PhaseResult`. Worktree create/merge/cleanup
+ * (item 3.2) lives at the call site, not here.
+ *
+ * Sequential fallback (item 3.7): when `laneCount === 1`, the
+ * orchestrator processes phases strictly in the input order, one at a
+ * time — semantically identical to the original `for (const phase of
+ * uncheckedPhases)` loop.
+ *
+ * Cancellation: an injected `AbortSignal` aborts pending phases (no
+ * new phases are dispatched) but does not interrupt phases already in
+ * flight — that's the runPhase callback's responsibility.
+ */
+
+interface PhaseResult {
+    /** Phase filename (e.g., "wave_1.md"). */
+    phaseFile: string;
+    /** Lane id this phase ran on. */
+    laneId: string;
+    /** Whether the phase completed successfully (all items checked). */
+    ok: boolean;
+    /**
+     * Iterations consumed by this phase. Aggregated by the caller into
+     * a session total.
+     */
+    iterations: number;
+    /** Cost in USD attributed to this phase. */
+    costUsd: number;
+    /** Optional structured payload returned by `runPhase`. */
+    payload?: unknown;
+    /**
+     * When `ok === false`, this signals that the orchestrator should
+     * stop scheduling new phases (the caller's contract is "first failure
+     * stops the run", matching the sequential loop's behavior).
+     */
+    fatal?: boolean;
+}
+interface RunLanesOptions {
+    /** Phases to run, in queue order. */
+    phases: string[];
+    /** Conflict graph from item 3.1. */
+    conflictGraph: ConflictGraph;
+    /**
+     * Number of parallel lanes. `1` falls back to sequential semantics
+     * (no overlap, phases dispatched in `phases` order).
+     */
+    laneCount: number;
+    /**
+     * Run a single phase. Receives the phase filename plus the lane id
+     * the caller should use for logging / worktree naming. Must return a
+     * `PhaseResult`. Errors thrown here propagate up to `runLanes`'s
+     * caller — the orchestrator does not catch them.
+     */
+    runPhase: (phaseFile: string, laneId: string) => Promise<PhaseResult>;
+    /**
+     * Optional cancellation. When aborted, no new phases are dispatched.
+     * In-flight phases continue until their own runPhase returns.
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * Optional structured logger for scheduling decisions. Tests pass a
+     * recording function; production passes a pino childLogger.
+     */
+    logger?: {
+        info?: (objOrMsg: unknown, msg?: string) => void;
+        debug?: (objOrMsg: unknown, msg?: string) => void;
+    };
+}
+interface RunLanesResult {
+    /** Per-phase results, in completion order. */
+    results: PhaseResult[];
+    /** Phases that were skipped because the run aborted. */
+    skipped: string[];
+}
+/**
+ * Run phases through N lanes with conflict-aware scheduling.
+ *
+ * Algorithm:
+ *   - Maintain a queue of pending phases (input order).
+ *   - Maintain a set of currently-running phases.
+ *   - Each scheduling step: fill idle lanes by picking the first queue
+ *     entry that doesn't conflict with anything running.
+ *   - Wait for any lane to finish (Promise.race), record its result,
+ *     re-evaluate the queue, repeat.
+ *   - Stop scheduling new phases when (a) the abort signal fires, OR
+ *     (b) any phase returns `fatal: true`.
+ *
+ * Sequential fallback (`laneCount === 1`): the queue is drained in
+ * order, one phase at a time — `Promise.race` over a single promise
+ * is just `await` semantics.
+ */
+declare function runLanes(opts: RunLanesOptions): Promise<RunLanesResult>;
+
+/**
+ * Scope-validator module for the autopilot (item 4.2).
+ *
+ * After each iteration, the orchestrator compares the files the agent
+ * actually touched (`git diff --name-only <baseRef>`) against the
+ * union of files declared in the current phase's plan-state items
+ * (`PlanItem.files[]`). Mismatches are logged as warnings:
+ *
+ *   - extra: agent edited a file NOT in the plan → "Scope drift"
+ *   - missing: plan expects a file but the agent didn't touch it → "Incomplete"
+ *
+ * Validation is informational — it never blocks the loop. Both arrays
+ * may be empty on a clean iteration.
+ */
+
+declare const execFileDefault$2: typeof execFile.__promisify__;
+interface ScopeValidation {
+    /** Files the agent edited that are NOT in the expected list (scope drift). */
+    extra: string[];
+    /** Files the expected list contains but the agent did NOT edit (incomplete). */
+    missing: string[];
+}
+/**
+ * Compare two file lists and return the symmetric differences.
+ *
+ * Both inputs are normalized — duplicates removed, sorted alphabetically.
+ * Path comparison is exact (no canonicalization); callers should pass
+ * paths in the same form (e.g. all relative-to-cwd).
+ */
+declare function validateScope(expected: string[], actual: string[]): ScopeValidation;
+interface GetChangedFilesOptions {
+    /**
+     * Test-only: inject execFile replacement.
+     * @internal
+     */
+    _deps?: {
+        execFile?: typeof execFileDefault$2;
+    };
+}
+/**
+ * Return the list of files changed in `cwd` since `baseRef` (a git SHA
+ * or ref). Uses `git diff --name-only` so committed AND uncommitted
+ * working-tree changes both count.
+ *
+ * Never throws — degrades to `[]` on git failure so callers can treat
+ * "git unavailable" the same as "no files changed".
+ */
+declare function getChangedFiles(cwd: string, baseRef: string, opts?: GetChangedFilesOptions): Promise<string[]>;
+
+/**
+ * Plan-validator module for the autopilot (item 4.5).
+ *
+ * Validates the structural integrity of a plan before execution starts:
+ *   - main.md exists for directory plans
+ *   - every phase file referenced in main.md exists on disk
+ *   - every phase file has at least one item with `intent:`
+ *   - soft warnings for items missing `files:`, `tests:`, or `verify:`
+ *
+ * Errors block execution (the orchestrator returns early). Warnings are
+ * informational — the run continues so the agent can still patch the
+ * plan in-flight.
+ *
+ * Pure function: only reads `fs` synchronously. Never throws — degrades
+ * to `{ errors: [], warnings: [...] }` on parse failure so callers can
+ * always render the report.
+ */
+interface ValidationError {
+    /** Stable machine-readable code (e.g., "missing-main", "missing-phase-file"). */
+    code: string;
+    /** Human-readable description of what's wrong. */
+    message: string;
+    /** Plan file path (relative to plan dir or absolute) when applicable. */
+    file?: string;
+    /** Plan-state item id (e.g., "4.1") when applicable. */
+    itemId?: string;
+}
+interface ValidationWarning {
+    code: string;
+    message: string;
+    file?: string;
+    itemId?: string;
+}
+interface ValidationReport {
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+/**
+ * Validate the plan at `planPath`. Returns a `ValidationReport`.
+ *
+ * For directory plans (path is a directory), checks main.md + each
+ * referenced phase file. For single-file plans, only the soft per-item
+ * checks apply.
+ *
+ * Never throws — any I/O failure becomes a warning rather than a thrown
+ * exception so callers can degrade gracefully.
+ */
+declare function validatePlan(planPath: string): ValidationReport;
+
+/**
+ * Git worktree helpers for parallel-lane execution (item 3.2).
+ *
+ * Each parallel lane runs against its own worktree branched from the
+ * current HEAD. On phase completion, the worktree's branch is merged
+ * back into the main repo with `--no-ff` to preserve per-phase commits.
+ *
+ * All git invocations follow the same `execFile + try/catch` shape used
+ * by `loop.ts` (lines 126-146 — see file-level comment in that module).
+ *
+ * Cleanup is best-effort: failures log warnings via the injected logger
+ * but never throw. Orphaned worktrees on disk surface in the debrief
+ * (item 3.6 wiring) so the user can manually `git worktree remove --force`.
+ *
+ * Pure runtime — no test pollution. Tests inject `_deps.execFile` to mock
+ * git invocations.
+ */
+
+declare const execFileDefault$1: typeof execFile.__promisify__;
+/**
+ * Minimal logger surface — accepts any subset of pino-like methods so
+ * tests can pass a no-op or a recording array. The real call sites pass
+ * pino childLoggers.
+ */
+interface WorktreeLogger {
+    warn?: (objOrMsg: unknown, msg?: string) => void;
+    info?: (objOrMsg: unknown, msg?: string) => void;
+    debug?: (objOrMsg: unknown, msg?: string) => void;
+}
+interface WorktreeHandle {
+    /** Filesystem path of the new worktree. */
+    path: string;
+    /** Branch name created for this worktree. */
+    branch: string;
+    /**
+     * Best-effort cleanup: `git worktree remove` then `git branch -D`.
+     * Failures are logged via the logger passed to createWorktree and never
+     * thrown. Safe to call multiple times (subsequent calls no-op).
+     */
+    cleanup: () => Promise<void>;
+}
+interface CreateWorktreeOptions {
+    /** Slug for the lane — used in branch and path naming. */
+    laneSlug: string;
+    /** Optional logger for cleanup-warning emission. */
+    logger?: WorktreeLogger;
+    /** Test-only: inject execFile replacement. */
+    _deps?: {
+        execFile?: typeof execFileDefault$1;
+    };
+}
+interface MergeWorktreeOptions {
+    /** Branch name to merge back into the current HEAD of repoRoot. */
+    branch: string;
+    /** Test-only: inject execFile replacement. */
+    _deps?: {
+        execFile?: typeof execFileDefault$1;
+    };
+}
+interface MergeResult {
+    ok: boolean;
+    /** Files reported as conflicting by `git merge`, when ok=false. */
+    conflicts?: string[];
+}
+/**
+ * Create a new git worktree branched from the current HEAD of `repoRoot`.
+ *
+ * Path: `<repoRoot>/.agent/worktrees/<laneSlug>-<epoch>`
+ * Branch: `autopilot/<laneSlug>`
+ *
+ * The `.agent/worktrees/` parent matches the existing `.agent/` convention
+ * for kill-switch and status state — keeps lane artefacts grouped with
+ * other autopilot runtime files.
+ *
+ * Throws on failure (the caller decides whether to fall back to sequential).
+ * Cleanup-via-handle is best-effort and logs only.
+ */
+declare function createWorktree(repoRoot: string, opts: CreateWorktreeOptions): Promise<WorktreeHandle>;
+/**
+ * Merge a worktree's branch back into the current HEAD of repoRoot.
+ * Uses `git merge --no-ff` so each phase keeps an explicit merge commit
+ * in history, making it trivial to bisect across parallel lanes.
+ *
+ * Returns `{ ok: true }` on success. On merge conflict, returns
+ * `{ ok: false, conflicts: [...] }` and aborts the merge so the
+ * working tree is restored — the caller falls back to sequential
+ * execution for that phase per item 3.2's conventions.
+ */
+declare function mergeWorktree(repoRoot: string, opts: MergeWorktreeOptions): Promise<MergeResult>;
+
+/**
+ * Auto-ship module for the autopilot (item 4.7).
+ *
+ * After all phases pass and a changeset has been generated, --ship
+ * pushes the current branch upstream and opens a PR via `gh pr create`.
+ *
+ * Hard rules (mirrored from AGENTS.md and the SPEAR Resolve stage):
+ *   - Never `git push --force` or `git push -f`
+ *   - Never push to `main` or `master`
+ *   - Never `--no-verify`
+ *   - Never merge a PR — only open one
+ *
+ * The PR title is the plan's H1 (verbatim). The PR body is the literal
+ * contents of main.md (or the single-file plan), passed to gh via
+ * `--body-file` to dodge shell-escaping bugs.
+ *
+ * Failure modes (all surface as thrown errors so the caller can log
+ * and degrade gracefully):
+ *   - Branch is `main`/`master`/detached HEAD → ABORT
+ *   - `git push` returns non-zero → ABORT
+ *   - `gh` is not installed or not authenticated → ABORT
+ *   - PR already exists for the branch → ABORT (call /ship to update)
+ */
+
+declare const execFileDefault: typeof execFile.__promisify__;
+interface AutoShipOptions {
+    /** Plan path (file or directory). The PR title comes from the plan's H1. */
+    planPath: string;
+    /** Repo root (used as cwd for git/gh invocations). */
+    repoRoot: string;
+    /**
+     * Test-only: inject execFile replacement.
+     * @internal
+     */
+    _deps?: {
+        execFile?: typeof execFileDefault;
+    };
+}
+interface AutoShipResult {
+    prUrl: string;
+    branch: string;
+    /** Title used for the PR. */
+    title: string;
+}
+/**
+ * Push the current branch and open a PR. Returns the PR URL on success;
+ * throws on any of the abort conditions documented at the module top.
+ */
+declare function autoShip(opts: AutoShipOptions): Promise<AutoShipResult>;
+
+/**
+ * Session state derivation from event streams.
+ *
+ * `deriveState` is a pure function: given a sequence of SessionEvents,
+ * it returns a `SessionHandle` describing the current state of the session.
+ * It handles partial streams (process died mid-session) and all event types.
+ */
+
+type SessionStatus = "running" | "enriching" | "verifying" | "complete" | "error" | "stale";
+interface SessionHandle {
+    /** Derived from planPath + startedAt — stable across polls. */
+    id: string;
+    planPath: string;
+    cwd: string;
+    /** fast-model flag from session:start */
+    fast: boolean;
+    /** resume flag from session:start */
+    resume: boolean;
+    status: SessionStatus;
+    currentPhase?: {
+        phase: string;
+        current: number;
+        total: number;
+    };
+    currentIteration?: {
+        iteration: number;
+        max: number;
+    };
+    totalIterations: number;
+    cost: number;
+    startedAt: string;
+    lastEventAt: string;
+    error?: string;
+    exitReason?: string;
+    enrichProgress?: {
+        done: number;
+        total: number;
+    };
+    verifyProgress?: {
+        passed: number;
+        total: number;
+    };
+}
+/**
+ * Pure reduce over a sequence of SessionEvents.
+ *
+ * Returns `null` if no `session:start` event is found (empty or pre-start stream).
+ * Handles partial streams: a stream without `session:done` is treated as "running"
+ * (or "enriching"/"verifying" depending on the last active event).
+ */
+declare function deriveState(events: SessionEvent[]): SessionHandle | null;
+
+/**
+ * Changeset generator for the autopilot (item 4.6).
+ *
+ * After all phases complete successfully, the autopilot generates a
+ * changeset file in the repo's `.changeset/` directory. The file follows
+ * Changesets v2 format:
+ *
+ *     ---
+ *     "@glrs-dev/harness-plugin-opencode": <bump-level>
+ *     ---
+ *
+ *     <description>
+ *
+ * Bump-level inference (per the wave_4 spec):
+ *   - "fix"/"bug" in title → patch
+ *   - "remove"/"break"/"v2" in title → major
+ *   - otherwise → minor (default)
+ *
+ * The package name is hard-coded to `@glrs-dev/harness-plugin-opencode`
+ * — the autopilot only ships changesets for that package today.
+ *
+ * Filename format: `<slug>-<random6>.md` to avoid collisions when the
+ * same plan re-runs.
+ */
+type BumpLevel = "patch" | "minor" | "major";
+interface GenerateChangesetResult {
+    /** Absolute path of the generated changeset file. */
+    path: string;
+    /** The contents written to the file. */
+    content: string;
+    /** Bump level chosen. */
+    bumpLevel: BumpLevel;
+}
+interface GenerateChangesetOptions {
+    /** Override the package name (default: "@glrs-dev/harness-plugin-opencode"). */
+    packageName?: string;
+    /**
+     * Test-only: deterministic random suffix for filename collision avoidance.
+     * @internal
+     */
+    _randomSuffix?: () => string;
+}
+/**
+ * Generate a Changesets v2 changeset file for a completed plan.
+ *
+ * Writes to `<repoRoot>/.changeset/<slug>-<random6>.md`. Creates the
+ * `.changeset/` directory if missing (Changesets ships with one but
+ * this is defensive in case a worktree drops it).
+ */
+declare function generateChangeset(planPath: string, repoRoot: string, opts?: GenerateChangesetOptions): Promise<GenerateChangesetResult>;
+
+/**
+ * Plan session runner for the interactive autopilot orchestrator.
+ *
+ * Runs a headless opencode session with the @plan agent, sends the
+ * scope path as the prompt, and detects the plan output path from
+ * the filesystem (multi-file directory or single-file .md).
+ */
+
+/**
+ * Injectable server dependencies for testing.
+ * @internal
+ */
+interface PlanSessionDeps {
+    /** Override filesystem existence checks for testing. */
+    existsSync?: (p: string) => boolean;
+}
+/**
+ * Run a headless @plan session.
+ *
+ * Starts an opencode server, creates a session with the @plan agent,
+ * sends a prompt instructing it to read the scope and produce a plan,
+ * then detects the plan output path from the filesystem.
+ *
+ * @plan is headless — autoRejectPermissions is true so it can't
+ * deadlock waiting on a human response.
+ */
+declare function runPlanSession(opts: PlanSessionOptions & {
+    timeoutMs?: number;
+    _deps?: PlanSessionDeps;
+    adapter: AgentAdapter;
+}): Promise<PlanSessionResult>;
+
+/**
+ * Shared type definitions for the scoper session.
+ * Defined here (in autopilot) so both the autopilot orchestrator
+ * (interactive.ts) and the CLI scoper command can import them without
+ * creating circular dependencies.
+ */
+interface ScoperSessionOptions {
+    /** Directory where scope.md will be written. */
+    planDir: string;
+    /** Slug for the plan (used to name the subdirectory). */
+    slug: string;
+    /** The user's initial goal text (embedded in the first prompt). */
+    initialGoal: string;
+    /** Timeout in milliseconds per turn (default: 5 minutes). */
+    timeoutMs?: number;
+    /**
+     * When provided, the scoper's initial prompt includes this plan content
+     * so the scoper can ground its questions in the existing plan.
+     */
+    existingPlanContent?: string;
+    /**
+     * Injectable dependencies for testing.
+     * @internal — concrete types are defined in the CLI's scoper.ts
+     */
+    _deps?: Record<string, unknown>;
+}
+interface ScoperSessionResult {
+    scopePath: string;
+}
+
+export { type SessionResult$1 as AdapterSessionResult, type AgentAdapter, type AgentHandle, type AutopilotLogger, type Checkpoint, type CostUpdateEvent, type CredentialExpiredEvent, type EnrichDoneEvent, type EnrichFileDoneEvent, type EnrichFileErrorEvent, type EnrichFileSkipEvent, type EnrichFileStartEvent, type EnrichStartEvent, type ErrorEvent, EventStreamReader, EventStreamWriter, type IterationDoneEvent, type IterationStartEvent, type LoopExitReason, type LoopResult, type LoopSessionDeps, type LoopSessionOptions, MAX_ITERATIONS, MAX_ITERATIONS_PER_PHASE_BY_TIER, type PhaseDoneEvent, type PhaseResult, type PhaseStartEvent, type PlanItem, type PlanSessionOptions, type PlanSessionResult, type PlanState, type RalphLoopOptions, STALL_MS, STALL_MS_BY_TIER, STATUS_INTERVAL_MS, STRUGGLE_THRESHOLD, type ScoperSessionOptions, type ScoperSessionResult, type SessionDoneEvent, type SessionEvent, SessionEventEmitter, type SessionHandle, type SessionResult, SessionRunner, type SessionRunnerDeps, type SessionRunnerOptions, type SessionStartEvent, type SessionStatus, StruggleDetector, TIMEOUT_MS, type ThinkingEvent, type ToolCallEvent, type VerifyDoneEvent, type VerifyResult, type VerifyResultEvent, type VerifyStartEvent, type WorktreeHandle, autoShip, buildConflictGraph, checkKillSwitch, childLogger, createAutopilotLogger, createStatusHeartbeat, createWorktree, deleteCheckpoint, deriveState, detectSentinel, detectSpecPhases, enrichPlanForFastModel, filterUncheckedSpecPhases, formatCost, formatElapsed, generateChangeset, getChangedFiles, hasParallelism, hasSpec, markPhaseCompleted, mergeWorktree, parseItems, parsePlanState, parseSpecItems, readCheckpoint, readSpecConstraints, readSpecGoal, recordHead, resetSoft, runLanes, runLoopSession, runPlanSession, runRalphLoop, runVerifyCommands, validateMainSpec, validatePhaseSpec, validatePlan, validateScope, writeCheckpoint };