@lmctl-ai/lmctl 0.1.342 → 0.2.2

package/dist/providers/transports/acp-profiles/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ACP provider profile registry.
+ *
+ * The generic ACP engine (transports/acp.ts) looks up the profile for a
+ * tool here; everything provider-specific lives in the profile modules.
+ */
+import type { AcpProviderProfile } from "./types.js";
+export declare function acpProfileForTool(tool: string): AcpProviderProfile | undefined;
+/**
+ * Read-only view of the per-profile `{ binary, baseArgs }` table for
+ * tests that pin the per-provider argv shape (e.g. flag-position
+ * regression checks). Production code reads the profiles directly; this
+ * alias exists only so the test suite can import a frozen view without
+ * making the table mutable from the outside.
+ */
+export declare const ACP_TOOLS_FOR_TEST: Readonly<Record<string, Readonly<{
+    binary: string;
+    args: readonly string[];
+}>>>;

package/dist/providers/transports/acp-profiles/kimi.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Kimi ACP profile.
+ *
+ * Kimi's ACP subcommand has no argv permission flag: the posture is
+ * protocol-level (`session/set_config_option` with configId "mode"),
+ * applied BEFORE any model config and BEFORE the first prompt, and it is
+ * FAIL-CLOSED — lmctl cannot answer `session/request_permission`, so a
+ * rejected mode change would leave the subprocess hung on its first tool
+ * call. Ordering and policy are the `sessionSetup` data below.
+ *
+ * Kimi 0.28.x exposes only an on/off thinking toggle, so a declared
+ * `effort=` cannot be honored here and is silently ignored.
+ */
+import type { AcpProviderProfile } from "./types.js";
+export declare function detectKimiRuntimeDead(resultText: string): string | null;
+/**
+ * Kimi logs a multi-line `Error handling notification … -32601 Method not
+ * found` block for the mandatory `notifications/initialized` notification
+ * on every spawn. It is routine, not a failure — strip exactly that block
+ * (and only that block) from the stderr tail attached to a no-result
+ * error report.
+ */
+export declare function filterKimiExpectedStderr(stderr: string): string;
+export declare const kimiProfile: AcpProviderProfile;

package/dist/providers/transports/acp-profiles/opencode.d.ts

@@ -0,0 +1,26 @@
+/**
+ * OpenCode ACP profile.
+ *
+ * OpenCode's ACP mode rejects every permission-bypass argv flag
+ * (`--dangerously-skip-permissions` is a `run`-subcommand-only flag,
+ * verified empirically). YOLO is satisfied via
+ * `<cwd>/.opencode/opencode.json` carrying `"permission": "allow"`,
+ * installed defensively before every chat spawn (preSpawn) so even
+ * pre-fix-seeded teams get the YOLO key without a re-create. The install
+ * no longer writes lmctl MCP entries.
+ *
+ * The profile also owns `probeOpenCodeAcpConfig` — a separate probe entry
+ * point (purpose "probe") used by lint/seed via teamfile-compat.ts. It
+ * intentionally differs from the chat spawn: no runtime permission-config
+ * install (initialize/session creation and config-option validation
+ * cannot request tools or incur an LLM call), and a rejected model/effort
+ * option is reported as probe evidence rather than absorbed as a warning.
+ */
+import type { AcpProviderProfile, OpenCodeAcpConfigProbeOptions, OpenCodeAcpConfigProbeResult } from "./types.js";
+export declare const openCodeProfile: AcpProviderProfile;
+/**
+ * Verify opencode's live per-session model/effort contract without prompting.
+ * No project permission config is installed: initialize/session creation and
+ * config-option validation cannot request tools or incur an LLM call.
+ */
+export declare function probeOpenCodeAcpConfig(opts: OpenCodeAcpConfigProbeOptions): Promise<OpenCodeAcpConfigProbeResult>;

package/dist/providers/transports/acp-profiles/types.d.ts

@@ -0,0 +1,258 @@
+/**
+ * `AcpProviderProfile` — the per-provider half of the ACP transport.
+ *
+ * transports/acp.ts is the generic protocol engine (RPC channel,
+ * lifecycle/abort/hold-open scaffolding, initialize → session/load|new →
+ * session/prompt skeleton, resume contract). Everything that used to be a
+ * per-provider `if (tool === …)` branch lives behind this interface in
+ * `acp-profiles/{kimi,opencode,copilot,gemini,hermes}.ts`.
+ *
+ * Conventions (binding, from the batch-redesign v2 review):
+ *  - Hooks receive ONE typed context object (no two-argument hooks):
+ *    permissionMode, model, effort, acpMode, purpose ('chat' | 'probe'),
+ *    and a warnings channel. Hook-specific inputs arrive on an extension
+ *    of that object (AcpSpawnContext, AcpSessionContext, …).
+ *  - Ordering/failure policy of post-open configuration is explicit
+ *    per-profile DATA: `sessionSetup` array order is the wire order and
+ *    each step declares `onFailure: "fail-closed" | "non-fatal"`. The
+ *    driver interprets the policy; profiles never branch on it inline.
+ *  - Result handling uses stateful hooks: gemini's replay isolation lives
+ *    in the output processor via `isolateResult`; kimi's runtime-dead
+ *    detection is the `onExitFinalization` telemetry hook. There are no
+ *    stateless classifyResult/filterStderr result transforms.
+ *  - `requireResume` is the generic driver's resume contract, NOT a
+ *    profile capability.
+ */
+import type { PermissionMode } from "../../yolo-contract.js";
+import type { AcpRpcChannel } from "../acp-rpc.js";
+/**
+ * ACP session mode ids this transport may set. Kept as a closed type so a
+ * typo cannot reach the wire as an unrecognized mode id.
+ */
+export type AcpMode = "default" | "accept_edits" | "dont_ask";
+/** Why an ACP process is being spawned. */
+export type AcpPurpose = "chat" | "probe";
+/**
+ * Typed context handed to every profile hook.
+ */
+export interface AcpProfileContext {
+    /** Resolved permission mode for this spawn ("yolo" is the default). */
+    readonly permissionMode: PermissionMode;
+    /** Per-session model override, when the caller declared one. */
+    readonly model?: string;
+    /** Per-session effort / variant override, when the caller declared one. */
+    readonly effort?: string;
+    /**
+     * Explicit ACP `session/set_mode` mode id, validated by the driver
+     * against the profile's `modeVocabulary` before spawn (fail-closed).
+     */
+    readonly acpMode?: AcpMode;
+    readonly purpose: AcpPurpose;
+    /**
+     * Warnings channel. Strings pushed here are human-readable records of
+     * provider config the turn proceeded past; for purpose "chat" they land
+     * on `AcpResult.warnings` (task #232), for purpose "probe" they are
+     * probe evidence.
+     */
+    readonly warnings: {
+        push(warning: string): void;
+    };
+}
+/** preSpawn hook context: the profile context plus the spawn target. */
+export interface AcpSpawnContext extends AcpProfileContext {
+    readonly cwd: string;
+    /** The already-built spawn environment; profiles may mutate it. */
+    readonly env: NodeJS.ProcessEnv;
+}
+/** afterSessionOpen step context: the profile context plus the open session. */
+export interface AcpSessionContext extends AcpProfileContext {
+    readonly sessionId: string;
+    /** Raw `session/new` / `session/load` response (model catalogs, currentModelId…). */
+    readonly response: Record<string, unknown>;
+    readonly sendRpc: AcpRpcChannel["sendRpc"];
+}
+/** onExitFinalization hook context: the finalized turn result. */
+export interface AcpFinalizeContext extends AcpProfileContext {
+    readonly sessionId: string;
+    readonly result: string;
+    readonly stopReason: string;
+    readonly exitCode: number | null;
+}
+/**
+ * Bundle-open identity verification context: everything a profile needs to
+ * prove the requested session was genuinely loaded.
+ */
+export interface AcpSessionIdentityContext extends AcpProfileContext {
+    readonly requestedSessionId: string;
+    /** Raw `session/load` response (its sessionId echo, if any, was already
+     * checked by the driver: a DIFFERENT echoed id always fails before this
+     * hook runs). */
+    readonly loadResponse: Record<string, unknown>;
+    readonly cwd: string;
+    /** The spawn env — provider-home overrides (KIMI_CODE_HOME etc.) reach
+     * the verifier through here. */
+    readonly env: NodeJS.ProcessEnv;
+}
+/**
+ * Per-profile session-identity strategy for BUNDLE open (`openAcpSession`
+ * strict mode). The driver never falls back to "assume the requested id":
+ * a profile must declare how a genuine load is proven.
+ *
+ *  - Providers whose session/load echoes the session id need nothing here:
+ *    the driver's exact-echo check is the whole strategy (default when this
+ *    field is absent — and the absence of an echo then fails closed).
+ *  - Providers whose load does NOT echo an id declare a hook:
+ *    kimi verifies via its on-disk session store; hermes relies on its
+ *    fail-closed load (a non-throwing load IS the proof — see the profile).
+ */
+export interface AcpSessionIdentity {
+    /** Verify at bundle open that the requested session was genuinely loaded.
+     * Throw on failure. Only called when the load response carried no
+     * contradicting echo. */
+    verifyLoadedSession(ctx: AcpSessionIdentityContext): Promise<void> | void;
+    /**
+     * Cheap between-messages re-check (catches an external re-seed/delete
+     * mid-bundle before the next prompt is sent). Optional — providers whose
+     * identity is pinned by the live process need nothing here (the per-turn
+     * expectedSession check upstream catches teamfile rotation).
+     */
+    recheckSession?(ctx: {
+        requestedSessionId: string;
+        cwd: string;
+        env: NodeJS.ProcessEnv;
+    }): Promise<void> | void;
+}
+/** Structured description of a session-step failure, built by the step. */
+export interface AcpStepFailure {
+    /** errorLog event name. The driver merges `{ event, provider, ...fields }`. */
+    readonly event: string;
+    readonly fields: Record<string, unknown>;
+    /** Human-readable stderr line (trailing newline included), when surfaced there. */
+    readonly stderrLine?: string;
+    /** Warnings-channel entry — the config the turn proceeded past. */
+    readonly warning?: string;
+    /** Thrown message; used only by fail-closed steps. */
+    readonly message: string;
+}
+/**
+ * One ordered post-open configuration step (after session/new|load, before
+ * the first prompt).
+ */
+export interface AcpSessionStep {
+    /** Stable id for logs and tests, e.g. "permission-mode" | "session-mode" | "model" | "effort". */
+    readonly id: string;
+    /**
+     * Failure policy — profile DATA, interpreted by the driver:
+     *  - "fail-closed": a rejected step aborts the turn before
+     *    session/prompt (a provider that refused the posture can hang on its
+     *    first tool call).
+     *  - "non-fatal": record the failure (errorLog + stderr + warnings
+     *    channel) and proceed with whatever config was already active.
+     */
+    readonly onFailure: "fail-closed" | "non-fatal";
+    applies(ctx: AcpSessionContext): boolean;
+    run(ctx: AcpSessionContext): Promise<void>;
+    describeFailure(ctx: AcpSessionContext, error: unknown): AcpStepFailure;
+    /** dlogv line on success (debug-gated). */
+    successLog?(ctx: AcpSessionContext): string;
+}
+/** Options for the opencode profile's probe entry point. */
+export interface OpenCodeAcpConfigProbeOptions {
+    cwd: string;
+    model: string;
+    effort?: string;
+    env?: NodeJS.ProcessEnv;
+    binaryPath?: string;
+    timeoutMs?: number;
+}
+export type OpenCodeAcpConfigProbeResult = {
+    status: "verified";
+} | {
+    status: "rejected";
+    option: "model" | "effort";
+    value: string;
+    error: string;
+} | {
+    status: "unavailable";
+    reason: "spawn" | "handshake" | "timeout";
+    error?: string;
+};
+export interface AcpProviderProfile {
+    /** Provider key: "kimi" | "opencode" | "copilot" | "gemini" | "hermes". */
+    readonly name: string;
+    /** Default binary; per-call overridable via `AcpOptions.binaryPath`. */
+    readonly binary: string;
+    /**
+     * Static base argv (the historical ACP_TOOLS entry). Per-call rewrites
+     * (permission mode, model) happen in `argv()` — never by mutating this.
+     */
+    readonly baseArgs: readonly string[];
+    /**
+     * Effective spawn argv for the resolved context. Absorbs the base args
+     * plus plan-mode rewrites (gemini's `-y` → `--approval-mode plan` swap)
+     * and spawn-time model flags (gemini `--model`). May warn (copilot
+     * plan/model gaps) or throw (hermes plan refusal).
+     */
+    argv(ctx: AcpProfileContext): string[];
+    /**
+     * Which mode the YOLO argv pre-flight asserts against the produced argv:
+     * the effective permission mode (default), or always "yolo" for
+     * providers that deliberately keep their yolo flag in plan mode
+     * (copilot).
+     */
+    readonly yoloAssertion?: "effective" | "always-yolo";
+    /**
+     * Pre-spawn filesystem/env preparation: opencode installs its runtime
+     * permission config, hermes sets HERMES_YOLO_MODE. Runs before the
+     * cwd-existence pre-check (historical ordering).
+     */
+    preSpawn?(ctx: AcpSpawnContext): void;
+    /**
+     * ACP `session/set_mode` vocabulary for providers whose permission
+     * posture is an ACP mode ladder (hermes). `known` is what the provider
+     * implements, `selectable` the subset lmctl is willing to drive a member
+     * into. Absent ⇒ the provider declares no vocabulary and any acpMode
+     * request is rejected fail-closed before spawn.
+     */
+    readonly modeVocabulary?: {
+        known: readonly AcpMode[];
+        selectable: readonly AcpMode[];
+    };
+    /**
+     * Ordered post-open configuration steps. Array order IS the wire order
+     * (kimi: permission mode before model; hermes: set_mode before
+     * set_model; opencode: model before effort). Per-step failure policy is
+     * the step's `onFailure`.
+     */
+    readonly sessionSetup?: readonly AcpSessionStep[];
+    /**
+     * Result-text isolation applied INSIDE the stateful output processor
+     * (parsers/acp.ts) — gemini's latest-agent-message replay isolation.
+     */
+    readonly isolateResult?: (text: string) => string;
+    /**
+     * Bundle-open session-identity strategy (see AcpSessionIdentity).
+     * Absent ⇒ the driver requires an exact sessionId echo in the load
+     * response and fails closed without one.
+     */
+    readonly sessionIdentity?: AcpSessionIdentity;
+    /**
+     * Structured telemetry emitted during exit finalization, after the
+     * output processor has produced the final result (kimi runtime-dead).
+     */
+    onExitFinalization?(ctx: AcpFinalizeContext): void;
+    /**
+     * Filters provider-known-benign stderr blocks out of the no-result
+     * error report (kimi's notifications/initialized -32601 block). This is
+     * error-path stderr hygiene, not a result transform.
+     */
+    filterExpectedStderr?(stderr: string): string;
+    /**
+     * Separate probe entry point (opencode only): verifies the provider's
+     * live per-session model/effort contract WITHOUT prompting. It
+     * intentionally differs from the chat spawn — no runtime
+     * permission-config install, and a rejected model/effort option is
+     * reported as probe evidence rather than absorbed as a warning.
+     */
+    readonly probe?: (opts: OpenCodeAcpConfigProbeOptions) => Promise<OpenCodeAcpConfigProbeResult>;
+}

package/dist/providers/transports/acp-rpc.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ACP JSON-RPC 2.0 channel over a spawned child's stdin/stdout.
+ *
+ * Pure protocol plumbing shared by the chat engine (transports/acp.ts)
+ * and profile-owned entry points that run their own spawn/RPC lifecycle
+ * (the opencode config probe in transports/acp-profiles/opencode.ts).
+ */
+import type { ChildProcess } from "node:child_process";
+export interface AcpRpcChannel {
+    sendRpc(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    sendNotification(method: string, params?: Record<string, unknown>): void;
+    close(error?: Error): void;
+}
+export declare function createAcpRpcChannel(child: ChildProcess, opts: {
+    provider: string;
+    onEvent?: (event: Record<string, unknown>) => void;
+    onNotification?: (event: Record<string, unknown>) => void;
+}): AcpRpcChannel;

package/dist/providers/transports/acp.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Generic ACP (Agent Client Protocol) transport — the protocol engine.
+ *
+ * Works with any CLI tool that supports ACP (Gemini, Copilot, OpenCode, Kimi,
+ * Hermes). Spawns the tool and communicates via ACP JSON-RPC 2.0 over
+ * stdin/stdout.
+ *
+ * Protocol:
+ *   initialize → session/new (or session/load) → session/prompt
+ *   ← session/update (agent_message_chunk, streaming)
+ *   ← result with stopReason
+ *
+ * Everything provider-specific (argv shapes, plan-mode rewrites, config
+ * installs, post-open mode/model/effort configuration, result isolation,
+ * exit telemetry, the opencode config probe) lives behind
+ * `AcpProviderProfile` in `./acp-profiles/`; this file is the generic
+ * driver: RPC channel lifecycle, abort/hold-open scaffolding, the
+ * initialize → load/new → prompt skeleton, and the resume contract
+ * (`requireResume` — deliberately NOT a profile capability).
+ *
+ * `sendAcpPrompt` is internally phased (spawn → open → configure → prompt
+ * → finalize) so a future `openAcpSession(profile, opts)` bundle seam can
+ * hoist the spawn+open phases out of the per-turn prompt phase without
+ * restructuring (batch redesign, item 2/3).
+ */
+import { type HoldOpenOptions } from "./hold-open.js";
+import { type PermissionMode } from "../yolo-contract.js";
+import { type AcpResult } from "../parsers/acp.js";
+import { ACP_TOOLS_FOR_TEST } from "./acp-profiles/index.js";
+import type { AcpMode } from "./acp-profiles/types.js";
+import { detectKimiRuntimeDead } from "./acp-profiles/kimi.js";
+import { probeOpenCodeAcpConfig } from "./acp-profiles/opencode.js";
+export { acpSessionIdFromResponse, acpStopReasonFromResponse, createAcpOutputProcessor, isolateGeminiLatestAgentMessage, supportsAcp, } from "../parsers/acp.js";
+export type { AcpOutputProcessor, AcpOutputProcessorResult, AcpResult, } from "../parsers/acp.js";
+export { ACP_TOOLS_FOR_TEST, detectKimiRuntimeDead, probeOpenCodeAcpConfig };
+export type { AcpMode } from "./acp-profiles/types.js";
+export type { OpenCodeAcpConfigProbeOptions, OpenCodeAcpConfigProbeResult, } from "./acp-profiles/types.js";
+export interface AcpOptions {
+    /** Existing session ID to load. If omitted, creates a new session. */
+    sessionId?: string;
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    /** Tool name — determines the provider profile (binary, argv, hooks) */
+    tool: string;
+    /**
+     * Override the spawned binary path. When set, this exact path is
+     * spawned (with the profile's standard ACP args) instead of the
+     * profile's default binary. Used for troubleshooting custom
+     * builds. (Task 63 fix 3.)
+     */
+    binaryPath?: string;
+    /** If true, failed session/load is an error. If false, falls back to session/new. */
+    requireResume?: boolean;
+    /**
+     * Per-session model override. Honored for Gemini via a
+     * spawn-time `--model` flag and for OpenCode/Kimi via ACP
+     * `session/set_config_option`. Format: `providerID/modelID` (e.g.
+     * `anthropic/claude-3-5-sonnet-20241022`). Copilot does not expose
+     * a per-session ACP model selection surface.
+     */
+    model?: string;
+    /**
+     * Per-session effort / variant override. OpenCode uses ACP configId
+     * `"effort"`. Kimi 0.28.x exposes only an on/off thinking toggle,
+     * so its model-defined effort cannot be overridden here.
+     */
+    effort?: string;
+    /**
+     * Teamfile alias of the spawned member, retained for diagnostics and
+     * provider-specific policy.
+     */
+    alias?: string;
+    /**
+     * Permission mode for this turn (default "yolo"). How "plan" is
+     * realized is profile policy: gemini's argv swaps `-y` for
+     * `--approval-mode plan`, kimi sets its protocol-level mode to "plan",
+     * copilot keeps `--yolo` and warns (no plan flag exists), opencode is
+     * config-file based, and hermes refuses plan mode outright.
+     *
+     * Caveat (gemini): plan mode in gemini-cli filters `write_file` by
+     * workspace path only; `run_shell_command` can still escape. A
+     * follow-up will tighten the sandbox for plan mode.
+     */
+    permissionMode?: PermissionMode;
+    /** Called for each text delta */
+    onDelta?: (text: string) => void;
+    /** Called for each raw JSON-RPC event */
+    onEvent?: (event: Record<string, unknown>) => void;
+    /** Abort signal — kills the provider process when aborted */
+    signal?: AbortSignal;
+    /**
+     * Defer closing the child's stdin past the turn's result while the session
+     * still has outstanding `run_in_background` dispatches (task #68, extended to
+     * ACP). Absent ⇒ the exact pre-existing synchronous close. See
+     * {@link HoldOpenOptions}.
+     */
+    holdOpen?: HoldOpenOptions;
+    /**
+     * Explicit ACP `session/set_mode` mode id to apply to the session on
+     * every spawn, after `session/new`/`session/load` completes.
+     *
+     * Needed by providers whose ACP mode ladder is NOT covered by an argv
+     * permission flag and NOT expressible through lmctl's own
+     * `permissionMode` vocabulary. Hermes is the only such provider today:
+     * its ladder (`default`/`accept_edits`/`dont_ask`) governs the file-EDIT
+     * gate, which `HERMES_YOLO_MODE` does not approve, so the mode must be
+     * set per process or every edit stalls on a
+     * `session/request_permission` round-trip this client cannot answer.
+     *
+     * Validated at the call site against the profile's mode vocabulary —
+     * an unconfigured value throws fail-closed (`assertAcpModeSupported`)
+     * rather than being forwarded as an unknown mode id.
+     */
+    acpMode?: AcpMode;
+}
+/**
+ * Fail-closed guard for `AcpOptions.acpMode`. Throws for a provider whose
+ * profile declares no mode vocabulary (nothing to validate against ⇒
+ * never guess) and for a mode outside the vocabulary's selectable subset.
+ */
+export declare function assertAcpModeSupported(tool: string, mode: AcpMode): void;
+export declare function filterExpectedAcpStderr(tool: string, stderr: string): string;
+/**
+ * Send a prompt via ACP to any supported tool.
+ */
+export declare function sendAcpPrompt(prompt: string, opts: AcpOptions): Promise<AcpResult>;
+/**
+ * Per-turn options for an open ACP bundle session. The spawn-time profile
+ * context (permissionMode, model, effort, acpMode) was fixed at open; a
+ * turn only carries its streaming callbacks and an abort signal.
+ */
+export interface AcpSessionTurnOptions {
+    /** Called for each text delta belonging to THIS turn. */
+    onDelta?: (text: string) => void;
+    /** Called for each raw JSON-RPC event during THIS turn. */
+    onEvent?: (event: Record<string, unknown>) => void;
+    /**
+     * Abort signal for THIS turn. Abortion rejects the turn with
+     * `Error("Aborted")`, sends a best-effort `session/cancel`
+     * notification, and leaves the session open and usable — the child is
+     * NOT killed (contrast with `sendAcpPrompt`, where abort terminates the
+     * one-shot process). Chunks a provider still emits for the cancelled
+     * turn are dropped by the output processor.
+     */
+    signal?: AbortSignal;
+}
+export interface AcpSessionTurnResult {
+    result: string;
+    sessionId: string;
+    stopReason: string;
+    durationMs: number;
+    /**
+     * The open-time profile configuration warnings (task #232 model/effort
+     * drops) are reported on the FIRST turn's result — in bundle mode the
+     * profile's sessionSetup runs once at open, not per spawn.
+     */
+    warnings?: string[];
+}
+/**
+ * An open ACP bundle session: one provider process serving many prompts.
+ *
+ * Lifecycle contract (agreed in the batch-redesign v2 review before
+ * implementation; pinned by tests/providers/acp-bundle.test.ts):
+ *
+ *  - Per-turn completion boundary: a turn ends at its `session/prompt`
+ *    result. The stateful output processor is retained across turns and
+ *    reset per turn (`beginTurn`), so chunks arriving after the boundary
+ *    (provider replay trailing a load, late deltas) never leak into the
+ *    next turn's result.
+ *  - Cancellation: aborting a turn rejects that turn, sends
+ *    `session/cancel`, and keeps the session usable.
+ *  - Hold-open policy: the process is NOT closed between turns — the
+ *    persistence IS the hold (the per-turn stdin close of
+ *    `sendAcpPrompt` is suppressed). `close()` runs the caller's
+ *    `holdOpen` outstanding-work check ONCE before ending stdin, so the
+ *    final turn's background dispatches are not orphaned.
+ *  - Unexpected exit: a mid-bundle process exit rejects the in-flight
+ *    turn and every later turn with an error naming the number of
+ *    completed prompts.
+ *  - Idempotent, bounded close: `close()` may be called repeatedly and
+ *    during an in-flight turn; a child that ignores stdin EOF is
+ *    terminated after a bounded wait — close never hangs.
+ *  - Identity: open requires `session/load` to return the EXACT
+ *    requested session id (no fallback to the requested id, no
+ *    session/new fallback) before prompt 1 is sent.
+ */
+export interface AcpSession {
+    readonly tool: string;
+    /** The verified session id (exact match to the requested id). */
+    readonly sessionId: string;
+    /** Successfully completed turns — the count bundle errors report. */
+    readonly completedTurns: number;
+    sendTurn(prompt: string, opts?: AcpSessionTurnOptions): Promise<AcpSessionTurnResult>;
+    close(): Promise<void>;
+}
+export interface AcpSessionOptions extends AcpOptions {
+    /**
+     * Shutdown cap: how long close() waits for the child to exit after
+     * stdin EOF before escalating to the terminate ladder (which is itself
+     * bounded by the same cap per step). Default 2000ms. Exists so tests
+     * and operator-driven shutdowns can tighten the bound.
+     */
+    closeTimeoutMs?: number;
+}
+/**
+ * Open a persistent ACP session for `opts.tool`: spawn → initialize →
+ * session/load (strict identity, fail-closed) → profile sessionSetup —
+ * everything `sendAcpPrompt` does per turn EXCEPT the prompt phase, which
+ * becomes `session.sendTurn`.
+ *
+ * `requireResume` is implied: a bundle without its exact teamfile session
+ * is always an error. `opts.signal` is intentionally not consulted here —
+ * bundle cancellation is per turn (`AcpSessionTurnOptions.signal`).
+ */
+export declare function openAcpSession(opts: AcpSessionOptions): Promise<AcpSession>;