@haven_ai/connect 0.1.27-alpha.0 → 0.1.29-alpha.0

package/dist/index.d.cts

@@ -125,6 +125,12 @@ interface StoredCredentialPaths {
 interface WriteCredentialInput {
     baseDir?: string;
     agentId: string;
+    /**
+     * #1696: wiring slug. Named agents live at ~/.haven/agents/<slug>/ (stable
+     * across a re-key by construction — the slug never rotates); unnamed keep
+     * the historical ~/.haven/agents/<agent-uuid>/. Both schemes coexist.
+     */
+    serverName?: string;
     apiKey: string;
     delegateKey: string;
     delegateAddress: string;
@@ -161,6 +167,69 @@ interface RuntimeProfile {
 }
 declare function runtimeProfile(runtime: string | undefined, env?: NodeJS.ProcessEnv): RuntimeProfile;
 declare function normalizeRuntime(runtime: string | undefined, env?: NodeJS.ProcessEnv): RuntimeId;
+/** The flag values a refusal message should offer. Mirrors RuntimeId. */
+declare const RUNTIME_FLAG_VALUES: "claude-code, codex-cli, codex-desktop, cursor, vscode, vscode-insiders, claude-desktop, hermes, other";
+interface RuntimeSelection {
+    runtime: RuntimeId | null;
+    source: 'force' | 'detected' | 'explicit' | 'prompted' | 'none';
+    /** Set when a confident environment detection overrode a contradicting explicit hint (#1672). */
+    overrodeHint?: RuntimeId;
+    /** Set when a supplied hint was not a runtime name at all and detection carried the run (#1719). */
+    discardedHint?: string;
+}
+interface RuntimeResolutionOptions {
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Rung 3b (#1719): the harness an AGENT executing this command reported for
+     * ITSELF, when detection found nothing to go on.
+     *
+     * It deliberately enters at the same precedence as `--runtime`, which is
+     * what makes it safe: a hint can only ever fill a vacuum, and loses to a
+     * confident detection exactly as #1672 made it. In practice the agent
+     * supplies it BY re-running with `--runtime <name>`; this field exists so a
+     * programmatic caller can pass a self-report without pretending to be a
+     * command-line flag, and so the ladder names the rung it has.
+     */
+    selfReported?: string;
+    /**
+     * Rung 4 (#1719): ask a human at an interactive terminal which of the
+     * clients installed on this machine to configure. Injected as a thunk so
+     * the ladder stays a policy function — the scan, the readline prompt, and
+     * the "nothing writable is installed" refusal all live in
+     * `installed-clients.ts`. Omitted (`--json`, no TTY, library callers) means
+     * the rung is skipped entirely, not answered with a guess.
+     */
+    promptForRuntime?: () => Promise<RuntimeId>;
+}
+/**
+ * Runtime resolution, detection-first (#1672) and self-resolving (#1719).
+ *
+ * The setup command carries no `--runtime`; the connector works out the
+ * runtime it is executing inside. Precedence:
+ *
+ * 1. `--runtime-force <name>` — always wins (unknown name refuses).
+ * 2. Environment detection over a CONTRADICTING hint. Detection only fires
+ *    inside a real agent shell, where writing a different client's config is
+ *    almost surely wrong — the claude-desktop-hint-in-Claude-Code dead end
+ *    this exists to close.
+ * 3. An explicit `--runtime`, or an agent's self-report, with no contradicting
+ *    detection (the legit plain-terminal "configure Claude Desktop by hand"
+ *    case — unchanged).
+ * 4. Detection alone.
+ * 5. An interactive pick among the clients actually installed here, when a
+ *    human is at a TTY. The scan populates the choices; it never selects.
+ * 6. Nothing known → `runtime: null`; the caller refuses BEFORE side effects
+ *    rather than guessing a config location.
+ *
+ * A hint that is not a runtime name at all is not a hint — it is a mistake, and
+ * the one thing it must never do is fall through to a config location nobody
+ * asked for. With no detection to fall back on it refuses (`runtime_unrecognized`).
+ * With a detection it loses to it, loudly, exactly like a contradicting hint:
+ * the detected client is the right write either way, and refusing there would
+ * turn every rollout window in which the dashboard learns an id before the
+ * published connector does into a hard failure.
+ */
+declare function resolveRuntimeSelection(explicit: string | undefined, force: string | undefined, options?: RuntimeResolutionOptions): Promise<RuntimeSelection>;
 
 type RuntimeMcpMode = 'local_stdio' | 'hosted_plus_signer' | 'manual';
 
@@ -184,6 +253,8 @@ interface PrepareLocalMcpRuntimeInput {
     signerPath: string;
     homeDir?: string;
     nodeVersion?: string;
+    /** #1696: wiring slug, recorded in the sidecar for per-agent inventory (#1697). */
+    serverName?: string;
 }
 interface PreparedLocalMcpRuntime {
     command: string;
@@ -199,6 +270,8 @@ interface PrepareSignerRuntimeInput {
     credentialDirectory: string;
     signerPath: string;
     homeDir?: string;
+    /** #1696: wiring slug, recorded in the sidecar for per-agent inventory (#1697). */
+    serverName?: string;
 }
 interface PreparedSignerRuntime {
     /** Absolute command to register as the signer MCP `command`. */
@@ -249,6 +322,11 @@ interface RuntimeInstallInput {
      * used when this is true and the runtime supports it.
      */
     localMcp?: boolean;
+    /**
+     * #1695: wiring slug for a NAMED MCP pair (haven-<slug> /
+     * haven-signer-<slug>). Absent = the bare pair, unchanged from today.
+     */
+    serverName?: string;
 }
 interface RuntimeInstallResult {
     runtime: RuntimeId;
@@ -333,13 +411,30 @@ declare function runtimeInstallCapabilities(runtime: string | undefined, env?: N
     restartRequired: boolean;
 };
 
-declare const CONNECTOR_VERSION = "0.1.27-alpha.0";
+declare const CONNECTOR_VERSION = "0.1.29-alpha.0";
 interface ConnectOptions {
     setupToken: string;
     apiBaseUrl: string;
     runtime?: string;
+    /** #1672 escape hatch: use exactly this runtime, ignoring environment detection. */
+    runtimeForce?: string;
+    /**
+     * #1719: the harness an AGENT running this command reported for itself. Enters
+     * at the same precedence as `runtime`, so it can only fill a vacuum — never
+     * override a detected environment.
+     */
+    runtimeSelfReport?: string;
+    /**
+     * #1719: this run may ask a human which installed client to configure. The
+     * CLI sets it for a non-`--json` run; a library caller must opt in. Combined
+     * with `deps.isTty`, it is what makes the prompt rung SKIPPED rather than
+     * answered in CI, in `--json` automation, and in library embeddings.
+     */
+    interactive?: boolean;
     credentialsDir?: string;
     environmentLabel?: string;
+    /** #1696: wiring slug for a named MCP pair + slug-keyed credential dir. */
+    serverName?: string;
     connectorVersion?: string;
     ackSigner?: boolean;
     ackLocalTools?: boolean;
@@ -401,6 +496,12 @@ interface ConnectDeps {
     redactPaths?: boolean;
     /** Overridable so the Node-floor refusal is testable without spawning a Node. */
     nodeVersion?: string;
+    /** Overridable so runtime detection (#1672) is testable without faking process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** Overridable so the #1719 TTY gate is testable without faking process.stdin. */
+    isTty?: boolean;
+    /** Overridable so the #1719 installed-client prompt is testable without readline. */
+    promptRuntime?: () => Promise<RuntimeId>;
 }
 interface ConnectResult {
     setupId: string;
@@ -420,6 +521,11 @@ declare function completionOutcome(input: {
 /**
  * A deliberately terse failure record: error messages can contain server or
  * filesystem detail, while this public contract must remain safe to serialize.
+ *
+ * #1719: a `ConnectError` carries its own code and next action, so it is read
+ * rather than guessed. The regex ladder below survives only for the refusals
+ * that are still plain `Error`s — every new failure mode joins the vocabulary
+ * instead of joining that ladder.
  */
 declare function failedConnectOutcome(runtimeHint: string | undefined, error: unknown): ConnectOutcome;
 /**
@@ -452,6 +558,12 @@ interface ParsedCli {
     /** #1589: diagnosis mode — no setup token required. */
     doctor: boolean;
     repair: boolean;
+    /** #1681: retire an agent credential directory in place — no token required. */
+    tombstone?: {
+        directory: string;
+        reason?: string;
+        replacedBy?: string;
+    };
 }
 declare function parseArgs(argv: string[], env?: NodeJS.ProcessEnv): ParsedCli;
 declare function helpText(): string;
@@ -459,13 +571,91 @@ declare function helpText(): string;
 declare function redactSecrets(value: string): string;
 declare function shortAddress(address: string): string;
 
+/**
+ * The connector's machine-readable failure vocabulary (#1719).
+ *
+ * Before this, a refusal was a bare `throw new Error(...)` and the automation
+ * contract recovered a code by regex-matching the message in
+ * `failedConnectOutcome`. That works only for as long as nobody rewords a
+ * sentence, and it gives the caller nothing to branch on that the wording did
+ * not accidentally provide. Every refusal this module fronts carries:
+ *
+ * - `code` — stable, snake_case, safe to switch on;
+ * - `nextAction` — the one thing to do next, in the same snake_case shape the
+ *   install-status contract already uses for `next_action`;
+ * - `message` — human/agent prose, still the thing printed to a terminal.
+ *
+ * Codes are additive and never renamed: a consumer pinned to an older
+ * connector must keep recognising the ones it already knows.
+ */
+declare class ConnectError extends Error {
+    readonly code: string;
+    readonly nextAction: string;
+    constructor(code: string, message: string, nextAction: string);
+}
+declare function isConnectError(err: unknown): err is ConnectError;
+
+/**
+ * Installed-client scan + interactive pick (#1719).
+ *
+ * The rung that answers "which runtime am I configuring?" for a HUMAN in a
+ * plain terminal, where there is no agent shell to detect. Two properties hold
+ * it up, and both are load-bearing:
+ *
+ * 1. **Only clients the connector can actually write.** A row that cannot be
+ *    configured is not a choice, it is a dead end wearing a choice's clothes.
+ * 2. **The scan populates the choices; it never selects.** Finding exactly one
+ *    installed app tells you what EXISTS, not where the user wants their agent
+ *    to run — and the cost of being wrong is an API key and a delegate key
+ *    written into an app the user does not use. `scanInstalledClients` returns
+ *    candidates and nothing else; only an answer typed at the prompt resolves
+ *    a runtime.
+ */
+interface InstalledClientCandidate {
+    runtime: RuntimeId;
+    label: string;
+    /** What made this a candidate — shown at the prompt so the pick is informed. */
+    detail: string;
+    /**
+     * The config file Haven would write for this client, when it owns one.
+     * `null` for Claude Code, which is configured through its own CLI. Set
+     * regardless of which evidence found the client — `evidence` is what says
+     * whether that file exists today.
+     */
+    configPath: string | null;
+    evidence: 'config-file' | 'client-directory';
+}
+interface ScanInstalledClientsOptions {
+    homeDir?: string;
+    /** Workspace root, for the project-local `.vscode/` marker. */
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Injectable so the scan is testable without a populated home directory. */
+    exists?: (path: string) => Promise<boolean>;
+}
+declare function scanInstalledClients(options?: ScanInstalledClientsOptions): Promise<InstalledClientCandidate[]>;
+interface PromptIo {
+    write: (text: string) => void;
+    /** Resolves the typed line, or `null` on EOF / Ctrl-C. */
+    question: (query: string) => Promise<string | null>;
+}
+declare function promptForInstalledClient(candidates: readonly InstalledClientCandidate[], io?: PromptIo): Promise<RuntimeId>;
+/**
+ * The whole rung as one thunk: scan, refuse if nothing writable is installed,
+ * otherwise prompt. This is what `resolveRuntimeSelection` calls, which is why
+ * the registry needs no knowledge of the filesystem or of readline.
+ */
+declare function resolveRuntimeByInstalledClientPrompt(options?: ScanInstalledClientsOptions & {
+    io?: PromptIo;
+}): Promise<RuntimeId>;
+
 declare const MCP_RUNTIME_MANIFEST: {
     readonly mcpPackage: "@haven_ai/mcp";
-    readonly mcpVersion: "0.1.27-alpha.0";
+    readonly mcpVersion: "0.1.29-alpha.0";
     readonly sdkPackage: "@haven_ai/sdk";
-    readonly sdkVersion: "0.1.27-alpha.0";
+    readonly sdkVersion: "0.1.29-alpha.0";
     readonly signerPackage: "@haven_ai/signer";
-    readonly signerVersion: "0.1.27-alpha.0";
+    readonly signerVersion: "0.1.29-alpha.0";
     readonly minimumNodeVersion: "22.0.0";
     readonly supportedClients: readonly ["codex-cli", "codex-desktop", "claude-code"];
     readonly requiredTools: readonly string[];
@@ -481,4 +671,4 @@ declare function mcpPackageSpec(): string;
 declare function sdkPackageSpec(): string;
 declare function signerPackageSpec(): string;
 
-export { CONNECTOR_VERSION, CONNECT_OUTCOME_SCHEMA_VERSION, type ConnectApiClient, type ConnectDeps, type ConnectOptions, type ConnectOutcome, type ConnectOutcomeStatus, type ConnectResult, type LocalDelegateKey, MCP_RUNTIME_MANIFEST, type ParsedCli, type PrepareSignerRuntimeInput, type PreparedSignerRuntime, type RegisterSetupInput, type RegisterSetupResponse, type ResolveSetupInput, type ResolvedSetup, type RuntimeId, type RuntimeInstallInput, type RuntimeInstallResult, type RuntimeProfile, type StoredCredentialPaths, type UpdateInstallStatusInput, type WriteCredentialInput, completionOutcome, createConnectApiClient, defaultAgentDirectory, delegateKeyFromPrivateKey, failedConnectOutcome, generateDelegateKey, helpText, installRuntime, mcpPackageSpec, normalizeRuntime, parseArgs, prepareSignerRuntime, redactSecrets, runConnect, runtimeInstallCapabilities, runtimeProfile, sdkPackageSpec, shortAddress, signerPackageSpec, writeCredentialFiles };
+export { CONNECTOR_VERSION, CONNECT_OUTCOME_SCHEMA_VERSION, type ConnectApiClient, type ConnectDeps, ConnectError, type ConnectOptions, type ConnectOutcome, type ConnectOutcomeStatus, type ConnectResult, type InstalledClientCandidate, type LocalDelegateKey, MCP_RUNTIME_MANIFEST, type ParsedCli, type PrepareSignerRuntimeInput, type PreparedSignerRuntime, type PromptIo, RUNTIME_FLAG_VALUES, type RegisterSetupInput, type RegisterSetupResponse, type ResolveSetupInput, type ResolvedSetup, type RuntimeId, type RuntimeInstallInput, type RuntimeInstallResult, type RuntimeProfile, type RuntimeResolutionOptions, type RuntimeSelection, type ScanInstalledClientsOptions, type StoredCredentialPaths, type UpdateInstallStatusInput, type WriteCredentialInput, completionOutcome, createConnectApiClient, defaultAgentDirectory, delegateKeyFromPrivateKey, failedConnectOutcome, generateDelegateKey, helpText, installRuntime, isConnectError, mcpPackageSpec, normalizeRuntime, parseArgs, prepareSignerRuntime, promptForInstalledClient, redactSecrets, resolveRuntimeByInstalledClientPrompt, resolveRuntimeSelection, runConnect, runtimeInstallCapabilities, runtimeProfile, scanInstalledClients, sdkPackageSpec, shortAddress, signerPackageSpec, writeCredentialFiles };

package/dist/index.d.ts

@@ -125,6 +125,12 @@ interface StoredCredentialPaths {
 interface WriteCredentialInput {
     baseDir?: string;
     agentId: string;
+    /**
+     * #1696: wiring slug. Named agents live at ~/.haven/agents/<slug>/ (stable
+     * across a re-key by construction — the slug never rotates); unnamed keep
+     * the historical ~/.haven/agents/<agent-uuid>/. Both schemes coexist.
+     */
+    serverName?: string;
     apiKey: string;
     delegateKey: string;
     delegateAddress: string;
@@ -161,6 +167,69 @@ interface RuntimeProfile {
 }
 declare function runtimeProfile(runtime: string | undefined, env?: NodeJS.ProcessEnv): RuntimeProfile;
 declare function normalizeRuntime(runtime: string | undefined, env?: NodeJS.ProcessEnv): RuntimeId;
+/** The flag values a refusal message should offer. Mirrors RuntimeId. */
+declare const RUNTIME_FLAG_VALUES: "claude-code, codex-cli, codex-desktop, cursor, vscode, vscode-insiders, claude-desktop, hermes, other";
+interface RuntimeSelection {
+    runtime: RuntimeId | null;
+    source: 'force' | 'detected' | 'explicit' | 'prompted' | 'none';
+    /** Set when a confident environment detection overrode a contradicting explicit hint (#1672). */
+    overrodeHint?: RuntimeId;
+    /** Set when a supplied hint was not a runtime name at all and detection carried the run (#1719). */
+    discardedHint?: string;
+}
+interface RuntimeResolutionOptions {
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Rung 3b (#1719): the harness an AGENT executing this command reported for
+     * ITSELF, when detection found nothing to go on.
+     *
+     * It deliberately enters at the same precedence as `--runtime`, which is
+     * what makes it safe: a hint can only ever fill a vacuum, and loses to a
+     * confident detection exactly as #1672 made it. In practice the agent
+     * supplies it BY re-running with `--runtime <name>`; this field exists so a
+     * programmatic caller can pass a self-report without pretending to be a
+     * command-line flag, and so the ladder names the rung it has.
+     */
+    selfReported?: string;
+    /**
+     * Rung 4 (#1719): ask a human at an interactive terminal which of the
+     * clients installed on this machine to configure. Injected as a thunk so
+     * the ladder stays a policy function — the scan, the readline prompt, and
+     * the "nothing writable is installed" refusal all live in
+     * `installed-clients.ts`. Omitted (`--json`, no TTY, library callers) means
+     * the rung is skipped entirely, not answered with a guess.
+     */
+    promptForRuntime?: () => Promise<RuntimeId>;
+}
+/**
+ * Runtime resolution, detection-first (#1672) and self-resolving (#1719).
+ *
+ * The setup command carries no `--runtime`; the connector works out the
+ * runtime it is executing inside. Precedence:
+ *
+ * 1. `--runtime-force <name>` — always wins (unknown name refuses).
+ * 2. Environment detection over a CONTRADICTING hint. Detection only fires
+ *    inside a real agent shell, where writing a different client's config is
+ *    almost surely wrong — the claude-desktop-hint-in-Claude-Code dead end
+ *    this exists to close.
+ * 3. An explicit `--runtime`, or an agent's self-report, with no contradicting
+ *    detection (the legit plain-terminal "configure Claude Desktop by hand"
+ *    case — unchanged).
+ * 4. Detection alone.
+ * 5. An interactive pick among the clients actually installed here, when a
+ *    human is at a TTY. The scan populates the choices; it never selects.
+ * 6. Nothing known → `runtime: null`; the caller refuses BEFORE side effects
+ *    rather than guessing a config location.
+ *
+ * A hint that is not a runtime name at all is not a hint — it is a mistake, and
+ * the one thing it must never do is fall through to a config location nobody
+ * asked for. With no detection to fall back on it refuses (`runtime_unrecognized`).
+ * With a detection it loses to it, loudly, exactly like a contradicting hint:
+ * the detected client is the right write either way, and refusing there would
+ * turn every rollout window in which the dashboard learns an id before the
+ * published connector does into a hard failure.
+ */
+declare function resolveRuntimeSelection(explicit: string | undefined, force: string | undefined, options?: RuntimeResolutionOptions): Promise<RuntimeSelection>;
 
 type RuntimeMcpMode = 'local_stdio' | 'hosted_plus_signer' | 'manual';
 
@@ -184,6 +253,8 @@ interface PrepareLocalMcpRuntimeInput {
     signerPath: string;
     homeDir?: string;
     nodeVersion?: string;
+    /** #1696: wiring slug, recorded in the sidecar for per-agent inventory (#1697). */
+    serverName?: string;
 }
 interface PreparedLocalMcpRuntime {
     command: string;
@@ -199,6 +270,8 @@ interface PrepareSignerRuntimeInput {
     credentialDirectory: string;
     signerPath: string;
     homeDir?: string;
+    /** #1696: wiring slug, recorded in the sidecar for per-agent inventory (#1697). */
+    serverName?: string;
 }
 interface PreparedSignerRuntime {
     /** Absolute command to register as the signer MCP `command`. */
@@ -249,6 +322,11 @@ interface RuntimeInstallInput {
      * used when this is true and the runtime supports it.
      */
     localMcp?: boolean;
+    /**
+     * #1695: wiring slug for a NAMED MCP pair (haven-<slug> /
+     * haven-signer-<slug>). Absent = the bare pair, unchanged from today.
+     */
+    serverName?: string;
 }
 interface RuntimeInstallResult {
     runtime: RuntimeId;
@@ -333,13 +411,30 @@ declare function runtimeInstallCapabilities(runtime: string | undefined, env?: N
     restartRequired: boolean;
 };
 
-declare const CONNECTOR_VERSION = "0.1.27-alpha.0";
+declare const CONNECTOR_VERSION = "0.1.29-alpha.0";
 interface ConnectOptions {
     setupToken: string;
     apiBaseUrl: string;
     runtime?: string;
+    /** #1672 escape hatch: use exactly this runtime, ignoring environment detection. */
+    runtimeForce?: string;
+    /**
+     * #1719: the harness an AGENT running this command reported for itself. Enters
+     * at the same precedence as `runtime`, so it can only fill a vacuum — never
+     * override a detected environment.
+     */
+    runtimeSelfReport?: string;
+    /**
+     * #1719: this run may ask a human which installed client to configure. The
+     * CLI sets it for a non-`--json` run; a library caller must opt in. Combined
+     * with `deps.isTty`, it is what makes the prompt rung SKIPPED rather than
+     * answered in CI, in `--json` automation, and in library embeddings.
+     */
+    interactive?: boolean;
     credentialsDir?: string;
     environmentLabel?: string;
+    /** #1696: wiring slug for a named MCP pair + slug-keyed credential dir. */
+    serverName?: string;
     connectorVersion?: string;
     ackSigner?: boolean;
     ackLocalTools?: boolean;
@@ -401,6 +496,12 @@ interface ConnectDeps {
     redactPaths?: boolean;
     /** Overridable so the Node-floor refusal is testable without spawning a Node. */
     nodeVersion?: string;
+    /** Overridable so runtime detection (#1672) is testable without faking process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** Overridable so the #1719 TTY gate is testable without faking process.stdin. */
+    isTty?: boolean;
+    /** Overridable so the #1719 installed-client prompt is testable without readline. */
+    promptRuntime?: () => Promise<RuntimeId>;
 }
 interface ConnectResult {
     setupId: string;
@@ -420,6 +521,11 @@ declare function completionOutcome(input: {
 /**
  * A deliberately terse failure record: error messages can contain server or
  * filesystem detail, while this public contract must remain safe to serialize.
+ *
+ * #1719: a `ConnectError` carries its own code and next action, so it is read
+ * rather than guessed. The regex ladder below survives only for the refusals
+ * that are still plain `Error`s — every new failure mode joins the vocabulary
+ * instead of joining that ladder.
  */
 declare function failedConnectOutcome(runtimeHint: string | undefined, error: unknown): ConnectOutcome;
 /**
@@ -452,6 +558,12 @@ interface ParsedCli {
     /** #1589: diagnosis mode — no setup token required. */
     doctor: boolean;
     repair: boolean;
+    /** #1681: retire an agent credential directory in place — no token required. */
+    tombstone?: {
+        directory: string;
+        reason?: string;
+        replacedBy?: string;
+    };
 }
 declare function parseArgs(argv: string[], env?: NodeJS.ProcessEnv): ParsedCli;
 declare function helpText(): string;
@@ -459,13 +571,91 @@ declare function helpText(): string;
 declare function redactSecrets(value: string): string;
 declare function shortAddress(address: string): string;
 
+/**
+ * The connector's machine-readable failure vocabulary (#1719).
+ *
+ * Before this, a refusal was a bare `throw new Error(...)` and the automation
+ * contract recovered a code by regex-matching the message in
+ * `failedConnectOutcome`. That works only for as long as nobody rewords a
+ * sentence, and it gives the caller nothing to branch on that the wording did
+ * not accidentally provide. Every refusal this module fronts carries:
+ *
+ * - `code` — stable, snake_case, safe to switch on;
+ * - `nextAction` — the one thing to do next, in the same snake_case shape the
+ *   install-status contract already uses for `next_action`;
+ * - `message` — human/agent prose, still the thing printed to a terminal.
+ *
+ * Codes are additive and never renamed: a consumer pinned to an older
+ * connector must keep recognising the ones it already knows.
+ */
+declare class ConnectError extends Error {
+    readonly code: string;
+    readonly nextAction: string;
+    constructor(code: string, message: string, nextAction: string);
+}
+declare function isConnectError(err: unknown): err is ConnectError;
+
+/**
+ * Installed-client scan + interactive pick (#1719).
+ *
+ * The rung that answers "which runtime am I configuring?" for a HUMAN in a
+ * plain terminal, where there is no agent shell to detect. Two properties hold
+ * it up, and both are load-bearing:
+ *
+ * 1. **Only clients the connector can actually write.** A row that cannot be
+ *    configured is not a choice, it is a dead end wearing a choice's clothes.
+ * 2. **The scan populates the choices; it never selects.** Finding exactly one
+ *    installed app tells you what EXISTS, not where the user wants their agent
+ *    to run — and the cost of being wrong is an API key and a delegate key
+ *    written into an app the user does not use. `scanInstalledClients` returns
+ *    candidates and nothing else; only an answer typed at the prompt resolves
+ *    a runtime.
+ */
+interface InstalledClientCandidate {
+    runtime: RuntimeId;
+    label: string;
+    /** What made this a candidate — shown at the prompt so the pick is informed. */
+    detail: string;
+    /**
+     * The config file Haven would write for this client, when it owns one.
+     * `null` for Claude Code, which is configured through its own CLI. Set
+     * regardless of which evidence found the client — `evidence` is what says
+     * whether that file exists today.
+     */
+    configPath: string | null;
+    evidence: 'config-file' | 'client-directory';
+}
+interface ScanInstalledClientsOptions {
+    homeDir?: string;
+    /** Workspace root, for the project-local `.vscode/` marker. */
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Injectable so the scan is testable without a populated home directory. */
+    exists?: (path: string) => Promise<boolean>;
+}
+declare function scanInstalledClients(options?: ScanInstalledClientsOptions): Promise<InstalledClientCandidate[]>;
+interface PromptIo {
+    write: (text: string) => void;
+    /** Resolves the typed line, or `null` on EOF / Ctrl-C. */
+    question: (query: string) => Promise<string | null>;
+}
+declare function promptForInstalledClient(candidates: readonly InstalledClientCandidate[], io?: PromptIo): Promise<RuntimeId>;
+/**
+ * The whole rung as one thunk: scan, refuse if nothing writable is installed,
+ * otherwise prompt. This is what `resolveRuntimeSelection` calls, which is why
+ * the registry needs no knowledge of the filesystem or of readline.
+ */
+declare function resolveRuntimeByInstalledClientPrompt(options?: ScanInstalledClientsOptions & {
+    io?: PromptIo;
+}): Promise<RuntimeId>;
+
 declare const MCP_RUNTIME_MANIFEST: {
     readonly mcpPackage: "@haven_ai/mcp";
-    readonly mcpVersion: "0.1.27-alpha.0";
+    readonly mcpVersion: "0.1.29-alpha.0";
     readonly sdkPackage: "@haven_ai/sdk";
-    readonly sdkVersion: "0.1.27-alpha.0";
+    readonly sdkVersion: "0.1.29-alpha.0";
     readonly signerPackage: "@haven_ai/signer";
-    readonly signerVersion: "0.1.27-alpha.0";
+    readonly signerVersion: "0.1.29-alpha.0";
     readonly minimumNodeVersion: "22.0.0";
     readonly supportedClients: readonly ["codex-cli", "codex-desktop", "claude-code"];
     readonly requiredTools: readonly string[];
@@ -481,4 +671,4 @@ declare function mcpPackageSpec(): string;
 declare function sdkPackageSpec(): string;
 declare function signerPackageSpec(): string;
 
-export { CONNECTOR_VERSION, CONNECT_OUTCOME_SCHEMA_VERSION, type ConnectApiClient, type ConnectDeps, type ConnectOptions, type ConnectOutcome, type ConnectOutcomeStatus, type ConnectResult, type LocalDelegateKey, MCP_RUNTIME_MANIFEST, type ParsedCli, type PrepareSignerRuntimeInput, type PreparedSignerRuntime, type RegisterSetupInput, type RegisterSetupResponse, type ResolveSetupInput, type ResolvedSetup, type RuntimeId, type RuntimeInstallInput, type RuntimeInstallResult, type RuntimeProfile, type StoredCredentialPaths, type UpdateInstallStatusInput, type WriteCredentialInput, completionOutcome, createConnectApiClient, defaultAgentDirectory, delegateKeyFromPrivateKey, failedConnectOutcome, generateDelegateKey, helpText, installRuntime, mcpPackageSpec, normalizeRuntime, parseArgs, prepareSignerRuntime, redactSecrets, runConnect, runtimeInstallCapabilities, runtimeProfile, sdkPackageSpec, shortAddress, signerPackageSpec, writeCredentialFiles };
+export { CONNECTOR_VERSION, CONNECT_OUTCOME_SCHEMA_VERSION, type ConnectApiClient, type ConnectDeps, ConnectError, type ConnectOptions, type ConnectOutcome, type ConnectOutcomeStatus, type ConnectResult, type InstalledClientCandidate, type LocalDelegateKey, MCP_RUNTIME_MANIFEST, type ParsedCli, type PrepareSignerRuntimeInput, type PreparedSignerRuntime, type PromptIo, RUNTIME_FLAG_VALUES, type RegisterSetupInput, type RegisterSetupResponse, type ResolveSetupInput, type ResolvedSetup, type RuntimeId, type RuntimeInstallInput, type RuntimeInstallResult, type RuntimeProfile, type RuntimeResolutionOptions, type RuntimeSelection, type ScanInstalledClientsOptions, type StoredCredentialPaths, type UpdateInstallStatusInput, type WriteCredentialInput, completionOutcome, createConnectApiClient, defaultAgentDirectory, delegateKeyFromPrivateKey, failedConnectOutcome, generateDelegateKey, helpText, installRuntime, isConnectError, mcpPackageSpec, normalizeRuntime, parseArgs, prepareSignerRuntime, promptForInstalledClient, redactSecrets, resolveRuntimeByInstalledClientPrompt, resolveRuntimeSelection, runConnect, runtimeInstallCapabilities, runtimeProfile, scanInstalledClients, sdkPackageSpec, shortAddress, signerPackageSpec, writeCredentialFiles };