specrails-desktop 2.2.0 → 2.3.0

package/server/dist/chat-manager.js

@@ -20,6 +20,7 @@ const providers_1 = require("./providers");
 const context_scope_1 = require("./context-scope");
 const user_mcp_config_1 = require("./user-mcp-config");
 const binary_probe_1 = require("./binary-probe");
+const explore_stdin_session_1 = require("./explore-stdin-session");
 const COMMAND_INSTRUCTION = 'When you want to suggest a SpecRails command for the user to execute, wrap it in a command block like this: ' +
     ':::command\n/specrails:implement #42\n::: ' +
     'The user will be prompted to confirm before the command runs.';
@@ -60,6 +61,9 @@ class ChatManager {
     _exploreLifecycle;
     /** FIFO queue of Explore turns waiting for a concurrency slot. */
     _exploreQueue;
+    /** Persistent-stdin Explore transport (big bet #3, flag-gated default OFF).
+     *  Holds long-lived claude children that survive between turns. */
+    _stdinSessions = new explore_stdin_session_1.ExploreStdinSessions();
     _cwd;
     _projectName;
     _adapter;
@@ -142,6 +146,9 @@ class ChatManager {
                 }
                 catch { /* best-effort */ }
             }
+            // Persistent-stdin children live OUTSIDE _activeProcesses between turns —
+            // idle-kill must reach them too (the next turn re-spawns with --resume).
+            this._stdinSessions.kill(conversationId);
         }, exports.EXPLORE_IDLE_KILL_MS);
     }
     /**
@@ -223,6 +230,8 @@ class ChatManager {
                 }
                 catch { /* best-effort */ }
             }
+            // Reclaim the slot from a persistent-stdin child parked between turns.
+            this._stdinSessions.kill(victim);
             this._clearIdleTimer(victim);
             this._exploreLifecycle.delete(victim);
             if (this._countStreamingExplore() < exports.EXPLORE_MAX_CONCURRENCY)
@@ -535,6 +544,10 @@ class ChatManager {
                 sessionId: conversation.session_id ?? undefined,
                 maxTurns: options?.maxTurns,
                 extraArgs: scopeFlags,
+                // "My approved MCPs" (scope.userMcp) loads the developer's user-scope,
+                // plugin, and connector MCP servers — which require the `user` setting
+                // source. Claude-only (codex reads ~/.codex natively, ignores this).
+                loadUserEnv: adapter.id === 'claude' && !!conversationScope?.userMcp,
             });
             if (conversationScope) {
                 console.log(`[chat-manager] scope=${JSON.stringify(conversationScope)} flags=${scopeFlags.join(' ')} promptBytes=${Buffer.byteLength(systemPrompt)}`);
@@ -543,6 +556,19 @@ class ChatManager {
             // not pipeline jobs. Telemetry is scoped to QueueManager pipeline runs only.
             // spawnAiCli reroutes multi-line argv values through stdin on Windows.
             const spawnCwd = this._resolveSpawnCwd(conversation.kind, conversationScope, adapter.id);
+            // Big bet #3 fast-path: persistent-stdin multi-turn for Explore (claude
+            // only, flag-gated default OFF). Reuses a single long-lived child across
+            // turns so turns 2+ skip spawn + session rehydration. Full fallback to the
+            // legacy spawn-per-turn path below when disabled / unsupported.
+            if ((0, explore_stdin_session_1.isExplorePersistentStdinEnabled)() &&
+                conversation.kind === 'explore' &&
+                adapter.capabilities.persistentStdin === true) {
+                return await this._streamPersistentExploreTurn({
+                    conversationId, conversation, adapter, binary, model, systemPrompt,
+                    scopeFlags, spawnCwd, promptForAdapter, isFirstTurn, userText,
+                    lightweight, conversationScope,
+                });
+            }
             const child = (0, cli_prompt_1.spawnAiCli)(binary, args, {
                 env: process.env,
                 stdio: ['ignore', 'pipe', 'pipe'],
@@ -862,6 +888,223 @@ class ChatManager {
             this._reservedTurns.delete(conversationId);
         }
     }
+    /**
+     * Persistent-stdin Explore turn (big bet #3). Reuses one long-lived claude
+     * child per conversation via `--input-format stream-json`: the user turn is
+     * written to the child's stdin, and the turn ends on the `result` event
+     * (NOT process close — the child stays alive for the next turn). Mirrors the
+     * legacy close-handler's finalisation (spec-draft parse, persist, session
+     * capture, chat_done, invocation accounting, lifecycle) without crash-respawn
+     * — a dead persistent child is evicted and the next turn re-spawns with
+     * `--resume`. Only reached when the flag is on; the legacy path is untouched.
+     */
+    async _streamPersistentExploreTurn(p) {
+        const { conversationId, conversation, adapter, binary, model, systemPrompt, scopeFlags, spawnCwd, promptForAdapter, isFirstTurn, userText, lightweight, conversationScope, } = p;
+        const sessionArgs = adapter.buildArgs('chat-stream', {
+            prompt: '',
+            systemPrompt,
+            model,
+            sessionId: conversation.session_id ?? undefined,
+            extraArgs: scopeFlags,
+            loadUserEnv: adapter.id === 'claude' && !!conversationScope?.userMcp,
+        });
+        const { child } = this._stdinSessions.getOrSpawn(conversationId, {
+            binary, args: sessionArgs, cwd: spawnCwd, env: process.env,
+        });
+        this._activeProcesses.set(conversationId, child);
+        this._buffers.set(conversationId, '');
+        this._emittedProposals.set(conversationId, new Set());
+        this._streamFilters.set(conversationId, { inBlock: false, pendingTail: '' });
+        const adapterEvents = [];
+        let capturedSessionId = null;
+        let stderrBuf = '';
+        const turnStartedAt = new Date().toISOString();
+        const emitDelta = (newText) => {
+            const prev = this._buffers.get(conversationId) ?? '';
+            this._buffers.set(conversationId, prev + newText);
+            const filter = this._streamFilters.get(conversationId);
+            const visibleDelta = filter ? filterDraftBlocksLive(filter, newText) : newText;
+            if (visibleDelta) {
+                this._broadcast({
+                    type: 'chat_stream',
+                    conversationId,
+                    delta: visibleDelta,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            const proposals = extractCommandProposals(this._buffers.get(conversationId) ?? '');
+            const emitted = this._emittedProposals.get(conversationId);
+            if (emitted) {
+                for (const proposal of proposals) {
+                    if (!emitted.has(proposal)) {
+                        emitted.add(proposal);
+                        this._broadcast({
+                            type: 'chat_command_proposal',
+                            conversationId,
+                            command: proposal,
+                            timestamp: new Date().toISOString(),
+                        });
+                    }
+                }
+            }
+        };
+        const recordInv = (status) => {
+            if (!this._projectId)
+                return;
+            try {
+                const { result, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, adapterEvents, {
+                    fallbackModel: model,
+                });
+                (0, ai_invocations_1.recordInvocation)(this._db, {
+                    id: (0, crypto_1.randomUUID)(),
+                    project_id: this._projectId,
+                    provider: adapter.id,
+                    surface: 'explore-spec',
+                    surface_ref_id: conversationId,
+                    conversation_id: conversationId,
+                    status,
+                    started_at: turnStartedAt,
+                    finished_at: new Date().toISOString(),
+                    total_cost_usd_estimated: estimated,
+                    ...result,
+                });
+                this._broadcast({ type: 'spending.invalidated', projectId: this._projectId });
+            }
+            catch (err) {
+                console.error('[chat-manager] recordInvocation failed:', err);
+            }
+        };
+        const cleanupTurnState = () => {
+            this._activeProcesses.delete(conversationId);
+            this._buffers.delete(conversationId);
+            this._emittedProposals.delete(conversationId);
+            this._streamFilters.delete(conversationId);
+        };
+        const markStreamingEnded = (success) => {
+            const life = this._exploreLifecycle.get(conversationId);
+            if (life) {
+                life.isStreaming = false;
+                life.lastActivityAt = Date.now();
+                if (success)
+                    life.crashCount = 0;
+                if (life.isMinimized)
+                    this._startIdleTimer(conversationId);
+            }
+            this._drainExploreQueue();
+        };
+        return new Promise((resolve) => {
+            let settled = false;
+            const finishTurn = () => {
+                if (settled)
+                    return;
+                settled = true;
+                this._stdinSessions.clearHandlers(conversationId);
+                const fullText = this._buffers.get(conversationId) ?? '';
+                const wasAborting = this._abortingConversations.has(conversationId);
+                cleanupTurnState();
+                this._abortingConversations.delete(conversationId);
+                markStreamingEnded(true);
+                recordInv(wasAborting ? 'aborted' : 'success');
+                const parsed = (0, spec_draft_parser_1.parseSpecDraftBlocks)(fullText);
+                const persistedText = parsed.blocks.length > 0 ? parsed.stripped : fullText;
+                if (parsed.blocks.length > 0) {
+                    const prevState = this._specDraftStates.get(conversationId);
+                    const nextState = (0, spec_draft_parser_1.applyBlocks)(prevState, parsed.blocks);
+                    this._specDraftStates.set(conversationId, nextState);
+                    this._broadcast({
+                        type: 'spec_draft.update',
+                        conversationId,
+                        draft: nextState.draft,
+                        ready: nextState.ready,
+                        chips: nextState.chips,
+                        changedFields: nextState.lastChangedFields,
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+                if (persistedText) {
+                    (0, db_1.addMessage)(this._db, { conversation_id: conversationId, role: 'assistant', content: persistedText });
+                }
+                if (capturedSessionId) {
+                    (0, db_1.updateConversation)(this._db, conversationId, { session_id: capturedSessionId });
+                }
+                this._broadcast({
+                    type: 'chat_done',
+                    conversationId,
+                    fullText: persistedText,
+                    timestamp: new Date().toISOString(),
+                });
+                if (isFirstTurn && fullText && !lightweight) {
+                    this._autoTitle(conversationId, userText, fullText);
+                }
+                resolve();
+            };
+            const onClose = (code) => {
+                // The persistent child died (crash / idle-kill / shutdown). If the turn
+                // already finished on its `result` event, ignore. No crash-respawn —
+                // the session is evicted by the transport; the next turn re-spawns with
+                // `--resume`, so no persisted state is lost.
+                if (settled)
+                    return;
+                settled = true;
+                this._stdinSessions.clearHandlers(conversationId);
+                const wasAborting = this._abortingConversations.has(conversationId);
+                cleanupTurnState();
+                this._abortingConversations.delete(conversationId);
+                markStreamingEnded(false);
+                recordInv(wasAborting ? 'aborted' : 'failed');
+                if (wasAborting) {
+                    resolve();
+                    return;
+                }
+                const stderrTail = stderrBuf.trim().slice(-500);
+                this._broadcast({
+                    type: 'chat_error',
+                    conversationId,
+                    error: stderrTail
+                        ? `${binary} exited with code ${code ?? 'unknown'}: ${stderrTail}`
+                        : `Process exited with code ${code ?? 'unknown'}`,
+                    timestamp: new Date().toISOString(),
+                });
+                resolve();
+            };
+            const onLine = (line) => {
+                const ev = adapter.parseStreamLine(line);
+                if (!ev)
+                    return;
+                adapterEvents.push(ev);
+                switch (ev.kind) {
+                    case 'text-delta':
+                        emitDelta(ev.text);
+                        break;
+                    case 'session-started':
+                        if (ev.sessionId)
+                            capturedSessionId = ev.sessionId;
+                        break;
+                    case 'result': {
+                        const sid = ev.payload.session_id;
+                        if (sid)
+                            capturedSessionId = sid;
+                        finishTurn();
+                        break;
+                    }
+                    default:
+                        break;
+                }
+            };
+            this._stdinSessions.setHandlers(conversationId, {
+                onLine,
+                onStderr: (s) => {
+                    stderrBuf += s;
+                    console.error(`[chat-manager] ${binary} stderr (${conversationId}):`, s.trim());
+                },
+                onClose,
+            });
+            if (!this._stdinSessions.writeTurn(conversationId, promptForAdapter)) {
+                // stdin already gone (child died between spawn and write) — fail the turn.
+                onClose(null);
+            }
+        });
+    }
     abort(conversationId) {
         const child = this._activeProcesses.get(conversationId);
         if (!child || !child.pid)
@@ -889,6 +1132,7 @@ class ChatManager {
             clearTimeout(this._exploreQueue[idx].timeoutTimer);
             this._exploreQueue.splice(idx, 1);
         }
+        this._stdinSessions.kill(conversationId);
         this._exploreLifecycle.delete(conversationId);
     }
     /**
@@ -907,6 +1151,8 @@ class ChatManager {
                 catch { /* best-effort */ }
             }
         }
+        // Persistent-stdin children outlive individual turns — tear them down too.
+        this._stdinSessions.killAll();
         for (const id of this._exploreLifecycle.keys()) {
             this._clearIdleTimer(id);
         }

package/server/dist/code-explorer-router.js

@@ -539,6 +539,84 @@ function createCodeExplorerRouter(deps) {
             absolutePath: abs,
         });
     });
+    // In-app editing (v1): overwrite an existing text file with new content.
+    // Same guards as the read path — traversal, deny-list, gitignore, size, and
+    // binary refusal — so the editor can never write outside the tree, clobber a
+    // secret/lockfile, or corrupt a binary. Creating new files / renames is out of
+    // scope here. After a write the existing hash-gated `summaryStale` flag makes
+    // the next GET /file surface the summary as stale (regenerate via the existing
+    // POST /file/regenerate-summary).
+    router.put('/file', (req, res) => {
+        const body = (req.body ?? {});
+        const relRaw = typeof body.path === 'string' ? body.path : undefined;
+        const content = typeof body.content === 'string' ? body.content : undefined;
+        if (!relRaw || content === undefined) {
+            res.status(400).json({ error: 'path and content are required' });
+            return;
+        }
+        const guard = resolveSafePath(deps.projectPath, relRaw);
+        if (!guard) {
+            res.status(400).json({ error: 'path traversal not allowed' });
+            return;
+        }
+        if (isDeniedRelPath(relRaw)) {
+            res.status(403).json({ error: 'path is excluded by the code-explorer deny-list' });
+            return;
+        }
+        const rel = normalizeRel(relRaw);
+        if (isGitIgnored(deps.projectPath, rel)) {
+            res.status(403).json({ error: 'path is gitignored' });
+            return;
+        }
+        if (Buffer.byteLength(content, 'utf8') > MAX_FILE_BYTES) {
+            res.status(413).json({ error: 'file too large' });
+            return;
+        }
+        if (/[\x00-\x08\x0e-\x1f]/.test(content)) {
+            res.status(415).json({ error: 'binary content not allowed' });
+            return;
+        }
+        const abs = guard;
+        let stat;
+        try {
+            stat = fs_1.default.statSync(abs);
+        }
+        catch {
+            res.status(404).json({ error: 'file not found (in-app editing only overwrites existing files)' });
+            return;
+        }
+        if (!stat.isFile()) {
+            res.status(400).json({ error: 'path is not a regular file' });
+            return;
+        }
+        // Refuse to overwrite a binary file as text (would corrupt it).
+        try {
+            const fd = fs_1.default.openSync(abs, 'r');
+            try {
+                const head = Buffer.alloc(Math.min(BINARY_PROBE_BYTES, stat.size));
+                fs_1.default.readSync(fd, head, 0, head.length, 0);
+                if (head.includes(0)) {
+                    res.status(415).json({ error: 'cannot edit a binary file' });
+                    return;
+                }
+            }
+            finally {
+                fs_1.default.closeSync(fd);
+            }
+        }
+        catch {
+            res.status(500).json({ error: 'failed to read file' });
+            return;
+        }
+        try {
+            fs_1.default.writeFileSync(abs, content, 'utf8');
+        }
+        catch {
+            res.status(500).json({ error: 'failed to write file' });
+            return;
+        }
+        res.json({ ok: true, bytes: Buffer.byteLength(content, 'utf8'), path: rel });
+    });
     router.get('/summary', async (req, res) => {
         const relRaw = req.query.path;
         if (!relRaw || typeof relRaw !== 'string') {

package/server/dist/command-resolver.js

@@ -53,6 +53,16 @@ The user's idea follows below. Begin the Explore Spec conversation.
 
 ${commandArgs}`.trim();
 }
+/**
+ * A `:`-separated command segment is safe iff it is a plain identifier: no path
+ * separators, no `.`/`..`, no NUL. Anything else could escape the
+ * commands/skills directory once joined into the lookup path.
+ */
+function isSafeSegment(seg) {
+    if (seg.length === 0 || seg === '.' || seg === '..')
+        return false;
+    return !/[/\\\0]/.test(seg);
+}
 /**
  * Try to find a command/skill .md file for the given command path parts
  * within the given base directory. Returns the resolved path or null.
@@ -87,6 +97,13 @@ function resolveCommand(command, cwd) {
     const builtIn = builtInCommand(commandPath, commandArgs);
     if (builtIn)
         return builtIn;
+    // Path-traversal guard: each segment is joined verbatim into
+    // `<baseDir>/.claude/commands/<...parts>.md`, so a segment like `..`, one
+    // containing a path separator, or an absolute fragment would escape the
+    // commands/skills directory and read an arbitrary file. Reject and leave the
+    // command unresolved (defense-in-depth even though the input is user-typed).
+    if (!parts.every(isSafeSegment))
+        return command;
     // 1. Check the project directory
     let resolvedPath = findCommandFile(cwd, parts);
     // 2. Fallback: check the app's own directory

package/server/dist/contract-refine-runner.js

@@ -19,6 +19,8 @@ exports.runContractRefineForQuick = runContractRefineForQuick;
 const node_crypto_1 = require("node:crypto");
 const node_readline_1 = require("node:readline");
 const cli_prompt_1 = require("./util/cli-prompt");
+const spawn_lifecycle_1 = require("./spawn-lifecycle");
+const registry_1 = require("./providers/registry");
 const explore_contract_refine_1 = require("./explore-contract-refine");
 const db_1 = require("./db");
 const explore_cwd_manager_1 = require("./explore-cwd-manager");
@@ -242,15 +244,45 @@ async function runContractRefine(deps, conversationId, ticketId) {
         projectName: deps.projectName,
     }, conversation);
     const startedAt = now().toISOString();
-    let child;
-    try {
-        child = spawn('claude', args, {
-            env: process.env,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            cwd,
-        });
-    }
-    catch (err) {
+    // Spawn/stream/timeout/settlement is owned by the shared spawn-lifecycle; the
+    // contract-refine-specific raw parse (fullText from assistant text blocks,
+    // the raw result event) and ALL finalize/record/broadcast logic stay here,
+    // byte-for-byte, so behaviour is unchanged (it still records via the legacy
+    // recordSafely path).
+    let fullText = '';
+    let resultEvent = null;
+    const run = await (0, spawn_lifecycle_1.runAiCliInvocation)({
+        adapter: (0, registry_1.getAdapter)('claude'),
+        binary: 'claude',
+        argv: args,
+        cwd,
+        env: process.env,
+        spawn,
+        timeoutMs,
+        onStdoutLine: (line) => {
+            let parsed = null;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (!parsed)
+                return;
+            const type = parsed.type;
+            if (type === 'result') {
+                resultEvent = parsed;
+            }
+            else if (type === 'assistant') {
+                const message = parsed.message;
+                for (const b of (message?.content ?? [])) {
+                    if (b.type === 'text' && typeof b.text === 'string')
+                        fullText += b.text;
+                }
+            }
+        },
+    });
+    if (run.spawnFailed) {
         recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, now().toISOString(), 'failed', null);
         deps.broadcast({
             type: 'explore.contract_refine_failed',
@@ -261,7 +293,7 @@ async function runContractRefine(deps, conversationId, ticketId) {
         });
         return { ok: false, reason: 'crashed', ticketId, conversationId };
     }
-    const result = await readRefineChildOutput(child, timeoutMs);
+    const result = { fullText, resultEvent, code: run.code, timedOut: run.timedOut };
     const finishedAt = now().toISOString();
     console.log(`[contract-refine-runner] spawn done code=${result.code} timedOut=${result.timedOut} hasResult=${!!result.resultEvent} textBytes=${result.fullText.length}`);
     if (result.timedOut) {

package/server/dist/db.js

@@ -600,6 +600,12 @@ function initDb(dbPath) {
     const db = new better_sqlite3_1.default(dbPath);
     db.pragma('journal_mode = WAL');
     db.pragma('foreign_keys = ON');
+    // Under load, QueueManager / ChatManager / FileSummaryManager write the same
+    // per-project DB concurrently with /analytics reads. Wait up to 5s on a lock
+    // instead of throwing SQLITE_BUSY, and cap the WAL so a long checkpoint can't
+    // grow it without bound.
+    db.pragma('busy_timeout = 5000');
+    db.pragma('journal_size_limit = 10000000'); // ~10 MB
     applyMigrations(db);
     // H-13: restrict the db + its WAL sidecars to 0600 (jobs.sqlite holds chat
     // transcripts and verbatim terminal command history). After migrations the

package/server/dist/desktop-db.js

@@ -315,6 +315,9 @@ function initDesktopDb(dbPath = getDesktopDbPath()) {
     const db = new better_sqlite3_1.default(dbPath);
     db.pragma('journal_mode = WAL');
     db.pragma('foreign_keys = ON');
+    // Wait up to 5s on a lock instead of throwing SQLITE_BUSY, and cap the WAL.
+    db.pragma('busy_timeout = 5000');
+    db.pragma('journal_size_limit = 10000000'); // ~10 MB
     applyDesktopMigrations(db);
     // H-13: desktop.sqlite stores webhook HMAC secrets in plaintext — restrict it
     // (and its WAL sidecars) to owner read/write.

package/server/dist/explore-stdin-session.js

@@ -0,0 +1,129 @@
+"use strict";
+// Persistent-stdin Explore transport (big bet #3).
+//
+// The default Explore turn spawns a fresh `claude` child per message (turns 2+
+// pay `--resume` session-rehydration latency). This module keeps ONE child
+// alive per conversation using claude's `--input-format stream-json` multi-turn
+// transport: each user turn is written as a newline-delimited JSON message to
+// the child's stdin, and the same long-lived child streams the response. The
+// child stays resident between turns, so turns 2+ skip spawn + rehydration.
+//
+// Transport only — it owns spawning, the persistent stdout/stderr fan-out, and
+// stdin framing. ChatManager drives per-turn rendering, persistence, and
+// lifecycle through the handler hooks. Default OFF behind a flag; claude-only
+// (gated by capabilities.persistentStdin); full fallback to the legacy
+// spawn-per-turn path means zero behaviour change when disabled.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExploreStdinSessions = void 0;
+exports.isExplorePersistentStdinEnabled = isExplorePersistentStdinEnabled;
+exports.frameStreamJsonUserMessage = frameStreamJsonUserMessage;
+const node_readline_1 = require("node:readline");
+const cli_prompt_1 = require("./util/cli-prompt");
+/**
+ * Persistent-stdin Explore is opt-in. Default OFF — set
+ * `SPECRAILS_EXPLORE_PERSISTENT_STDIN=1` to enable. Any other value (or unset)
+ * keeps the legacy spawn-per-turn path, so this is also the escape hatch.
+ */
+function isExplorePersistentStdinEnabled() {
+    return process.env.SPECRAILS_EXPLORE_PERSISTENT_STDIN === '1';
+}
+/**
+ * Frame one user turn as a stream-json input line for claude's
+ * `--input-format stream-json` transport. Newline-terminated so the child reads
+ * exactly one message per turn. Content is sent as a plain string (claude
+ * accepts string content for user messages).
+ */
+function frameStreamJsonUserMessage(text) {
+    return JSON.stringify({ type: 'user', message: { role: 'user', content: text } }) + '\n';
+}
+/**
+ * Owns the long-lived claude children for persistent-stdin Explore. Keyed by
+ * conversation id. One child per conversation; a single stdout reader fans each
+ * line out to the conversation's currently-installed turn handler.
+ */
+class ExploreStdinSessions {
+    _sessions = new Map();
+    has(id) {
+        return this._sessions.has(id);
+    }
+    size() {
+        return this._sessions.size;
+    }
+    /**
+     * Return the live child for a conversation, spawning one in persistent mode
+     * if none exists. `isNew` is true only when a child was just spawned (the
+     * caller writes the first turn either way).
+     */
+    getOrSpawn(id, spec) {
+        const existing = this._sessions.get(id);
+        if (existing && existing.child.pid && !existing.child.killed) {
+            return { child: existing.child, isNew: false };
+        }
+        const spawn = spec.spawn ?? cli_prompt_1.spawnAiCli;
+        const child = spawn(spec.binary, spec.args, {
+            env: spec.env ?? process.env,
+            // stdin MUST be piped — it is the per-turn transport.
+            stdio: ['pipe', 'pipe', 'pipe'],
+            cwd: spec.cwd,
+        });
+        const session = { child, reader: null, handlers: null };
+        if (child.stdout) {
+            session.reader = (0, node_readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+            session.reader.on('line', (line) => session.handlers?.onLine(line));
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (chunk) => session.handlers?.onStderr(chunk.toString()));
+        }
+        const onExit = (code) => {
+            // Evict first so a handler that re-spawns inside onClose sees a clean slot.
+            if (this._sessions.get(id) === session)
+                this._sessions.delete(id);
+            session.handlers?.onClose(code);
+        };
+        child.on('close', onExit);
+        child.on('error', () => onExit(null));
+        this._sessions.set(id, session);
+        return { child, isNew: true };
+    }
+    /** Install the handlers for the current turn (replaces any prior turn's). */
+    setHandlers(id, handlers) {
+        const s = this._sessions.get(id);
+        if (s)
+            s.handlers = handlers;
+    }
+    /** Detach the current turn's handlers (between turns stray lines are dropped). */
+    clearHandlers(id) {
+        const s = this._sessions.get(id);
+        if (s)
+            s.handlers = null;
+    }
+    /** Write one framed user turn to the persistent child's stdin. */
+    writeTurn(id, text) {
+        const s = this._sessions.get(id);
+        if (!s || !s.child.stdin || s.child.stdin.destroyed)
+            return false;
+        return s.child.stdin.write(frameStreamJsonUserMessage(text));
+    }
+    /** Kill and forget one conversation's persistent child (idempotent). */
+    kill(id) {
+        const s = this._sessions.get(id);
+        if (!s)
+            return;
+        this._sessions.delete(id);
+        try {
+            s.reader?.close();
+        }
+        catch { /* best-effort */ }
+        try {
+            if (s.child.pid && !s.child.killed)
+                s.child.kill('SIGTERM');
+        }
+        catch { /* already gone */ }
+    }
+    /** Kill every persistent child (shutdown / project removal). */
+    killAll() {
+        for (const id of Array.from(this._sessions.keys()))
+            this.kill(id);
+    }
+}
+exports.ExploreStdinSessions = ExploreStdinSessions;