@excitedjs/agent-runtime-claude-code 0.5.0-beta.168 → 0.5.0

package/dist/runtime.js

@@ -1,71 +1,18 @@
-/**
- * `builtin:claude-code` AgentRuntime (issue #110 PR6, resident stream-json
- * transport since issue #120; extracted into `@excitedjs/agent-runtime-claude-code`
- * in issue #209).
- *
- * A real second agent runtime that proves the AgentRuntimeProvider abstraction
- * is not "Codex renamed". Like Codex it runs a **resident child process**
- * supervised for the runtime's lifetime — but it differs in every
- * runtime-specific dimension:
- *
- * - **Stream-json over stdio, not an app-server WebSocket.** The resident child
- *   is `claude --print --input-format stream-json --output-format stream-json`
- *   (see `./args.ts`); turns are NDJSON `user` lines on stdin and
- *   `init`/`assistant`/`result` envelopes on stdout (see `./stream.ts`). There
- *   is no `initialize` handshake — the child emits `init` lazily with the first
- *   turn — so readiness is "child spawned", not "handshake completed".
- * - **MCP injection is an inline JSON config document** (`--mcp-config <json>`),
- *   not Codex's `-c mcp_servers.*` TOML CLI flags.
- * - **Runtime-owned config** is `DispatcherClaudeCodeConfig` (bin / model /
- *   permission_mode / remote_control / extra_args / extra_env), distinct from
- *   the Codex config.
- * - **Completion delivery** is a plain user turn (no fake task-notification),
- *   not the Codex inbox-then-trigger path.
- *
- * Process spawning goes through an injectable {@link ClaudeCodeSessionFactory}
- * seam (mirroring Codex's process-factory seam), so the lifecycle contract is
- * fully unit-testable with a fake session. A live `claude` binary is exercised
- * only by the opt-in live test.
- *
- * Failure contract (unchanged by #120): a turn failure (spawn error, child
- * exit, error `result`) is never swallowed. For inbound/restart turns it drives
- * the runtime to `degraded` with a persisted `last_error` (observable via
- * status/doctor). For `completionInput` it surfaces as a `failed`
- * result the caller can act on (PR8 delivery retry). `channelInput` still
- * returns after accept (submit != completion) so the channel can ack promptly.
- *
- * Restart: an unexpected child exit marks the runtime `degraded`; the next turn
- * re-spawns the resident child with `--resume <session_id>`, restoring the
- * conversation. There is no background backoff timer — re-spawn is lazy and
- * bound to the (serialized) turn queue, so it stays deterministic.
- *
- * Per-turn idle deadline: a turn whose still-alive child goes silent — never
- * emitting another stream line (a stall, or a wait on input the runtime cannot
- * satisfy) — would otherwise pend forever and wedge the serial queue, and behind
- * it TeamMate completion delivery, which awaits this runtime. `turn_timeout_ms`
- * is a *max-idle* window (issue #156): it is reset on every inbound stream line,
- * so a long but continuously-streaming turn (e.g. a deep audit running many
- * tool calls for far longer than the window) is never reaped, while a child that
- * emits nothing for the whole window still is — turning an infinite hang into a
- * normal degraded + `last_error` (inbound) or `failed` delivery result.
- *
- * Reference: the resident stream-json protocol model and process-supervision
- * shape are adapted from the Claudemux `next` implementation; the AgentRuntime /
- * Channel / DispatcherService boundaries (provider seam, runtime-owned MCP
- * injection, degraded/last_error status, TeamMate delivery result contract) are
- * Dreamux's own, per `.agents/decisions/agent-runtime-provider.md`.
- */
-import { mkdir, rename, rm, symlink, writeFile, } from 'node:fs/promises';
+/** Resident Claude Code AgentRuntime using stream-json stdio. */
 import { randomUUID } from 'node:crypto';
-import { dirname, join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { BUILTIN_CLAUDE_CODE_PROVIDER_REF } from './provider-ref.js';
 import { claudeCodeResidentArgs } from './args.js';
 import { stringifyClaudeCodeMcpConfig } from './mcp-config.js';
-import { adapterExists, skillAdapterKey, skillDirsInRoot, uniqueSkillSources, } from './skill-adapter.js';
-import { renderChannelInput, unsupportedFeatureError, } from '@excitedjs/dreamux-utils';
+import { skillAdapterKey } from './skill-adapter.js';
+import { materializeClaudeSkillAddDir } from './skill-materializer.js';
+import { DEFAULT_MESSAGE_ID_DEDUPE_WINDOW, renderChannelInput, unsupportedFeatureError, } from '@excitedjs/dreamux-utils';
 import { CLAUDE_CODE_AGENT_RUNTIME_CAPABILITIES } from './provider.js';
 import { consoleFallbackLogger } from './logger.js';
-let nextRuntimeInstanceId = 0;
+import { ClaudeSteerAdmissionError } from './rpc.js';
+import { createRuntimeSubmission, handleProtocolEvent, } from './runtime-submissions.js';
+import { asError, classifySteerFailure, reserveSource, } from './source-reservation.js';
+import { buildClaudeProcessEnv, resolveRuntimeTranscriptPath, } from './runtime-session.js';
 function errMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -88,21 +35,31 @@ export class ClaudeCodeRuntime {
     logger;
     status = 'declared';
     threadId;
+    transcriptLocator;
+    resumeOnNextSpawn;
     resumed;
     stopped = false;
     seen = new Set();
+    seenOrder = [];
     seenTextInputIds = new Set();
+    seenTextInputIdOrder = [];
+    sourceIdDedupeWindow;
+    pendingChannelSources = new Map();
+    pendingTextSources = new Map();
+    pendingAdmissions = new Set();
     queue = Promise.resolve();
-    runtimeInstanceId = ++nextRuntimeInstanceId;
-    turnCounter = 0;
     session = null;
-    lastResult = null;
+    sessionStarting = null;
+    startTask = null;
+    stopTask = null;
+    generation = 0;
     activeTurn = null;
     queuedTurnCount = 0;
     idlePromise = null;
     idleResolve = null;
     constructor(identity, deps) {
         this.deps = deps;
+        const checkpoint = identity.checkpoint ?? null;
         this.dispatcherId = identity.runtime_id;
         this.config = deps.config;
         this.bin = deps.resolveBinPath(this.config.bin);
@@ -113,8 +70,11 @@ export class ClaudeCodeRuntime {
         // central logs root (B2): core no longer names a per-runtime log file. The
         // host supplies a unique, filesystem-safe `runtime_id`.
         this.stderrLogPath = join(deps.paths.logsDir(), 'claude-code', `${this.dispatcherId}.stderr.log`);
-        this.threadId = identity.checkpoint_id ?? null;
-        this.resumed = (identity.checkpoint_id ?? null) !== null;
+        this.threadId = checkpoint?.id ?? null;
+        this.transcriptLocator = checkpoint?.transcript_locator ?? null;
+        this.resumeOnNextSpawn = checkpoint !== null;
+        this.resumed = identity.checkpoint !== null;
+        this.sourceIdDedupeWindow = Math.max(0, deps.sourceIdDedupeWindow ?? DEFAULT_MESSAGE_ID_DEDUPE_WINDOW);
         this.logger = deps.logger ?? consoleFallbackLogger(this.dispatcherId);
     }
     getStatus() {
@@ -124,55 +84,102 @@ export class ClaudeCodeRuntime {
         return CLAUDE_CODE_AGENT_RUNTIME_CAPABILITIES;
     }
     getCheckpoint() {
-        return this.threadId === null ? null : { id: this.threadId };
+        return this.threadId === null
+            ? null
+            : {
+                id: this.threadId,
+                transcript_locator: this.transcriptLocator,
+            };
     }
     wasCheckpointResumed() {
         return this.resumed;
     }
-    async getLast() {
-        return this.lastResult;
-    }
     async getContext() {
         return null;
     }
     async resume() {
         await this.start();
     }
-    async start() {
+    start() {
+        if (this.stopped) {
+            return Promise.reject(new Error('claude-code runtime is stopped'));
+        }
+        if (this.startTask !== null)
+            return this.startTask;
+        if (this.status === 'ready')
+            return Promise.resolve();
+        const generation = this.generation;
+        const task = this.startRuntime(generation);
+        this.startTask = task;
+        void task.finally(() => {
+            if (this.startTask === task)
+                this.startTask = null;
+        }).catch(() => undefined);
+        return task;
+    }
+    async startRuntime(generation) {
+        this.assertGeneration(generation);
         await this.setStatus('starting');
         try {
-            await this.materializeSkillAddDir();
+            await materializeClaudeSkillAddDir(this.skillAddDirRoot, this.deps.skillSources ?? []);
+            this.assertGeneration(generation);
             // Spawn the resident child up front so the runtime is truly resident
             // (Codex-aligned). A missing/broken `claude` binary fails here and drives
             // the runtime to degraded + throws, rather than a silent no-op.
             await this.ensureSession();
+            this.assertGeneration(generation);
         }
         catch (err) {
-            await this.setStatus('degraded', err);
+            if (!this.stopped && generation === this.generation) {
+                await this.setStatus('degraded', err);
+            }
             throw err;
         }
         await this.setStatus('ready');
+        this.assertGeneration(generation);
     }
     async stop() {
-        if (this.stopped)
+        if (this.status === 'stopped')
             return;
+        if (this.stopTask !== null)
+            return this.stopTask;
         this.stopped = true;
+        this.generation += 1;
+        if (this.activeTurn !== null)
+            this.stopUnsettled(this.activeTurn);
+        const task = this.stopRuntime();
+        this.stopTask = task;
+        try {
+            await task;
+        }
+        catch (error) {
+            if (this.stopTask === task)
+                this.stopTask = null;
+            throw error;
+        }
+    }
+    async stopRuntime() {
+        const sessionAtStop = this.session;
+        const sessionStop = sessionAtStop?.stop() ?? null;
+        void sessionStop?.catch(() => undefined);
         await this.setStatus('stopping');
         const session = this.session;
-        this.session = null;
         if (session !== null) {
-            try {
-                await session.stop();
-            }
-            catch (err) {
-                this.log('warn', 'claude-code session stop errored', err);
-            }
+            await (session === sessionAtStop && sessionStop !== null
+                ? sessionStop
+                : session.stop());
+            if (this.session === session)
+                this.session = null;
         }
-        this.queuedTurnCount = 0;
+        await this.drainAdmissions();
+        await this.queue;
         this.resolveIdleWaitersIfIdle();
         await this.setStatus('stopped');
     }
-    async completionInput(input) {
+    completionInput(input) {
+        return this.trackAdmission(this.completionInputImpl(input));
+    }
+    async completionInputImpl(input) {
         if (this.stopped)
             return { status: 'stopped' };
         if (input.outputSchema !== undefined) {
@@ -188,91 +195,88 @@ export class ClaudeCodeRuntime {
                 return { status: 'failed', error };
             }
         }
-        const key = input.sourceId;
-        if (key !== undefined && key !== '' && this.seenTextInputIds.has(key)) {
-            return { status: 'duplicate' };
-        }
-        if (key !== undefined && key !== '')
-            this.seenTextInputIds.add(key);
-        // Plain-text teammate/completion turns share the same active steerable
-        // logical-turn slot as channel inbound (PR #282 E2E regression): a send
-        // that arrives while an earlier turn is still in-flight folds into that
-        // active turn via `steerTurn({ priority: 'next' })` and returns the same
-        // `turnId`, aligned with the Codex runtime's `claimActiveTurnSlot`
-        // semantics. This is the runtime-owned plain-text path — no channel/XML
-        // rendering is applied.
-        const active = this.activeTurn;
-        if (active !== null) {
-            try {
-                await this.steerActiveTurn(active, input.text);
-                return { status: 'submitted', turnId: active.turnId };
-            }
-            catch (err) {
-                return {
-                    status: 'failed',
-                    error: err instanceof Error ? err : new Error(String(err)),
-                };
-            }
-        }
-        const turnId = this.nextTurnId('turn');
-        this.recordQueuedTurnStart();
-        const turn = {
-            turnId,
-            pendingSteers: [],
-            session: null,
-            steerQueue: Promise.resolve(),
-            // Dreamux-owned plain text turns are real user turns, not synthetic
-            // system injections.
-            submitOptions: { isSynthetic: false },
-        };
-        this.activeTurn = turn;
-        void this.runActiveTurnOnQueue(input.text, turn).then((resultText) => this.markTurnSucceeded(turnId, resultText), (err) => this.markTurnFailed(turnId, err));
-        return { status: 'submitted', turnId };
+        return reserveSource(input.sourceId, this.seenTextInputIds, this.seenTextInputIdOrder, this.pendingTextSources, this.sourceIdDedupeWindow, () => this.acceptTextInput(input));
+    }
+    async acceptTextInput(input) {
+        return this.acceptInput(input.text, { isSynthetic: false });
     }
-    async channelInput(input) {
+    channelInput(input) {
+        return this.trackAdmission(this.channelInputImpl(input));
+    }
+    async channelInputImpl(input) {
         if (this.stopped)
             return { status: 'stopped' };
-        const key = input.sourceId;
-        if (key !== '' && this.seen.has(key))
-            return { status: 'duplicate' };
-        if (key !== '')
-            this.seen.add(key);
         // This runtime owns wrapping the channel input into its delivery shape: a
         // structured channel turn becomes the native `<channel source="…">` block;
         // a plain turn passes through unchanged.
-        const text = renderChannelInput(input);
+        let text;
+        try {
+            text = renderChannelInput(input);
+        }
+        catch (error) {
+            return { status: 'failed', error: asError(error) };
+        }
+        return reserveSource(input.sourceId, this.seen, this.seenOrder, this.pendingChannelSources, this.sourceIdDedupeWindow, () => this.acceptChannelInput(text));
+    }
+    async acceptChannelInput(text) {
+        return this.acceptInput(text);
+    }
+    async acceptInput(text, submitOptions) {
+        if (this.stopped)
+            return { status: 'stopped' };
+        const commandUuid = randomUUID();
+        const deferred = createRuntimeSubmission();
         const active = this.activeTurn;
         if (active !== null) {
+            active.submissions.set(commandUuid, deferred);
             try {
-                await this.steerActiveTurn(active, text);
-                return { status: 'submitted', turnId: active.turnId };
+                await this.steerActiveTurn(active, text, commandUuid);
+                return { status: 'submitted', submission: deferred.submission };
             }
-            catch (err) {
-                return {
-                    status: 'failed',
-                    error: err instanceof Error ? err : new Error(String(err)),
-                };
+            catch (error) {
+                active.submissions.delete(commandUuid);
+                deferred.settle({ kind: 'failed', error: asError(error) });
+                return classifySteerFailure(error, this.stopped);
             }
         }
-        const turnId = this.nextTurnId('turn');
         this.recordQueuedTurnStart();
+        let resolveSession;
+        let rejectSession;
+        const sessionReady = new Promise((resolve, reject) => {
+            resolveSession = resolve;
+            rejectSession = reject;
+        });
+        void sessionReady.catch(() => undefined);
         const turn = {
-            turnId,
-            pendingSteers: [],
+            initialCommandUuid: commandUuid,
+            submissions: new Map([[commandUuid, deferred]]),
+            started: [],
+            completedCommands: new Set(),
+            activitySequence: 0,
+            tools: new Map(),
             session: null,
+            sessionReady,
+            resolveSession,
+            rejectSession,
             steerQueue: Promise.resolve(),
-            // Channel-initial turns carry no explicit submit options; the native
-            // `submitTurn(prompt)` call is unchanged from before the shared active-slot
-            // refactor (the existing test asserts `submitOptions[0]` is undefined).
+            generation: this.generation,
+            ...(submitOptions !== undefined ? { submitOptions } : {}),
         };
         this.activeTurn = turn;
-        // Submit-then-serialize: return after accept (so the channel can ack
-        // promptly), run the turn on the serial queue. A turn failure cannot be
-        // returned to this caller without blocking the channel ack on full turn
-        // completion. Instead, a failed turn drives the runtime to `degraded` with a
-        // persisted `last_error` (visible via status/doctor) — never swallowed.
-        void this.runActiveTurnOnQueue(text, turn).then((resultText) => this.markTurnSucceeded(turnId, resultText), (err) => this.markTurnFailed(turnId, err));
-        return { status: 'submitted', turnId };
+        void this.runActiveTurnOnQueue(text, turn).then(() => this.markTurnSucceeded(turn), (err) => this.markTurnFailed(turn, err));
+        return { status: 'submitted', submission: deferred.submission };
+    }
+    trackAdmission(admission) {
+        this.pendingAdmissions.add(admission);
+        void admission.finally(() => {
+            this.pendingAdmissions.delete(admission);
+        }).catch(() => undefined);
+        return admission;
+    }
+    async drainAdmissions() {
+        while (this.pendingAdmissions.size > 0) {
+            await Promise.allSettled([...this.pendingAdmissions]);
+        }
     }
     waitIdle() {
         if (this.queuedTurnCount === 0)
@@ -292,61 +296,68 @@ export class ClaudeCodeRuntime {
         return run;
     }
     async runActiveTurn(prompt, active) {
-        const session = await this.ensureSession();
-        const steers = active.pendingSteers.splice(0);
-        const fullPrompt = steers.length === 0 ? prompt : [prompt, ...steers].join('\n\n');
-        const outcome = session.submitTurn(fullPrompt, active.submitOptions);
-        active.session = session;
         try {
-            return await this.applyTurnOutcome(await outcome, active.turnId);
+            this.assertGeneration(active.generation);
+            const session = await this.ensureSession();
+            this.assertGeneration(active.generation);
+            const outcome = session.submitTurn(prompt, active.submitOptions, active.initialCommandUuid);
+            active.session = session;
+            active.resolveSession(session);
+            await outcome;
+            this.assertGeneration(active.generation);
+            this.log('info', 'claude-code turn completed');
         }
         finally {
             active.session = null;
             if (this.activeTurn === active)
                 this.activeTurn = null;
-            active.pendingSteers = [];
         }
     }
-    async steerActiveTurn(active, prompt) {
-        const session = active.session;
-        if (session === null) {
-            active.pendingSteers.push(prompt);
-            return;
-        }
-        const steer = active.steerQueue.then(() => session.steerTurn(prompt, { priority: 'next' }));
+    async steerActiveTurn(active, prompt, commandUuid) {
+        this.assertGeneration(active.generation);
+        const session = active.session ?? await active.sessionReady;
+        const steer = active.steerQueue.then(() => {
+            this.assertGeneration(active.generation);
+            if (active.session !== session || this.session !== session) {
+                throw new ClaudeSteerAdmissionError('failed', 'claude-code session changed before live steer');
+            }
+            return session.steerTurn(prompt, { priority: 'next' }, commandUuid);
+        });
         active.steerQueue = steer.then(() => undefined, () => undefined);
         await steer;
+        this.assertGeneration(active.generation);
     }
-    async markTurnSucceeded(turnId, resultText) {
+    async markTurnSucceeded(turn) {
         this.recordQueuedTurnEnd();
-        this.deps.onTurnSettled?.({
-            turnId,
-            status: 'completed',
-            result: { text: resultText },
-        });
+        this.stopUnsettled(turn);
         if (this.stopped)
             return;
         if (this.status !== 'ready')
             await this.setStatus('ready');
     }
-    async markTurnFailed(turnId, err) {
+    async markTurnFailed(turn, err) {
         this.recordQueuedTurnEnd();
-        this.log('error', `claude-code turn ${turnId} failed`, err);
+        this.log('error', 'claude-code turn failed', err);
+        turn.rejectSession(asError(err));
         // A turn that fails after stop() was requested (the resident child is being
         // torn down) is a `stopped` settlement; otherwise it is a genuine `failed`.
         // Fire before the stopped early-return so an interrupted teammate turn is
         // never lost.
-        this.deps.onTurnSettled?.({
-            turnId,
-            status: this.stopped ? 'stopped' : 'failed',
-            result: { text: null },
-            error: err instanceof Error ? err : new Error(String(err)),
-        });
+        for (const deferred of turn.submissions.values()) {
+            deferred.settle(this.stopped
+                ? { kind: 'stopped' }
+                : { kind: 'failed', error: asError(err) });
+        }
         if (this.stopped)
             return;
         // Surface the failure as durable runtime state rather than swallowing it.
         await this.setStatus('degraded', err);
     }
+    stopUnsettled(turn) {
+        for (const deferred of turn.submissions.values()) {
+            deferred.settle({ kind: 'stopped' });
+        }
+    }
     recordQueuedTurnStart() {
         this.queuedTurnCount += 1;
     }
@@ -362,18 +373,47 @@ export class ClaudeCodeRuntime {
         this.idleResolve = null;
         resolve?.();
     }
-    /**
-     * Ensure a live resident session exists, spawning (or re-spawning after an
-     * unexpected exit) as needed. Re-spawn resumes the persisted session id so the
-     * conversation survives a crash.
-     */
+    /** Ensure a live resident session exists, resuming after a child exit. */
     async ensureSession() {
+        if (this.stopped)
+            throw new Error('claude-code runtime is stopped');
+        if (this.sessionStarting !== null)
+            return this.sessionStarting;
         if (this.session !== null && this.session.isAlive())
             return this.session;
+        const generation = this.generation;
+        const starting = this.createSession(generation);
+        this.sessionStarting = starting;
+        void starting.finally(() => {
+            if (this.sessionStarting === starting)
+                this.sessionStarting = null;
+        }).catch(() => undefined);
+        return starting;
+    }
+    async createSession(generation) {
+        this.assertGeneration(generation);
+        const previous = this.session;
+        if (previous !== null) {
+            await previous.stop();
+            if (this.session === previous)
+                this.session = null;
+            this.assertGeneration(generation);
+        }
+        const resuming = this.resumeOnNextSpawn;
+        const candidateSessionId = resuming
+            ? this.threadId
+            : (this.deps.generateSessionId?.() ?? randomUUID());
+        const candidatePath = await this.resolveTranscriptPath({
+            sessionId: candidateSessionId,
+            locator: resuming ? this.transcriptLocator : null,
+            resume: resuming,
+        });
         const args = claudeCodeResidentArgs({
             config: this.config,
             mcpConfigJson: this.mcpConfigJson,
-            resumeSessionId: this.threadId,
+            ...(resuming
+                ? { resumeSessionId: candidateSessionId }
+                : { freshSessionId: candidateSessionId }),
             systemPromptAppend: this.deps.systemPromptAppend,
             skillAddDirs: (this.deps.skillSources ?? []).length === 0
                 ? []
@@ -385,7 +425,7 @@ export class ClaudeCodeRuntime {
             bin: this.bin,
             args,
             cwd: this.cwd,
-            env: this.buildProcessEnv(this.config.extra_env),
+            env: buildClaudeProcessEnv(this.deps.injectEnv, this.config.extra_env),
             stderrLogPath: this.stderrLogPath,
             turnTimeoutMs: this.config.turn_timeout_ms,
             remoteControl: this.config.remote_control,
@@ -394,109 +434,87 @@ export class ClaudeCodeRuntime {
                     this.log('info', `claude-code remote control URL: ${url}`);
                 }
                 : undefined,
+            onProtocolEvent: (event) => this.onProtocolEvent(event),
             log: (level, msg, err) => this.log(level, msg, err),
         });
         session.setOnExit(() => {
             void this.onSessionExit(session);
         });
-        await session.start();
+        // Retain termination authority before spawn.
         this.session = session;
-        return session;
-    }
-    async materializeSkillAddDir() {
-        const sources = this.deps.skillSources ?? [];
-        if (sources.length === 0)
-            return;
-        const manifest = join(this.skillAddDirRoot, '.dreamux-skill-adapter.json');
-        if (await adapterExists(manifest))
-            return;
-        const tmpRoot = `${this.skillAddDirRoot}.${randomUUID()}.tmp`;
-        const tmpSkillsRoot = join(tmpRoot, '.claude', 'skills');
         try {
-            await mkdir(tmpSkillsRoot, { recursive: true });
-            const linkedNames = new Map();
-            for (const source of uniqueSkillSources(sources)) {
-                for (const skill of await skillDirsInRoot(source.path)) {
-                    const previous = linkedNames.get(skill.name);
-                    if (previous !== undefined && previous !== skill.path) {
-                        throw new Error(`duplicate Claude skill name ${JSON.stringify(skill.name)} from ` +
-                            `${previous} and ${skill.path}`);
-                    }
-                    if (previous !== undefined)
-                        continue;
-                    linkedNames.set(skill.name, skill.path);
-                    await symlink(skill.path, join(tmpSkillsRoot, skill.name), 'dir');
-                }
-            }
-            await writeFile(join(tmpRoot, '.dreamux-skill-adapter.json'), `${JSON.stringify({
-                version: 1,
-                key: skillAdapterKey(sources),
-                sources: uniqueSkillSources(sources).map((source) => ({
-                    name: source.name,
-                    path: resolve(source.path),
-                })),
-            }, null, 2)}\n`, { mode: 0o600 });
-            await mkdir(dirname(this.skillAddDirRoot), { recursive: true });
-            await rename(tmpRoot, this.skillAddDirRoot);
+            this.assertGeneration(generation);
+            await session.start();
+            this.assertGeneration(generation);
+            await this.deps.state.setCheckpoint({
+                id: candidateSessionId,
+                transcript_locator: candidatePath,
+            });
+            this.assertGeneration(generation);
+            this.threadId = candidateSessionId;
+            this.transcriptLocator = candidatePath;
+            this.resumeOnNextSpawn = true;
         }
-        catch (err) {
-            if (err.code === 'EEXIST') {
-                await rm(tmpRoot, { recursive: true, force: true }).catch(() => undefined);
-                return;
+        catch (error) {
+            if (this.stopped)
+                throw error;
+            try {
+                await session.stop();
+                if (this.session === session)
+                    this.session = null;
             }
-            await rm(tmpRoot, { recursive: true, force: true }).catch(() => undefined);
-            throw err;
+            catch (stopError) {
+                throw new AggregateError([error, stopError], 'claude session start failed and termination could not be proved');
+            }
+            throw error;
         }
+        return session;
+    }
+    resolveTranscriptPath(input) {
+        return resolveRuntimeTranscriptPath({
+            sessionId: input.sessionId,
+            cwd: this.cwd,
+            locator: input.locator,
+            env: buildClaudeProcessEnv(this.deps.injectEnv, this.config.extra_env),
+            resume: input.resume,
+            override: this.deps.resolveTranscriptPath,
+        });
     }
     /** React to an unexpected resident-child exit: degrade and drop the session. */
     async onSessionExit(session) {
         if (this.session !== session)
             return; // already replaced/stopped
-        this.session = null;
         if (this.stopped)
             return;
         this.log('error', 'claude-code resident child exited unexpectedly');
-        await this.setStatus('degraded', new Error('claude resident child exited'));
-    }
-    async applyTurnOutcome(outcome, turnId) {
-        if (outcome.sessionId !== null &&
-            outcome.sessionId !== '' &&
-            outcome.sessionId !== this.threadId) {
-            this.threadId = outcome.sessionId;
-            await this.deps.state.setCheckpoint({ id: outcome.sessionId });
+        try {
+            await session.stop();
+            if (this.session === session)
+                this.session = null;
         }
-        const resultText = outcome.isError || outcome.text === '' ? null : outcome.text;
-        if (outcome.isError) {
-            const detail = outcome.errors.length > 0
-                ? outcome.errors.join('; ')
-                : (outcome.subtype ?? 'unknown error');
-            throw new Error(`claude turn ${turnId} returned an error result: ${detail}`);
+        catch (error) {
+            await this.setStatus('degraded', error);
+            return;
         }
-        // When --json-schema was requested, Claude must return a validated
-        // `structured_output`; fail loud rather than surfacing free-form text.
-        if (this.deps.outputSchema !== undefined && !outcome.hasStructuredOutput) {
-            throw new Error(`claude turn ${turnId} did not return structured_output for a ` +
-                `--json-schema session`);
+        if (!this.stopped) {
+            await this.setStatus('degraded', new Error('claude resident child exited'));
+        }
+    }
+    onProtocolEvent(event) {
+        const active = this.activeTurn;
+        if (active === null)
+            return;
+        handleProtocolEvent(active, event, {
+            threadId: this.threadId,
+            outputSchemaEnabled: this.deps.outputSchema !== undefined,
+            activitySink: this.deps.activitySink,
+            log: (level, message, error) => this.log(level, message, error),
+        });
+    }
+    assertGeneration(generation) {
+        if (this.stopped || generation !== this.generation) {
+            throw new Error('claude-code runtime is stopped');
         }
-        // Only cache the result once all validation passes, so a failed schema turn
-        // never leaks its unvalidated free-form text through getLast().
-        if (resultText !== null)
-            this.lastResult = { text: resultText };
-        this.log('info', `claude-code turn ${turnId} completed`);
-        return resultText;
-    }
-    nextTurnId(kind) {
-        return `claude-${kind}-${this.runtimeInstanceId}-${++this.turnCounter}`;
-    }
-    buildProcessEnv(extraEnv) {
-        // Neutral env boundary: { ...process.env, ...injectEnv, ...extra_env }.
-        // `injectEnv` is the host's optional injection seam (empty today); `extraEnv`
-        // is this provider's own `config.extra_env`, merged last so it can override.
-        return {
-            ...globalThis.process.env,
-            ...(this.deps.injectEnv ?? {}),
-            ...extraEnv,
-        };
     }
     async setStatus(status, err) {
         // The in-memory status is authoritative (getStatus reads it). Persisting it is