nebula-notebook 0.2.0 → 0.2.1

package/node_modules/nebula-autocomplete/README.md

@@ -0,0 +1,145 @@
+# nebula-autocomplete
+
+LLM code autocomplete for notebook editors, backed by **Claude Code CLI** or
+**Codex CLI** subscription auth (no API key). Three entry points:
+
+| Import | What it is |
+|---|---|
+| `nebula-autocomplete` | `AutocompleteEngine` + `ClaudeBackend` / `CodexBackend` (Node) |
+| `nebula-autocomplete/server` | `registerAutocompleteRoute(fastify, engine)` — SSE endpoint |
+| `nebula-autocomplete/client` | `createCompletionFetcher(url)` — browser SSE client |
+| `nebula-autocomplete/codemirror` | `ghostText(fetcher)` — CodeMirror 6 inline ghost text |
+
+> **Licensing:** subscription auth is for personal use. Anthropic/OpenAI
+> consumer terms prohibit routing other users through your subscription or
+> offering subscription login in a distributed app. To ship this to others,
+> implement a `CompletionBackend` that calls the provider API with a key —
+> the rest of the stack is unchanged.
+
+## Measured latency (2026-07, M-series Mac)
+
+| Backend | Model | Warm TTFB | Notes |
+|---|---|---|---|
+| `ClaudeBackend` | haiku 4.5 | ~1.4–2.1s | token-streamed; warm process pool |
+| `CodexBackend` | gpt-5.6-luna, low effort | ~2.2–2.7s | buffered; one-shot exec |
+
+Cache hits return in 0ms. Claude's harness costs ~24k input tokens per
+completion, codex ~12.6k — that overhead is inherent to CLI backends and is
+why a raw-API backend (~0.6–1s) is the upgrade path for keystroke-grade UX.
+
+## Quick start (server side)
+
+```ts
+import { AutocompleteEngine, ClaudeBackend } from "nebula-autocomplete";
+import { registerAutocompleteRoute } from "nebula-autocomplete/server";
+
+const engine = new AutocompleteEngine({
+  backend: new ClaudeBackend(),          // or new CodexBackend({ codexHome })
+  cacheSize: 128,
+  contextBudget: 6000,                   // chars of cross-cell context
+});
+
+// inside your Fastify route registration (prefix "/api"):
+registerAutocompleteRoute(fastify, engine); // POST /api/autocomplete (SSE)
+
+process.on("exit", () => engine.dispose());
+```
+
+`CodexBackend` tip: create a clean `CODEX_HOME` containing only `auth.json`
+(`mkdir -p .codex-home && cp ~/.codex/auth.json .codex-home/`) and pass it as
+`codexHome` — it skips global MCP servers/plugins/hooks (~2s/request faster).
+`gpt-5.6-luna` is the fast model that works with ChatGPT-subscription auth;
+`*-codex-mini` variants are API-key-only.
+
+## Quick start (client side, CodeMirror 6)
+
+```ts
+import { createCompletionFetcher } from "nebula-autocomplete/client";
+import { ghostText } from "nebula-autocomplete/codemirror";
+
+const fetchCompletion = createCompletionFetcher("/api/autocomplete");
+
+const extension = ghostText(
+  ({ prefix, suffix }, { signal, onChunk }) =>
+    fetchCompletion(
+      {
+        prefix,
+        suffix,
+        language: "python",
+        cells: allCellsRef.current ?? [],       // cross-cell context
+        activeCellIndex,
+        sessionKey: cellId,                      // supersedes stale requests
+      },
+      { signal, onChunk },
+    ).then((r) => r.text),
+  { debounceMs: 400 },
+);
+// add `extension` to the editor's extensions array
+```
+
+Tab accepts the suggestion, Escape dismisses, any edit or cursor move
+invalidates it. Ghost text renders via a `.cm-ghost-text` span (style it in
+your theme if the default 0.45 opacity doesn't fit).
+
+## Integrating into nebula-notebook
+
+This package now lives inside the nebula-notebook repo at
+`packages/autocomplete` and is wired up already:
+
+1. **Dependency** (in-repo `file:` link; bundled into the published tarball via
+   `bundledDependencies`):
+   - root `package.json`: `"nebula-autocomplete": "file:packages/autocomplete"`
+   - `node-server/package.json`: `"nebula-autocomplete": "file:../packages/autocomplete"`
+   `dist/` is built automatically by this package's `prepare` script on
+   `npm install` (see `scripts/postinstall.cjs`).
+2. **Server**: in `node-server/src/index.ts` where routes are registered under
+   `/api` (~line 302), create one engine at startup and call
+   `registerAutocompleteRoute(app, engine)`. Dispose it on shutdown.
+3. **Client**: in `components/CodeEditor.tsx`, add the `ghostText(...)`
+   extension to the extensions `useMemo` (~line 725). The existing
+   kernel/static dropdown completion (`createCombinedCompletionSource`, line
+   533) stays as-is — ghost text is complementary, not a replacement. Cells
+   context is already available via the `allCellsRef` prop (line 51).
+4. **Dev proxy**: nothing to add — Vite already proxies `/api` to the node
+   server (`vite.config.ts:19`).
+
+## API sketch
+
+- `engine.complete(req, { signal, onChunk }) → Promise<CompletionResult>` —
+  builds the prompt (instruction + nearest-cells context within budget +
+  `<CURSOR>` marker), checks the LRU cache, and calls the backend. Requests
+  sharing a `sessionKey` supersede each other. Output is fence-stripped and
+  prefix-echo-trimmed.
+- `CompletionBackend` — implement `{ name, complete(prompt, {signal, onChunk}), dispose() }`
+  to add a backend (e.g. Anthropic API for production).
+
+## Trajectory hygiene
+
+Completions must not spam CLI history/trajectory stores. Verified behavior:
+
+- **claude**: print mode + stream-json + `--tools ""` was observed to persist
+  nothing on macOS (claude 2.1.201), but Claude Code **can** write
+  `~/.claude/projects/<munged-cwd>/*.jsonl` session transcripts on other
+  versions/platforms — so we don't rely on that. Each worker runs in its own
+  UUID cwd; the backend deletes the matching `~/.claude/projects/*` transcript
+  dir on worker recycle (per-worker, so it never touches an active worker) and
+  the whole set on `dispose()`. Matching is by UUID token via
+  `transcriptDirMatchesToken`, which is munge-algorithm-independent and cannot
+  collide with a real project. Respects `CLAUDE_CONFIG_DIR`. The throwaway
+  `workspaceDir` (also removed on dispose) is a second guard.
+- **codex**: `--ephemeral` (no session/rollout files),
+  `history.persistence="none"` (no prompt history), and
+  `features.plugins=false` (skips the curated-plugins sync, which otherwise
+  clones tens of MB into `CODEX_HOME/.tmp` on **every** exec). Verified: zero
+  files and stable directory size across repeated completions. Codex still
+  maintains a few small bounded sqlite files in `CODEX_HOME`.
+
+## Development
+
+```sh
+npm install
+npm run build     # tsc → dist/
+npm test          # vitest unit tests (no CLI calls)
+npm run smoke     # live end-to-end vs claude   (uses your subscription)
+NEBULA_CODEX_HOME=path/to/.codex-home npm run smoke codex
+```

package/node_modules/nebula-autocomplete/dist/backends/claude.d.ts

@@ -0,0 +1,69 @@
+import type { CompletionBackend } from "../types.js";
+import { type Transport } from "../transport.js";
+export interface ClaudeBackendOptions {
+    /** Model passed to --model. Default "haiku" (fastest tier). */
+    model?: string;
+    /** Warm worker processes. Default 2. */
+    poolSize?: number;
+    /** Turns before a worker is recycled (stream-json turns share history). Default 8. */
+    maxTurnsPerWorker?: number;
+    /** Accumulated prompt chars before a worker is recycled. History size — not
+     *  turn count — is what drags TTFB, so this is the primary recycle driver.
+     *  Default 18_000 (~3 big-notebook prompts). */
+    maxHistoryCharsPerWorker?: number;
+    /** Per-turn timeout. Default 45_000 ms. */
+    turnTimeoutMs?: number;
+    /** Working directory for workers — keep it empty so no CLAUDE.md loads. */
+    workspaceDir?: string;
+    /** Path to the claude binary. Default "claude". */
+    binary?: string;
+    /** Where the claude process runs: locally (default) or over ssh on the user's
+     *  machine (remote Nebula + local agent). Default { kind: "local" }. */
+    transport?: Transport;
+    /** Thinking-token budget. Default 0: thinking never streams as ghost text
+     *  (observed burning a whole turn invisibly), but a budget can improve
+     *  tricky completions — surfaced as an Advanced setting. */
+    maxThinkingTokens?: number;
+}
+/**
+ * Persistent warm pool of `claude` CLI processes (subscription auth) in
+ * stream-json mode. Workers are recycled after maxTurnsPerWorker completions
+ * so conversation history never bloats the context.
+ */
+export declare class ClaudeBackend implements CompletionBackend {
+    readonly name = "claude";
+    private pool;
+    private opts;
+    private disposed;
+    private readonly wsToken;
+    constructor(options?: ClaudeBackendOptions);
+    /**
+     * Delete any Claude Code session-transcript directories that belong to this
+     * backend. Claude writes `~/.claude/projects/<munged-cwd>/*.jsonl` on some
+     * versions/platforms; the munged name preserves alphanumerics, so our
+     * wsToken (a UUID) always survives. We match by comparing alphanumeric-only
+     * forms, which is munge-algorithm-independent and cannot collide with a real
+     * project path. Best-effort: never throws into the caller.
+     */
+    private pruneTranscripts;
+    private ensurePool;
+    /**
+     * Spawn a worker wired for background self-healing: the claude CLI exits on
+     * its own after long idle, and replacing it lazily (at the next request)
+     * put the whole cold start — process boot + ssh reconnect + warmup turn —
+     * on the user's first post-idle completion (multi-second "autocomplete is
+     * dead after I come back" lag). Respawning the moment a worker dies keeps
+     * the pool warm through idle, so the first keystroke after a break pays the
+     * same ~1.5s as any other. Crash-loop guard: only self-respawn for workers
+     * that were healthy (survived 60s or completed a turn) — a broken binary
+     * dies instantly and would otherwise spawn-loop forever.
+     */
+    private spawnWorker;
+    complete(prompt: string, { signal, onChunk, diag }?: {
+        signal?: AbortSignal;
+        onChunk?: (t: string) => void;
+        diag?: import("../types.js").CompletionDiag;
+    }): Promise<string>;
+    private attempt;
+    dispose(): void;
+}

package/node_modules/nebula-autocomplete/dist/backends/claude.js

@@ -0,0 +1,449 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, readdirSync, rmSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { transcriptDirMatchesToken } from "../core/text.js";
+import { planSpawn, planRemoteCleanup } from "../transport.js";
+function isWorkerDeath(err) {
+    return err instanceof Error && err.message === "claude worker exited";
+}
+class ClaudeWorker {
+    opts;
+    busy = false;
+    dead = false;
+    turns = 0;
+    /** Total prompt chars sent — the real recycle driver: stream-json history
+     *  grows with every prompt, and TTFB grows with HISTORY SIZE, not turn
+     *  count (measured: 6.4KB prompts drag +~0.2s/turn; 1.5KB prompts don't). */
+    sentChars = 0;
+    bornAt = Date.now();
+    /** True once the warmup turn has settled — pool selection prefers warmed
+     *  workers so a request never waits ~5s on a still-booting one while a
+     *  warm sibling sits idle (observed: workerWait 4506ms, pool 0/2 busy). */
+    warmedDone = false;
+    /** Invoked once when the process exits/errors — lets the pool respawn in the background. */
+    onDeath;
+    warmed;
+    // Each worker runs in its OWN cwd subdir so Claude's per-cwd transcript
+    // directory is unique per worker. Pruning a recycled worker's transcripts
+    // then can't touch a concurrently-active worker's dir. cwdToken is the
+    // subdir name — it appears in the munged transcript-dir name.
+    cwd;
+    cwdToken = randomUUID();
+    pending = null;
+    buf = "";
+    proc;
+    // For the ssh transport: an ephemeral config dir on the REMOTE side so claude's
+    // transcripts don't accumulate on the user's machine — wiped on kill().
+    remoteConfigDir;
+    constructor(opts) {
+        this.opts = opts;
+        const argv = [
+            "-p",
+            "--model", opts.model,
+            // Strip tools and MCP servers from the harness prompt — the largest
+            // per-turn latency saver (measured ~2.3s -> ~1.4s TTFB).
+            "--tools", "",
+            "--mcp-config", '{"mcpServers":{}}',
+            "--strict-mcp-config",
+            "--input-format", "stream-json",
+            "--output-format", "stream-json",
+            "--include-partial-messages",
+            "--verbose",
+        ];
+        const env = {
+            // Generous cap: hitting it surfaces as an ERROR that discards the turn,
+            // so a tight cap converts long completions into nothing (observed).
+            // Runaways are bounded by the turn timeout and by supersession
+            // interrupts instead; long ghost text streams visibly and the user can
+            // ignore or Escape it.
+            CLAUDE_CODE_MAX_OUTPUT_TOKENS: "4096",
+            // Default 0: thinking tokens never stream as ghost text — observed as
+            // a 17s turn burning the whole budget with NOTHING shown. Users can
+            // opt into a budget (Advanced) for higher-quality completions.
+            MAX_THINKING_TOKENS: String(opts.maxThinkingTokens ?? 0),
+            CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
+        };
+        if (opts.transport.kind === "ssh") {
+            // Remote: run in a fresh remote tmp dir; keep transcripts in an ephemeral
+            // remote config dir (auth still comes from the user's real login via their
+            // ~/.zshenv token). No local workspace dir.
+            this.cwd = `/tmp/nebula-autocomplete-ws-${this.cwdToken}`;
+            this.remoteConfigDir = `/tmp/nebula-autocomplete-cfg-${this.cwdToken}`;
+            env.CLAUDE_CONFIG_DIR = this.remoteConfigDir;
+        }
+        else {
+            this.cwd = join(opts.workspaceDir, this.cwdToken);
+            this.remoteConfigDir = "";
+            mkdirSync(this.cwd, { recursive: true });
+        }
+        const plan = planSpawn(opts.transport, opts.binary, argv, env, this.cwd);
+        this.proc = spawn(plan.command, plan.args, {
+            ...plan.options,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.proc.stdout.on("data", (d) => this.onData(d));
+        this.proc.on("exit", () => {
+            this.dead = true;
+            this.pending?.reject(new Error("claude worker exited"));
+            this.pending = null;
+            const cb = this.onDeath;
+            this.onDeath = undefined; // fire once
+            cb?.();
+        });
+        this.proc.on("error", (err) => {
+            this.dead = true;
+            this.pending?.reject(err instanceof Error ? err : new Error(String(err)));
+            this.pending = null;
+            const cb = this.onDeath;
+            this.onDeath = undefined;
+            cb?.();
+        });
+        this.warmed = this.runTurn("Reply with exactly: ok").then(() => { this.warmedDone = true; }, () => { this.warmedDone = true; });
+    }
+    onData(data) {
+        this.buf += data.toString();
+        let idx;
+        while ((idx = this.buf.indexOf("\n")) !== -1) {
+            const line = this.buf.slice(0, idx);
+            this.buf = this.buf.slice(idx + 1);
+            if (!line.trim() || !this.pending)
+                continue;
+            let ev;
+            try {
+                ev = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (ev.type === "stream_event") {
+                const event = ev.event;
+                if (event?.type === "content_block_delta" && event.delta?.type === "text_delta") {
+                    this.pending.streamed = (this.pending.streamed ?? "") + event.delta.text;
+                    this.pending.onChunk?.(event.delta.text);
+                }
+            }
+            else if (ev.type === "result") {
+                const p = this.pending;
+                this.pending = null;
+                clearTimeout(p.timer);
+                // CLI failures (not logged in, out of credits, …) arrive as a result
+                // event with is_error / non-success subtype. Reject those turns —
+                // resolving would cache and render the error text as a suggestion.
+                if (ev.is_error === true || (typeof ev.subtype === "string" && ev.subtype !== "success")) {
+                    const msg = typeof ev.result === "string" && ev.result.trim()
+                        ? ev.result.trim()
+                        : `claude turn failed (${ev.subtype ?? "error"})`;
+                    // Hitting the output-token cap arrives as an ERROR, discarding a
+                    // completion we already streamed in full (observed: 35s turn, 512
+                    // tokens, then thrown away). The streamed text IS the completion —
+                    // truncated, but the tag/trim pipeline handles a missing close tag.
+                    if (/output token maximum/i.test(msg) && p.streamed) {
+                        p.resolve(p.streamed);
+                    }
+                    else {
+                        const note = /output token maximum/i.test(msg)
+                            ? ` (streamed ${p.streamed?.length ?? 0}ch before the cap)`
+                            : "";
+                        p.reject(new Error(msg + note));
+                    }
+                }
+                else {
+                    p.resolve(typeof ev.result === "string" ? ev.result : "");
+                }
+            }
+        }
+    }
+    runTurn(text, onChunk, signal) {
+        return new Promise((resolve, reject) => {
+            if (this.dead)
+                return reject(new Error("claude worker is dead"));
+            const timer = setTimeout(() => {
+                this.pending = null;
+                this.kill();
+                reject(new Error("claude turn timed out"));
+            }, this.opts.turnTimeoutMs);
+            const pending = { onChunk, resolve, reject, timer };
+            // Supersession: a dispatched turn CAN be cancelled — the stream-json
+            // protocol accepts {type:"control_request",request:{subtype:"interrupt"}}
+            // and ends the running turn in ~10ms (measured), leaving the worker
+            // reusable. Without this, a superseded completion held its worker for
+            // the full turn and the successor's "queued" time was a whole turn.
+            // Guard on `this.pending === pending` so a late abort can never kill a
+            // successor's turn that reused this worker.
+            const onAbort = () => {
+                if (this.pending === pending && !this.dead) {
+                    try {
+                        this.proc.stdin.write(JSON.stringify({
+                            type: "control_request",
+                            request_id: `int-${Date.now()}`,
+                            request: { subtype: "interrupt" },
+                        }) + "\n");
+                    }
+                    catch { /* worker dying anyway */ }
+                }
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            const cleanup = () => signal?.removeEventListener("abort", onAbort);
+            pending.resolve = (v) => { cleanup(); resolve(v); };
+            pending.reject = (e) => { cleanup(); reject(e); };
+            this.pending = pending;
+            if (signal?.aborted)
+                onAbort();
+            const msg = {
+                type: "user",
+                message: { role: "user", content: [{ type: "text", text }] },
+            };
+            this.proc.stdin.write(JSON.stringify(msg) + "\n");
+        });
+    }
+    kill() {
+        this.dead = true;
+        try {
+            this.proc.kill();
+        }
+        catch {
+            /* already gone */
+        }
+        // Remote no-trace: wipe this worker's ephemeral config + workspace dirs on
+        // the user's machine. Fire-and-forget over the (still-warm) control channel.
+        if (this.opts.transport.kind === "ssh") {
+            for (const dir of [this.remoteConfigDir, this.cwd]) {
+                if (!dir)
+                    continue;
+                try {
+                    const c = planRemoteCleanup(this.opts.transport, dir);
+                    spawn(c.command, c.args, { stdio: "ignore" }).unref();
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        }
+    }
+}
+/**
+ * Persistent warm pool of `claude` CLI processes (subscription auth) in
+ * stream-json mode. Workers are recycled after maxTurnsPerWorker completions
+ * so conversation history never bloats the context.
+ */
+export class ClaudeBackend {
+    name = "claude";
+    pool = [];
+    opts;
+    disposed = false;
+    // Unique token embedded in the workspace path. Claude Code keys its session
+    // transcript directory (~/.claude/projects/<munged-cwd>) off the process cwd,
+    // so this token survives path munging and lets us find and delete only our
+    // own transcript dirs — never a real session. See pruneTranscripts().
+    wsToken = randomUUID();
+    constructor(options = {}) {
+        // For ssh transport, give all workers a shared ControlMaster socket so the
+        // handshake is paid once and reconnects are ~free.
+        let transport = options.transport ?? { kind: "local" };
+        if (transport.kind === "ssh" && !transport.controlPath) {
+            // Keep the ControlMaster socket path SHORT: unix-socket paths max ~104
+            // chars, and macOS tmpdir() is a long /var/folders/... path that overflows
+            // it (→ ssh aborts). /tmp + a short token stays well under the limit.
+            transport = { ...transport, controlPath: `/tmp/nac-${this.wsToken.slice(0, 8)}` };
+        }
+        this.opts = {
+            model: options.model ?? "haiku",
+            poolSize: options.poolSize ?? 2,
+            // MEASURED (10 sequential real turns, one worker): per-turn latency does
+            // NOT grow with turn count — turns 7-9 averaged FASTER than 0-2, so the
+            // CLI/API handles its own history efficiently (prompt caching). Keep 8:
+            // recycling more often would just burn a warmup API call per recycle
+            // for zero latency benefit.
+            maxTurnsPerWorker: options.maxTurnsPerWorker ?? 8,
+            // MEASURED: TTFB grows with accumulated HISTORY, not turns — 6.4KB
+            // real-notebook prompts dragged ttfb 3.2s@turn5 -> 4.0s@turn7, while a
+            // 10-turn run of 1.5KB prompts showed no drag at all. Cap history size;
+            // the turn cap above is just a backstop. Recycling is background-warmed
+            // (spawnWorker/ensurePool), so tighter recycling costs the user nothing.
+            maxHistoryCharsPerWorker: options.maxHistoryCharsPerWorker ?? 18_000,
+            turnTimeoutMs: options.turnTimeoutMs ?? 45_000,
+            // Default to a per-instance dir so the transcript-dir name is unique to
+            // this backend. A caller-supplied dir is used verbatim (its transcripts
+            // are then only pruned if its basename happens to contain wsToken — so
+            // prefer letting the default apply for full hygiene).
+            workspaceDir: options.workspaceDir ?? join(tmpdir(), `nebula-autocomplete-ws-${this.wsToken}`),
+            binary: options.binary ?? "claude",
+            transport,
+            maxThinkingTokens: options.maxThinkingTokens ?? 0,
+        };
+        // Local transport keeps its worker workspaces under workspaceDir; ssh workers
+        // use remote dirs, so no local dir is needed.
+        if (transport.kind === "local")
+            mkdirSync(this.opts.workspaceDir, { recursive: true });
+        this.ensurePool();
+    }
+    /**
+     * Delete any Claude Code session-transcript directories that belong to this
+     * backend. Claude writes `~/.claude/projects/<munged-cwd>/*.jsonl` on some
+     * versions/platforms; the munged name preserves alphanumerics, so our
+     * wsToken (a UUID) always survives. We match by comparing alphanumeric-only
+     * forms, which is munge-algorithm-independent and cannot collide with a real
+     * project path. Best-effort: never throws into the caller.
+     */
+    pruneTranscripts(token = this.wsToken) {
+        // ssh transport: transcripts live on the remote machine in a per-worker
+        // ephemeral CLAUDE_CONFIG_DIR, wiped by ClaudeWorker.kill(). Nothing local.
+        if (this.opts.transport.kind === "ssh")
+            return;
+        try {
+            const projectsDir = join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude"), "projects");
+            for (const entry of readdirSync(projectsDir)) {
+                if (transcriptDirMatchesToken(entry, token)) {
+                    rmSync(join(projectsDir, entry), { recursive: true, force: true });
+                }
+            }
+        }
+        catch {
+            /* projects dir absent (nothing written) or unreadable — nothing to prune */
+        }
+    }
+    ensurePool() {
+        if (this.disposed)
+            return;
+        this.pool = this.pool.filter((w) => !w.dead);
+        while (this.pool.length < this.opts.poolSize) {
+            this.pool.push(this.spawnWorker());
+        }
+    }
+    /**
+     * Spawn a worker wired for background self-healing: the claude CLI exits on
+     * its own after long idle, and replacing it lazily (at the next request)
+     * put the whole cold start — process boot + ssh reconnect + warmup turn —
+     * on the user's first post-idle completion (multi-second "autocomplete is
+     * dead after I come back" lag). Respawning the moment a worker dies keeps
+     * the pool warm through idle, so the first keystroke after a break pays the
+     * same ~1.5s as any other. Crash-loop guard: only self-respawn for workers
+     * that were healthy (survived 60s or completed a turn) — a broken binary
+     * dies instantly and would otherwise spawn-loop forever.
+     */
+    spawnWorker() {
+        const w = new ClaudeWorker(this.opts);
+        w.onDeath = () => {
+            if (this.disposed)
+                return;
+            const wasHealthy = w.turns > 0 || Date.now() - w.bornAt > 60_000;
+            if (!wasHealthy)
+                return;
+            setTimeout(() => this.ensurePool(), 250);
+        };
+        return w;
+    }
+    async complete(prompt, { signal, onChunk, diag } = {}) {
+        if (this.disposed)
+            throw new Error("backend disposed");
+        signal?.throwIfAborted();
+        // A pooled worker can die between turns (the CLI process exits on its own
+        // in some versions). Retry once on a guaranteed-fresh worker before giving
+        // up — but never after the caller aborted or emitted partial ghost text.
+        let emitted = false;
+        const guard = (t) => {
+            if (!signal?.aborted) {
+                emitted = true;
+                onChunk?.(t);
+            }
+        };
+        try {
+            return await this.attempt(prompt, signal, guard, false, diag);
+        }
+        catch (err) {
+            if (this.disposed || signal?.aborted || emitted || !isWorkerDeath(err))
+                throw err;
+            if (diag)
+                diag.retried = true;
+            return await this.attempt(prompt, signal, guard, true, diag);
+        }
+    }
+    async attempt(prompt, signal, guard, forceFresh, diag) {
+        const tAcquire = performance.now();
+        this.ensurePool();
+        if (diag) {
+            diag.transport = this.opts.transport.kind;
+            diag.poolSize = this.pool.length;
+            diag.poolBusy = this.pool.filter((w) => w.busy && !w.dead).length;
+        }
+        // Prefer a WARMED idle worker; only fall back to a still-warming one
+        // (and only then to a cold spawn). Landing on a booting worker costs the
+        // whole warmup (~5s over ssh) even when a warm sibling is idle.
+        let worker = forceFresh
+            ? undefined
+            : this.pool.find((w) => !w.busy && !w.dead && w.warmedDone) ??
+                this.pool.find((w) => !w.busy && !w.dead);
+        if (!worker) {
+            worker = this.spawnWorker();
+            this.pool.push(worker);
+            if (diag)
+                diag.coldSpawn = true;
+            console.log(`[autocomplete] cold worker spawn (${this.opts.transport.kind}): pool ${this.pool.length - 1} all busy/dead`);
+        }
+        worker.busy = true;
+        if (diag) {
+            diag.workerTurn = worker.turns;
+            diag.workerHistoryChars = worker.sentChars;
+        }
+        // Always wait for the warmup turn: dispatching while it is in flight
+        // would steal its pending handler and resolve with the warmup's output.
+        await worker.warmed;
+        if (diag)
+            diag.workerWaitMs = Math.round(performance.now() - tAcquire);
+        try {
+            const full = await worker.runTurn(prompt, guard, signal);
+            signal?.throwIfAborted();
+            return full;
+        }
+        finally {
+            worker.turns += 1;
+            worker.sentChars += prompt.length;
+            worker.busy = false;
+            if (worker.turns >= this.opts.maxTurnsPerWorker ||
+                worker.sentChars >= this.opts.maxHistoryCharsPerWorker ||
+                worker.dead) {
+                const recycled = worker;
+                recycled.kill();
+                // Prune only THIS worker's transcript dir (matched by its own cwd
+                // token) so a concurrently-active worker's dir is never disturbed.
+                // Bounds growth over a long-lived server, not just at shutdown.
+                this.pruneTranscripts(recycled.cwdToken);
+                if (this.opts.transport.kind === "local") {
+                    try {
+                        rmSync(recycled.cwd, { recursive: true, force: true });
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                } // ssh worker dirs are remote — cleaned by recycled.kill()
+                this.ensurePool(); // warm replacement spawns in the background
+            }
+        }
+    }
+    dispose() {
+        this.disposed = true;
+        for (const w of this.pool)
+            w.kill();
+        this.pool = [];
+        this.pruneTranscripts();
+        if (this.opts.transport.kind === "ssh") {
+            // Tear down the shared ControlMaster connection.
+            if (this.opts.transport.controlPath) {
+                try {
+                    spawn("ssh", ["-O", "exit", "-o", `ControlPath=${this.opts.transport.controlPath}`,
+                        `${this.opts.transport.user}@${this.opts.transport.host}`], { stdio: "ignore" }).unref();
+                }
+                catch { /* best-effort */ }
+            }
+            return;
+        }
+        try {
+            rmSync(this.opts.workspaceDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}