lark-remote 0.1.6 → 0.1.7

package/dist/runner/{codex/app-server → common/jsonrpc}/connection-manager.js

@@ -1,60 +1,89 @@
 /**
- * ConnectionManager: manages Codex App Server connections per workspace.
+ * ConnectionManager: manages agent-server connections per workspace, shared by
+ * all workspace-lifetime JSON-line runners (codex app-server, kimi acp,
+ * opencode acp, and pi rpc).
  *
  * Each workspace gets its own connection (transport + client). Connections are
  * created on demand via `acquire()`, cached for reuse, and released after an
  * idle timeout (30 minutes default).
+ *
+ * The manager is protocol-agnostic over the concrete client. The default
+ * `clientFactory` builds a JsonRpcClient with the `initialize` handshake (the
+ * ACP-style reference protocol); protocols that are NOT JSON-RPC (pi's
+ * `--mode rpc`, which has no handshake and binds the session at spawn) inject
+ * their own `clientFactory` + `buildArgs` + `shouldReuse` + `bindSession`.
  */
 import { JsonlRpcTransport } from './transport.js';
-import { CodexAppServerClient } from './client.js';
+import { JsonRpcClient } from './client.js';
 import { getLogger } from '../../../logger/index.js';
 const DEFAULT_IDLE_TTL_MS = 30 * 60 * 1000; // 30 minutes
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000; // 60 seconds
 export class ConnectionManager {
     slots = new Map();
     binary;
-    args;
+    buildArgs;
     env;
     requestTimeoutMs;
     idleTtlMs;
+    initializeParams;
+    clientFactory;
+    shouldReuse;
+    logTag;
     /** Callback when a connection is lost — cleared from slot map. */
     onConnectionLost;
     constructor(opts) {
         this.binary = opts.binary;
-        this.args = opts.args ?? ['app-server', '--stdio'];
+        this.buildArgs = opts.buildArgs ?? (() => opts.args ?? []);
         this.env = opts.env ?? {};
         this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
         this.idleTtlMs = opts.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+        this.initializeParams = opts.initializeParams ?? {};
+        this.clientFactory =
+            opts.clientFactory ??
+                ((ctx) => new JsonRpcClient(ctx.transport, {
+                    onNotification: () => { },
+                    onServerRequest: () => { },
+                    onClose: ctx.baseOnClose,
+                }, ctx.requestTimeoutMs, this.initializeParams));
+        this.shouldReuse = opts.shouldReuse ?? (({ client }) => client.ready && client.healthy);
+        this.logTag = opts.logTag ?? 'jsonrpc-connection-manager';
     }
     /**
      * Acquire a connection for the given workspace.
-     * Creates a new connection if one does not exist or the previous one was lost.
+     * Creates a new connection if one does not exist or the previous one was lost
+     * (or, for session-bound protocols, bound to a different session).
      * Serializes creation so concurrent calls share the same connection.
      */
-    async acquire(workspace) {
+    async acquire(workspace, req = {}) {
         const existing = this.slots.get(workspace);
         if (existing) {
             // If a create is in flight, wait for it
             if (existing.createPromise) {
                 return existing.createPromise;
             }
-            // If the client is ready and its transport is alive, return it
-            if (existing.client.ready && existing.client.healthy) {
+            // Reuse when the (session-aware) reuse predicate holds — e.g. the client
+            // is ready and its transport is alive (default), or it is bound to the
+            // requested session (pi). Otherwise replace it so the next run respawns
+            // the process.
+            if (this.shouldReuse({
+                client: existing.client,
+                req,
+                boundSessionId: existing.boundSessionId,
+            })) {
                 return existing.client;
             }
-            // Client is disposed, dead (e.g. app-server process killed externally),
-            // or not ready — replace it so the next run respawns the process.
             this.disposeSlot(workspace);
         }
-        const createPromise = this.createClient(workspace);
+        const createPromise = this.createClient(workspace, req);
         this.slots.set(workspace, {
             client: null, // placeholder
+            boundSessionId: req.sessionId,
             idleTimer: null,
-            createPromise: createPromise,
+            createPromise,
         });
         try {
             const client = await createPromise;
-            // P2-2 竞态：创建期间 release()/disposeAll() 已把 slot 删掉（并可能已
+            // 竞态：创建期间 release()/disposeAll() 已把 slot 删掉（并可能已
             // dispose 连接）。此时不能再把新连接塞回 slot——否则会复活一个无人管理、
             // 无 idle timer 的连接泄漏。归还给调用者继续使用，但不再缓存。
             const slotAfterCreate = this.slots.get(workspace);
@@ -63,6 +92,7 @@ export class ConnectionManager {
             }
             this.slots.set(workspace, {
                 client,
+                boundSessionId: req.sessionId,
                 idleTimer: null,
                 createPromise: null,
             });
@@ -78,6 +108,16 @@ export class ConnectionManager {
             throw err;
         }
     }
+    /**
+     * Record the session id a fresh connection actually bound to (e.g. discovered
+     * via a protocol `get_state` after a fresh spawn). This lets a subsequent run
+     * resume the SAME session on the live connection instead of respawning it.
+     */
+    bindSession(workspace, sessionId) {
+        const slot = this.slots.get(workspace);
+        if (slot)
+            slot.boundSessionId = sessionId;
+    }
     /**
      * Release (dispose) a connection for the given workspace.
      */
@@ -108,7 +148,7 @@ export class ConnectionManager {
         if (slot) {
             this.clearIdleTimer(slot);
             slot.idleTimer = setTimeout(() => {
-                getLogger().info(`[codex-connection-manager] idle timeout for workspace=${workspace}, releasing connection`);
+                getLogger().info(`[${this.logTag}] idle timeout for workspace=${workspace}, releasing connection`);
                 this.disposeSlot(workspace);
             }, this.idleTtlMs);
         }
@@ -116,23 +156,19 @@ export class ConnectionManager {
     // =========================================================================
     // Internal
     // =========================================================================
-    async createClient(workspace) {
+    async createClient(workspace, req) {
         const transport = new JsonlRpcTransport({
             binary: this.binary,
-            args: this.args,
+            args: this.buildArgs(req),
             cwd: workspace,
             env: this.env,
         });
         let client = null;
-        const hooks = {
-            onNotification: (_method, _params) => {
-                // Notifications are handled by the runner via translator
-            },
-            onServerRequest: (_id, _method, _params) => {
-                // Server requests are handled by the runner via translator
-            },
-            onClose: () => {
-                getLogger().info(`[codex-connection-manager] connection closed workspace=${workspace}`);
+        client = this.clientFactory({
+            transport,
+            requestTimeoutMs: this.requestTimeoutMs,
+            baseOnClose: () => {
+                getLogger().info(`[${this.logTag}] connection closed workspace=${workspace}`);
                 // 只清理自己创建的 slot：并发 release + 重新 acquire 后 slot 可能已被
                 // 新连接占据，误删会破坏新连接。
                 if (this.slots.get(workspace)?.client === client) {
@@ -140,8 +176,7 @@ export class ConnectionManager {
                     this.onConnectionLost?.(workspace);
                 }
             },
-        };
-        client = new CodexAppServerClient(transport, hooks, this.requestTimeoutMs);
+        });
         await client.connect();
         return client;
     }
@@ -162,7 +197,7 @@ export class ConnectionManager {
                 await slot.client.dispose();
             }
             catch (err) {
-                getLogger().warn(`[codex-connection-manager] dispose error workspace=${workspace}: ${err}`);
+                getLogger().warn(`[${this.logTag}] dispose error workspace=${workspace}: ${err}`);
             }
         }
     }

package/dist/runner/{codex/app-server → common/jsonrpc}/transport.d.ts

@@ -1,9 +1,10 @@
 /**
- * JSONL-RPC transport for the Codex app-server protocol.
+ * JSONL-RPC transport shared by JSON-line-RPC agent servers
+ * (codex app-server, kimi acp, and future ACP-style integrations).
  *
- * Wraps a child process (spawned from `codex app-server`) with
- * JSON-line-based bidirectional communication: each line on stdout is a JSON
- * message from the server; each `write()` sends a JSON line to stdin.
+ * Wraps a child process with JSON-line-based bidirectional communication:
+ * each line on stdout is a JSON message from the server; each `write()`
+ * sends a JSON line to stdin.
  */
 export interface TransportEvents {
     onMessage(msg: unknown): void;

package/dist/runner/{codex/app-server → common/jsonrpc}/transport.js

@@ -1,12 +1,13 @@
 /**
- * JSONL-RPC transport for the Codex app-server protocol.
+ * JSONL-RPC transport shared by JSON-line-RPC agent servers
+ * (codex app-server, kimi acp, and future ACP-style integrations).
  *
- * Wraps a child process (spawned from `codex app-server`) with
- * JSON-line-based bidirectional communication: each line on stdout is a JSON
- * message from the server; each `write()` sends a JSON line to stdin.
+ * Wraps a child process with JSON-line-based bidirectional communication:
+ * each line on stdout is a JSON message from the server; each `write()`
+ * sends a JSON line to stdin.
  */
 import { spawn } from 'node:child_process';
-import { ProcessStopper } from '../../common/process-stopper.js';
+import { ProcessStopper } from '../process-stopper.js';
 import { getLogger } from '../../../logger/index.js';
 /** Max bytes for a single line before we disconnect (10MB). */
 const MAX_LINE_BYTES = 10 * 1024 * 1024;
@@ -40,11 +41,9 @@ export class JsonlRpcTransport {
      */
     async start(events) {
         this.events = events;
-        // 与 exec 模式对齐（SpawningRunner.getSpawnEnv 全量透传 process.env）：
-        // codex 是用户自己的可信二进制，provider 认证依赖 OPENAI_API_KEY /
-        // ANTHROPIC_API_KEY / 自定义 provider 的 env_key（codex-config.ts
-        // providerEnvKeys），代理环境依赖 HTTP(S)_PROXY、TMPDIR 等；任何白名单
-        // 收窄都会打断认证或网络。调用方 this.env 覆盖 process.env 同名键。
+        // agent 是用户自己的可信二进制，provider 认证依赖 API key /
+        // 自定义 provider 的 env_key，代理环境依赖 HTTP(S)_PROXY、TMPDIR 等；
+        // 任何白名单收窄都会打断认证或网络。调用方 this.env 覆盖 process.env 同名键。
         const childEnv = { ...process.env, ...this.env };
         const proc = spawn(this.binary, this.args, {
             cwd: this.cwd,
@@ -64,9 +63,9 @@ export class JsonlRpcTransport {
             events.onClose(reason);
             return;
         }
-        getLogger().info(`[codex-transport] spawned pid=${proc.pid} binary=${this.binary}`);
+        getLogger().info(`[jsonrpc-transport] spawned pid=${proc.pid} binary=${this.binary}`);
         proc.stdin?.on('error', (err) => {
-            getLogger().warn(`[codex-transport] stdin error: ${err.message}`);
+            getLogger().warn(`[jsonrpc-transport] stdin error: ${err.message}`);
             this.handleClose('epipe');
         });
         // Stderr: rolling buffer, last 64KB retained, only log
@@ -74,7 +73,7 @@ export class JsonlRpcTransport {
         proc.stderr?.on('data', (chunk) => {
             const text = chunk.toString('utf-8');
             stderrBuf = (stderrBuf + text).slice(-MAX_STDERR_BYTES);
-            getLogger().debug(`[codex-transport] stderr: ${text.trimEnd()}`);
+            getLogger().debug(`[jsonrpc-transport] stderr: ${text.trimEnd()}`);
         });
         // Stdout: line-split with 10MB line limit
         let remainder = '';
@@ -87,7 +86,7 @@ export class JsonlRpcTransport {
                 if (line.length === 0)
                     continue;
                 if (line.length > MAX_LINE_BYTES) {
-                    getLogger().error(`[codex-transport] line exceeds ${MAX_LINE_BYTES} bytes, disconnecting`);
+                    getLogger().error(`[jsonrpc-transport] line exceeds ${MAX_LINE_BYTES} bytes, disconnecting`);
                     this.handleClose('parse_error');
                     return;
                 }
@@ -96,7 +95,7 @@ export class JsonlRpcTransport {
                     events.onMessage(msg);
                 }
                 catch (err) {
-                    getLogger().warn(`[codex-transport] failed to parse JSON: ${err.message} line=${line.slice(0, 200)}`);
+                    getLogger().warn(`[jsonrpc-transport] failed to parse JSON: ${err.message} line=${line.slice(0, 200)}`);
                 }
             }
         });
@@ -116,11 +115,11 @@ export class JsonlRpcTransport {
             }
             const reason = signal ? `signal:${signal}` : `exit:${code}`;
             events.onClose(reason);
-            getLogger().info(`[codex-transport] process exited pid=${proc.pid} code=${code} signal=${signal}`);
+            getLogger().info(`[jsonrpc-transport] process exited pid=${proc.pid} code=${code} signal=${signal}`);
         };
         proc.once('exit', onExit);
         proc.once('error', (err) => {
-            getLogger().error(`[codex-transport] process error: ${err.message}`);
+            getLogger().error(`[jsonrpc-transport] process error: ${err.message}`);
             this.handleClose(`error:${err.message}`);
         });
     }
@@ -219,13 +218,13 @@ export class JsonlRpcTransport {
             // 异常路径（EPIPE/超长行/进程 error）也要收掉子进程，避免孤儿进程
             // 继续运行（如超长行场景子进程还在往 stdout 灌数据）。
             void this.stopper.stop(proc).catch((err) => {
-                getLogger().warn(`[codex-transport] failed to stop process during close: ${err instanceof Error ? err.message : String(err)}`);
+                getLogger().warn(`[jsonrpc-transport] failed to stop process during close: ${err instanceof Error ? err.message : String(err)}`);
             });
         }
         // 统一关闭出口：EPIPE/超长行/进程 error 都必须通知上层（connection-manager
         // 靠 onClose 删除 slot、client 靠它 failPending），否则 slot 悬挂死连接。
         this.events?.onClose(reason);
-        getLogger().info(`[codex-transport] closed: ${reason}`);
+        getLogger().info(`[jsonrpc-transport] closed: ${reason}`);
     }
 }
 //# sourceMappingURL=transport.js.map

package/dist/runner/common/jsonrpc/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * JSON-RPC 2.0 base types shared by all JSON-line-RPC agent protocols
+ * (codex app-server, kimi acp, and future ACP-style integrations).
+ *
+ * Protocol-specific method/params types live in each protocol's own
+ * protocol-types.ts; only the wire envelope lives here.
+ */
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcSuccessResponse {
+    jsonrpc: '2.0';
+    id: number | string;
+    result: unknown;
+}
+export interface JsonRpcErrorResponse {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}

package/dist/runner/common/jsonrpc/types.js

@@ -0,0 +1,9 @@
+/**
+ * JSON-RPC 2.0 base types shared by all JSON-line-RPC agent protocols
+ * (codex app-server, kimi acp, and future ACP-style integrations).
+ *
+ * Protocol-specific method/params types live in each protocol's own
+ * protocol-types.ts; only the wire envelope lives here.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/runner/common/process-stopper.d.ts

@@ -23,6 +23,7 @@ export declare class ProcessStopper {
      * Pass `immediate: true` to skip the grace window — SIGTERM and SIGKILL
      * are sent back-to-back. Safe to call on an already-exited process.
      */
-    stop(proc: ChildProcess, opts?: StopOptions): Promise<void>;
+    /** proc 可为 null（调用方已清理 currentProcess）；nullish 直接返回。 */
+    stop(proc: ChildProcess | null, opts?: StopOptions): Promise<void>;
 }
 export {};

package/dist/runner/common/process-stopper.js

@@ -19,6 +19,7 @@ export class ProcessStopper {
      * Pass `immediate: true` to skip the grace window — SIGTERM and SIGKILL
      * are sent back-to-back. Safe to call on an already-exited process.
      */
+    /** proc 可为 null（调用方已清理 currentProcess）；nullish 直接返回。 */
     async stop(proc, opts) {
         if (!proc || proc.exitCode !== null || proc.signalCode !== null) {
             return;

package/dist/runner/common/runner-utils.d.ts

@@ -1,21 +1,14 @@
-import type { ChildProcess } from 'node:child_process';
 import type { AgentEvent } from '../types.js';
 /**
- * Return the stdio config ['pipe','pipe','pipe'] used by runners that need
- * to write the prompt to the child's stdin (codex/opencode).
+ * Return the stdio config ['pipe','pipe','pipe'] used by the runner that
+ * writes the prompt to the child's stdin (claude).
  */
 export declare function pipeAllStdio(): ('ignore' | 'pipe')[];
-/**
- * Write the prompt message to the child's stdin and close it.
- * Used by codex/opencode runners which pass the prompt via stdin
- * rather than argv.
- */
-export declare function endStdinWithPrompt(proc: ChildProcess, message: string): void;
 /**
  * Build a synthetic system.init event for pre-spawn failure paths.
  *
- * When the runner exits before spawning a process (validateBeforeRun failure,
- * ENOENT spawn failure), no real system.init arrives from stdout. Without a
+ * When the runner exits before spawning a process (e.g. ENOENT spawn failure),
+ * no real system.init arrives from stdout. Without a
  * synthetic init, the bridge's pre-init result guard (§9.22) and the run-state
  * reducer's sessionId check would silently drop the error result, leaving the
  * card showing "输出流已结束，但未收到 result 事件" instead of the actual
@@ -26,8 +19,8 @@ export declare function syntheticInitEvent(sessionId?: string): AgentEvent;
 /**
  * Build a standardized auth/error result event for yield.
  *
- * Used by CodexExecRunner and OpencodeExecRunner when initialization or request
- * sending fails (e.g. not logged in, session creation failed). Produces a
+ * Used when initialization or request sending fails (e.g. not logged in,
+ * session creation failed). Produces a
  * `result`/`error` event so the bridge can render a card instead of crashing.
  */
 export declare function authErrorEvent(errorMessage: string, sessionId?: string): AgentEvent;

package/dist/runner/common/runner-utils.js

@@ -1,56 +1,15 @@
 /**
- * Return the stdio config ['pipe','pipe','pipe'] used by runners that need
- * to write the prompt to the child's stdin (codex/opencode).
+ * Return the stdio config ['pipe','pipe','pipe'] used by the runner that
+ * writes the prompt to the child's stdin (claude).
  */
 export function pipeAllStdio() {
     return ['pipe', 'pipe', 'pipe'];
 }
-/**
- * Write the prompt message to the child's stdin and close it.
- * Used by codex/opencode runners which pass the prompt via stdin
- * rather than argv.
- */
-export function endStdinWithPrompt(proc, message) {
-    const stdin = proc.stdin;
-    if (!stdin)
-        return;
-    // Guard against async EPIPE: proc.stdin.end() may emit an 'error' event
-    // asynchronously after the call returns (the child may have already exited),
-    // which the synchronous try/catch below cannot catch.
-    // Check for .once availability — in test environments stdin may be a mock
-    // object that lacks EventEmitter methods.
-    if (typeof stdin.once === 'function') {
-        stdin.once('error', (err) => {
-            if (err.code === 'EPIPE') {
-                // Child exited before we could write — not an error, just a race.
-            }
-            else {
-                // Re-throw unexpected errors so they surface as unhandled-exception
-                // rather than being silently swallowed by the EventEmitter default handler.
-                throw err;
-            }
-        });
-    }
-    try {
-        stdin.end(message, 'utf-8');
-    }
-    catch (err) {
-        if (err &&
-            typeof err === 'object' &&
-            'code' in err &&
-            err.code === 'EPIPE') {
-            // Child exited before we could write — not an error, just a race.
-        }
-        else {
-            throw err;
-        }
-    }
-}
 /**
  * Build a synthetic system.init event for pre-spawn failure paths.
  *
- * When the runner exits before spawning a process (validateBeforeRun failure,
- * ENOENT spawn failure), no real system.init arrives from stdout. Without a
+ * When the runner exits before spawning a process (e.g. ENOENT spawn failure),
+ * no real system.init arrives from stdout. Without a
  * synthetic init, the bridge's pre-init result guard (§9.22) and the run-state
  * reducer's sessionId check would silently drop the error result, leaving the
  * card showing "输出流已结束，但未收到 result 事件" instead of the actual
@@ -70,8 +29,8 @@ export function syntheticInitEvent(sessionId = '') {
 /**
  * Build a standardized auth/error result event for yield.
  *
- * Used by CodexExecRunner and OpencodeExecRunner when initialization or request
- * sending fails (e.g. not logged in, session creation failed). Produces a
+ * Used when initialization or request sending fails (e.g. not logged in,
+ * session creation failed). Produces a
  * `result`/`error` event so the bridge can render a card instead of crashing.
  */
 export function authErrorEvent(errorMessage, sessionId = '') {

package/dist/runner/common/spawning-runner.d.ts

@@ -37,8 +37,8 @@ export declare function unregisterExitCleanup(handler: ExitCleanupHandler): void
  *
  * `translate()` returns `AgentEvent | AgentEvent[] | null` (single event,
  * multiple events, or filtered-out). `isTerminal()` / `finish()` / `getTerminalError()`
- * / `hasAgentTerminalError()` are folded into the unified result event via
- * `resolveTranslatorError()`.
+ * / `hasAgentTerminalError()` are folded into the unified result event at the
+ * end of `run()`.
  *
  * `getSessionId()` / `getLastUsage()` are optional because ClaudeRunner uses
  * the stateless `translate()` hook (no translator object) and reads neither.
@@ -56,26 +56,21 @@ export interface RunnerTranslator {
  * Abstract base class for runners that spawn a child process per turn.
  *
  * Encapsulates the spawn + completion + cleanup orchestration shared by
- * Claude/Codex/OpenCode/Pi/Kimi runners. Subclasses override:
+ * Claude/Pi runners. Subclasses override:
  *   - buildArgv(opts)              → agent-specific CLI flags (required)
- *   - createTranslator(opts)       → stateful translator (codex/opencode/pi/kimi)
+ *   - createTranslator(opts)       → stateful translator (pi)
  *     OR translate(raw, ctx)       → stateless passthrough (claude)
  *
  * Optional hooks (with sensible defaults):
  *   - getStdio()                   → stdio config (default ['ignore','pipe','pipe'])
- *   - getSpawnEnv(opts)            → env vars (default process.env)
- *   - setupStdin(proc, message)    → write prompt to stdin (default no-op)
  *   - createStreamReader(stdout)   → JSONL or readline parser (default createJSONLStream)
- *   - validateBeforeRun(opts)      → pre-spawn validation (default no-op)
- *   - awaitCompletion(proc, p)     → wait for exit (default return p; kimi adds 5s race)
- *   - awaitSpawnError(proc)        → wait for spawn error (default once('error'); kimi adds 5s race)
- *   - resolveTranslatorError(t, c) → translatorError precedence (default honors agent errors)
+ *   - awaitSpawnError(proc)        → wait for spawn error (default once('error'))
  *
  * The base class always emits a unified result event at the end of `run()`
  * via `buildResultEvent(...)` — never throws on non-zero exit. This matches
- * the contract pinned by codex/opencode/pi/kimi subclass anchors and the
- * bridge's `runAgentStreamToEnd` error handling (which accepts both thrown
- * errors and yielded error-result events).
+ * the contract pinned by the agent subclass anchors and the bridge's
+ * `runAgentStreamToEnd` error handling (which accepts both thrown errors and
+ * yielded error-result events).
  */
 export declare abstract class SpawningRunner {
     protected currentProcess: ChildProcess | null;
@@ -84,6 +79,8 @@ export declare abstract class SpawningRunner {
     protected readonly spawnHeartbeat: SpawnHeartbeat;
     protected binary: string;
     protected stopGraceMs: number;
+    /** Accumulated stderr tail for the current run (filled by spawnChild). */
+    protected spawnStderr: string;
     /**
      * Log prefix used in all operational log lines emitted by this runner
      * (spawn, pid file, non-zero exit, stderr, killOrphan, stop cleanup) and
@@ -131,58 +128,19 @@ export declare abstract class SpawningRunner {
     get isRunning(): boolean;
     /**
      * stdio config for spawn. Default: stdin ignored (claude/kimi/pi pass the
-     * prompt via argv). codex/opencode override to ['pipe','pipe','pipe'] so
-     * they can write the prompt to stdin via `setupStdin`.
+     * prompt via argv).
      */
     protected getStdio(): ('ignore' | 'pipe')[];
-    /**
-     * Env vars for spawn. Default: process.env. opencode overrides to sync
-     * PWD=opts.cwd (opencode's directory detection reads PWD, not cwd).
-     */
-    protected getSpawnEnv(_opts: SpawnOptions): NodeJS.ProcessEnv;
-    /**
-     * Write the prompt to the child's stdin (called after spawn succeeds).
-     * Default: no-op. codex/opencode override to `proc.stdin.end(message)`.
-     */
-    protected setupStdin(_proc: ChildProcess, _message: string): void;
     /**
      * Create an async iterator over the child's stdout. Default: createJSONLStream
      * (claude/kimi/pi) with P1-4 backpressure enabled (pauseThreshold=100).
-     * Subclasses that need to silently skip non-JSON lines should override
-     * `handleBadStreamLine` instead of this method.
      */
     protected createStreamReader(stdout: Readable): AsyncGenerator<unknown>;
-    /**
-     * Hook called when createJSONLStream encounters a line that cannot be parsed
-     * as JSON. Default: log a warning via getLogger().warn (same format as
-     * jsonl-stream's built-in warning). Subclasses override to change behavior
-     * (e.g. codex/opencode silently skip by providing an empty override).
-     */
-    protected handleBadStreamLine(line: string): void;
     /**
      * Create a stateful translator for this run. Default: null (uses the
-     * stateless `translate(raw, ctx)` hook). codex/opencode/pi/kimi override to
-     * return their translator instance.
+     * stateless passthrough). pi overrides to return its translator instance.
      */
     protected createTranslator(_opts: SpawnOptions): RunnerTranslator | null;
-    /**
-     * Pre-spawn validation. Return an AgentEvent to yield it and abort run()
-     * (e.g. codex's API key check yields an error result and returns).
-     * Default: null (no validation).
-     */
-    protected validateBeforeRun(_opts: SpawnOptions): AgentEvent | null;
-    /**
-     * Await process completion. Default: return the completion promise as-is.
-     * kimi overrides to add a 5s timeout race + SIGKILL fallback (kimi
-     * sometimes hangs after stdout closes).
-     */
-    protected awaitCompletion(_proc: ChildProcess, completion: Promise<{
-        code: number | null;
-        signal: NodeJS.Signals | null;
-    }>): Promise<{
-        code: number | null;
-        signal: NodeJS.Signals | null;
-    }>;
     /**
      * Await the spawn 'error' event when proc.pid === undefined. Races a
      * finite timeout (review P2-11) against the 'error' event: Node guarantees
@@ -194,24 +152,20 @@ export declare abstract class SpawningRunner {
      */
     protected awaitSpawnError(proc: ChildProcess): Promise<Error | undefined>;
     /**
-     * Resolve the translatorError to pass to buildResultEvent. Default
-     * precedence (most-specific first):
-     *   - agent-reported terminal error (translator.hasAgentTerminalError()):
-     *     always wins — the agent error is the root cause, signal/code is a
-     *     consequence. E.g. codex `turn.failed` then non-zero exit.
-     *   - stream-ended-early symptom (translator.getTerminalError() set by
-     *     finish('failed')): ONLY surfaces when there is no external cause
-     *     (signal / non-zero code / user stop). The signal/code is the root
-     *     cause; the early stream-end is a symptom.
-     *   - otherwise: undefined (signal/code/stoppedByUser drives the message).
+     * Spawn the agent binary with the subclass's argv and run the shared spawn
+     * lead-in: pid-undefined check, pid-file write, heartbeat start, and stderr
+     * accumulation (tail-capped).
+     *
+     * Throws a `SpawnChildError` (carrying the user-facing spawn failure
+     * message) when the process fails to spawn (binary missing / pid undefined).
+     * On success returns the spawned child plus the accumulated stderr tail.
      *
-     * Subclasses can override for custom precedence but the default matches
-     * the contract pinned by codex/opencode subclass anchors.
+     * Shared by the base `run()` (yields an authErrorEvent on failure) and
+     * ClaudeSession's `doStartProcess` (returns the error message), which would
+     * otherwise duplicate ~60 lines of spawn lead-in with two copies of the
+     * STDERR_TAIL_BYTES cap.
      */
-    protected resolveTranslatorError(translator: RunnerTranslator | null, ctx: {
-        code: number | null;
-        signal: NodeJS.Signals | null;
-    }): string | undefined;
+    protected spawnChild(opts: SpawnOptions): Promise<ChildProcess>;
     /**
      * Spawn the agent binary with argv built by buildArgv(opts), iterate its
      * stdout stream, and yield translated events. Always emits a unified