charness 0.0.0-stage → 3.1.0

package/dist/adapters/claudeJsonStreamAdapter.js

@@ -0,0 +1,1891 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClaudeJsonStreamAdapter = exports.claudeJsonStreamUsageLogPrefix = void 0;
+exports.readLatestCompactSummaryFromTranscript = readLatestCompactSummaryFromTranscript;
+const crypto_1 = require("crypto");
+const events_1 = require("events");
+const fs = __importStar(require("fs"));
+const sessionKey_1 = require("../sessionKey");
+const apiErrorRetry_1 = require("../apiErrorRetry");
+const installManager_1 = require("../installManager");
+const mcpConfig_1 = require("../mcpConfig");
+const claudeCompactHook_1 = require("../utils/claudeCompactHook");
+const claudePlatformFlags_1 = require("./claudePlatformFlags");
+const state_1 = require("../state");
+const resolveBinary_1 = require("../utils/resolveBinary");
+const displayVerbosity_1 = require("../utils/displayVerbosity");
+const i18n_1 = require("../i18n");
+const resumeContext_1 = require("../resumeContext");
+const effortLevels_1 = require("../effortLevels");
+const claudeCliAdapter_1 = require("./claudeCliAdapter");
+const claudeStreamJson_1 = require("../utils/claudeStreamJson");
+const claudeMcpHeal_1 = require("../utils/claudeMcpHeal");
+const tmuxExec_1 = require("../utils/tmuxExec");
+const pollBackoff_1 = require("../utils/pollBackoff");
+const claudeRuntimeInfo_1 = require("../utils/claudeRuntimeInfo");
+const jsonStreamBusyWatchdog_1 = require("../utils/jsonStreamBusyWatchdog");
+const jsonStreamHost_1 = require("../utils/jsonStreamHost");
+const adapterNames_1 = require("./adapterNames");
+const claudeCodeVersion_1 = require("../utils/claudeCodeVersion");
+const sessionLaunchDefaults_1 = require("./sessionLaunchDefaults");
+/**
+ * In-flight explicit stops, per key — a second stop (or a start's implicit stop)
+ * AWAITS the first instead of racing it: the delayed first `tmux kill-session`
+ * could otherwise land AFTER a fresh same-name spawn and kill the new session.
+ * MODULE-level, shared by the idle and the per-turn adapter instances: both host
+ * a conversation under the SAME tmux name and dir, and a `/claude_mode` switch
+ * stops the process on one instance while the other spawns the next.
+ */
+const stopsInFlightByKey = new Map();
+/**
+ * @description Coalesce window for streamed answer/thinking deltas before an
+ * `output`/`thinking` emit — the CLI streams per-token, so raw per-delta emits
+ * would flood Telegram with edits. Mirrors OpenCode's `sseOutputBatchMs` (500).
+ */
+const streamOutputBatchMs = 350;
+/** Prefix of the per-turn token accounting line (L-D11); the process-level e2e
+ *  and the live cache check read it. */
+exports.claudeJsonStreamUsageLogPrefix = '[ClaudeJson] usage ';
+/** How long to wait for the `initialize` control-response handshake before
+ *  proceeding without the interactive control channel (questions unavailable). */
+const initializeHandshakeTimeoutMs = 15000;
+/**
+ * @description SECOND Claude backend: drives the `claude` CLI over its
+ * documented `--input-format stream-json --output-format stream-json` protocol
+ * (typed events, no TUI scrape) as an EXTERNAL tmux-hosted process per
+ * {@link SessionKey} (plan 2026-07-05-jsonstream-restart-isolation): a `#!/bin/sh`
+ * wrapper backgrounds claude with stdin on a FIFO the process itself holds
+ * `0<>` and stdout appended to a `stdout.jsonl` the adapter TAILS — so a bot
+ * restart (every hot reload) neither EOFs claude's stdin nor loses its output;
+ * the restarted bot re-adopts the tmux session and replays the missed tail.
+ * Same structured events, on the SAME subscription billing (proven
+ * `apiKeySource:"none"` + `seven_day` rate-limit event; the wrapper runs
+ * `env -u ANTHROPIC_API_KEY`, never `--bare`).
+ *
+ * Structural template is {@link import('./openCodeAdapter').OpenCodeAdapter}
+ * (event-driven, own process, per-key session map); the Claude on-disk
+ * transcript readers are reused for `/sessions` / resume / recap.
+ *
+ * Interactive questions (`AskUserQuestion`) reach Telegram through the same
+ * `question` event + pin flow as OpenCode: the CLI surfaces them as a
+ * `control_request` (`subtype:"can_use_tool"`, `tool_name:"AskUserQuestion"`)
+ * on stdout, answered with a `control_response` carrying
+ * `updatedInput.answers` on stdin — a wire protocol reverse-engineered from a
+ * live capture + the open-source `@anthropic-ai/claude-agent-sdk`. Ordinary
+ * tool permissions are auto-allowed (operator trusts their own agent — parity
+ * with the tmux backend's `bypassPermissions`), so only questions block.
+ *
+ * A topic flips between it and the tmux-scrape backend via `/claude_mode`
+ * (they share the on-disk transcript, so the switch resumes the same
+ * conversation). The DEFAULT Claude backend (`getDefaultClaudeBackendName`):
+ * `/login` is handled out-of-band by the bot (`claude auth login` in a pty),
+ * so it no longer needs a TUI to sign in.
+ */
+class ClaudeJsonStreamAdapter extends events_1.EventEmitter {
+    name;
+    label;
+    /**
+     * `idle` — the process stays between turns and is stopped at the idle mark (L3);
+     * `perTurn` — the process is stopped right after each turn (L5, L-D3), by the
+     * bot on the `turnEnded` event. Same host, same session layout: one process per
+     * conversation at a time whichever lifecycle runs it.
+     */
+    lifecycle;
+    constructor(options = { lifecycle: 'idle' }) {
+        super();
+        this.lifecycle = options.lifecycle;
+        this.name = options.lifecycle === 'perTurn' ? adapterNames_1.claudePerTurnAdapterName : adapterNames_1.claudeJsonStreamAdapterName;
+        this.label = options.lifecycle === 'perTurn' ? 'Claude Code (per-turn)' : 'Claude Code (stream)';
+    }
+    /** Emits incremental text deltas (like the tmux scrape) → the transports
+     *  synthesise continuation (`getDmDraftContinuation` / group delta path). */
+    outputsDeltas = true;
+    /** No TUI banner → keep the bot's `agent.ready` cue + one-shot boot ping (L2). */
+    selfGreetsOnStart = false;
+    sessions = new Map();
+    claudePath = (0, resolveBinary_1.resolveClaudeBinary)();
+    displayPrefsReader = null;
+    seenWatermarkWriter = null;
+    jsonStreamTailWriter = null;
+    sessionLaunchDefaultsReader = null;
+    claudeConfigDirReader = null;
+    /** The stops in flight — the module-level map shared by both lifecycles' instances (see {@link stopsInFlightByKey}). */
+    stopsInFlight = stopsInFlightByKey;
+    setDisplayPrefsReader(reader) {
+        this.displayPrefsReader = reader;
+    }
+    setSeenWatermarkWriter(writer) {
+        this.seenWatermarkWriter = writer;
+    }
+    setJsonStreamTailWriter(writer) {
+        this.jsonStreamTailWriter = writer;
+    }
+    setSessionLaunchDefaultsReader(reader) {
+        this.sessionLaunchDefaultsReader = reader;
+    }
+    setClaudeConfigDirReader(reader) {
+        this.claudeConfigDirReader = reader;
+    }
+    claudeRateLimitSink = null;
+    /** Where a session's `rate_limit_event` frames go (the bot's per-profile usage cache). */
+    setClaudeRateLimitSink(sink) {
+        this.claudeRateLimitSink = sink;
+    }
+    /** The config directory the conversation's next process must start with (its account profile). */
+    resolveConfigDir(key) {
+        return this.claudeConfigDirReader?.(key) ?? null;
+    }
+    getLaunchOptions(key) {
+        return (0, sessionLaunchDefaults_1.getSessionLaunchOptions)({
+            savedEffort: this.getEffort(key),
+            defaults: this.sessionLaunchDefaultsReader?.(key) ?? null,
+            botDefaultEffort: effortLevels_1.defaultEffortLevel,
+        });
+    }
+    getDisplayPrefs(key) {
+        return this.displayPrefsReader?.(key) ?? (0, displayVerbosity_1.getDefaultDisplayPrefs)();
+    }
+    advanceSeenWatermark(key, watermark) {
+        this.seenWatermarkWriter?.(key, watermark);
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    //  Lifecycle (S1)
+    // ─────────────────────────────────────────────────────────────────────────
+    async startSession(key, workDir, _args, sessionId) {
+        await this.stopSessionInternal(key);
+        const id = sessionId && (0, claudeCliAdapter_1.checkIsValidUuid)(sessionId) ? sessionId : (0, crypto_1.randomUUID)();
+        await this.spawnSession(key, workDir, id, { ...this.getLaunchOptions(key), resume: false, configDir: this.resolveConfigDir(key) });
+    }
+    async resumeSession(key, workDir, sessionId, options) {
+        await this.stopSessionInternal(key);
+        if (!(0, claudeCliAdapter_1.checkIsValidUuid)(sessionId))
+            throw new Error(`Invalid sessionId: ${sessionId}`);
+        await this.spawnSession(key, workDir, sessionId, { ...this.getLaunchOptions(key), resume: true, configDir: this.resolveConfigDir(key) });
+        // Post the short last-N-turn context block ONLY on the explicit user resume
+        // (`/sessions` pick) — a silent re-attach stays quiet (ResumeSessionOptions).
+        if (options?.isWithRecentContext) {
+            try {
+                const turns = await this.getRecentTurns(key, workDir, sessionId, resumeContext_1.resumeContextTurnLimit);
+                const rendered = (0, resumeContext_1.formatResumeContext)(turns);
+                if (rendered)
+                    this.emit('output', key, rendered, { isComplete: true });
+            }
+            catch (e) {
+                console.warn(`[ClaudeJson] resume context block failed:`, e instanceof Error ? e.message : e);
+            }
+        }
+    }
+    /**
+     * @description Spawn (or re-spawn) the CLI process for a thread as an
+     * EXTERNAL tmux-hosted process (wrapper + FIFO stdin + stdout file — the
+     * probe-proven layout in `utils/jsonStreamHost.ts`), start the stdout tail
+     * poller, and complete the `initialize` control handshake (which enables the
+     * `AskUserQuestion` control channel). Rejects — with the wrapper's exit code
+     * and a stderr excerpt — if the process fails to come up. Reused by start /
+     * resume / effort-respawn.
+     */
+    async spawnSession(key, workDir, sessionId, opts) {
+        if (!(0, installManager_1.checkIsInstalled)('claude')) {
+            this.emit('output', key, 'Installing Claude Code...');
+            await (0, installManager_1.installTool)('claude');
+        }
+        // Claude writes the transcript only with the first turn, so a session that never took one
+        // (e.g. `/model` right after `/new`) has nothing to `--resume` and the CLI exits
+        // "No conversation found". Such a session is started again under the same id instead.
+        const isResumable = opts.resume && fs.existsSync((0, claudeCliAdapter_1.getClaudeTranscriptPath)(workDir, sessionId));
+        const mcpFlags = await (0, mcpConfig_1.prepareMcpFlags)({ key, dataDir: (0, state_1.resolveDataDir)() });
+        const args = [
+            '-p',
+            // Followed by an option on purpose: `--disallowedTools` takes several values.
+            ...(0, claudePlatformFlags_1.getClaudePlatformFlags)(key),
+            '--input-format', 'stream-json',
+            '--output-format', 'stream-json',
+            '--include-partial-messages',
+            '--verbose',
+            '--replay-user-messages',
+            // Bypass ALL permission checks (tmux-backend parity) so the operator's own
+            // agent never stalls on a permission prompt. `--dangerously-skip-permissions`
+            // + `bypassPermissions` means regular tools (Bash/Read/…) never route through
+            // the stdio prompt tool at all. `--permission-prompt-tool stdio` STAYS: it is
+            // what keeps `AskUserQuestion` in the tool list AND still routes it through the
+            // control channel even under bypass (verified live on v2.1.201 — bypass does
+            // NOT suppress AskUserQuestion, and `apiKeySource` stays `none`). The residual
+            // circuit-breakers claude never bypasses (`rm -rf /`, `rm -rf ~`) still arrive
+            // as `can_use_tool` and are answered by the generic auto-allow below.
+            '--dangerously-skip-permissions',
+            '--permission-mode', 'bypassPermissions',
+            '--permission-prompt-tool', 'stdio',
+        ];
+        if (isResumable)
+            args.push('--resume', sessionId);
+        else
+            args.push('--session-id', sessionId);
+        if (opts.model)
+            args.push('--model', opts.model);
+        if (opts.effort)
+            args.push('--effort', opts.effort);
+        args.push(...mcpFlags);
+        // Overflow-triggered compaction gets the bot's summary guidance (see the module).
+        args.push(...(0, claudeCompactHook_1.prepareClaudeCompactHookFlags)((0, state_1.resolveDataDir)()));
+        // Subscription billing: the wrapper runs `env -u ANTHROPIC_API_KEY` (a set
+        // key would meter the API); a tracker conversation's wrapper starts claude
+        // with `env -i` and the agent allowlist instead (R32) — no key either. The CLI
+        // reads the OAuth login from ~/.claude — `apiKeySource:"none"` (probe-verified
+        // under the wrapper).
+        const sessionDir = (0, jsonStreamHost_1.resolveJsonStreamSessionDir)((0, state_1.resolveDataDir)(), key);
+        const paths = (0, jsonStreamHost_1.getJsonStreamSessionPaths)(sessionDir);
+        const tmuxName = (0, jsonStreamHost_1.buildJsonStreamTmuxSessionName)(key);
+        console.log(`[ClaudeJson] spawn ${(0, sessionKey_1.keyToString)(key)} session=${sessionId} resume=${isResumable} effort=${opts.effort} model=${opts.model ?? 'default'} configDir=${opts.configDir ?? 'default'} (tmux ${tmuxName})`);
+        let pid;
+        let fifoFd;
+        try {
+            // Fresh host layout — a stale dir/fifo from a crashed run must not be reused.
+            fs.rmSync(sessionDir, { recursive: true, force: true });
+            fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+            await (0, tmuxExec_1.execFilePromise)('mkfifo', [paths.stdinFifo]);
+            fs.writeFileSync(paths.wrapperFile, (0, jsonStreamHost_1.buildWrapperScript)(this.claudePath, args, workDir, paths, (0, claudePlatformFlags_1.getClaudePlatformEnvironment)(key), opts.configDir), { mode: 0o755 });
+            // A stale same-name tmux session (crashed bot / pre-adopt build) would make
+            // `new-session` fail — and must not keep running unowned next to ours.
+            await (0, tmuxExec_1.tmuxAsync)('kill-session', '-t', (0, tmuxExec_1.getTmuxSessionTarget)(tmuxName));
+            await (0, tmuxExec_1.tmuxOrThrowAsync)('new-session', '-d', '-s', tmuxName, paths.wrapperFile);
+            const pidRead = await (0, jsonStreamHost_1.waitForPidFile)(paths.pidFile);
+            if (pidRead === null)
+                throw new Error(`claude never wrote its pid file${describeSpawnFailure(paths)}`);
+            pid = pidRead;
+            const fdRead = await (0, jsonStreamHost_1.openFifoWriterNonBlocking)(paths.stdinFifo);
+            if (fdRead === null)
+                throw new Error(`claude is not holding its stdin FIFO${describeSpawnFailure(paths)}`);
+            fifoFd = fdRead;
+        }
+        catch (e) {
+            (0, mcpConfig_1.cleanupMcpTempFiles)({ key, dataDir: (0, state_1.resolveDataDir)() });
+            await (0, tmuxExec_1.tmuxAsync)('kill-session', '-t', (0, tmuxExec_1.getTmuxSessionTarget)(tmuxName));
+            try {
+                fs.rmSync(sessionDir, { recursive: true, force: true });
+            }
+            catch { /* best-effort */ }
+            throw new Error(`Failed to start Claude stream session: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const session = {
+            key, workDir, sessionId,
+            pid, paths, fifoFd,
+            stdinWriteChain: Promise.resolve(),
+            tail: (0, jsonStreamHost_1.createStdoutTailState)(0),
+            pollTimer: null, pollDelayMs: pollBackoff_1.basePollIntervalMs, unchangedStreak: 0,
+            isOversizeWarned: false, lastPersistedTailOffset: 0,
+            reader: new claudeStreamJson_1.ClaudeStreamLineReader(),
+            isActive: true, isStopping: false, isSuspending: false, isRespawning: false, isBusy: false, unconsumedInputCount: 0,
+            lastStdoutActivityAt: Date.now(), outstandingToolUseIds: new Set(),
+            model: opts.model, reportedModel: null, effort: opts.effort,
+            configDir: opts.configDir, isConfigDirSwitchPending: false,
+            currentResponseText: '', emittedLength: 0, outputTimer: null,
+            reasoningText: '', reasoningStartedAt: null, reasoningTimer: null, reasoningActive: false,
+            toolNamesById: new Map(), questionToolUseIds: new Set(),
+            subagentActive: false, childResponseText: '', childEmittedLength: 0, childOutputTimer: null,
+            pendingInitResolve: null, initRequestId: null, pendingControlRequests: new Map(),
+            compactionInProgress: false, pendingCompaction: null,
+            pendingQuestion: null, apiErrorFired: false, swallowNextAbortError: false,
+            lastWatermarkOffset: -1,
+            backgroundTaskIds: new Set(), claudeCodeVersion: null, applyingChunk: null,
+            adoptCatchUpOffset: null, adoptCatchUpResolvers: [],
+        };
+        this.sessions.set((0, sessionKey_1.keyToString)(key), session);
+        // A fresh spawn starts a fresh stdout file — reset the persisted tail offset
+        // so a later adopt never resumes from a previous run's position.
+        this.jsonStreamTailWriter?.(key, buildTailRecord(session, 0));
+        this.schedulePoll(session, pollBackoff_1.basePollIntervalMs);
+        // Initialize handshake: declares the interactive control channel (permission
+        // prompts + AskUserQuestion route to stdio). Without it AskUserQuestion is not
+        // even in the tool list (verified). Best-effort — proceed on timeout so a
+        // handshake hiccup never blocks a plain-output session. The response arrives
+        // through the tail poller started above.
+        await this.performInitialize(session);
+        this.emit('started', key);
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    //  External-process transport: stdout tail poll + exit detection
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Arm the next tail poll (single-flight `setTimeout` chain, mirroring the
+     *  scrape backend's `schedulePoll` — never overlapping ticks). */
+    schedulePoll(session, delayMs) {
+        if (!session.isActive)
+            return;
+        if (session.pollTimer)
+            clearTimeout(session.pollTimer);
+        session.pollDelayMs = delayMs;
+        session.pollTimer = setTimeout(() => {
+            session.pollTimer = null;
+            this.pollTailTick(session);
+        }, delayMs);
+    }
+    /** Snap the tail cadence back to base — called on every stdin write, when
+     *  fresh output is expected shortly (mirrors the scrape backend's write snap). */
+    snapPollToBase(session) {
+        if (!session.isActive)
+            return;
+        session.unchangedStreak = 0;
+        this.schedulePoll(session, pollBackoff_1.basePollIntervalMs);
+    }
+    pollTailTick(session) {
+        if (!session.isActive || this.sessions.get((0, sessionKey_1.keyToString)(session.key)) !== session)
+            return;
+        let isChanged = false;
+        try {
+            isChanged = this.drainStdoutTail(session);
+        }
+        catch (e) {
+            console.warn(`[ClaudeJson] stdout tail read failed for ${(0, sessionKey_1.keyToString)(session.key)}:`, e instanceof Error ? e.message : e);
+        }
+        // Exit detection (locked decision): the wrapper writes `exitcode` when
+        // claude exits; pid-alive covers a hard-killed wrapper that never wrote it.
+        const exitCode = (0, jsonStreamHost_1.readExitCodeFile)(session.paths.exitCodeFile);
+        if (exitCode !== null || !(0, jsonStreamHost_1.checkIsPidAlive)(session.pid)) {
+            // Final drain — bytes flushed at process exit may postdate the read above.
+            try {
+                this.drainStdoutTail(session);
+            }
+            catch { /* already reported above */ }
+            this.finalizeExternalExit(session, exitCode ?? (0, jsonStreamHost_1.readExitCodeFile)(session.paths.exitCodeFile));
+            return;
+        }
+        this.settleAdoptCatchUp(session, false);
+        // Backstop: a busy session gone silent with nothing in flight lost its
+        // terminal `result` — clear the stuck flag so the typing indicator can't hang.
+        this.maybeClearBusyOnIdle(session);
+        const next = (0, pollBackoff_1.getNextPollDelay)({ isChanged, currentDelayMs: session.pollDelayMs, unchangedStreak: session.unchangedStreak });
+        session.unchangedStreak = next.unchangedStreak;
+        this.schedulePoll(session, next.delayMs);
+    }
+    /**
+     * @description Idle watchdog (bounded safety net). `isBusy` is cleared in
+     * exactly one place — a processed terminal `result` (`handleTurnEnd`) — so a
+     * single missed `result` (an aborted `interrupt`, a process gone quiet after
+     * the answer, a future CLI dropping the line) hangs the native typing
+     * indicator indefinitely. When the session is busy but stdout has been silent
+     * past {@link busyIdleWatchdogMs} and nothing is genuinely in flight, the turn
+     * has really ended: clear the flag. The pure decision + its rationale live in
+     * `utils/jsonStreamBusyWatchdog` — every in-flight signal (tool / sub-agent /
+     * question / batched answer) vetoes the clear, so a legitimately long-running
+     * turn is never truncated (a working agent never goes silent with nothing in
+     * flight — it streams deltas or waits on a tool/sub-agent/user).
+     */
+    maybeClearBusyOnIdle(session) {
+        const shouldClear = (0, jsonStreamBusyWatchdog_1.checkShouldClearBusyOnIdle)({
+            isBusy: session.isBusy,
+            msSinceStdoutActivity: Date.now() - session.lastStdoutActivityAt,
+            idleTimeoutMs: jsonStreamBusyWatchdog_1.busyIdleWatchdogMs,
+            outstandingToolCount: session.outstandingToolUseIds.size,
+            subagentActive: session.subagentActive,
+            hasPendingQuestion: session.pendingQuestion !== null,
+            hasUnflushedAnswer: session.currentResponseText.length !== session.emittedLength,
+        });
+        if (!shouldClear)
+            return;
+        console.warn(`[ClaudeJson] busy-idle watchdog: ${(0, sessionKey_1.keyToString)(session.key)} idle ${jsonStreamBusyWatchdog_1.busyIdleWatchdogMs}ms with nothing in flight — clearing stuck busy (missed terminal result?)`);
+        session.isBusy = false;
+        this.finishReasoning(session);
+        // The record must not keep saying "turn in flight": an adopt would restore the cleared flag.
+        this.jsonStreamTailWriter?.(session.key, buildTailRecord(session, session.lastPersistedTailOffset));
+    }
+    /**
+     * @description Read whatever `stdout.jsonl` grew since the last poll and feed
+     * it through the SAME decode → line-reader → classifier pipeline the stdio
+     * pipe used to feed. Returns whether anything new was consumed (drives the
+     * adaptive poll backoff). After consuming, persists the line-boundary tail
+     * offset so a bot restart resumes exactly where processing stopped.
+     */
+    drainStdoutTail(session) {
+        const size = (0, jsonStreamHost_1.getFileSize)(session.paths.stdoutFile);
+        if (size === null)
+            return false; // not created yet (claude still booting)
+        if (size > jsonStreamHost_1.stdoutOversizeWarnBytes && !session.isOversizeWarned) {
+            session.isOversizeWarned = true;
+            console.warn(`[ClaudeJson] stdout log for ${(0, sessionKey_1.keyToString)(session.key)} exceeds ${jsonStreamHost_1.stdoutOversizeWarnBytes} bytes (no rotation in v1)`);
+        }
+        const decision = (0, jsonStreamHost_1.getStdoutTailDecision)(session.tail, size);
+        if (decision.kind === 'reseed') {
+            // External truncation — the retained partial line died with the old file.
+            session.reader = new claudeStreamJson_1.ClaudeStreamLineReader();
+            return false;
+        }
+        if (decision.kind === 'none')
+            return false;
+        const chunk = (0, jsonStreamHost_1.readFileByteRange)(session.paths.stdoutFile, decision.startOffset, decision.endOffset);
+        if (chunk.length === 0)
+            return false;
+        const text = (0, jsonStreamHost_1.decodeStdoutTailChunk)(session.tail, chunk);
+        if (text) {
+            // Any new stdout — even a `tool_progress` frame the classifier ignores —
+            // means the process is alive and working; feed the idle watchdog's clock.
+            session.lastStdoutActivityAt = Date.now();
+            this.onStdout(session, text);
+        }
+        // Persist the consumption boundary ONLY when nothing sits in the answer /
+        // child batchers: the offset means "everything before here has LEFT the
+        // adapter", so text still waiting in a 350ms batch must hold it back —
+        // otherwise a reload in that window skips the batched text on replay
+        // (live seam-loss 2026-07-05: lines 216–221 were consumed
+        // into the batch, the offset moved past them, and the kill dropped them).
+        // A deferred persist happens in `flushAnswer` / the child flush, right
+        // after the batched text is emitted.
+        if (checkIsEmitCaughtUp(session))
+            this.persistTailOffset(session);
+        return true;
+    }
+    /** Persist the tail's line-boundary offset (monotonic; inert until the
+     *  writer is registered — same idiom as the seen-watermark writer). */
+    persistTailOffset(session) {
+        if (session.applyingChunk) {
+            session.applyingChunk.isPersistDeferred = true;
+            return;
+        }
+        const boundary = (0, jsonStreamHost_1.getStdoutLineBoundaryOffset)(session.tail, session.reader.pending);
+        if (boundary <= session.lastPersistedTailOffset)
+            return;
+        session.lastPersistedTailOffset = boundary;
+        this.jsonStreamTailWriter?.(session.key, buildTailRecord(session, boundary));
+    }
+    /**
+     * @description Single teardown convergence point for the external process —
+     * both the explicit stop (`isStopping` → `stopped`) and the poll tick's exit
+     * detection (→ `closed`, with the wrapper-reported exit code and a stderr
+     * excerpt). Kills any tmux leftovers, removes the host dir, and cleans the
+     * MCP temp files. A respawn owns its own transition (`isRespawning`).
+     */
+    finalizeExternalExit(session, exitCode) {
+        if (session.isRespawning)
+            return; // an effort/model re-spawn owns the transition
+        const key = session.key;
+        // Only act if this session is still the current one for the key.
+        if (this.sessions.get((0, sessionKey_1.keyToString)(key)) !== session)
+            return;
+        this.clearTimers(session);
+        session.isActive = false;
+        this.sessions.delete((0, sessionKey_1.keyToString)(key));
+        this.settleAdoptCatchUp(session, true);
+        this.closeFifo(session);
+        const stderrTail = session.isStopping ? '' : (0, jsonStreamHost_1.readStderrTail)(session.paths.stderrFile);
+        void (0, tmuxExec_1.tmuxAsync)('kill-session', '-t', (0, tmuxExec_1.getTmuxSessionTarget)((0, jsonStreamHost_1.buildJsonStreamTmuxSessionName)(key)));
+        try {
+            fs.rmSync(session.paths.dir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+        (0, mcpConfig_1.cleanupMcpTempFiles)({ key, dataDir: (0, state_1.resolveDataDir)() });
+        if (session.isSuspending) {
+            // The session id stays persisted: the next trigger resumes the conversation (L3).
+            console.log(`[ClaudeJson] session ${(0, sessionKey_1.keyToString)(key)} suspended (code=${exitCode})`);
+            this.emit('suspended', key);
+        }
+        else if (session.isStopping) {
+            console.log(`[ClaudeJson] session ${(0, sessionKey_1.keyToString)(key)} stopped (code=${exitCode})`);
+            this.emit('stopped', key);
+        }
+        else {
+            console.warn(`[ClaudeJson] session ${(0, sessionKey_1.keyToString)(key)} exited unexpectedly (code=${exitCode})${stderrTail ? ` stderr: ${stderrTail}` : ''}`);
+            this.emit('closed', key);
+        }
+    }
+    /** Close the FIFO fd AFTER any queued writes settle, so an in-flight write
+     *  never hits a closed fd (EBADF noise on every stop). */
+    closeFifo(session) {
+        const fd = session.fifoFd;
+        session.stdinWriteChain = session.stdinWriteChain
+            .catch(() => { })
+            .then(() => { try {
+            fs.closeSync(fd);
+        }
+        catch { /* already closed */ } });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    //  Reattach at boot (S3) — adopt the external process, resume the tail
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Scan tmux for `cjson-…` sessions that outlived the bot (mirror of the
+     *  scrape backend's scan). The bot decides adopt-vs-orphan per key — this
+     *  method only lists. */
+    async listExistingTmuxSessions() {
+        const raw = await (0, tmuxExec_1.tmuxAsync)('list-sessions', '-F', '#{session_name}');
+        if (!raw)
+            return [];
+        const result = [];
+        for (const name of raw.split('\n').map((s) => s.trim()).filter(Boolean)) {
+            const key = (0, jsonStreamHost_1.parseJsonStreamTmuxSessionName)(name);
+            if (key)
+                result.push({ key, sessionName: name });
+        }
+        return result;
+    }
+    /** Kill an orphan `cjson-…` tmux session AND its host dir (the dir is
+     *  per-thread, derived from the parsed name; an unparseable name only
+     *  kills the tmux session). */
+    async killOrphanTmuxSession(sessionName) {
+        console.log(`[ClaudeJson] kill orphan tmux session: ${sessionName}`);
+        await (0, tmuxExec_1.tmuxAsync)('kill-session', '-t', (0, tmuxExec_1.getTmuxSessionTarget)(sessionName));
+        const key = (0, jsonStreamHost_1.parseJsonStreamTmuxSessionName)(sessionName);
+        if (!key)
+            return;
+        try {
+            fs.rmSync((0, jsonStreamHost_1.resolveJsonStreamSessionDir)((0, state_1.resolveDataDir)(), key), { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    }
+    /**
+     * @description Adopt an external json-stream process that survived a bot
+     * restart: reopen the stdin FIFO writer and resume the stdout tail from the
+     * persisted line-boundary offset — everything claude produced during the
+     * downtime replays through the normal pipeline, so the in-flight turn is
+     * delivered end-to-end (which is why the bot posts NO reattach recap for an
+     * adopt). An unknown / foreign-session offset seeds to the CURRENT EOF (no
+     * backlog flood — the first-migration case). No initialize handshake — the
+     * surviving process completed it at spawn; a pending question is restored
+     * from the sidecar so its buttons stay answerable. Returns `false` — after
+     * killing the leftovers — when the process is dead (exitcode present / pid
+     * gone / FIFO unheld): the caller falls back to the dead-process `--resume`
+     * reopen.
+     */
+    async adoptExistingTmuxSession(key, sessionName, workDir, claudeSessionId, persistedTail) {
+        const names = await (0, tmuxExec_1.tmuxAsync)('list-sessions', '-F', '#{session_name}');
+        if (!names.split('\n').includes(sessionName)) {
+            console.log(`[ClaudeJson] adopt: tmux session ${sessionName} no longer exists`);
+            return false;
+        }
+        const k = (0, sessionKey_1.keyToString)(key);
+        if (this.sessions.has(k)) {
+            console.log(`[ClaudeJson] adopt: already tracking ${k}, skipping`);
+            return true;
+        }
+        const sessionDir = (0, jsonStreamHost_1.resolveJsonStreamSessionDir)((0, state_1.resolveDataDir)(), key);
+        const paths = (0, jsonStreamHost_1.getJsonStreamSessionPaths)(sessionDir);
+        const pid = (0, jsonStreamHost_1.readPidFile)(paths.pidFile);
+        const exitCode = (0, jsonStreamHost_1.readExitCodeFile)(paths.exitCodeFile);
+        if (pid === null || exitCode !== null || !(0, jsonStreamHost_1.checkIsPidAlive)(pid)) {
+            console.log(`[ClaudeJson] adopt: ${sessionName} process is dead (pid=${pid} exit=${exitCode}), cleaning up`);
+            await this.killOrphanTmuxSession(sessionName);
+            return false;
+        }
+        const fifoFd = await (0, jsonStreamHost_1.openFifoWriterNonBlocking)(paths.stdinFifo);
+        if (fifoFd === null) {
+            console.log(`[ClaudeJson] adopt: ${sessionName} is not holding its stdin FIFO, cleaning up`);
+            await this.killOrphanTmuxSession(sessionName);
+            return false;
+        }
+        const size = (0, jsonStreamHost_1.getFileSize)(paths.stdoutFile) ?? 0;
+        const { startOffset, backgroundTaskIds, isTurnInFlight, outstandingToolUseIds, claudeCodeVersion } = (0, jsonStreamHost_1.resolveAdoptedTail)(persistedTail, claudeSessionId, size);
+        console.log(`[ClaudeJson] adopt: re-attaching to ${sessionName} in ${workDir} (pid=${pid}, tail=${startOffset}/${size})`);
+        const session = {
+            key, workDir, sessionId: claudeSessionId,
+            pid, paths, fifoFd,
+            stdinWriteChain: Promise.resolve(),
+            tail: (0, jsonStreamHost_1.createStdoutTailState)(startOffset),
+            pollTimer: null, pollDelayMs: pollBackoff_1.basePollIntervalMs, unchangedStreak: 0,
+            isOversizeWarned: false, lastPersistedTailOffset: startOffset,
+            reader: new claudeStreamJson_1.ClaudeStreamLineReader(),
+            // isBusy starts from the PERSISTED turn-in-flight flag: a turn in a long, silent
+            // tool call leaves no frame after the tail offset to rebuild it from. The
+            // replayed/live events then keep it right (deltas/toolUse set it, `result`
+            // clears it) — see `applyAction`.
+            isActive: true, isStopping: false, isSuspending: false, isRespawning: false, isBusy: isTurnInFlight, unconsumedInputCount: 0,
+            // The outstanding tools come from the record too: they veto the busy-idle watchdog, which would
+            // otherwise clear the restored turn after its silence window and let the stale-tool stop kill it.
+            lastStdoutActivityAt: Date.now(), outstandingToolUseIds: new Set(outstandingToolUseIds),
+            model: null, reportedModel: null, effort: null,
+            // The account the surviving process runs on is in its own wrapper; the bot compares it with the topic's pick.
+            configDir: (0, jsonStreamHost_1.readWrapperScriptConfigDir)(paths.wrapperFile), isConfigDirSwitchPending: false,
+            currentResponseText: '', emittedLength: 0, outputTimer: null,
+            reasoningText: '', reasoningStartedAt: null, reasoningTimer: null, reasoningActive: false,
+            toolNamesById: new Map(), questionToolUseIds: new Set(),
+            subagentActive: false, childResponseText: '', childEmittedLength: 0, childOutputTimer: null,
+            pendingInitResolve: null, initRequestId: null, pendingControlRequests: new Map(),
+            compactionInProgress: false, pendingCompaction: null,
+            pendingQuestion: this.readQuestionSidecar(paths),
+            apiErrorFired: false, swallowNextAbortError: false,
+            lastWatermarkOffset: -1,
+            // The frames that built the list and reported the version lie before the
+            // tail offset (not replayed): both come from the persisted record.
+            backgroundTaskIds: new Set(backgroundTaskIds), claudeCodeVersion, applyingChunk: null,
+            // Nothing to catch up on when the tail already sits at EOF.
+            adoptCatchUpOffset: startOffset < size ? size : null, adoptCatchUpResolvers: [],
+        };
+        if (session.pendingQuestion) {
+            // The external process is still blocked on this question — busy, and the
+            // question's internal tool_result echo must stay suppressed after answer.
+            session.isBusy = true;
+            session.questionToolUseIds.add(session.pendingQuestion.toolUseId);
+        }
+        this.sessions.set(k, session);
+        this.schedulePoll(session, pollBackoff_1.basePollIntervalMs);
+        this.emit('started', key);
+        return true;
+    }
+    /**
+     * @description Resolves once an ADOPTED session's tail has consumed what its
+     * stdout held at the adopt — the replayed frames have rebuilt the live state
+     * (busy, tasks, input) — or once the session is gone. Immediate for a session
+     * that was not adopted or whose tail already sat at EOF. The stale-tool-list
+     * stop (L4) looks only after this: a look before it would read a turn in flight
+     * as idle.
+     */
+    whenAdoptReplayed(key) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session || session.adoptCatchUpOffset === null)
+            return Promise.resolve();
+        return new Promise((resolve) => { session.adoptCatchUpResolvers.push(resolve); });
+    }
+    /** Settle the adopt catch-up once the tail consumed up to the adopt-time EOF (or the session ended). */
+    settleAdoptCatchUp(session, isSessionGone) {
+        if (session.adoptCatchUpOffset === null)
+            return;
+        if (!isSessionGone && session.tail.consumedBytes < session.adoptCatchUpOffset)
+            return;
+        session.adoptCatchUpOffset = null;
+        const resolvers = session.adoptCatchUpResolvers.splice(0);
+        for (const resolve of resolvers)
+            resolve();
+    }
+    /** Restore a pending question persisted by a previous bot life (see
+     *  {@link writeQuestionSidecar}). Parse-boundary narrowing; the questions
+     *  array re-runs the same validator as a live control_request, so a corrupt
+     *  sidecar yields `null`, never a malformed pending question. */
+    readQuestionSidecar(paths) {
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(paths.questionFile, 'utf8'));
+        }
+        catch {
+            return null; // absent (the common case) or corrupt
+        }
+        if (!(0, claudeStreamJson_1.checkIsStreamRecord)(parsed))
+            return null;
+        const { requestId, toolUseId, rawInput, questions } = parsed;
+        if (typeof requestId !== 'string' || typeof toolUseId !== 'string')
+            return null;
+        if (!(0, claudeStreamJson_1.checkIsStreamRecord)(rawInput) || !Array.isArray(questions))
+            return null;
+        const revalidated = this.parseQuestions({ questions });
+        if (revalidated.length === 0)
+            return null;
+        return { requestId, toolUseId, rawInput, questions: revalidated };
+    }
+    performInitialize(session) {
+        const requestId = 'init_' + (0, crypto_1.randomUUID)();
+        session.initRequestId = requestId;
+        const request = {
+            type: 'control_request',
+            request_id: requestId,
+            request: { subtype: 'initialize', supportedDialogKinds: ['refusal_fallback_prompt'] },
+        };
+        return new Promise((resolve) => {
+            let settled = false;
+            const done = () => { if (!settled) {
+                settled = true;
+                session.pendingInitResolve = null;
+                resolve();
+            } };
+            session.pendingInitResolve = done;
+            this.writeStdin(session, request);
+            setTimeout(() => {
+                if (!settled)
+                    console.warn(`[ClaudeJson] initialize handshake timed out for ${(0, sessionKey_1.keyToString)(session.key)} — questions may be unavailable`);
+                done();
+            }, initializeHandshakeTimeoutMs);
+        });
+    }
+    stopSession(key) {
+        void this.stopSessionInternal(key);
+    }
+    /**
+     * @description Stop the process but KEEP the session resumable (lifecycle plan
+     * L3): the same teardown as a stop (SIGTERM, tmux kill, host dir removed —
+     * L-D13), converging on `suspended` instead of `stopped`, so the bot keeps the
+     * persisted id and the retry / compaction state the stop would drop. The caller
+     * checks `checkIsWorking` first — a suspend kills a background task like any
+     * stop. Joins a stop already in flight.
+     */
+    async suspendSession(key) {
+        await this.stopSessionInternal(key, { isSuspend: true });
+    }
+    async stopSessionInternal(key, options = { isSuspend: false }) {
+        const k = (0, sessionKey_1.keyToString)(key);
+        const inFlight = this.stopsInFlight.get(k);
+        if (inFlight)
+            return inFlight; // join the running stop instead of racing it
+        const session = this.sessions.get(k);
+        if (!session)
+            return;
+        const stopPromise = this.performStop(session, options).finally(() => { this.stopsInFlight.delete(k); });
+        this.stopsInFlight.set(k, stopPromise);
+        return stopPromise;
+    }
+    /** Explicit stop = hard-kill the EXTERNAL process (released sessions are
+     *  never adopted — locked decision): SIGTERM the pid, kill the tmux session,
+     *  then converge through {@link finalizeExternalExit} (dir removal + `stopped`,
+     *  or `suspended` for an idle stop that keeps the session resumable). */
+    async performStop(session, options) {
+        // Reject a pending question server-side before teardown so the model's
+        // AskUserQuestion turn is unblocked (deny), mirroring OpenCode's reject.
+        this.rejectQuestion(session.key);
+        session.isStopping = true;
+        session.isSuspending = options.isSuspend;
+        // Let the reject (and any queued frame) reach the FIFO before the kill.
+        await session.stdinWriteChain.catch(() => { });
+        try {
+            process.kill(session.pid, 'SIGTERM');
+        }
+        catch { /* already gone */ }
+        await (0, tmuxExec_1.tmuxAsync)('kill-session', '-t', (0, tmuxExec_1.getTmuxSessionTarget)((0, jsonStreamHost_1.buildJsonStreamTmuxSessionName)(session.key)));
+        this.finalizeExternalExit(session, null);
+    }
+    checkIsActive(key) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        return session?.isActive === true;
+    }
+    checkIsBusy(key) {
+        return this.sessions.get((0, sessionKey_1.keyToString)(key))?.isBusy === true;
+    }
+    checkHasUnconsumedInput(key) {
+        return (this.sessions.get((0, sessionKey_1.keyToString)(key))?.unconsumedInputCount ?? 0) > 0;
+    }
+    /**
+     * @description Whether the process is WORKING and must not be stopped (L-D2):
+     * a running turn, a background task the CLI still runs (background Bash /
+     * Monitor / sub-agent — a stop kills them, and a finished one starts its own
+     * turn), input written but not yet taken in, or a bot-issued compaction in
+     * flight. An unknown / inactive session is not working.
+     */
+    checkIsWorking(key) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive)
+            return false;
+        return session.isBusy || this.checkHasBackgroundWork(key);
+    }
+    /** Background tasks, input not yet taken in, a compaction in flight — "working" minus the turn (L-D2). */
+    checkHasBackgroundWork(key) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive)
+            return false;
+        return session.backgroundTaskIds.size > 0
+            || session.unconsumedInputCount > 0
+            || session.compactionInProgress;
+    }
+    /** The CLI version the live process reported on `system/init`, `null` until then (L-D10 gate input). */
+    getClaudeCodeVersion(key) {
+        return this.sessions.get((0, sessionKey_1.keyToString)(key))?.claudeCodeVersion ?? null;
+    }
+    /** L-D10: only a CLI that reports the background-task list may be stopped automatically. */
+    checkIsAutoStopSupported(key) {
+        return (0, claudeCodeVersion_1.checkIsClaudeAutoStopSupported)(this.getClaudeCodeVersion(key));
+    }
+    async getRuntimeInfo(key) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive) {
+            return { version: null, model: null, contextWindowTokens: null, contextUsedTokens: null };
+        }
+        const filePath = (0, claudeCliAdapter_1.getClaudeTranscriptPath)(session.workDir, session.sessionId);
+        try {
+            return await (0, claudeRuntimeInfo_1.readClaudeRuntimeInfo)(filePath);
+        }
+        catch {
+            return { version: null, model: null, contextWindowTokens: null, contextUsedTokens: null };
+        }
+    }
+    getClaudeSessionId(key) {
+        return this.sessions.get((0, sessionKey_1.keyToString)(key))?.sessionId ?? null;
+    }
+    /**
+     * @description Real, CONFIRMED compaction on the json-stream backend (F3):
+     * send `/compact` (or `/compact <instruction>` for F2's closing section) as a
+     * stream-json user turn — the CLI parses the slash command, compacts, and
+     * reports the outcome on a `compact_boundary` (success, with token counts) /
+     * a failing `compact_status` frame. The whole turn's own output is suppressed
+     * (`compactionInProgress`) so only the bot's confirmation shows. Resolves the
+     * {@link CompactionResult} — a success carrying the boundary frame's pre/post
+     * token counts (`null` when only `compact_status success` was seen) — awaiting
+     * the terminal signal so the caller can post its notice AFTER the context was
+     * really compacted.
+     */
+    async compactContext(key, instruction) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive)
+            return { ok: false, error: (0, i18n_1.t)('compact.start_agent_first') };
+        if (session.pendingCompaction) {
+            return { ok: false, error: (0, i18n_1.t)('compact.failed', { reason: 'a compaction is already running' }) };
+        }
+        if (session.isBusy)
+            return { ok: false, error: (0, i18n_1.t)('compact.busy') };
+        const trimmed = instruction?.trim();
+        const text = trimmed ? `/compact ${trimmed}` : '/compact';
+        const startedAt = Date.now();
+        const result = await new Promise((resolve) => {
+            // Bounded by SILENCE, not by elapsed time. A flat 3-minute cap on total
+            // elapsed time is what made idle compaction look mute: a real 3 min 15.6 s
+            // compaction (`compact_metadata.duration_ms: 195649`) was declared failed
+            // while the CLI was succeeding, so the notice was never posted. Summarising
+            // scales with the context being summarised, and compact-on-idle exists FOR
+            // big contexts — any fixed cap fails exactly where the feature matters.
+            // While it works the CLI heartbeats `system/status status:"compacting"`
+            // every few seconds, so real silence is the honest death signal.
+            const timer = setInterval(() => {
+                const verdict = (0, jsonStreamBusyWatchdog_1.getCompactionWaitVerdict)({
+                    msSinceStdoutActivity: Date.now() - session.lastStdoutActivityAt,
+                    msSinceCompactionStarted: Date.now() - startedAt,
+                    silenceTimeoutMs: jsonStreamBusyWatchdog_1.compactionSilenceTimeoutMs,
+                    absoluteTimeoutMs: jsonStreamBusyWatchdog_1.compactionAbsoluteTimeoutMs,
+                });
+                if (verdict === 'keepWaiting')
+                    return;
+                const outcome = (0, jsonStreamBusyWatchdog_1.getCompactionTimeoutOutcome)({
+                    verdict,
+                    sawSuccess: session.pendingCompaction?.sawSuccess === true,
+                });
+                if (outcome.kind === 'succeededWithoutTokenCounts') {
+                    this.resolveCompaction(session, { ok: true, preTokens: null, postTokens: null });
+                    return;
+                }
+                this.resolveCompaction(session, {
+                    ok: false,
+                    error: outcome.reason === 'silent'
+                        ? `the CLI went silent for ${Math.round(jsonStreamBusyWatchdog_1.compactionSilenceTimeoutMs / 1000)}s without confirming the compaction`
+                        : `the compaction did not finish within ${Math.round(jsonStreamBusyWatchdog_1.compactionAbsoluteTimeoutMs / 60_000)} min`,
+                });
+            }, jsonStreamBusyWatchdog_1.compactionWaitPollMs);
+            timer.unref?.();
+            session.pendingCompaction = { resolve, timer, sawSuccess: false };
+            session.compactionInProgress = true;
+            // Fresh turn: reset the answer cursor + idle-watchdog clock, mark busy.
+            session.currentResponseText = '';
+            session.emittedLength = 0;
+            session.isBusy = true;
+            session.lastStdoutActivityAt = Date.now();
+            // Not counted as unconsumed input: a bot-issued `/compact` is a control
+            // turn whose echo is not guaranteed, and it only runs on an idle session.
+            this.writeStdin(session, { type: 'user', message: { role: 'user', content: text } });
+        });
+        if (result.ok) {
+            console.log(`[ClaudeJson] compacted ${(0, sessionKey_1.keyToString)(key)} (pre=${result.preTokens ?? '?'} post=${result.postTokens ?? '?'})`);
+            return result;
+        }
+        console.warn(`[ClaudeJson] compaction failed for ${(0, sessionKey_1.keyToString)(key)}: ${result.error}`);
+        // The raw internal reason is wrapped into the user-facing template HERE (not at
+        // the resolve sites) so every failure path reads the same way in the topic.
+        return { ok: false, error: (0, i18n_1.t)('compact.failed', { reason: result.error }) };
+    }
+    /**
+     * @description Read the newest compaction summary from the on-disk transcript
+     * (the `isCompactSummary:true` message) so F2 can lift its appended closing
+     * section into the idle-compaction notice. Returns `null` when the session is
+     * inactive, the transcript is unreadable, or no summary is present.
+     */
+    async getLatestCompactionSummary(key) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive)
+            return null;
+        return readLatestCompactSummaryFromTranscript((0, claudeCliAdapter_1.getClaudeTranscriptPath)(session.workDir, session.sessionId));
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    //  Input (S3)
+    // ─────────────────────────────────────────────────────────────────────────
+    sendInput(key, input) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive) {
+            console.warn(`[ClaudeJson] sendInput to inactive session ${(0, sessionKey_1.keyToString)(key)} dropped`);
+            return;
+        }
+        // A fresh user turn begins → reset the answer cursor so its first tail is a
+        // new message (the bot also flips `needsNewMessage` for delta adapters).
+        session.currentResponseText = '';
+        session.emittedLength = 0;
+        session.apiErrorFired = false;
+        session.isBusy = true;
+        // A fresh turn resets the idle-watchdog clock: without this a session that
+        // sat idle for minutes (busy=false, clock stale) would trip the watchdog on
+        // its very next poll — before claude has a chance to emit the first token.
+        session.lastStdoutActivityAt = Date.now();
+        // The turn in flight is persisted at once (same offset, flipped flag): a restart
+        // during a long, silent tool call finds no frame after the offset to rebuild it.
+        this.jsonStreamTailWriter?.(key, buildTailRecord(session, session.lastPersistedTailOffset));
+        this.writeUserMessage(session, input);
+    }
+    sendSignal(key, _signal) {
+        this.sendInterrupt(key);
+    }
+    sendEscape(key) {
+        this.sendInterrupt(key);
+    }
+    sendInterrupt(key) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive)
+            return;
+        this.writeStdin(session, {
+            type: 'control_request',
+            request_id: 'interrupt_' + (0, crypto_1.randomUUID)(),
+            request: { subtype: 'interrupt' },
+        });
+        // An interrupt ABORTS the current turn. The CLI does not reliably emit a
+        // terminal `result` for an aborted turn, so clearing `isBusy` here (rather
+        // than waiting on the idle watchdog) makes the explicit stop deterministic —
+        // the typing indicator drops immediately. If output resumes, a delta re-arms
+        // busy; if a `result` does arrive, `handleTurnEnd` is a harmless no-op.
+        session.isBusy = false;
+        session.outstandingToolUseIds.clear();
+        // When the CLI DOES emit a terminal `result{is_error}` for this abort, it
+        // carries no text → `claudeStreamJson` labels it the literal `'API error'`.
+        // Arm the one-shot so `handleTurnEnd` swallows it instead of relaying a bogus
+        // "Claude error: API error" (the reported triple-message on question-cancel,
+        // and any bare `/esc` mid-turn). Consumed by the next `handleTurnEnd`.
+        session.swallowNextAbortError = true;
+    }
+    /** Write one user turn, counting it until Claude echoes it back (it has read it). */
+    writeUserMessage(session, content) {
+        session.unconsumedInputCount += 1;
+        this.writeStdin(session, { type: 'user', message: { role: 'user', content } });
+    }
+    /** Enqueue one stream-json frame onto the stdin FIFO. Fire-and-forget for
+     *  callers (sync signature preserved); the per-session chain keeps wire
+     *  order and absorbs transient `EAGAIN` (see `writeFifoText`). */
+    writeStdin(session, obj) {
+        const line = JSON.stringify(obj) + '\n';
+        session.stdinWriteChain = session.stdinWriteChain
+            .then(() => (0, jsonStreamHost_1.writeFifoText)(session.fifoFd, line))
+            .catch((e) => console.error(`[ClaudeJson] stdin write failed for ${(0, sessionKey_1.keyToString)(session.key)}:`, e instanceof Error ? e.message : e));
+        // New input → output expected shortly; snap the tail poll back to base.
+        this.snapPollToBase(session);
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    //  Output parsing (S2) + control channel (S4)
+    // ─────────────────────────────────────────────────────────────────────────
+    onStdout(session, chunk) {
+        const applyingChunk = { isPersistDeferred: false };
+        session.applyingChunk = applyingChunk;
+        try {
+            this.applyStdoutLines(session, session.reader.push(chunk));
+        }
+        finally {
+            session.applyingChunk = null;
+        }
+        // A persist a handler asked for mid-chunk (see `applyingChunk`) runs now,
+        // under the same emit-caught-up gate the drain applies.
+        if (applyingChunk.isPersistDeferred && checkIsEmitCaughtUp(session))
+            this.persistTailOffset(session);
+    }
+    applyStdoutLines(session, lines) {
+        for (const line of lines) {
+            const msg = (0, claudeStreamJson_1.parseStreamJsonLine)(line);
+            if (!msg)
+                continue;
+            for (const action of (0, claudeStreamJson_1.classifyClaudeStreamMessage)(msg)) {
+                this.applyAction(session, action);
+            }
+            // S7: advance the seen-watermark as each PARENT assistant message settles
+            // (is relayed), not only at turn end. The external process normally
+            // SURVIVES a bot restart now (adopt replays the stdout tail — no recap),
+            // but when the process itself DIES mid-turn the dead-process `--resume`
+            // fallback recaps from this watermark: without the per-message advance
+            // the aborted turn's already-relayed assistant messages would re-count
+            // as a false "missed N" (same shared recap reader as the tmux backend,
+            // the 2026-07-04 bug). A settled `assistant` message is on disk here, so
+            // the transcript EOF includes it. A CHILD (sub-agent) message
+            // (`parent_tool_use_id` set) must never advance the watermark.
+            if (msg.type === 'assistant' && msg.parent_tool_use_id == null) {
+                this.advanceWatermarkFromTranscript(session);
+            }
+        }
+    }
+    /**
+     * @description Settle the CLI's reply to a control_request the BOT wrote,
+     * matched by `request_id`: the spawn-time `initialize` handshake, plus the MCP
+     * heal's `mcp_status` / `mcp_reconnect` round-trips. A response for an id we
+     * are not waiting on belongs to nothing of ours — ignore it rather than guess
+     * which awaiter it might settle.
+     */
+    handleControlResponse(session, action) {
+        if (session.pendingInitResolve && action.requestId === session.initRequestId) {
+            session.pendingInitResolve();
+            return;
+        }
+        const pending = session.pendingControlRequests.get(action.requestId);
+        if (!pending)
+            return;
+        session.pendingControlRequests.delete(action.requestId);
+        clearTimeout(pending.timer);
+        pending.resolve({ isSuccess: action.isSuccess, payload: action.payload });
+    }
+    /**
+     * @description Write ONE bot-issued control_request and resolve with its
+     * `control_response`, or `null` when none arrives within
+     * {@link mcpControlRequestTimeoutMs}. The reply comes back through the normal
+     * stdout-tail → classifier path (the CLI answers on the same stdio control
+     * channel `can_use_tool` uses), so the bounded timer is what keeps a silent
+     * CLI from hanging the caller. Never rejects: an unanswered request is an
+     * unknown, not an error.
+     *
+     * A session that is no longer the live one for its key gets NOTHING written:
+     * its fd is closed (and its number reusable), so a write after teardown could
+     * land in an unrelated file — and no reply could ever settle the awaiter
+     * anyway. Same identity guard as the poll tick and the exit finalizer.
+     */
+    requestControl(session, requestId, frame) {
+        if (!session.isActive || this.sessions.get((0, sessionKey_1.keyToString)(session.key)) !== session)
+            return Promise.resolve(null);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                // Only the entry still parked here is ours to time out — a response that
+                // landed first already removed it (and resolved).
+                if (!session.pendingControlRequests.delete(requestId))
+                    return;
+                resolve(null);
+            }, claudeMcpHeal_1.mcpControlRequestTimeoutMs);
+            timer.unref?.();
+            session.pendingControlRequests.set(requestId, { resolve, timer });
+            this.writeStdin(session, frame);
+        });
+    }
+    /**
+     * @description Heal the bot's own injected MCP server inside this LIVE session:
+     * ask `mcp_status`, and reconnect the server ONLY when it reports `failed`
+     * (the latched state a bot restart leaves behind — the CLI never retries it,
+     * so the bot's tools stay gone for the rest of the session). `connected` is
+     * left strictly alone, and any other status (`needs-auth`, an unknown future
+     * one) is skipped rather than guessed at — see `decideMcpHeal`.
+     *
+     * Control frames only: nothing written here can be read as a user turn, the
+     * session is never marked busy, and the pending-request map is keyed by
+     * `request_id` so the `can_use_tool` / `interrupt` paths are untouched.
+     *
+     * `healed` is reported off the reconnect's own ack, and that ack is MEASURED to
+     * be both synchronous and honest — so no confirming third round-trip is needed
+     * and adding one would only be ceremony. Against a still-dead endpoint the
+     * reconnect answers `{subtype:'error', error:'ECONNREFUSED…'}` (never a hollow
+     * success), and after a successful one an IMMEDIATELY following `mcp_status`
+     * already reads `connected`. Do not re-litigate this as a missing verification.
+     */
+    async healMcpServer(key, serverName) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive)
+            return 'unavailable';
+        const statusRequestId = 'mcp_status_' + (0, crypto_1.randomUUID)();
+        const status = await this.requestControl(session, statusRequestId, (0, claudeMcpHeal_1.buildMcpStatusControlRequest)(statusRequestId));
+        // No answer (timeout) or an `error` verdict: nothing is known about the
+        // server, so nothing may be done to it.
+        if (!status?.isSuccess)
+            return 'unavailable';
+        const decision = (0, claudeMcpHeal_1.decideMcpHeal)((0, claudeMcpHeal_1.getMcpServerStatus)(status.payload, serverName));
+        if (decision === 'healthy')
+            return 'healthy';
+        if (decision === 'skip')
+            return 'skipped';
+        const reconnectRequestId = 'mcp_reconnect_' + (0, crypto_1.randomUUID)();
+        const reconnect = await this.requestControl(session, reconnectRequestId, (0, claudeMcpHeal_1.buildMcpReconnectControlRequest)(reconnectRequestId, serverName));
+        // `mcp_reconnect` answers a bare success ack (no inner record); anything
+        // else means the reconnect did not land, so the server is still broken.
+        return reconnect?.isSuccess === true ? 'healed' : 'unavailable';
+    }
+    applyAction(session, action) {
+        // A bot-issued `/compact` turn produces its own noise ("Not enough messages
+        // to compact.", the summarisation itself) — suppress ALL of it so only the
+        // bot's confirmation shows. The compact_* frames + turn end still drive the
+        // awaiter; a stray provider error still surfaces. (A CLI-side AUTO compaction
+        // during a normal turn is NOT gated here — `compactionInProgress` is only set
+        // by our own `compactContext`, and `pendingCompaction` guards the handlers.)
+        if (session.compactionInProgress) {
+            switch (action.kind) {
+                case 'turnEnd':
+                    this.handleTurnEnd(session, action);
+                    return;
+                case 'compactStatus':
+                    this.handleCompactStatus(session, action);
+                    return;
+                case 'compactBoundary':
+                    this.handleCompactBoundary(session, action);
+                    return;
+                case 'init':
+                    this.handleInit(session, action);
+                    return;
+                case 'backgroundTasks':
+                    this.handleBackgroundTasks(session, action);
+                    return;
+                case 'apiRetry':
+                    this.maybeEmitApiError(session, action.text);
+                    return;
+                // A reply to one of OUR control requests is never the compaction turn's
+                // output — its awaiter must settle whatever else is running.
+                case 'controlResponse':
+                    this.handleControlResponse(session, action);
+                    return;
+                default: return; // swallow text / thinking / tool / toolResult / control / echo
+            }
+        }
+        switch (action.kind) {
+            case 'init':
+                // Per-turn `init` re-emits; the id is fixed by our `--session-id`, so the
+                // id itself is nothing to act on. The MODEL it carries is load-bearing:
+                // it is the only report of what claude actually runs. Without capturing
+                // it `/status` and the pinned banner showed no model at all on a default
+                // start / resume / adopt (nothing ever set the `--model` pick).
+                this.handleInit(session, action);
+                return;
+            case 'backgroundTasks':
+                this.handleBackgroundTasks(session, action);
+                return;
+            case 'textDelta':
+                // Mid-turn activity marks the session busy: `sendInput` normally set it,
+                // but an ADOPTED session (bot restart mid-turn) reconstructs the busy
+                // state purely from the replayed/live events; `turnEnd` clears it.
+                session.isBusy = true;
+                if (action.isSubagent)
+                    this.handleSubagentText(session, action.text);
+                else
+                    this.appendAnswerDelta(session, action.text);
+                return;
+            case 'thinkingDelta':
+                session.isBusy = true;
+                if (action.isSubagent)
+                    return; // child reasoning never rendered (parity)
+                this.appendThinkingDelta(session, action.text);
+                return;
+            case 'toolUse':
+                session.isBusy = true;
+                this.handleToolUse(session, action);
+                return;
+            case 'toolResult':
+                this.handleToolResult(session, action);
+                return;
+            case 'turnEnd':
+                this.handleTurnEnd(session, action);
+                return;
+            case 'controlRequest':
+                this.handleControlRequest(session, action);
+                return;
+            case 'controlResponse':
+                this.handleControlResponse(session, action);
+                return;
+            case 'apiRetry':
+                this.maybeEmitApiError(session, action.text);
+                return;
+            case 'compactStatus':
+                // A CLI-side auto-compaction (no bot-issued `/compact`) — no awaiter to
+                // resolve, so this is a no-op; the guard lives in the handler.
+                this.handleCompactStatus(session, action);
+                return;
+            case 'compactBoundary':
+                this.handleCompactBoundary(session, action);
+                return;
+            case 'rateLimit':
+                // Subscription usage-window signal; not surfaced to the topic (parity) — handed to the bot's usage
+                // cache for the profile this process runs on.
+                this.claudeRateLimitSink?.(session.configDir, {
+                    status: action.status, rateLimitType: action.rateLimitType, resetsAtMs: action.resetsAtMs, windows: action.windows,
+                });
+                return;
+            case 'userEcho':
+                // Claude has read one of our user messages. A message written mid-turn
+                // is taken into the RUNNING turn, so the session is busy from here until
+                // the turn's `result`, even if an earlier `result` already cleared it.
+                session.unconsumedInputCount = Math.max(0, session.unconsumedInputCount - 1);
+                session.isBusy = true;
+                return;
+        }
+    }
+    handleInit(session, action) {
+        if (action.model)
+            session.reportedModel = action.model;
+        if (action.claudeCodeVersion)
+            session.claudeCodeVersion = action.claudeCodeVersion;
+    }
+    /** Replace the live background-task list with the frame's (it is re-sent
+     *  WHOLE on every change, so no diffing). The tail-offset persist that follows
+     *  this frame's drain carries the new list to `state.json`. */
+    handleBackgroundTasks(session, action) {
+        session.backgroundTaskIds = new Set(action.taskIds);
+    }
+    // — compaction (F3) —
+    handleCompactStatus(session, action) {
+        const pending = session.pendingCompaction;
+        if (!pending)
+            return;
+        if (action.result === 'success') {
+            // Wait for the boundary frame (it carries the pre/post token counts).
+            pending.sawSuccess = true;
+            return;
+        }
+        // Any non-success result (e.g. "not enough messages") is a failure.
+        this.resolveCompaction(session, {
+            ok: false,
+            error: action.error ?? action.result ?? 'compaction did not run',
+        });
+    }
+    handleCompactBoundary(session, action) {
+        if (!session.pendingCompaction) {
+            // The CLI's own compaction (a context overflow mid-turn, or one met while replaying the downtime tail):
+            // nobody waits for it, but the conversation's context was replaced all the same.
+            this.emit('contextCompacted', session.key, action.trigger);
+            return;
+        }
+        this.resolveCompaction(session, { ok: true, preTokens: action.preTokens, postTokens: action.postTokens }, action.trigger);
+    }
+    /**
+     * Resolve (and clear) the in-flight compaction awaiter exactly once. Every way a bot-issued compaction can
+     * succeed (its boundary, its turn end, the timeout that saw its success) ends here, so a success is told
+     * once as `contextCompacted`.
+     */
+    resolveCompaction(session, result, trigger = null) {
+        const pending = session.pendingCompaction;
+        if (!pending)
+            return;
+        session.pendingCompaction = null;
+        session.compactionInProgress = false;
+        if (pending.timer)
+            clearInterval(pending.timer);
+        pending.resolve(result);
+        if (result.ok)
+            this.emit('contextCompacted', session.key, trigger);
+    }
+    // — answer text —
+    appendAnswerDelta(session, text) {
+        // Reasoning is over the moment the answer starts (Claude closes the thinking
+        // block before the text block).
+        this.finishReasoning(session);
+        session.currentResponseText += text;
+        if (session.outputTimer)
+            return; // a flush is already scheduled
+        session.outputTimer = setTimeout(() => {
+            session.outputTimer = null;
+            this.flushAnswer(session, false);
+        }, streamOutputBatchMs);
+    }
+    flushAnswer(session, isFinal) {
+        if (session.outputTimer) {
+            clearTimeout(session.outputTimer);
+            session.outputTimer = null;
+        }
+        const tail = session.currentResponseText.slice(session.emittedLength);
+        if (tail) {
+            session.emittedLength = session.currentResponseText.length;
+            const meta = isFinal ? { isFinal: true } : {};
+            // NO isContinuation: `outputsDeltas` adapters let the transports synthesise it.
+            this.emit('output', session.key, tail, meta);
+        }
+        // The answer batcher is drained — the held-back consumption boundary is now
+        // safe to persist (see `drainStdoutTail`).
+        if (checkIsEmitCaughtUp(session))
+            this.persistTailOffset(session);
+    }
+    // — reasoning / thinking —
+    appendThinkingDelta(session, text) {
+        if (!session.reasoningActive) {
+            session.reasoningActive = true;
+            session.reasoningStartedAt = Date.now();
+            session.reasoningText = '';
+        }
+        session.reasoningText += text;
+        if (session.reasoningTimer)
+            return;
+        session.reasoningTimer = setTimeout(() => {
+            session.reasoningTimer = null;
+            this.emit('thinking', session.key, { phase: 'live', text: session.reasoningText });
+        }, streamOutputBatchMs);
+    }
+    finishReasoning(session) {
+        if (!session.reasoningActive)
+            return;
+        if (session.reasoningTimer) {
+            clearTimeout(session.reasoningTimer);
+            session.reasoningTimer = null;
+        }
+        const durationMs = session.reasoningStartedAt ? Date.now() - session.reasoningStartedAt : undefined;
+        this.emit('thinking', session.key, { phase: 'done', text: session.reasoningText, durationMs });
+        session.reasoningActive = false;
+        session.reasoningStartedAt = null;
+    }
+    // — tools —
+    handleToolUse(session, action) {
+        // AskUserQuestion never renders as a tool (it is intercepted on the control
+        // channel); guard defensively.
+        if (action.tool === 'AskUserQuestion')
+            return;
+        if (action.isSubagent) {
+            this.markSubagentActive(session);
+            return;
+        }
+        session.toolNamesById.set(action.toolUseId, action.tool);
+        // Track it as in flight until its tool_result returns — a busy session with
+        // an outstanding tool (e.g. a long silent Bash) must NOT trip the idle
+        // watchdog even though stdout goes quiet while the tool runs.
+        session.outstandingToolUseIds.add(action.toolUseId);
+        // Transient status only; the completed body arrives as a toolResult.
+        this.emit('status', session.key, `🔧 ${action.tool}`);
+    }
+    handleToolResult(session, action) {
+        // The tool returned — no longer in flight (do this before any early return so
+        // the outstanding-tool set can never leak and pin the idle watchdog open).
+        session.outstandingToolUseIds.delete(action.toolUseId);
+        // Skip AskUserQuestion's internal "questions have been answered" tool_result.
+        if (session.questionToolUseIds.has(action.toolUseId))
+            return;
+        const tool = session.toolNamesById.get(action.toolUseId) ?? 'tool';
+        if (!action.output.trim())
+            return;
+        // Mode-agnostic emit — the bot applies the per-thread `/tool_results` pref.
+        this.emit('toolResult', session.key, { tool, output: action.output });
+    }
+    // — sub-agent (v1) —
+    markSubagentActive(session) {
+        session.subagentActive = true;
+        this.emit('subagentStatus', session.key, { active: true, title: null });
+    }
+    handleSubagentText(session, text) {
+        if (this.getDisplayPrefs(session.key).subagent === 'full') {
+            session.childResponseText += text;
+            if (session.childOutputTimer)
+                return;
+            session.childOutputTimer = setTimeout(() => {
+                session.childOutputTimer = null;
+                const tail = session.childResponseText.slice(session.childEmittedLength);
+                if (!tail.trim())
+                    return;
+                session.childEmittedLength = session.childResponseText.length;
+                this.emit('output', session.key, tail, { isSubagent: true });
+                // Child batcher drained — release the held-back tail offset (see
+                // `drainStdoutTail`).
+                if (checkIsEmitCaughtUp(session))
+                    this.persistTailOffset(session);
+            }, streamOutputBatchMs);
+        }
+        else {
+            this.markSubagentActive(session);
+        }
+    }
+    clearSubagent(session) {
+        if (session.childOutputTimer) {
+            clearTimeout(session.childOutputTimer);
+            session.childOutputTimer = null;
+        }
+        session.childResponseText = '';
+        session.childEmittedLength = 0;
+        if (session.subagentActive) {
+            session.subagentActive = false;
+            this.emit('subagentStatus', session.key, { active: false, title: null });
+        }
+    }
+    // — turn end —
+    /** Every terminal `result` — a normal turn, a compaction turn, an error — ends with the `turnEnded` event. */
+    handleTurnEnd(session, action) {
+        this.applyTurnEnd(session, action);
+        // After the handlers above: the bot's per-turn stop (L5) reads the session's state as settled here.
+        this.emit('turnEnded', session.key);
+        this.applyPendingConfigDirSwitch(session);
+    }
+    applyTurnEnd(session, action) {
+        // L-D11: every turn's accounting, the compaction turn included — the
+        // cross-process prompt-cache check reads these lines, so they must be real
+        // and repeatable, never reconstructed from a transcript afterwards.
+        if (action.usage) {
+            const { inputTokens, cacheReadTokens, cacheWriteTokens, outputTokens } = action.usage;
+            console.log(`${exports.claudeJsonStreamUsageLogPrefix}${(0, sessionKey_1.keyToString)(session.key)}: input=${inputTokens} cacheRead=${cacheReadTokens} cacheWrite=${cacheWriteTokens} output=${outputTokens}`);
+        }
+        session.isBusy = false;
+        // Self-healing accounting: a FAILED turn (usage limit, API error) may never echo the messages that were
+        // queued behind it, and a count left above zero would make the session look "working" forever — a pending
+        // account switch would never fire. A message still genuinely queued is echoed later (the decrement clamps
+        // at zero and the echo marks the session busy again), so zeroing here can only under-count briefly.
+        if (action.isError)
+            session.unconsumedInputCount = 0;
+        session.outstandingToolUseIds.clear();
+        this.finishReasoning(session);
+        this.clearSubagent(session);
+        // A bot-issued `/compact` turn ends here. Emit NOTHING (the summary text /
+        // "not enough" message are suppressed) and settle the awaiter: a still-pending
+        // compaction with no failure signal is a clean success (fallback for a build
+        // that skipped the boundary frame); an errored turn is a failure.
+        if (session.compactionInProgress) {
+            session.swallowNextAbortError = false;
+            if (session.pendingCompaction) {
+                const sawSuccess = session.pendingCompaction.sawSuccess;
+                this.resolveCompaction(session, sawSuccess || !action.isError
+                    ? { ok: true, preTokens: null, postTokens: null }
+                    : { ok: false, error: action.errorText ?? 'compaction failed' });
+            }
+            else {
+                session.compactionInProgress = false;
+            }
+            return;
+        }
+        // One-shot: consume the interrupt's swallow flag for THIS terminal result
+        // (read-and-clear so it can never leak onto a later, unrelated turn).
+        const swallowAbortError = session.swallowNextAbortError;
+        session.swallowNextAbortError = false;
+        if (action.isError && action.errorText) {
+            // Our own interrupt produced this error result — relay nothing (no bogus
+            // "Claude error", no spurious retry). A REAL provider error arriving
+            // WITHOUT a preceding interrupt still classifies / surfaces normally.
+            if (swallowAbortError) {
+                console.log(`[ClaudeJson] swallowed interrupt-aborted turn error for ${(0, sessionKey_1.keyToString)(session.key)}: ${action.errorText}`);
+                return;
+            }
+            const emitted = this.maybeEmitApiError(session, action.errorText);
+            if (!emitted)
+                this.emit('output', session.key, `Claude error: ${action.errorText}`, { isFinal: true });
+            return;
+        }
+        // Reconciliation backstop: if the delta stream under-delivered vs the final
+        // `result` text, append the gap so the answer is never short.
+        if (action.resultText && action.resultText.length > session.currentResponseText.length
+            && action.resultText.startsWith(session.currentResponseText)) {
+            session.currentResponseText = action.resultText;
+        }
+        this.flushAnswer(session, true);
+        // Advance the seen watermark to the transcript's current byte size so a bot
+        // restart can count assistant messages produced while it was down. Also runs
+        // per settled parent message (see `onStdout`); this turn-end call is the
+        // safety-net catch-up for the final assistant line.
+        this.advanceWatermarkFromTranscript(session);
+    }
+    /**
+     * @description Advance the persisted seen-watermark to the transcript's current
+     * byte size when it grew past the last write (S7). A cheap `fs.statSync().size`
+     * (NOT a whole-file read — this runs per settled parent assistant message, not
+     * only at turn end) plus a monotonic guard, mirroring the tmux backend's
+     * {@link import('./claudeCliAdapter').ClaudeCliAdapter} advance so both Claude
+     * paths track "relayed up to here". Best-effort — a transcript not yet on disk
+     * leaves the watermark where it was; the next relayed message re-tries.
+     */
+    advanceWatermarkFromTranscript(session) {
+        try {
+            const filePath = (0, claudeCliAdapter_1.getClaudeTranscriptPath)(session.workDir, session.sessionId);
+            const eof = fs.statSync(filePath).size;
+            if (eof <= session.lastWatermarkOffset)
+                return; // monotonic: only real growth writes
+            session.lastWatermarkOffset = eof;
+            this.advanceSeenWatermark(session.key, { sessionId: session.sessionId, claudeTranscriptOffset: eof });
+        }
+        catch {
+            // Transcript not yet on disk (UUID just born) / stat failed — retry next relay.
+        }
+    }
+    // — api error —
+    /** Classify + emit an `apiError` once per episode; returns whether it fired. */
+    maybeEmitApiError(session, text) {
+        if (session.apiErrorFired)
+            return false;
+        const apiError = (0, apiErrorRetry_1.classifyAgentApiError)(text, Date.now());
+        if (!apiError)
+            return false;
+        session.apiErrorFired = true;
+        this.emit('apiError', session.key, apiError);
+        return true;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    //  Questions & permissions — control channel (S4)
+    // ─────────────────────────────────────────────────────────────────────────
+    handleControlRequest(session, action) {
+        if (action.subtype === 'can_use_tool') {
+            if (action.toolName === 'AskUserQuestion' && action.input && action.toolUseId) {
+                session.questionToolUseIds.add(action.toolUseId);
+                this.surfaceQuestion(session, action.requestId, action.toolUseId, action.input);
+                return;
+            }
+            // Any other tool → auto-allow (operator trusts their own agent; parity with
+            // the tmux backend's bypassPermissions). Under bypass this fires only for the
+            // residual circuit-breakers claude never bypasses (`rm -rf /`, `rm -rf ~`).
+            // `buildCanUseToolAllow` guarantees the schema-required `updatedInput`.
+            this.writeControlResponse(session, action.requestId, (0, claudeStreamJson_1.buildCanUseToolAllow)(action.input, action.toolUseId));
+            return;
+        }
+        if (action.subtype === 'request_user_dialog') {
+            // No dialog UI in Telegram → cancel so the CLI falls back gracefully.
+            this.writeControlResponse(session, action.requestId, { behavior: 'cancelled' });
+            return;
+        }
+        // Unknown control request → generic success so the CLI is never left hanging.
+        this.writeControlResponse(session, action.requestId, {});
+    }
+    surfaceQuestion(session, requestId, toolUseId, rawInput) {
+        const questions = this.parseQuestions(rawInput);
+        if (questions.length === 0) {
+            // Nothing to ask — allow with the raw input so the turn continues.
+            this.writeControlResponse(session, requestId, (0, claudeStreamJson_1.buildCanUseToolAllow)(rawInput, toolUseId));
+            return;
+        }
+        session.pendingQuestion = { requestId, toolUseId, rawInput, questions };
+        session.isBusy = true;
+        this.writeQuestionSidecar(session);
+        const payload = { requestId, questions };
+        this.emit('question', session.key, payload);
+    }
+    /**
+     * @description Persist the pending question to the host dir. The external
+     * claude process stays BLOCKED on its `can_use_tool` across a bot restart,
+     * but the control_request line lies BEFORE the persisted tail offset (it was
+     * consumed pre-restart), so tail replay alone would never resurface it — the
+     * sidecar is what lets an adopting bot still answer over the FIFO. Removed
+     * the moment the question resolves (answer / reject); dies with the dir on
+     * stop.
+     */
+    writeQuestionSidecar(session) {
+        if (!session.pendingQuestion)
+            return;
+        try {
+            fs.writeFileSync(session.paths.questionFile, JSON.stringify(session.pendingQuestion));
+        }
+        catch (e) {
+            console.warn(`[ClaudeJson] cannot persist pending question for ${(0, sessionKey_1.keyToString)(session.key)}:`, e instanceof Error ? e.message : e);
+        }
+    }
+    clearQuestionSidecar(session) {
+        try {
+            fs.unlinkSync(session.paths.questionFile);
+        }
+        catch { /* absent */ }
+    }
+    /** Map the AskUserQuestion `input.questions` to the shared question shape
+     *  (dropping option `preview`, which breaks in the Telegram relay). */
+    parseQuestions(rawInput) {
+        const rawQuestions = Array.isArray(rawInput.questions) ? rawInput.questions : [];
+        const result = [];
+        for (const raw of rawQuestions) {
+            if (typeof raw !== 'object' || raw === null)
+                continue;
+            const q = raw;
+            if (typeof q.question !== 'string')
+                continue;
+            const rawOptions = Array.isArray(q.options) ? q.options : [];
+            const options = rawOptions
+                .map((o) => {
+                if (typeof o !== 'object' || o === null)
+                    return null;
+                const oo = o;
+                if (typeof oo.label !== 'string')
+                    return null;
+                return typeof oo.description === 'string' ? { label: oo.label, description: oo.description } : { label: oo.label };
+            })
+                .filter((o) => o !== null);
+            if (options.length === 0)
+                continue;
+            const question = { question: q.question, options };
+            if (typeof q.header === 'string')
+                question.header = q.header;
+            if (q.multiSelect === true)
+                question.multiple = true;
+            result.push(question);
+        }
+        return result;
+    }
+    answerQuestion(key, answers) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive || !session.pendingQuestion)
+            return;
+        const pending = session.pendingQuestion;
+        session.pendingQuestion = null;
+        this.clearQuestionSidecar(session);
+        // The turn resumes now; reset the idle-watchdog clock so the (possibly long)
+        // wait for the user's answer doesn't instantly trip it before output resumes.
+        session.lastStdoutActivityAt = Date.now();
+        // Build the answers map: question text → selected label(s) (comma-joined for
+        // multi-select), the exact shape AskUserQuestion expects.
+        const answersMap = {};
+        pending.questions.forEach((q, i) => {
+            const selected = answers[i] ?? [];
+            answersMap[q.question] = selected.join(',');
+        });
+        this.writeControlResponse(session, pending.requestId, (0, claudeStreamJson_1.buildCanUseToolAllow)({ ...pending.rawInput, answers: answersMap }, pending.toolUseId));
+    }
+    rejectQuestion(key) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.pendingQuestion)
+            return;
+        const pending = session.pendingQuestion;
+        session.pendingQuestion = null;
+        this.clearQuestionSidecar(session);
+        this.writeControlResponse(session, pending.requestId, (0, claudeStreamJson_1.buildCanUseToolDeny)('User declined to answer the question.', pending.toolUseId));
+    }
+    writeControlResponse(session, requestId, response) {
+        this.writeStdin(session, { type: 'control_response', response: { subtype: 'success', request_id: requestId, response } });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    //  Session history / resume (S5) — reuse the shared Claude transcript readers
+    // ─────────────────────────────────────────────────────────────────────────
+    async getSessions(_key, workDir) {
+        return (0, claudeCliAdapter_1.listClaudeSessionsForWorkDir)((0, claudeCliAdapter_1.getClaudeProjectsRoot)(), workDir);
+    }
+    async getRecentTurns(_key, workDir, sessionId, limit) {
+        const filePath = (0, claudeCliAdapter_1.getClaudeTranscriptPath)(workDir, sessionId);
+        return (0, claudeCliAdapter_1.readRecentClaudeTurns)(filePath, limit);
+    }
+    async getReattachRecap(key, workDir, sessionId, watermark) {
+        const filePath = (0, claudeCliAdapter_1.getClaudeTranscriptPath)(workDir, sessionId);
+        const offset = watermark?.claudeTranscriptOffset;
+        const isWatermarkKnown = typeof offset === 'number' && watermark?.sessionId === sessionId;
+        const { missedCount, turns, headOffset } = (0, claudeCliAdapter_1.readClaudeReattachTranscript)(filePath, offset ?? 0, resumeContext_1.resumeContextTurnLimit);
+        const headWatermark = headOffset === undefined ? undefined : { sessionId, claudeTranscriptOffset: headOffset };
+        return { missedCount: isWatermarkKnown ? missedCount : 0, turns, isWatermarkKnown, isActive: this.checkIsBusy(key), headWatermark };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    //  Model / effort (S6) — spawn flags; a live change re-spawns with --resume
+    // ─────────────────────────────────────────────────────────────────────────
+    async setModel(key, modelId) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive)
+            return (0, i18n_1.t)('model.start_agent_first');
+        await this.respawnWithChange(session, { model: modelId, effort: session.effort });
+        return null;
+    }
+    /**
+     * @description The model the session is RUNNING. Claude's own `system/init`
+     * report wins over the pinned `--model` pick: it is the resolved id (an alias
+     * like `opus` resolves to its snapshot) and it is the only value present when
+     * no pick was ever made. The pick is the fallback for the window between a
+     * `/model` re-spawn and its first `init`, so the label never blanks out
+     * mid-switch.
+     */
+    getCurrentModel(key) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        return session?.reportedModel ?? session?.model ?? null;
+    }
+    async getAvailableModels() {
+        // The CLI `--model` accepts these aliases (resolved to the latest snapshot).
+        return ['fable', 'opus', 'sonnet', 'haiku'];
+    }
+    async setEffort(key, level) {
+        if (!(0, effortLevels_1.checkIsClaudeEffortLevel)(level)) {
+            return (0, i18n_1.t)('effort.invalid_level', { level, valid: (0, effortLevels_1.getClaudeAvailableLevels)().join(', ') });
+        }
+        (0, claudeCliAdapter_1.saveEffortPref)(key, level);
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive)
+            return (0, i18n_1.t)('effort.start_agent_first');
+        await this.respawnWithChange(session, { model: session.model, effort: level });
+        return null;
+    }
+    getEffort(key) {
+        return (0, claudeCliAdapter_1.loadEffortPrefs)()[(0, sessionKey_1.keyToString)(key)] ?? null;
+    }
+    async getAvailableEffortLevels(_key) {
+        return (0, effortLevels_1.getClaudeAvailableLevels)();
+    }
+    /**
+     * @description Apply a model/effort change by re-spawning the child with
+     * `--resume <sessionId>` (the on-disk session persists, so only an in-flight
+     * streaming reply is lost — same trade-off as OpenCode's server restart). The
+     * intermediate exit is suppressed (`isRespawning`) so the bot sees no
+     * closed/stopped churn.
+     */
+    async respawnWithChange(session, change) {
+        const { key, workDir, sessionId } = session;
+        const configDir = change.configDir === undefined ? session.configDir : change.configDir;
+        session.isRespawning = true;
+        this.rejectQuestion(key);
+        await session.stdinWriteChain.catch(() => { });
+        this.clearTimers(session);
+        session.isActive = false;
+        this.closeFifo(session);
+        try {
+            process.kill(session.pid, 'SIGTERM');
+        }
+        catch { /* gone */ }
+        await (0, tmuxExec_1.tmuxAsync)('kill-session', '-t', (0, tmuxExec_1.getTmuxSessionTarget)((0, jsonStreamHost_1.buildJsonStreamTmuxSessionName)(key)));
+        // spawnSession lays the host dir out fresh and replaces the map entry.
+        await this.spawnSession(key, workDir, sessionId, { effort: change.effort, model: change.model, resume: true, configDir });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    //  Account profile (`/account`) — the spawn's CLAUDE_CONFIG_DIR; a live change re-spawns
+    // ─────────────────────────────────────────────────────────────────────────
+    /** The `CLAUDE_CONFIG_DIR` the live process runs with (`null` = default profile); `undefined` without a live process. */
+    getSessionClaudeConfigDir(key) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        return session?.isActive ? session.configDir : undefined;
+    }
+    /**
+     * @description Bring the live process onto the account profile its conversation resolves to NOW: nothing
+     * when it already runs there; a re-spawn with `--resume` (the `/model` path — same conversation, model and
+     * effort kept) when it is idle; deferred to the end of its turn when it works, since a re-spawn kills the turn
+     * and any background task. A sleeping conversation needs nothing: its next resume reads the reader.
+     *
+     * `isAfterLimit`: the switch answers a usage limit (the offer button, auto-switch, a pick during the limit
+     * wait). The turn is dead and the model cannot act on the limited account, so the re-spawn happens NOW even
+     * when the session looks working (busy flag, unconsumed input). Live background tasks (background Bash,
+     * sub-agents) are stopped by it too — a deliberate choice: the user chose to move, and a process on a limited
+     * account cannot make progress; the caller says so when `checkHasBackgroundWork` was true.
+     */
+    async applyClaudeConfigDir(key, options = {}) {
+        const session = this.sessions.get((0, sessionKey_1.keyToString)(key));
+        if (!session?.isActive)
+            return 'inactive';
+        const wanted = this.resolveConfigDir(key);
+        if (wanted === session.configDir) {
+            session.isConfigDirSwitchPending = false;
+            return 'unchanged';
+        }
+        if (!options.isAfterLimit && this.checkIsWorking(key)) {
+            session.isConfigDirSwitchPending = true;
+            return 'deferred';
+        }
+        session.isConfigDirSwitchPending = false;
+        console.log(`[ClaudeJson] ${(0, sessionKey_1.keyToString)(key)}: re-spawning under configDir=${wanted ?? 'default'} (was ${session.configDir ?? 'default'})`);
+        await this.respawnWithChange(session, { model: session.model, effort: session.effort, configDir: wanted });
+        return 'respawned';
+    }
+    /** A deferred profile switch runs once the turn that held it off has ended (and nothing else works). */
+    applyPendingConfigDirSwitch(session) {
+        if (!session.isConfigDirSwitchPending || !session.isActive)
+            return;
+        if (this.checkIsWorking(session.key))
+            return; // a background task still runs: the next turn end looks again
+        // Detached from the tail poll that delivered the `result`: the re-spawn tears this very session down.
+        setTimeout(() => {
+            void this.applyClaudeConfigDir(session.key).catch((e) => console.warn(`[ClaudeJson] ${(0, sessionKey_1.keyToString)(session.key)}: the deferred profile switch failed:`, e instanceof Error ? e.message : e));
+        }, 0).unref?.();
+    }
+    clearTimers(session) {
+        if (session.pollTimer) {
+            clearTimeout(session.pollTimer);
+            session.pollTimer = null;
+        }
+        if (session.outputTimer) {
+            clearTimeout(session.outputTimer);
+            session.outputTimer = null;
+        }
+        if (session.reasoningTimer) {
+            clearTimeout(session.reasoningTimer);
+            session.reasoningTimer = null;
+        }
+        if (session.childOutputTimer) {
+            clearTimeout(session.childOutputTimer);
+            session.childOutputTimer = null;
+        }
+        // An in-flight compaction dies with the session: the process that was going
+        // to confirm it is gone, so settle the caller now instead of leaving it
+        // parked until the silence watchdog notices a session that no longer exists.
+        this.resolveCompaction(session, { ok: false, error: 'the session ended before the compaction confirmed' });
+        // Same reasoning for bot-issued control requests: the process they were
+        // talking to is going away (stop / exit / model-effort respawn), so their
+        // replies can never arrive. Settle each as an unknown (`null`) and drop the
+        // map, rather than leaving a caller parked on the round-trip timeout and a
+        // timer armed against a dead session.
+        const pendingControls = [...session.pendingControlRequests.values()];
+        session.pendingControlRequests.clear();
+        for (const pending of pendingControls) {
+            clearTimeout(pending.timer);
+            pending.resolve(null);
+        }
+    }
+}
+exports.ClaudeJsonStreamAdapter = ClaudeJsonStreamAdapter;
+/** The tail record persisted for a session at `offsetBytes` — the offset and the working
+ *  state in force there (task list, turn in flight, outstanding tools) travel together
+ *  (see `JsonStreamTailOffset`). */
+function buildTailRecord(session, offsetBytes) {
+    return {
+        sessionId: session.sessionId,
+        offsetBytes,
+        backgroundTaskIds: [...session.backgroundTaskIds],
+        isTurnInFlight: session.isBusy,
+        outstandingToolUseIds: [...session.outstandingToolUseIds],
+        // Only once known: the record never claims a version the process did not report.
+        ...(session.claudeCodeVersion !== null ? { claudeCodeVersion: session.claudeCodeVersion } : {}),
+    };
+}
+/**
+ * @description Whether every consumed event has LEFT the adapter — nothing is
+ * waiting in the answer / sub-agent 350ms batchers. Gates the tail-offset
+ * persist: batched-but-unemitted text must keep the persisted offset BEHIND
+ * it, so a restart replays (never skips) it. Live thinking text is
+ * deliberately ignored — it renders as a transient frame, so a lost batch of
+ * it at a reload seam costs nothing permanent.
+ */
+function checkIsEmitCaughtUp(session) {
+    return session.currentResponseText.length === session.emittedLength
+        && session.childResponseText.length === session.childEmittedLength;
+}
+/**
+ * @description Extract the newest compaction summary from a Claude on-disk
+ * transcript: the last JSONL line with `isCompactSummary === true`, whose
+ * `message.content` (a string, or `{type:'text'}` blocks) holds the summary the
+ * `/compact` turn produced. Returns `null` for an unreadable file or when no
+ * summary line is present. Reads the whole file — cheap enough for the
+ * once-per-idle-compaction call.
+ */
+function readLatestCompactSummaryFromTranscript(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let summary = null;
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (!(0, claudeStreamJson_1.checkIsStreamRecord)(obj) || obj.isCompactSummary !== true)
+            continue;
+        const message = (0, claudeStreamJson_1.checkIsStreamRecord)(obj.message) ? obj.message : null;
+        const content = message?.content;
+        if (typeof content === 'string' && content.trim()) {
+            summary = content;
+        }
+        else if (Array.isArray(content)) {
+            const chunks = [];
+            for (const block of content) {
+                if ((0, claudeStreamJson_1.checkIsStreamRecord)(block) && block.type === 'text' && typeof block.text === 'string') {
+                    chunks.push(block.text);
+                }
+            }
+            if (chunks.join('').trim())
+                summary = chunks.join('');
+        }
+    }
+    return summary;
+}
+/** Spawn-fail diagnostics: the wrapper's exit code + a stderr excerpt (the
+ *  passive `stderr.log` is read ONLY here and at unexpected exit — locked
+ *  decision, no live stderr consumer). */
+function describeSpawnFailure(paths) {
+    const exitCode = (0, jsonStreamHost_1.readExitCodeFile)(paths.exitCodeFile);
+    const stderrTail = (0, jsonStreamHost_1.readStderrTail)(paths.stderrFile);
+    const parts = [];
+    if (exitCode !== null)
+        parts.push(`exit=${exitCode}`);
+    if (stderrTail)
+        parts.push(`stderr: ${stderrTail}`);
+    return parts.length > 0 ? ` (${parts.join(', ')})` : '';
+}
+//# sourceMappingURL=claudeJsonStreamAdapter.js.map