/**
 * agent-bridge headless responder autospawn (T-CHAT-AS-TERMINAL CAT.5.1).
 *
 * The chat-transport daemon (`src/channels/daemon/autospawn.ts`) already
 * autospawns from the MCP chat-bridge boot. The HEADLESS RESPONDER — the
 * agent-bridge daemon that ANSWERS chat when no terminal is live (CAT.5 the
 * project umbrella's headless responder, CAT.6 the project-less `general`
 * session) — did NOT. This module mirrors that chat-daemon autospawn so the
 * headless responder is ALWAYS-ON too: started opportunistically on MCP boot,
 * keyed PER-INSTANCE so `loop` + `general` run concurrently (CAT.5.1's
 * per-scope lock/pid in daemon.ts).
 *
 * SAFE to autospawn the project headless even while a terminal is live: CAT.5's
 * lease-ownership guard makes it STAND DOWN. The headless only answers when it
 * owns a fresh umbrella lease; while a human `chat watch` lease is present the
 * dispatcher's flush-time `isLeaseFreshAndOwnedBy` guard suppresses it — it
 * idles at zero token cost (fs-only heartbeat) until the human lease lapses.
 *
 * Behavior (mirrors `ensureChatDaemonRunning`):
 *   - No-op when no chat platform is configured.
 *   - No-op when the SCOPED daemon (its own pidfile) is already running.
 *   - Else acquire an atomic per-scope spawn-lock (`fs.open(lock, 'wx')`) so two
 *     MCP servers don't double-spawn; the loser waits briefly for the pidfile.
 *     Stale lock (> 15s) is reclaimed.
 *   - Always async + non-throwing. A resolution failure (no project uuid / no
 *     pack) → `{ status: 'no_config' }` (skip that scope, never throw).
 *
 * It spawns `dist/cli.js agent-bridge start [--general]` DETACHED:
 *   - general: `agent-bridge start --general` (env as-is — the worker resolves
 *     the built-in `general` pack itself).
 *   - project umbrella: `agent-bridge start` with `OPENSQUID_PROJECT_UUID` +
 *     `OPENSQUID_PACK_ROOT` injected into the child env (resolved exactly like
 *     cli.ts's non-general path: `resolveProjectUuid` + `resolvePackRootFromEnv`).
 *     If the project uuid can't be resolved → skip (no-op).
 *
 * Imports from: node:fs, node:os, node:path, node:child_process, node:url,
 *   ../../channels/config, ../../channels/routing, ../paths, ./daemon.
 * Imported by: src/mcp/chat-bridge-server.ts (boot) + tests.
 */
import { type AgentBridgeScopeKey } from './daemon.js';
export interface AgentBridgeAutoSpawnResult {
    status: 'spawned' | 'already_running' | 'waited_for_peer' | 'no_config' | 'error';
    pid?: number;
    error?: string;
}
/**
 * What to autospawn: either the project-less `general` session, or a project
 * umbrella's headless responder (keyed by umbrella id + cwd → project/pack).
 */
export type EnsureTarget = {
    kind: 'general';
} | {
    kind: 'umbrella';
    /** The umbrella the cwd resolves to (CAT.5 — the scope identity). */
    umbrellaId: string;
    /** Working dir to resolve the project uuid / pack root from. */
    cwd: string;
};
/**
 * Resolve the CLI binary (`dist/cli.js`). From the MCP server at
 * `dist/mcp/chat-bridge-server.js` the CLI sits at `dist/cli.js`; from this
 * module's built location (`dist/runtime/agent_bridge/autospawn.js`) it's three
 * dirs up. We resolve relative to the MCP-server layout to match the chat
 * daemon's `resolveCliEntrypoint`, honoring `OPENSQUID_CLI_ENTRYPOINT`.
 */
export declare function resolveCliEntrypoint(): string;
/** A pidfile-liveness probe result, scope-keyed. */
export interface ScopedStatus {
    running: boolean;
    pid?: number;
}
/** A detached spawn invocation: argv (after the cli entrypoint) + child env. */
export interface SpawnInvocation {
    args: string[];
    env: NodeJS.ProcessEnv;
}
/**
 * Injection seams for tests — exercise the autospawn FSM WITHOUT reading the
 * developer's real chat config or spawning a live daemon.
 */
export interface EnsureAgentBridgeDeps {
    /** Override the spawned worker's entrypoint (defaults to `dist/cli.js`). */
    entrypoint?: string;
    /** Override the "is any platform configured" probe. */
    isConfigured?: () => Promise<boolean>;
    /** Override the scoped-liveness probe. */
    statusFn?: (scope: AgentBridgeScopeKey) => Promise<ScopedStatus>;
    /** Override the detached spawn. */
    spawnFn?: (entrypoint: string, inv: SpawnInvocation) => {
        pid?: number;
    };
    /** Override the project-uuid resolver (tests). */
    resolveProjectUuidFn?: (opts: {
        cwd: string;
        env?: NodeJS.ProcessEnv;
    }) => Promise<string | null>;
    /** Override the pack-root resolver (tests). */
    resolvePackRootFn?: (env?: NodeJS.ProcessEnv) => string;
    /** Override base env threaded into the child (defaults to `process.env`). */
    env?: NodeJS.ProcessEnv;
}
/**
 * Best-effort: ensure the headless agent-bridge responder for `target` is
 * running. Returns on the no-op paths (no config, already running, peer
 * spawning, unresolvable scope). NEVER throws.
 */
export declare function ensureAgentBridgeRunning(target: EnsureTarget, opts?: EnsureAgentBridgeDeps): Promise<AgentBridgeAutoSpawnResult>;
/**
 * MCP-boot convenience (CAT.5.1): ensure (a) the GENERAL headless responder
 * (always) and (b) the headless responder for the umbrella the cwd resolves to
 * (if any). Each is fire-and-forget at the call site; this helper awaits both
 * and returns their results for logging. Never throws.
 *
 * `cwd` defaults to `CLAUDE_PROJECT_DIR ?? process.cwd()` (matches the MCP
 * server's active-umbrella resolution). `umbrellaForCwd` lets the caller pass
 * the already-resolved umbrella (the MCP boot resolves it once for logging).
 */
export declare function ensureHeadlessRespondersForBoot(opts: {
    /** The umbrella the cwd resolves to (null ⇒ only the general responder). */
    umbrellaForCwd: string | null;
    /** Working dir for the project/pack resolution. */
    cwd?: string;
    /** Test seam — forwarded to each `ensureAgentBridgeRunning`. */
    deps?: EnsureAgentBridgeDeps;
    /** Test seam — override the ensure fn itself (asserts call shape). */
    ensureFn?: typeof ensureAgentBridgeRunning;
}): Promise<{
    general: AgentBridgeAutoSpawnResult;
    umbrella: AgentBridgeAutoSpawnResult | null;
}>;
//# sourceMappingURL=autospawn.d.ts.map