@moondeck/station 0.0.0-stage → 1.0.0

package/lib/engines.ts

@@ -0,0 +1,1342 @@
+/**
+ * Engine connect/disconnect for the local host UI (ADR-028, ADR-044 P2).
+ *
+ * A single descriptor table for the AI coding engines the host can run
+ * (Claude, Codex, Kimi, Grok, Cursor) plus the connect/disconnect/status logic
+ * the local UI drives (the desktop app renders that same UI). It writes the
+ * `.env.local` the RUNNING launchd/npm host reads (UAI_HOME) and sets
+ * `process.env` so a connect takes effect WITHOUT a host restart — the
+ * adapters' `available()` and task-up's env injection both read `process.env`.
+ *
+ * CLI resolution: a host supervised by the desktop app (or launchd) inherits a
+ * minimal GUI PATH that lacks wherever the engine CLIs live (~/.local/bin,
+ * npm/nvm/asdf prefixes, Homebrew), so spawning a bare `claude`/`codex` would
+ * ENOENT even though the CLI is installed. We resolve binaries the way the
+ * owner's terminal would — well-known install dirs first, then the login
+ * shell's PATH (same trick as the desktop's docker.ts) — and spawn with that
+ * PATH so `#!/usr/bin/env node` shebangs resolve too.
+ *
+ * Three auth modes:
+ *   - token-command  (Claude): `claude setup-token` shows a token; we run the
+ *                    CLI under a PTY (script(1)), capture the `sk-ant-oat…`
+ *                    value live from the terminal stream and persist it as
+ *                    CLAUDE_CODE_OAUTH_TOKEN. A pasted token is accepted too.
+ *                    The PTY is load-bearing: the CLI's Ink UI buffers ALL
+ *                    output until unmount when stdout isn't a TTY and its
+ *                    final screens wait for a keypress — under plain pipes it
+ *                    emits nothing and never exits (the eternal "Connecting…"
+ *                    of 0.8.11). We resolve as soon as the token appears and
+ *                    kill the CLI rather than wait for it to end on its own.
+ *   - login-command  (Codex/Kimi/Grok): `<cli> login` runs a browser OAuth and
+ *                    writes a config file; success = that file appearing.
+ *   - api-key        (Cursor): no command — persist a pasted CURSOR_API_KEY.
+ *
+ * Besides its primary mode, an engine can accept a pasted API key as an
+ * alternative (`apiKeyHint`/`apiKeyUrl` in the catalog drive the UI):
+ *   - claude → ANTHROPIC_API_KEY (the adapter already forwards it; a pasted
+ *     `sk-ant-oat…` still lands in CLAUDE_CODE_OAUTH_TOKEN — classified by
+ *     prefix, so either credential works in either paste box).
+ *   - codex  → ~/.codex/auth.json `{"OPENAI_API_KEY": …}`, the same plaintext
+ *     file `codex login --with-api-key` writes. Written directly (not via the
+ *     CLI): task-up docker-cp's that FILE into containers, so a keychain-backed
+ *     CLI login would break task auth, and this works with no host CLI at all.
+ *   - grok   → XAI_API_KEY (documented pay-as-you-go fallback of the grok CLI;
+ *     the adapter forwards it into task containers).
+ *   - kimi   → none: Kimi Code reads keys only from its config.toml via the
+ *     interactive `/login`, never from the environment — so we don't offer a
+ *     paste box we can't honor.
+ *
+ * Detection mirrors each adapter's `available()`: env/`.env.local` for
+ * claude/cursor, a config file under the owner home for codex/kimi/grok.
+ *
+ * Every side-effecting seam (spawn, the `.env.local` path, the owner home,
+ * process.env) is injectable so the flows are unit-testable without touching
+ * the real filesystem or spawning anything.
+ */
+
+import {
+  execFile as nodeExecFile,
+  spawn as nodeSpawn,
+  type ChildProcess,
+} from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { env } from "./env";
+
+export type EngineKind =
+  | "claude"
+  | "codex"
+  | "kimi"
+  | "grok"
+  | "cursor"
+  | "opencode";
+export type EngineAuthMode =
+  | "token-command"
+  | "login-command"
+  | "api-key"
+  // The owner signs in with the engine's OWN interactive CLI in their terminal
+  // (e.g. `opencode auth login` — an arrow-key TUI we can't drive from the
+  // fire-and-log connect panel), and we just detect the credential it writes.
+  | "external-login";
+
+/** One entry of the engine catalog the UI's "Add engine" panel renders. */
+export interface EngineCatalogEntry {
+  kind: EngineKind;
+  label: string;
+  authMode: EngineAuthMode;
+  /** One-line help shown under the engine in the picker. */
+  notes: string | null;
+  /** Where to mint an API key (api-key mode only). */
+  getKeyUrl: string | null;
+  /** Placeholder for the pasted-API-key alternative; null = not supported. */
+  apiKeyHint: string | null;
+  /** Where to mint a key for the pasted-API-key alternative. */
+  apiKeyUrl: string | null;
+  /**
+   * Human-readable install command the UI shows next to "Install & connect"
+   * when the CLI is missing (null = nothing to install, e.g. Cursor).
+   */
+  installHint: string | null;
+  /**
+   * The command the owner runs in their OWN terminal to sign in
+   * (external-login mode only; null otherwise).
+   */
+  loginCmd: string | null;
+}
+
+interface EngineDescriptor {
+  label: string;
+  authMode: EngineAuthMode;
+  notes: string;
+  getKeyUrl?: string;
+  /** Pasted-API-key alternative (absent = login/token only, e.g. kimi). */
+  apiKeyHint?: string;
+  apiKeyUrl?: string;
+  /** external-login: the CLI command the owner runs in their terminal. */
+  loginCmd?: string;
+}
+
+/** Static descriptor table — the single source of truth for engine metadata. */
+const DESCRIPTORS: Record<EngineKind, EngineDescriptor> = {
+  claude: {
+    label: "Claude",
+    authMode: "token-command",
+    notes:
+      "Opens your browser to authorize Claude, then captures the token automatically.",
+    apiKeyHint: "sk-ant-…",
+    apiKeyUrl: "https://console.anthropic.com/settings/keys",
+  },
+  codex: {
+    label: "Codex",
+    authMode: "login-command",
+    notes: "Opens your browser to sign in to your OpenAI Codex account.",
+    apiKeyHint: "sk-…",
+    apiKeyUrl: "https://platform.openai.com/api-keys",
+  },
+  kimi: {
+    label: "Kimi Code",
+    authMode: "login-command",
+    notes:
+      "Sign in with your Moonshot Kimi Code subscription. Activates after the next image rebuild.",
+  },
+  grok: {
+    label: "Grok",
+    authMode: "login-command",
+    notes:
+      "Sign in with your xAI Grok subscription. Activates after the next image rebuild.",
+    apiKeyHint: "xai-…",
+    apiKeyUrl: "https://console.x.ai",
+  },
+  cursor: {
+    label: "Cursor",
+    authMode: "api-key",
+    notes: "Paste a Cursor API key. Requires Cursor Pro.",
+    getKeyUrl: "https://cursor.com/dashboard?tab=integrations",
+  },
+  opencode: {
+    label: "OpenCode",
+    // `opencode auth login` is an interactive arrow-key TUI (provider picker →
+    // per-provider auth) — it can't be driven from the fire-and-log connect
+    // panel, so the owner runs it in their own terminal and we detect the
+    // auth.json it writes.
+    authMode: "external-login",
+    loginCmd: "opencode auth login",
+    notes:
+      "Sign in from your terminal with `opencode auth login` (an interactive picker), then check the connection here. Activates after the next image rebuild.",
+  },
+};
+
+/** Display order (matches the cloud picker's ordering intent). */
+const ORDER: EngineKind[] = [
+  "claude",
+  "codex",
+  "kimi",
+  "grok",
+  "cursor",
+  "opencode",
+];
+
+// ---------------------------------------------------------------------------
+// Injectable seams.
+// ---------------------------------------------------------------------------
+
+/** How a login/token command is spawned. Tests provide a fake. */
+export type EngineSpawn = (
+  command: string,
+  args: string[],
+  env: NodeJS.ProcessEnv,
+) => ChildProcess;
+
+export interface EngineSeams {
+  /** Spawn a CLI, piping stdin/stdout/stderr. */
+  spawn: EngineSpawn;
+  /** Absolute path to the `.env.local` the running host reads (UAI_HOME). */
+  envLocalPath: () => string;
+  /** The owner's real home — where codex/kimi/grok write their config dirs. */
+  ownerHome: () => string;
+  /** The live process env (adapters + task-up read creds from here). */
+  procEnv: NodeJS.ProcessEnv;
+  /** PATH as the owner's login shell sees it (null when unprobeable). */
+  loginShellPath: () => Promise<string | null>;
+  /** System-wide bin dirs probed for engine CLIs (tests pin to []). */
+  systemBinDirs: string[];
+  /**
+   * Wrap a CLI invocation so the child gets a real PTY (script(1)), or null
+   * to spawn directly. Tests pin null; token-command needs the wrap (see
+   * defaultPtyWrap for why).
+   */
+  ptyWrap: ((bin: string, args: string[]) => PtyCommand | null) | null;
+}
+
+/** A wrapped invocation: what to actually spawn to run a CLI under a PTY. */
+export interface PtyCommand {
+  command: string;
+  args: string[];
+}
+
+function defaultSeams(): EngineSeams {
+  return {
+    spawn: (command, args, spawnEnv) =>
+      nodeSpawn(command, args, {
+        // macOS: stdin MUST be /dev/null ("ignore"), never a node pipe. Node's
+        // child pipes are SOCKETPAIRS, and Apple's BSD script(1) hard-exits on
+        // a socket stdin ("tcgetattr/ioctl: Operation not supported on
+        // socket") while tolerating /dev/null (ENOTTY → notty mode). The
+        // "Press Enter" auto-ack is therefore Linux-only; the real token flow
+        // needs no input before the token renders (verified empirically).
+        stdio: [
+          process.platform === "darwin" ? "ignore" : "pipe",
+          "pipe",
+          "pipe",
+        ],
+        env: spawnEnv,
+      }),
+    envLocalPath: () => join(env.uaiHome, ".env.local"),
+    ownerHome: () => process.env.UAI_OWNER_HOME?.trim() || homedir(),
+    procEnv: process.env,
+    loginShellPath: probeLoginShellPath,
+    systemBinDirs: ["/opt/homebrew/bin", "/usr/local/bin"],
+    ptyWrap: defaultPtyWrap,
+  };
+}
+
+/**
+ * Lend a CLI a real PTY via script(1) — no native deps, ships with macOS
+ * (BSD) and Linux (util-linux; argument conventions differ, hence the
+ * branch). Ink-based CLIs (claude) render nothing under plain pipes: Ink
+ * detects a non-TTY stdout and buffers every frame until unmount, and the
+ * interactive screens can't complete without a terminal — so the child sat
+ * silent forever. The inner `stty cols 400` matters too: at the default 80
+ * columns the token line WRAPS and a wrapped token extracts truncated.
+ */
+function defaultPtyWrap(bin: string, args: string[]): PtyCommand | null {
+  if (!existsSync("/usr/bin/script")) return null;
+  const stty = "stty cols 400 rows 100 2>/dev/null";
+  if (process.platform === "darwin") {
+    // BSD script: `script -q /dev/null command [args…]` — command is exec'd
+    // as an argv (no shell), so route through sh only to set the width.
+    return {
+      command: "/usr/bin/script",
+      args: ["-q", "/dev/null", "/bin/sh", "-c", `${stty}; exec "$0" "$@"`, bin, ...args],
+    };
+  }
+  if (process.platform === "linux") {
+    // util-linux script: the command is a single shell string (-c).
+    const quoted = [bin, ...args]
+      .map((a) => `'${a.replace(/'/g, `'\\''`)}'`)
+      .join(" ");
+    return {
+      command: "/usr/bin/script",
+      args: ["-qec", `${stty}; exec ${quoted}`, "/dev/null"],
+    };
+  }
+  return null;
+}
+
+/**
+ * The PATH the owner's shell exports. Probes an INTERACTIVE login shell
+ * first: nvm/asdf/fnm put their PATH setup in `.zshrc`/`.bashrc`, which a
+ * plain login shell (`-lc`) never sources — that gap hid `npm i -g` installs
+ * from the probe. Falls back to `-lc` for profiles that misbehave when run
+ * interactively without a terminal. Null on failure of both; callers fall
+ * back to the inherited PATH.
+ *
+ * Cached (module-level, 5 min): the CLI-found statuses probe on every
+ * /api/engines poll and shelling out each time would be rude. Staleness is
+ * harmless — every installer this module runs lands in a candidate dir,
+ * which is checked before the probe.
+ */
+export async function probeLoginShellPath(
+  budgetMs: number = LOGIN_PATH_PROBE_BUDGET_MS,
+  seams: Partial<LoginShellProbeSeams> = {},
+): Promise<string | null> {
+  const { runShell, now: clock } = { ...defaultProbeSeams(), ...seams };
+  const now = clock();
+  if (loginPathCache && now - loginPathCache.at < LOGIN_PATH_CACHE_MS) {
+    return loginPathCache.value;
+  }
+  // ONE deadline for the pair. A per-spawn timeout bounds each attempt but not
+  // the request: two 8s attempts is a 16s stall on a live /api/engines poll.
+  //
+  // The pair shares the budget, but `-lic` may not SPEND it all: the reserve
+  // below keeps the `-lc` retry reachable. Sharing one deadline outright would
+  // starve the fallback in exactly the case it exists for — see the reserve.
+  const deadline = now + budgetMs;
+  const value =
+    (await runBounded(
+      runShell,
+      clock,
+      "-lic",
+      deadline - fallbackReserve(budgetMs),
+    )) ?? (await runBounded(runShell, clock, "-lc", deadline));
+  loginPathCache = { value, at: now };
+  return value;
+}
+
+/**
+ * Convert the remaining slice of the shared budget into one attempt's timeout,
+ * skipping the spawn entirely when a previous attempt already consumed it.
+ */
+async function runBounded(
+  runShell: LoginShellProbeSeams["runShell"],
+  clock: LoginShellProbeSeams["now"],
+  flags: string,
+  deadline: number,
+): Promise<string | null> {
+  const remaining = deadline - clock();
+  if (remaining <= 0) return null;
+  return runShell(flags, remaining);
+}
+
+/** Drop the memoized login PATH. Exported for tests (module-level cache). */
+export function resetLoginShellPathCache(): void {
+  loginPathCache = null;
+}
+
+let loginPathCache: { value: string | null; at: number } | null = null;
+const LOGIN_PATH_CACHE_MS = 5 * 60_000;
+/**
+ * Total wall-clock budget for the login-shell PATH probe, across BOTH
+ * attempts. `/api/engines` awaits this on a cold cache, so the bound has to
+ * be on the pair — see probeLoginShellPath.
+ */
+const LOGIN_PATH_PROBE_BUDGET_MS = 8_000;
+/**
+ * Slice of the budget held back so the `-lc` retry can always run.
+ *
+ * The interactive attempt is the one that stalls — it sources `.zshrc`, which
+ * is what makes it slow — and that is precisely when the non-interactive
+ * fallback is worth trying, because `-lc` skips that file. Letting `-lic`
+ * spend the whole budget therefore starves the fallback in the one case it
+ * exists for, and the probe resolves null: NOT "no login PATH" but "we gave
+ * up", cached as the former for LOGIN_PATH_CACHE_MS. `/api/engines` then
+ * reports every CLI absent for five minutes on a box where they are installed.
+ *
+ * Bounding the pair and keeping the fallback are not in tension: the total is
+ * still `budgetMs`, it is just no longer spendable entirely by the attempt
+ * most likely to hang.
+ */
+const LOGIN_PATH_FALLBACK_RESERVE_MS = 3_000;
+
+/**
+ * Never larger than half the budget, so a caller-shrunk budget (tests) still
+ * gives both attempts a real slice instead of collapsing one to zero.
+ */
+function fallbackReserve(budgetMs: number): number {
+  return Math.min(LOGIN_PATH_FALLBACK_RESERVE_MS, Math.floor(budgetMs / 2));
+}
+
+/**
+ * The probe's two side effects, injectable like every other seam in this file.
+ *
+ * Budget arithmetic is the whole point of this code and it is a function of
+ * elapsed time, so a test that races real `sleep`s against a real clock is
+ * measuring the runner's load, not the logic — it fails on a busy self-hosted
+ * runner exactly like the stall it was written to prevent. Pin both and the
+ * assertions become the timeouts handed to each attempt.
+ */
+export interface LoginShellProbeSeams {
+  /** Run `$SHELL <flags> /usr/bin/env`, bounded by `timeoutMs`. */
+  runShell: (flags: string, timeoutMs: number) => Promise<string | null>;
+  now: () => number;
+}
+
+function defaultProbeSeams(): LoginShellProbeSeams {
+  return { runShell: shellPath, now: Date.now };
+}
+
+/**
+ * Run `$SHELL <flags> /usr/bin/env` and pull PATH out. `/usr/bin/env` (not
+ * `echo $PATH`) so the value is the real colon-joined exported PATH under any
+ * shell — fish's `$PATH` is a list and would echo space-joined — and the
+ * LAST `PATH=` line wins so profile echo noise can't spoof it.
+ */
+function shellPath(flags: string, timeoutMs: number): Promise<string | null> {
+  return new Promise((resolve) => {
+    const shell = process.env.SHELL?.trim() || "/bin/zsh";
+    nodeExecFile(
+      shell,
+      [flags, "/usr/bin/env"],
+      { timeout: timeoutMs },
+      (err, stdout) => {
+        if (err) return resolve(null);
+        const lines = String(stdout)
+          .split(/\r?\n/)
+          .filter((l) => l.startsWith("PATH="));
+        const last = lines[lines.length - 1];
+        resolve(last ? last.slice("PATH=".length).trim() || null : null);
+      },
+    );
+  });
+}
+
+function withDefaults(seams: Partial<EngineSeams>): EngineSeams {
+  return { ...defaultSeams(), ...seams };
+}
+
+// ---------------------------------------------------------------------------
+// Public catalog / status.
+// ---------------------------------------------------------------------------
+
+/** The static engine catalog (kind, label, authMode, notes, key URLs). */
+export function engineCatalog(): EngineCatalogEntry[] {
+  return ORDER.map((kind) => {
+    const d = DESCRIPTORS[kind];
+    return {
+      kind,
+      label: d.label,
+      authMode: d.authMode,
+      notes: d.notes,
+      getKeyUrl: d.getKeyUrl ?? null,
+      apiKeyHint: d.apiKeyHint ?? null,
+      apiKeyUrl: d.apiKeyUrl ?? null,
+      installHint:
+        kind === "codex" ? CODEX_INSTALL_HINT : (INSTALLERS[kind] ?? null),
+      loginCmd: d.loginCmd ?? null,
+    };
+  });
+}
+
+/** kind → whether the engine's CLI is resolvable on this host right now. */
+export async function engineCliStatuses(
+  seams: Partial<EngineSeams> = {},
+): Promise<Record<EngineKind, boolean>> {
+  const s = withDefaults(seams);
+  // Resolve the login PATH at most ONCE per call. Every kind that isn't in a
+  // candidate dir falls through to the probe, so six kinds would otherwise
+  // await it six times — bounding each probe wouldn't bound the request. The
+  // default seam memoizes for 5 min, but the per-request bound must not
+  // depend on that cache being warm.
+  let loginOnce: Promise<string | null> | null = null;
+  const scoped: EngineSeams = {
+    ...s,
+    loginShellPath: () => (loginOnce ??= s.loginShellPath()),
+  };
+  const out = {} as Record<EngineKind, boolean>;
+  for (const kind of ORDER) out[kind] = await engineCliFound(kind, scoped);
+  return out;
+}
+
+/** kind → connected, for every engine. */
+export function engineStatuses(
+  seams: Partial<EngineSeams> = {},
+): Record<EngineKind, boolean> {
+  const s = withDefaults(seams);
+  return {
+    claude: detect("claude", s),
+    codex: detect("codex", s),
+    kimi: detect("kimi", s),
+    grok: detect("grok", s),
+    cursor: detect("cursor", s),
+    opencode: detect("opencode", s),
+  };
+}
+
+/** Whether a single engine is connected on this host right now. */
+export function detectEngine(
+  kind: EngineKind,
+  seams: Partial<EngineSeams> = {},
+): boolean {
+  return detect(kind, withDefaults(seams));
+}
+
+export function isEngineKind(value: unknown): value is EngineKind {
+  return (
+    value === "claude" ||
+    value === "codex" ||
+    value === "kimi" ||
+    value === "grok" ||
+    value === "cursor" ||
+    value === "opencode"
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Connect / disconnect.
+// ---------------------------------------------------------------------------
+
+export interface ConnectOptions {
+  /** A pasted API key — primary for Cursor, alternative for claude/codex/grok. */
+  apiKey?: string;
+  /** token-command manual fallback: a pasted token or API key (Claude). */
+  pastedToken?: string;
+  /**
+   * ADR-076: when set, a token captured by the token-command flow (or pasted)
+   * is handed to this sink INSTEAD of being persisted as the default credential
+   * — used to register an EXTRA account. The sink's result becomes the connect
+   * result.
+   */
+  onToken?: (token: string) => ConnectResult | Promise<ConnectResult>;
+}
+
+export interface ConnectResult {
+  ok: boolean;
+  message: string;
+}
+
+/**
+ * Connect an engine. api-key/paste resolve synchronously; login/token spawn a
+ * CLI and stream its output to `onLog` (the browser OAuth happens meanwhile).
+ */
+export async function connectEngine(
+  kind: EngineKind,
+  opts: ConnectOptions,
+  onLog: (line: string) => void,
+  seams: Partial<EngineSeams> = {},
+): Promise<ConnectResult> {
+  const s = withDefaults(seams);
+  const d = DESCRIPTORS[kind];
+
+  // A pasted API key connects without spawning anything — the only flow for
+  // api-key engines (Cursor), an alternative for the others.
+  if (d.authMode === "api-key" || opts.apiKey !== undefined) {
+    return saveApiKey(kind, d, opts.apiKey ?? "", s);
+  }
+
+  // external-login (OpenCode): the owner ran the engine's own interactive CLI
+  // in their terminal — we never spawn it. "Connect" just re-detects the
+  // credential that login wrote.
+  if (d.authMode === "external-login") {
+    return detect(kind, s)
+      ? { ok: true, message: `${d.label} connected.` }
+      : {
+          ok: false,
+          message: d.loginCmd
+            ? `Not signed in yet. Run \`${d.loginCmd}\` in your terminal, then check again.`
+            : `${d.label} isn't signed in yet.`,
+        };
+  }
+
+  if (d.authMode === "token-command") {
+    // Manual paste fallback — accept a token (or API key) without spawning.
+    if (opts.pastedToken !== undefined) {
+      const token = opts.pastedToken.trim();
+      if (!token) return { ok: false, message: "Paste a token." };
+      if (/\s/.test(token) || token.length < 20) {
+        return {
+          ok: false,
+          message: "That doesn't look like a token. Paste just the value.",
+        };
+      }
+      // Adding an extra account? Route the pasted value to the sink instead of
+      // the default credential.
+      if (opts.onToken) return await opts.onToken(token);
+      // One paste box serves both credential kinds — classify by prefix so an
+      // `sk-ant-api…` platform key doesn't get stored as an OAuth token.
+      upsertEnvLocal(
+        token.startsWith("sk-ant-api")
+          ? "ANTHROPIC_API_KEY"
+          : "CLAUDE_CODE_OAUTH_TOKEN",
+        token,
+        s,
+      );
+      return { ok: true, message: `${d.label} connected.` };
+    }
+    return runTokenCommand(kind, d.label, onLog, s, opts.onToken);
+  }
+
+  return runLoginCommand(kind, d.label, onLog, s);
+}
+
+/** Persist a pasted API key where the engine's adapter actually reads it. */
+function saveApiKey(
+  kind: EngineKind,
+  d: EngineDescriptor,
+  raw: string,
+  s: EngineSeams,
+): ConnectResult {
+  const key = raw.trim();
+  if (!key) return { ok: false, message: `Paste your ${d.label} API key.` };
+  if (/\s/.test(key) || key.length < 8) {
+    return {
+      ok: false,
+      message: "That doesn't look like an API key. Paste just the value.",
+    };
+  }
+  switch (kind) {
+    case "cursor":
+      upsertEnvLocal("CURSOR_API_KEY", key, s);
+      break;
+    case "claude":
+      // Accept either credential kind here too (see the paste fallback above).
+      upsertEnvLocal(
+        key.startsWith("sk-ant-oat") ? "CLAUDE_CODE_OAUTH_TOKEN" : "ANTHROPIC_API_KEY",
+        key,
+        s,
+      );
+      break;
+    case "grok":
+      // The grok CLI's documented pay-as-you-go fallback; the adapter forwards
+      // it into task containers.
+      upsertEnvLocal("XAI_API_KEY", key, s);
+      break;
+    case "codex":
+      writeCodexAuthJson(key, s);
+      break;
+    case "kimi":
+      return {
+        ok: false,
+        message:
+          "Kimi Code authenticates via subscription sign-in — it doesn't read API keys from the environment.",
+      };
+  }
+  return { ok: true, message: `${d.label} connected.` };
+}
+
+/**
+ * Write `~/.codex/auth.json` the way `codex login --with-api-key` does. We
+ * write the plaintext file directly (not via the CLI) because task-up
+ * docker-cp's this exact FILE into containers — a keychain-backed CLI login
+ * would leave nothing to copy — and it must work without a host codex CLI.
+ */
+function writeCodexAuthJson(key: string, s: EngineSeams): void {
+  const file = join(s.ownerHome(), ".codex", "auth.json");
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ OPENAI_API_KEY: key }, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    /* best effort */
+  }
+}
+
+/** Disconnect an engine: forget its credential (env line and/or config file). */
+export function disconnectEngine(
+  kind: EngineKind,
+  seams: Partial<EngineSeams> = {},
+): void {
+  const s = withDefaults(seams);
+  if (kind === "cursor") {
+    removeEnvLocal("CURSOR_API_KEY", s);
+    return;
+  }
+  if (kind === "claude") {
+    removeEnvLocal("CLAUDE_CODE_OAUTH_TOKEN", s);
+    removeEnvLocal("ANTHROPIC_API_KEY", s);
+    removeEnvLocal("ANTHROPIC_AUTH_TOKEN", s);
+    return;
+  }
+  // grok can be connected via login (auth.json) OR a pasted key — drop both.
+  if (kind === "grok") removeEnvLocal("XAI_API_KEY", s);
+  // login-command engines: remove the config file the adapter detects.
+  try {
+    rmSync(configPath(kind, s), { force: true });
+  } catch {
+    /* best effort */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Install a missing engine CLI (ADR-074).
+// ---------------------------------------------------------------------------
+
+/**
+ * Pinned installer one-liners — the same vendor installers the standard task
+ * image already trusts (host-agent/images/standard/Dockerfile), shown
+ * VERBATIM in the UI before running. Every one lands its binary in a
+ * candidateBins dir, so the next resolve finds it with no restart:
+ * claude → ~/.local/bin, kimi → ~/.kimi-code/bin, grok → ~/.grok/bin.
+ * Codex has no vendor script — resolved at run time (brew, then npm).
+ */
+const INSTALLERS: Partial<Record<EngineKind, string>> = {
+  claude: "curl -fsSL https://claude.ai/install.sh | bash",
+  kimi: "curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash",
+  grok: "curl -fsSL https://x.ai/cli/install.sh | bash",
+  opencode: "curl -fsSL https://opencode.ai/install | bash",
+};
+
+const CODEX_INSTALL_HINT = "brew install codex — or: npm i -g @openai/codex";
+
+/** Installers can compile/download; give them real time. */
+const INSTALL_TIMEOUT_MS = 15 * 60_000;
+
+export interface InstallResult {
+  ok: boolean;
+  message: string;
+}
+
+/**
+ * Install an engine's CLI with its pinned installer, streaming output to
+ * `onLog`. Refuses when there's nothing to install (api-key engines) and
+ * short-circuits when the CLI is already resolvable. Success = the installer
+ * exits 0 AND the CLI resolves afterwards.
+ */
+export async function installEngineCli(
+  kind: EngineKind,
+  onLog: (line: string) => void,
+  seams: Partial<EngineSeams> = {},
+): Promise<InstallResult> {
+  const s = withDefaults(seams);
+  const d = DESCRIPTORS[kind];
+  if (d.authMode === "api-key") {
+    return {
+      ok: false,
+      message: `${d.label} doesn't use a CLI on the host — paste an API key instead.`,
+    };
+  }
+  if (await engineCliFound(kind, s)) {
+    return { ok: true, message: `${d.label} CLI is already installed.` };
+  }
+  const inv = await resolveInstaller(kind, s);
+  if (!inv) {
+    return {
+      ok: false,
+      message:
+        "No way to install Codex automatically: install Homebrew or Node.js first, then `brew install codex` or `npm i -g @openai/codex`.",
+    };
+  }
+  let child: ChildProcess;
+  try {
+    child = s.spawn(inv.command, inv.args, {
+      ...s.procEnv,
+      ...(inv.path ? { PATH: inv.path } : {}),
+    });
+  } catch (err) {
+    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer: NodeJS.Timeout | undefined;
+    const done = (r: InstallResult, kill = false): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (kill) {
+        try {
+          child.kill();
+        } catch {
+          /* already gone */
+        }
+      }
+      resolve(r);
+    };
+    const relay = createLineRelay(onLog);
+    child.stdout?.on("data", relay);
+    child.stderr?.on("data", relay);
+    child.on("error", (err: NodeJS.ErrnoException) =>
+      done({ ok: false, message: err.message }),
+    );
+    child.on("exit", (code) => {
+      void (async () => {
+        if (code !== 0) {
+          done({
+            ok: false,
+            message: `Install failed (exit ${code ?? "?"}) — see the log above.`,
+          });
+          return;
+        }
+        done(
+          (await engineCliFound(kind, s))
+            ? { ok: true, message: `${d.label} CLI installed.` }
+            : {
+                ok: false,
+                message:
+                  "The installer finished but the CLI still isn't findable — install it manually, then try Connect.",
+              },
+        );
+      })();
+    });
+    timer = setTimeout(
+      () =>
+        done(
+          { ok: false, message: "The installer timed out — see the log above." },
+          true,
+        ),
+      INSTALL_TIMEOUT_MS,
+    );
+  });
+}
+
+interface InstallInvocation {
+  command: string;
+  args: string[];
+  /** Child PATH override (npm needs its own dir leading so node resolves). */
+  path?: string;
+}
+
+/** Vendor script via sh for most engines; brew-then-npm for Codex. */
+async function resolveInstaller(
+  kind: EngineKind,
+  s: EngineSeams,
+): Promise<InstallInvocation | null> {
+  if (kind !== "codex") {
+    const script = INSTALLERS[kind];
+    return script ? { command: "/bin/sh", args: ["-c", script] } : null;
+  }
+  const brew = s.systemBinDirs.map((dir) => join(dir, "brew")).find(existsSync);
+  if (brew) return { command: brew, args: ["install", "codex"] };
+  const npm = await findBinNamed("npm", s);
+  if (npm) {
+    return {
+      command: npm,
+      args: ["install", "-g", "@openai/codex"],
+      path: prependPath([dirname(npm)], s.procEnv.PATH ?? ""),
+    };
+  }
+  return null;
+}
+
+/** Find an arbitrary tool the same way engine CLIs are found. */
+async function findBinNamed(
+  name: string,
+  s: EngineSeams,
+): Promise<string | null> {
+  const home = s.ownerHome();
+  const dirs = [
+    join(home, ".local", "bin"),
+    ...nodeManagerBinDirs(home),
+    ...s.systemBinDirs,
+  ];
+  for (const dir of dirs) {
+    const file = join(dir, name);
+    if (existsSync(file)) return file;
+  }
+  const login = await s.loginShellPath();
+  const dir = login?.split(":").find((p) => p && existsSync(join(p, name)));
+  return dir ? join(dir, name) : null;
+}
+
+/** Whether an engine's CLI resolves right now (candidates, then login PATH). */
+async function engineCliFound(
+  kind: EngineKind,
+  s: EngineSeams,
+): Promise<boolean> {
+  if (DESCRIPTORS[kind].authMode === "api-key") return true; // never spawned
+  if (candidateBins(kind, s).some(existsSync)) return true;
+  const login = await s.loginShellPath();
+  return !!login
+    ?.split(":")
+    .some((dir) => dir.length > 0 && existsSync(join(dir, kind)));
+}
+
+/**
+ * Accumulate a child's output and forward each distinct, meaningful,
+ * COMPLETE line to `onLog` once — same discipline as the token flow's
+ * relay, for plain (non-PTY) installer output with \r progress noise.
+ */
+function createLineRelay(onLog: (line: string) => void): (b: Buffer) => void {
+  let raw = "";
+  const forwarded = new Set<string>();
+  return (b) => {
+    raw += b.toString("utf8");
+    if (raw.length > 262_144) raw = raw.slice(-131_072);
+    const text = sanitizeTerminalOutput(raw);
+    for (const line of significantLines(text.slice(0, text.lastIndexOf("\n") + 1))) {
+      if (!forwarded.has(line)) {
+        forwarded.add(line);
+        onLog(line);
+      }
+    }
+  };
+}
+
+/**
+ * Flatten a PTY byte stream into plain text lines. Strips OSC sequences
+ * (incl. OSC-8 hyperlink wrappers, keeping their visible text), CSI
+ * sequences (cursor-column moves become a space — Ink positions words with
+ * `ESC[<n>G` instead of writing spaces), stray ESC singles, and normalizes
+ * `\r` to `\n`. Identity on already-plain text apart from whitespace runs.
+ */
+export function sanitizeTerminalOutput(raw: string): string {
+  return raw
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, "") // OSC …BEL / …ST
+    .replace(/\x1b\[[0-9;:?<=>]*[!-/]*[@-~]/g, " ") // CSI
+    .replace(/\x1b[()][0-9A-B]/g, "") // charset selects
+    .replace(/\x1b[78=>DEHM]/g, "") // save/restore cursor etc.
+    .replace(/\r\n?/g, "\n")
+    .replace(/[^\S\n]+/g, " ");
+}
+
+/** Lines worth showing a human: non-blank, not spinner or logo-art glyphs. */
+function significantLines(text: string): string[] {
+  return text
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 1 && !/^[·✢✳✶✻✽*+.…|/\\\-░▒▓█▄▀\s]+$/u.test(l));
+}
+
+/**
+ * Extract a Claude OAuth token from `claude setup-token` output. The CLI shows
+ * the token (an `sk-ant-oat…` value) on its own line near the end; scan from the
+ * bottom for it, falling back to a lone long token-charset line.
+ */
+export function extractClaudeToken(stdout: string): string | null {
+  const lines = stdout
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const m = /(sk-ant-[A-Za-z0-9_-]{16,})/.exec(lines[i] ?? "");
+    if (m?.[1]) return m[1];
+  }
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i] ?? "";
+    if (/^[A-Za-z0-9_-]{40,}$/.test(line)) return line;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Internals.
+// ---------------------------------------------------------------------------
+
+function detect(kind: EngineKind, s: EngineSeams): boolean {
+  switch (kind) {
+    case "claude":
+      return (
+        envOrFileHas("CLAUDE_CODE_OAUTH_TOKEN", s) ||
+        envOrFileHas("ANTHROPIC_API_KEY", s) ||
+        envOrFileHas("ANTHROPIC_AUTH_TOKEN", s)
+      );
+    case "cursor":
+      return envOrFileHas("CURSOR_API_KEY", s);
+    case "grok":
+      return existsSync(configPath(kind, s)) || envOrFileHas("XAI_API_KEY", s);
+    case "codex":
+    case "kimi":
+    case "opencode":
+      return existsSync(configPath(kind, s));
+  }
+}
+
+/** True when `key` is set in process.env or present in `.env.local`. */
+function envOrFileHas(key: string, s: EngineSeams): boolean {
+  if (s.procEnv[key]) return true;
+  try {
+    const body = readFileSync(s.envLocalPath(), "utf8");
+    return new RegExp(`^${key}=.+`, "m").test(body);
+  } catch {
+    return false;
+  }
+}
+
+/** Config file whose presence gates a login-command engine. */
+function configPath(kind: EngineKind, s: EngineSeams): string {
+  const home = s.ownerHome();
+  if (kind === "codex") return join(home, ".codex", "auth.json");
+  if (kind === "kimi") {
+    return join(home, ".kimi-code", "credentials", "kimi-code.json");
+  }
+  if (kind === "opencode") {
+    return join(home, ".local", "share", "opencode", "auth.json");
+  }
+  return join(home, ".grok", "auth.json");
+}
+
+/**
+ * Well-known install locations for an engine CLI — the dirs a GUI-launched
+ * host's minimal PATH misses. Home-relative entries resolve against the OWNER
+ * home (seam-injectable). The binary name equals the engine kind for all four
+ * CLI engines.
+ */
+function candidateBins(kind: EngineKind, s: EngineSeams): string[] {
+  const home = s.ownerHome();
+  const common = [
+    join(home, ".local", "bin"),
+    ...nodeManagerBinDirs(home),
+    ...s.systemBinDirs,
+  ];
+  switch (kind) {
+    case "claude":
+      // Native installer symlinks ~/.local/bin/claude (preferred); the older
+      // "local install" migration keeps a wrapper at ~/.claude/local/claude.
+      return [
+        join(home, ".local", "bin"),
+        join(home, ".claude", "local"),
+        ...nodeManagerBinDirs(home),
+        ...s.systemBinDirs,
+      ].map((d) => join(d, "claude"));
+    case "codex":
+      return common.map((d) => join(d, "codex"));
+    case "kimi":
+      return [join(home, ".kimi-code", "bin"), ...common].map((d) =>
+        join(d, "kimi"),
+      );
+    case "grok":
+      return [join(home, ".grok", "bin"), ...common].map((d) => join(d, "grok"));
+    case "opencode":
+      // opencode.ai/install lands the binary in ~/.opencode/bin.
+      return [join(home, ".opencode", "bin"), ...common].map((d) =>
+        join(d, "opencode"),
+      );
+    case "cursor":
+      return []; // api-key mode — never spawned
+  }
+}
+
+/**
+ * Bin dirs of the common node version managers — `npm i -g` lands CLIs here,
+ * and none of these are on a GUI PATH or even in a NON-interactive login
+ * shell's PATH (their init lives in .zshrc/.bashrc), which is exactly how an
+ * installed `codex` still read "not found". Deterministic dirs beat shell
+ * probing: no subprocess, no profile side effects.
+ */
+function nodeManagerBinDirs(home: string): string[] {
+  const dirs = [
+    join(home, ".asdf", "shims"), // shims exec asdf by absolute path
+    join(home, ".volta", "bin"),
+    join(home, ".bun", "bin"),
+    join(home, ".npm-global", "bin"),
+    // fnm's stable default-alias bin — the per-shell multishell paths its
+    // shell init exports are ephemeral. macOS, XDG, and legacy layouts.
+    join(home, "Library", "Application Support", "fnm", "aliases", "default", "bin"),
+    join(home, ".local", "share", "fnm", "aliases", "default", "bin"),
+    join(home, ".fnm", "aliases", "default", "bin"),
+  ];
+  // nvm has no stable "current" symlink — enumerate installed versions,
+  // newest first (numeric compare: lexicographic would put v9 over v22).
+  // A version dir's bin also holds its `node`, so the shebang of whatever
+  // we find there resolves against the same dir once it leads PATH.
+  try {
+    const versions = join(home, ".nvm", "versions", "node");
+    dirs.push(
+      ...readdirSync(versions)
+        .sort(compareVersionDesc)
+        .map((v) => join(versions, v, "bin")),
+    );
+  } catch {
+    /* no nvm */
+  }
+  return dirs;
+}
+
+function compareVersionDesc(a: string, b: string): number {
+  const parts = (s: string): number[] =>
+    s.replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
+  const [a1 = 0, a2 = 0, a3 = 0] = parts(a);
+  const [b1 = 0, b2 = 0, b3 = 0] = parts(b);
+  return b1 - a1 || b2 - a2 || b3 - a3;
+}
+
+interface ResolvedBin {
+  /** Command to spawn — absolute when found, else the bare name. */
+  bin: string;
+  /** PATH for the child, augmented so nested lookups (node, git) resolve. */
+  path: string;
+}
+
+/**
+ * Find the engine CLI the way the owner's terminal would: well-known install
+ * dirs first (fast, no subprocess), then the login shell's PATH (sources the
+ * owner's profile — covers nvm/asdf/npm prefixes), else the bare name against
+ * the inherited PATH so a genuinely missing CLI still surfaces the friendly
+ * ENOENT "install it first" message.
+ */
+async function resolveEngineBin(
+  kind: EngineKind,
+  s: EngineSeams,
+): Promise<ResolvedBin> {
+  const inherited = s.procEnv.PATH ?? "";
+  for (const file of candidateBins(kind, s)) {
+    if (existsSync(file)) {
+      return { bin: file, path: prependPath([dirname(file)], inherited) };
+    }
+  }
+  const login = await s.loginShellPath();
+  if (login) {
+    const dirs = login.split(":").filter(Boolean);
+    const dir = dirs.find((d) => existsSync(join(d, kind)));
+    // Found or not, hand the login PATH to the child — it is the environment
+    // where the CLI (and whatever it shells out to) is known to work.
+    return {
+      bin: dir ? join(dir, kind) : kind,
+      path: prependPath(dirs, inherited),
+    };
+  }
+  return { bin: kind, path: inherited };
+}
+
+/** Prepend dirs to a colon-joined PATH, deduped, order-preserving. */
+function prependPath(prepend: string[], current: string): string {
+  const seen = new Set<string>();
+  return [...prepend, ...current.split(":")]
+    .filter((p) => p.length > 0 && !seen.has(p) && (seen.add(p), true))
+    .join(":");
+}
+
+/** Resolve the CLI and spawn it (optionally under a PTY) with the augmented PATH. */
+async function spawnEngineCli(
+  kind: EngineKind,
+  args: string[],
+  s: EngineSeams,
+  pty = false,
+): Promise<ChildProcess> {
+  const { bin, path } = await resolveEngineBin(kind, s);
+  const wrapped = pty && s.ptyWrap ? s.ptyWrap(bin, args) : null;
+  const spawnEnv: NodeJS.ProcessEnv = { ...s.procEnv, PATH: path };
+  // A GUI-supervised host has no TERM; give the PTY child a sane one.
+  if (wrapped && !spawnEnv.TERM) spawnEnv.TERM = "xterm-256color";
+  return wrapped
+    ? s.spawn(wrapped.command, wrapped.args, spawnEnv)
+    : s.spawn(bin, args, spawnEnv);
+}
+
+/** Browser authorization is human-paced — give it real time before bailing. */
+const TOKEN_FLOW_TIMEOUT_MS = 10 * 60_000;
+
+const TOKEN_FLOW_FALLBACK =
+  "Try again, or run `claude setup-token` in your terminal and paste the token here.";
+
+async function runTokenCommand(
+  kind: EngineKind,
+  label: string,
+  onLog: (line: string) => void,
+  s: EngineSeams,
+  onToken?: (token: string) => ConnectResult | Promise<ConnectResult>,
+): Promise<ConnectResult> {
+  let child: ChildProcess;
+  try {
+    child = await spawnEngineCli(kind, ["setup-token"], s, true);
+  } catch (err) {
+    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer: NodeJS.Timeout | undefined;
+    const done = (r: ConnectResult, kill = false): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (kill) {
+        try {
+          child.kill();
+        } catch {
+          /* already gone */
+        }
+      }
+      resolve(r);
+    };
+    let raw = "";
+    let capturing = false;
+    const forwarded = new Set<string>();
+    const acked = new Set<string>();
+    const saveToken = (token: string): void => {
+      // The token renders on several redraws (and again on exit) — capture once.
+      if (capturing) return;
+      capturing = true;
+      // ADR-076: adding an EXTRA account routes the captured token to the sink
+      // (which stores it as a separate account) instead of the default env.
+      if (onToken) {
+        Promise.resolve(onToken(token))
+          .then((r) => done(r, true))
+          .catch((err) =>
+            done(
+              { ok: false, message: err instanceof Error ? err.message : String(err) },
+              true,
+            ),
+          );
+        return;
+      }
+      upsertEnvLocal("CLAUDE_CODE_OAUTH_TOKEN", token, s);
+      done({ ok: true, message: `${label} connected.` }, true);
+    };
+    const onChunk = (b: Buffer): void => {
+      raw += b.toString("utf8");
+      // A pending spinner redraws for minutes — keep only the tail (the token
+      // and final screens are at the end) so re-sanitizing stays cheap.
+      if (raw.length > 262_144) raw = raw.slice(-131_072);
+      const text = sanitizeTerminalOutput(raw);
+      // Act only on COMPLETE lines: a trailing partial may still be missing
+      // the rest of an escape sequence — or the rest of the TOKEN, and the
+      // extractor would happily return a truncated prefix.
+      const complete = text.slice(0, text.lastIndexOf("\n") + 1);
+      for (const line of significantLines(complete)) {
+        // Each distinct line once — Ink redraws the same screen constantly
+        // and would flood the UI log.
+        if (!forwarded.has(line)) {
+          forwarded.add(line);
+          onLog(line);
+        }
+        // Auto-acknowledge keypress gates (once per distinct screen text) —
+        // with a PTY the CLI accepts input, and nobody is at its keyboard.
+        if (/press enter/i.test(line) && !acked.has(line)) {
+          acked.add(line);
+          try {
+            child.stdin?.write("\r");
+          } catch {
+            /* best effort */
+          }
+        }
+      }
+      // The whole point: capture the token the moment it renders. The CLI's
+      // final screen lingers for a keypress; we don't wait for exit.
+      const token = extractClaudeToken(complete);
+      if (token) saveToken(token);
+    };
+    child.stdout?.on("data", onChunk);
+    child.stderr?.on("data", onChunk);
+    child.on("error", (err: NodeJS.ErrnoException) =>
+      done({
+        ok: false,
+        message:
+          err.code === "ENOENT"
+            ? `${label} CLI not found on PATH — install Claude Code first.`
+            : err.message,
+      }),
+    );
+    child.on("exit", () => {
+      const token = extractClaudeToken(sanitizeTerminalOutput(raw));
+      if (!token) {
+        done({
+          ok: false,
+          message: `The sign-in didn't finish. ${TOKEN_FLOW_FALLBACK}`,
+        });
+        return;
+      }
+      saveToken(token);
+    });
+    timer = setTimeout(
+      () =>
+        done(
+          {
+            ok: false,
+            message: `Timed out waiting for the browser authorization. ${TOKEN_FLOW_FALLBACK}`,
+          },
+          true,
+        ),
+      TOKEN_FLOW_TIMEOUT_MS,
+    );
+  });
+}
+
+async function runLoginCommand(
+  kind: EngineKind,
+  label: string,
+  onLog: (line: string) => void,
+  s: EngineSeams,
+): Promise<ConnectResult> {
+  let child: ChildProcess;
+  try {
+    child = await spawnEngineCli(kind, ["login"], s);
+  } catch (err) {
+    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (r: ConnectResult): void => {
+      if (!settled) {
+        settled = true;
+        resolve(r);
+      }
+    };
+    child.stdout?.on("data", (b: Buffer) => relay(b.toString("utf8"), onLog));
+    child.stderr?.on("data", (b: Buffer) => relay(b.toString("utf8"), onLog));
+    child.on("error", (err: NodeJS.ErrnoException) =>
+      done({
+        ok: false,
+        message:
+          err.code === "ENOENT"
+            ? `${label} CLI not found — install it first.`
+            : err.message,
+      }),
+    );
+    child.on("exit", () => {
+      done(
+        detect(kind, s)
+          ? { ok: true, message: `${label} connected.` }
+          : { ok: false, message: `${label} login didn't complete.` },
+      );
+    });
+  });
+}
+
+function relay(text: string, onLog: (line: string) => void): void {
+  for (const l of text.split(/\r?\n/)) {
+    if (l.trim()) onLog(l.trim());
+  }
+}
+
+/** Upsert KEY=value into the host's `.env.local` (0600) AND process.env. */
+function upsertEnvLocal(key: string, value: string, s: EngineSeams): void {
+  const file = s.envLocalPath();
+  mkdirSync(dirname(file), { recursive: true });
+  let body = "";
+  try {
+    body = readFileSync(file, "utf8");
+  } catch {
+    /* new file */
+  }
+  const line = `${key}=${value}`;
+  const re = new RegExp(`^${key}=.*$`, "m");
+  body = re.test(body)
+    ? body.replace(re, line)
+    : body + (body && !body.endsWith("\n") ? "\n" : "") + line + "\n";
+  writeFileSync(file, body, { mode: 0o600 });
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    /* best effort */
+  }
+  // Immediate effect: the running host reads creds from process.env (adapters'
+  // available() + task-up env injection), not by reloading .env.local — so set
+  // it here or a connect wouldn't take effect until a restart.
+  s.procEnv[key] = value;
+}
+
+/** Remove a KEY line from `.env.local` and process.env (no-op if absent). */
+function removeEnvLocal(key: string, s: EngineSeams): void {
+  const file = s.envLocalPath();
+  try {
+    const body = readFileSync(file, "utf8");
+    const next = body
+      .split(/\r?\n/)
+      .filter((l) => !new RegExp(`^${key}=`).test(l))
+      .join("\n");
+    writeFileSync(file, next, { mode: 0o600 });
+  } catch {
+    /* no file */
+  }
+  delete s.procEnv[key];
+}