/**
 * Tandem Backseat Agent Lifecycle for Story 95-2
 *
 * Manages spawn/kill lifecycle for backseat observer agents in phased workflows.
 * When a workflow phase has a `tandem:` config block, BikeLane spawns a background
 * subagent that observes the primary agent's work.
 */
import type { WorkflowPhase } from './workflow-schema.js';
/**
 * Handle to a running backseat agent
 */
export interface BackseatHandle {
    /** Background task ID from Task tool */
    taskId: string;
    /** Partner agent name (from tandem config) */
    partner: string;
    /** Model used (should always be 'haiku') */
    model: string;
    /** Whether task runs in background */
    runInBackground: boolean;
    /** Normalized observation scopes */
    scope: string[];
    /** Path to observation file: .session/{storyId}-tandem-{partner}.md */
    observationFilePath: string;
    /** Whether cleanup handler was registered at spawn time */
    cleanupRegistered: boolean;
}
/**
 * Parameters for spawning a backseat agent
 */
export interface SpawnBackseatParams {
    /** Phase config (must have tandem block to spawn) */
    phase: WorkflowPhase;
    /** Current story ID */
    storyId: string;
    /** Path to .session directory */
    sessionDir: string;
    /** Process adapter for real spawn/terminate. Omit for in-memory only (tests). */
    adapter?: ProcessAdapter;
}
/**
 * Cleanup handler for tandem backseat processes
 */
export interface TandemCleanupHandler {
    /** Story ID this handler belongs to */
    storyId: string;
    /** Cleanup function to execute */
    cleanup: () => Promise<void>;
}
/**
 * Standard result object per framework pattern
 */
export interface TandemResult<T = unknown> {
    success: boolean;
    data?: T;
    error?: string;
}
/**
 * Adapter for real process spawn/terminate operations.
 *
 * The library module cannot call Claude Code's Task tool directly —
 * callers (workflow-executor) inject the real implementation.
 * Tests use the default no-op adapter.
 */
export interface ProcessAdapter {
    /** Spawn a background process. Returns the real task ID. */
    spawn(params: {
        partner: string;
        model: string;
        storyId: string;
        scope: string[];
        observationFilePath: string;
    }): Promise<{
        taskId: string;
    }>;
    /** Terminate a background process by task ID. */
    terminate(taskId: string): Promise<void>;
}
/**
 * Reset all in-memory state. For testing only.
 */
export declare function _resetForTesting(): void;
/**
 * Spawn a backseat agent for a tandem-configured phase.
 *
 * If phase has no tandem config, returns success with no handle (no-op).
 * If phase has tandem config, spawns background subagent and returns handle.
 */
export declare function spawnBackseat(params: SpawnBackseatParams): Promise<TandemResult<BackseatHandle>>;
/**
 * Terminate a running backseat agent.
 *
 * Handles already-stopped tasks gracefully (no throw).
 */
export declare function terminateBackseat(handle: BackseatHandle, adapter?: ProcessAdapter): Promise<TandemResult<{
    status: string;
}>>;
/**
 * Get the active backseat handle for a story, if any.
 *
 * Returns null if no backseat is running for this story.
 */
export declare function getActiveBackseat(storyId: string): BackseatHandle | null;
/**
 * Register a cleanup handler for tandem backseat processes.
 *
 * Handlers are executed on crash recovery or explicit cleanup.
 */
export declare function registerCleanupHandler(handler: TandemCleanupHandler): void;
/**
 * Execute all cleanup handlers for a story.
 *
 * Must not throw even if individual handlers fail.
 * Clears handlers after execution (idempotent).
 */
export declare function executeCleanupHandlers(storyId: string): Promise<void>;
//# sourceMappingURL=tandem-lifecycle.d.ts.map