pikiloom 0.4.72 → 0.4.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pikiloom",
-  "version": "0.4.72",
+  "version": "0.4.73",
   "description": "Put the world's smartest AI agents in your pocket. Command local Claude & Gemini via IM. | 让最好用的 IM 变成你电脑上的顶级 Agent 控制台",
   "type": "module",
   "bin": {

package/packages/kernel/dist/attachments.d.ts

@@ -0,0 +1,36 @@
+/** Mime type when the file is an inlineable image, else null. */
+export declare function imageMimeForFile(filePath: string): string | null;
+/** The text note substituted for a non-image attachment. */
+export declare function attachedFileNote(filePath: string): string;
+/**
+ * Anthropic scales any image whose long edge exceeds 1568px before the model sees it, and —
+ * once a single request carries MORE THAN 20 images — outright REJECTS any image over 2000px
+ * on a side ("dimensions exceed max allowed size for many-image requests"). A long session
+ * full of screenshots easily crosses 20 images, at which point one freshly attached (or
+ * mid-turn steered) full-resolution screenshot gets the whole image stripped from the turn.
+ * Capping the long edge at Anthropic's own downscale threshold loses no detail the model
+ * would have kept and makes the many-image rejection unreachable. Other providers only gain
+ * from smaller uploads.
+ */
+export declare const MAX_IMAGE_EDGE = 1568;
+/**
+ * Pixel dimensions parsed from an image buffer's header (PNG / JPEG / GIF / WebP),
+ * or null when the bytes aren't one of those formats. Header-only: never decodes.
+ */
+export declare function imageDimensions(buf: Buffer): {
+    width: number;
+    height: number;
+} | null;
+type Resizer = 'sips' | 'magick' | 'convert' | 'none';
+/** Test seam: force re-probing (and optionally stub) the resize engine. */
+export declare function resetResizerForTest(value?: Resizer | null): void;
+/**
+ * Swap oversized raster images (long edge > {@link MAX_IMAGE_EDGE}) for downscaled temp
+ * copies, leaving everything else — small images, non-images, unreadable paths, animated
+ * gifs — untouched. Best-effort by design: any probe/resize failure keeps the original, so
+ * an attachment is never dropped; the worst case is the pre-existing behaviour. Called once
+ * per dispatch at the Hub chokepoints (turn start + mid-turn steer), so every driver —
+ * built-in or host-plugged — sends model-safe images.
+ */
+export declare function normalizeImageAttachments(attachments: string[] | undefined, log?: (msg: string) => void): Promise<string[] | undefined>;
+export {};

package/packages/kernel/dist/attachments.js

@@ -0,0 +1,162 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path, { extname } from 'node:path';
+// Attachment vocabulary + normalization, shared by the runtime (Hub) and every driver.
+// NOT part of the public API — nothing here is re-exported by any barrel.
+// Every driver inlines the same image formats (the Anthropic vision set, which the
+// others accept too) and notes non-image files the same way.
+const IMAGE_MIME_BY_EXT = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.webp': 'image/webp',
+};
+/** Mime type when the file is an inlineable image, else null. */
+export function imageMimeForFile(filePath) {
+    return IMAGE_MIME_BY_EXT[extname(filePath).toLowerCase()] ?? null;
+}
+/** The text note substituted for a non-image attachment. */
+export function attachedFileNote(filePath) {
+    return `[Attached file: ${filePath}]`;
+}
+/**
+ * Anthropic scales any image whose long edge exceeds 1568px before the model sees it, and —
+ * once a single request carries MORE THAN 20 images — outright REJECTS any image over 2000px
+ * on a side ("dimensions exceed max allowed size for many-image requests"). A long session
+ * full of screenshots easily crosses 20 images, at which point one freshly attached (or
+ * mid-turn steered) full-resolution screenshot gets the whole image stripped from the turn.
+ * Capping the long edge at Anthropic's own downscale threshold loses no detail the model
+ * would have kept and makes the many-image rejection unreachable. Other providers only gain
+ * from smaller uploads.
+ */
+export const MAX_IMAGE_EDGE = 1568;
+/**
+ * Pixel dimensions parsed from an image buffer's header (PNG / JPEG / GIF / WebP),
+ * or null when the bytes aren't one of those formats. Header-only: never decodes.
+ */
+export function imageDimensions(buf) {
+    if (buf.length >= 24 && buf.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) {
+        return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+    }
+    if (buf.length >= 10 && (buf.subarray(0, 6).toString('latin1') === 'GIF87a' || buf.subarray(0, 6).toString('latin1') === 'GIF89a')) {
+        return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+    }
+    if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xd8) {
+        // JPEG: walk segments to the first SOF (skips arbitrarily large EXIF/APPn blocks).
+        let i = 2;
+        while (i + 9 < buf.length) {
+            if (buf[i] !== 0xff) {
+                i++;
+                continue;
+            }
+            const marker = buf[i + 1];
+            if (marker === 0xff) {
+                i++;
+                continue;
+            } // fill byte
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                return { width: buf.readUInt16BE(i + 7), height: buf.readUInt16BE(i + 5) };
+            }
+            if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd9)) {
+                i += 2;
+                continue;
+            } // standalone
+            i += 2 + buf.readUInt16BE(i + 2);
+        }
+        return null;
+    }
+    if (buf.length >= 30 && buf.subarray(0, 4).toString('latin1') === 'RIFF' && buf.subarray(8, 12).toString('latin1') === 'WEBP') {
+        const chunk = buf.subarray(12, 16).toString('latin1');
+        if (chunk === 'VP8X')
+            return { width: 1 + buf.readUIntLE(24, 3), height: 1 + buf.readUIntLE(27, 3) };
+        if (chunk === 'VP8L')
+            return { width: 1 + (buf.readUInt32LE(21) & 0x3fff), height: 1 + ((buf.readUInt32LE(21) >> 14) & 0x3fff) };
+        if (chunk === 'VP8 ')
+            return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff };
+    }
+    return null;
+}
+let resizerCache = null;
+function run(cmd, args) {
+    return new Promise((resolve, reject) => {
+        execFile(cmd, args, { timeout: 10_000 }, (err) => (err ? reject(err) : resolve()));
+    });
+}
+function detectResizer() {
+    if (resizerCache)
+        return resizerCache;
+    if (process.platform === 'darwin')
+        return (resizerCache = 'sips');
+    resizerCache = (async () => {
+        for (const cmd of ['magick', 'convert']) {
+            try {
+                await run(cmd, ['-version']);
+                return (resizerCache = cmd);
+            }
+            catch { /* try next */ }
+        }
+        return (resizerCache = 'none');
+    })();
+    return resizerCache;
+}
+/** Test seam: force re-probing (and optionally stub) the resize engine. */
+export function resetResizerForTest(value = null) {
+    resizerCache = value;
+}
+// Downscale `src` so its long edge is `maxEdge`, into a fresh temp file; null = keep the
+// original (no engine, or the engine failed/produced nothing). WebP output support varies
+// by sips version, so webp is re-encoded as PNG — the extension switch keeps the drivers'
+// mime mapping truthful.
+async function resizeToTemp(src, maxEdge) {
+    const resizer = await detectResizer();
+    if (resizer === 'none')
+        return null;
+    const srcExt = extname(src).toLowerCase();
+    const outExt = srcExt === '.webp' ? '.png' : srcExt;
+    const out = path.join(os.tmpdir(), `pikiloom-att-${randomUUID().slice(0, 8)}${outExt}`);
+    try {
+        if (resizer === 'sips') {
+            const format = srcExt === '.webp' ? ['-s', 'format', 'png'] : [];
+            await run('sips', [...format, '-Z', String(maxEdge), src, '--out', out]);
+        }
+        else {
+            await run(resizer, [src, '-resize', `${maxEdge}x${maxEdge}>`, out]);
+        }
+        return fs.statSync(out).size > 0 ? out : null;
+    }
+    catch {
+        fs.rmSync(out, { force: true });
+        return null;
+    }
+}
+/**
+ * Swap oversized raster images (long edge > {@link MAX_IMAGE_EDGE}) for downscaled temp
+ * copies, leaving everything else — small images, non-images, unreadable paths, animated
+ * gifs — untouched. Best-effort by design: any probe/resize failure keeps the original, so
+ * an attachment is never dropped; the worst case is the pre-existing behaviour. Called once
+ * per dispatch at the Hub chokepoints (turn start + mid-turn steer), so every driver —
+ * built-in or host-plugged — sends model-safe images.
+ */
+export async function normalizeImageAttachments(attachments, log) {
+    if (!attachments?.length)
+        return attachments;
+    const out = [...attachments];
+    for (let i = 0; i < out.length; i++) {
+        const file = out[i];
+        const mime = imageMimeForFile(file);
+        if (!mime || mime === 'image/gif')
+            continue; // gif: resizing would mangle animation
+        try {
+            const dims = imageDimensions(fs.readFileSync(file));
+            if (!dims || Math.max(dims.width, dims.height) <= MAX_IMAGE_EDGE)
+                continue;
+            const resized = await resizeToTemp(file, MAX_IMAGE_EDGE);
+            if (resized) {
+                out[i] = resized;
+                log?.(`[attachments] downscaled ${path.basename(file)} ${dims.width}x${dims.height} -> long edge ${MAX_IMAGE_EDGE}`);
+            }
+        }
+        catch { /* unreadable — the drivers' own fallback (file note) handles it */ }
+    }
+    return out;
+}

package/packages/kernel/dist/contracts/driver.d.ts

@@ -79,6 +79,7 @@ export interface DriverResult {
     sessionId?: string | null;
     usage?: UniversalUsage | null;
     anchor?: string | null;
+    transport?: 'cold' | 'warm' | null;
 }
 export interface TuiInput {
     workdir: string;

package/packages/kernel/dist/drivers/claude-pool.d.ts

@@ -0,0 +1,20 @@
+import type { ChildProcess } from 'node:child_process';
+export declare function claudeWarmIdleTtlMs(): number;
+export declare function claudeWarmMaxProcesses(): number;
+export declare class ClaudeWarmPool {
+    private readonly parked;
+    size(): number;
+    /**
+     * Reclaim the parked process for `sessionId`, or null when there is none, it died while
+     * parked, or its spawn fingerprint no longer matches (that entry is destroyed — the turn
+     * must go cold so the new model/effort/config actually applies).
+     */
+    take(sessionId: string, fingerprint: string): ChildProcess | null;
+    /** Park a process after a clean settle. The caller has already detached its turn listeners. */
+    put(sessionId: string, fingerprint: string, child: ChildProcess): void;
+    /** Destroy the parked process for a session (rewind made its in-memory context stale, TTL, cap). */
+    evictSession(sessionId: string): void;
+    dispose(): void;
+    /** Remove bookkeeping without deciding the child's fate. */
+    private unpark;
+}

package/packages/kernel/dist/drivers/claude-pool.js

@@ -0,0 +1,125 @@
+import { sigterm } from './shared.js';
+// ── Warm Claude process pool ─────────────────────────────────────────────────────────
+// A `claude -p --input-format stream-json` process stays alive after `result` for as long
+// as its stdin is open, and a user message written to that stdin runs a NEW turn in the
+// same conversation (the steer path has always relied on this). Every cold spawn costs
+// ~4s of CLI init before the first model request — the single largest local overhead of a
+// Claude turn — so after a clean settle the driver parks the process here instead of
+// killing it, and the session's next continuation turn skips the spawn entirely.
+//
+// Discipline (mirrors mirasim's Codex warm pool):
+//  - keyed by native session id; one process per session, serial turns only.
+//  - a process is reused only when its spawn-time fingerprint (model/effort/workdir/…)
+//    still matches what a cold spawn would use; any drift destroys it and goes cold.
+//  - idle processes are destroyed after a TTL; the pool is size-capped (oldest-idle out).
+//  - only CLEAN settles pool (no error / abort / timeout / background hold); everything
+//    else keeps today's kill semantics, so pooling can never leak a wedged process.
+// Idle TTL before a parked process is destroyed. Override with PIKILOOM_CLAUDE_WARM_IDLE_MS.
+const CLAUDE_WARM_IDLE_TTL_DEFAULT_MS = 10 * 60_000;
+export function claudeWarmIdleTtlMs() {
+    const raw = Number(process.env.PIKILOOM_CLAUDE_WARM_IDLE_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : CLAUDE_WARM_IDLE_TTL_DEFAULT_MS;
+}
+// Max parked processes (each holds a full CLI + its MCP servers — roughly 0.5–1 GB).
+// Override with PIKILOOM_CLAUDE_WARM_MAX.
+const CLAUDE_WARM_MAX_DEFAULT = 4;
+export function claudeWarmMaxProcesses() {
+    const raw = Number(process.env.PIKILOOM_CLAUDE_WARM_MAX);
+    return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : CLAUDE_WARM_MAX_DEFAULT;
+}
+// After ending a parked process's stdin, force-kill only if it hasn't exited on its own
+// within this window — same leak-guard shape as a graceful turn settle.
+const CLAUDE_WARM_DESTROY_GUARD_MS = 15_000;
+/** End a no-longer-poolable process the same way a graceful settle does. */
+function destroyClaudeChild(child) {
+    try {
+        child.stdin?.end();
+    }
+    catch { /* ignore */ }
+    if (child.exitCode != null || child.killed)
+        return;
+    const guard = setTimeout(() => sigterm(child), CLAUDE_WARM_DESTROY_GUARD_MS);
+    if (typeof guard.unref === 'function')
+        guard.unref();
+}
+export class ClaudeWarmPool {
+    parked = new Map();
+    size() {
+        return this.parked.size;
+    }
+    /**
+     * Reclaim the parked process for `sessionId`, or null when there is none, it died while
+     * parked, or its spawn fingerprint no longer matches (that entry is destroyed — the turn
+     * must go cold so the new model/effort/config actually applies).
+     */
+    take(sessionId, fingerprint) {
+        const entry = this.parked.get(sessionId);
+        if (!entry)
+            return null;
+        this.unpark(sessionId, entry);
+        if (entry.child.exitCode != null || entry.child.killed)
+            return null;
+        if (entry.fingerprint !== fingerprint) {
+            destroyClaudeChild(entry.child);
+            return null;
+        }
+        return entry.child;
+    }
+    /** Park a process after a clean settle. The caller has already detached its turn listeners. */
+    put(sessionId, fingerprint, child) {
+        if (child.exitCode != null || child.killed || !child.stdin || child.stdin.destroyed) {
+            destroyClaudeChild(child);
+            return;
+        }
+        this.evictSession(sessionId); // never two processes for one session
+        while (this.parked.size >= Math.max(claudeWarmMaxProcesses(), 0)) {
+            const oldest = [...this.parked.entries()].sort((a, b) => a[1].parkedAt - b[1].parkedAt)[0];
+            if (!oldest)
+                break;
+            this.evictSession(oldest[0]);
+        }
+        if (claudeWarmMaxProcesses() <= 0) {
+            destroyClaudeChild(child);
+            return;
+        }
+        const onClose = () => {
+            const cur = this.parked.get(sessionId);
+            if (cur?.child === child) {
+                this.unpark(sessionId, cur);
+            }
+        };
+        // Keep both pipes flowing while parked so the CLI can never block on a full pipe.
+        const drain = () => { };
+        child.stdout?.on('data', drain);
+        child.stderr?.on('data', drain);
+        child.on('close', onClose);
+        const idleTimer = setTimeout(() => {
+            const cur = this.parked.get(sessionId);
+            if (cur?.child === child)
+                this.evictSession(sessionId);
+        }, claudeWarmIdleTtlMs());
+        if (typeof idleTimer.unref === 'function')
+            idleTimer.unref();
+        this.parked.set(sessionId, { child, fingerprint, parkedAt: Date.now(), idleTimer, onClose, drain });
+    }
+    /** Destroy the parked process for a session (rewind made its in-memory context stale, TTL, cap). */
+    evictSession(sessionId) {
+        const entry = this.parked.get(sessionId);
+        if (!entry)
+            return;
+        this.unpark(sessionId, entry);
+        destroyClaudeChild(entry.child);
+    }
+    dispose() {
+        for (const sessionId of [...this.parked.keys()])
+            this.evictSession(sessionId);
+    }
+    /** Remove bookkeeping without deciding the child's fate. */
+    unpark(sessionId, entry) {
+        clearTimeout(entry.idleTimer);
+        entry.child.stdout?.off('data', entry.drain);
+        entry.child.stderr?.off('data', entry.drain);
+        entry.child.off('close', entry.onClose);
+        this.parked.delete(sessionId);
+    }
+}

package/packages/kernel/dist/drivers/claude.d.ts

@@ -1,5 +1,12 @@
 import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, DriverEvent, TuiInput, TuiSpec, NativeSessionInfo } from '../contracts/driver.js';
 import type { UniversalPlan } from '../protocol/index.js';
+export interface ClaudeDriverOptions {
+    /** Keep the CLI process alive after a clean turn and reuse it for the session's next
+     *  continuation turn (skips the ~4s spawn+init). Off by default: a parked process holds
+     *  real memory and keeps the event loop alive, which a one-shot embedder must not inherit
+     *  silently. Long-lived hosts opt in and call dispose() on shutdown. */
+    warmPool?: boolean;
+}
 export declare class ClaudeDriver implements AgentDriver {
     private readonly bin;
     readonly id = "claude";
@@ -11,7 +18,12 @@ export declare class ClaudeDriver implements AgentDriver {
         fork: boolean;
         rewind: boolean;
     };
-    constructor(bin?: string);
+    private readonly pool;
+    constructor(bin?: string, opts?: ClaudeDriverOptions);
+    /** Destroy every parked warm process. Long-lived hosts call this on shutdown. */
+    dispose(): void;
+    /** Parked warm processes right now (tests + telemetry). */
+    warmPoolSize(): number;
     tui(input: TuiInput): TuiSpec;
     listNativeSessions(opts: {
         workdir: string;
@@ -24,6 +36,7 @@ export declare class ClaudeDriver implements AgentDriver {
         workdir: string;
     }): string | null;
 }
+export declare function claudeProcessFingerprint(bin: string, input: AgentTurnInput): string;
 export declare function claudeResumeArgs(sessionId: string, fork?: {
     anchor?: string | null;
 } | null, rewind?: {

package/packages/kernel/dist/drivers/claude.js

@@ -1,17 +1,24 @@
 import { spawn } from 'node:child_process';
 import { readFileSync } from 'node:fs';
+import { ClaudeWarmPool } from './claude-pool.js';
 import { claudeTranscriptTailAnchor, discoverClaudeNativeSessions } from './native.js';
 import { attachedFileNote, contextPercent, createLineBuffer, imageMimeForFile, parseJsonLine, sigterm, wireAbort } from './shared.js';
-// Real driver: shells the local `claude` CLI in stream-json mode and normalizes its
-// events into kernel DriverEvents. Faithful to pikiloom's claude.ts event shapes
-// (system / stream_event{message_start,content_block_delta,message_delta} / assistant / result),
-// but fully self-contained. Proves "下层 Claude 不变".
 export class ClaudeDriver {
     bin;
     id = 'claude';
     capabilities = { steer: true, interact: false, resume: true, tui: true, fork: true, rewind: true };
-    constructor(bin = 'claude') {
+    pool;
+    constructor(bin = 'claude', opts = {}) {
         this.bin = bin;
+        this.pool = opts.warmPool ? new ClaudeWarmPool() : null;
+    }
+    /** Destroy every parked warm process. Long-lived hosts call this on shutdown. */
+    dispose() {
+        this.pool?.dispose();
+    }
+    /** Parked warm processes right now (tests + telemetry). */
+    warmPoolSize() {
+        return this.pool?.size() ?? 0;
     }
     // Interactive Claude Code TUI (no -p): the kernel spawns this in a PTY and passes
     // the terminal through. Model/resume/BYOK-env come from the kernel's resolution.
@@ -54,6 +61,17 @@ export class ClaudeDriver {
             args.push('--replay-user-messages'); // parity: mid-turn steer
         if (input.extraArgs?.length)
             args.push(...input.extraArgs);
+        // Warm reuse: a rewind rebranches the session's transcript, so a parked process's
+        // in-memory conversation is stale — destroy it. A fork never touches the parent's
+        // transcript (the parked parent stays valid); the fork turn itself must cold-spawn
+        // for its --fork-session flags. Only a plain continuation may reclaim a process, and
+        // only when the spawn fingerprint still matches what a cold spawn would use now.
+        const fingerprint = claudeProcessFingerprint(this.bin, input);
+        if (input.rewind && input.sessionId)
+            this.pool?.evictSession(input.sessionId);
+        const pooled = (!input.fork && !input.rewind && input.sessionId && this.pool)
+            ? this.pool.take(input.sessionId, fingerprint)
+            : null;
         const state = {
             text: '', reasoning: '', streamedText: false, streamedReasoning: false,
             // Dangling-tool-loop tracking: sawToolResult flips on the first tool_result; textSinceToolResult
@@ -82,6 +100,8 @@ export class ClaudeDriver {
         };
         return new Promise((resolve) => {
             let child;
+            let transport = 'cold';
+            let promptDelivered = false;
             let settled = false;
             // One-shot guard for the truncated-turn recovery injection (see the result handler).
             let truncatedRecoveryAttempted = false;
@@ -101,6 +121,8 @@ export class ClaudeDriver {
             const usageOf = () => this.usage(state);
             const unref = (tm) => { if (tm && typeof tm.unref === 'function')
                 tm.unref(); };
+            let disposeAbort = null;
+            let detachTurnListeners = () => { };
             const clearHoldCap = () => { if (holdCapTimer) {
                 clearTimeout(holdCapTimer);
                 holdCapTimer = null;
@@ -118,18 +140,29 @@ export class ClaudeDriver {
             // kill=false only ends stdin and lets Claude shut down on its own, so any still-running
             // detached background work survives a clean exit (a hard kill mid-flight is exactly what
             // tore the background — and the wake-up — down before). A leak-guard SIGTERM is the backstop.
-            const finish = (r, kill = true) => {
+            const finish = (r, kill = true, park = false) => {
                 if (settled)
                     return;
                 settled = true;
                 clearHoldCap();
                 clearQuiet();
                 clearModelStall();
+                disposeAbort?.();
+                // Park instead of kill: only a CLEAN settle qualifies (ok, no error, no abort, the
+                // process still healthy, session known) — every other exit keeps today's semantics,
+                // so pooling can never leak a wedged or errored process.
+                if (park && this.pool && state.sessionId && r.ok && !r.error && !ctx.signal.aborted
+                    && child && !child.killed && child.exitCode == null) {
+                    detachTurnListeners();
+                    this.pool.put(state.sessionId, fingerprint, child);
+                    resolve({ ...r, transport });
+                    return;
+                }
                 try {
                     child?.stdin?.end();
                 }
                 catch { /* ignore */ }
-                if (!child.killed && child.exitCode == null) {
+                if (child && !child.killed && child.exitCode == null) {
                     if (kill)
                         sigterm(child);
                     else {
@@ -137,12 +170,12 @@ export class ClaudeDriver {
                         unref(guard);
                     }
                 }
-                resolve(r);
+                resolve({ ...r, transport });
             };
             const settleResult = (opts = {}) => finish({
                 ok: opts.ok ?? !state.error, text: state.text, reasoning: state.reasoning || undefined,
                 error: state.error, stopReason: opts.stopReason ?? state.stopReason, sessionId: state.sessionId, anchor: state.anchor, usage: usageOf(),
-            }, opts.kill ?? true);
+            }, opts.kill ?? true, opts.park ?? false);
             // Cap while holding for a still-running background task (stopReason marks it as
             // "still running in the background" so the terminal presentation reads right). Idempotent —
             // the countdown is absolute from the first arm. Sub-agent-backed holds use the longer
@@ -199,14 +232,32 @@ export class ClaudeDriver {
                 }, claudeModelStallMs(input.effort));
                 unref(modelStallTimer);
             };
-            try {
-                child = spawn(this.bin, args, { cwd: input.workdir, env: { ...process.env, ...(input.env || {}) }, stdio: ['pipe', 'pipe', 'pipe'] });
+            // Acquire the process: a reclaimed warm process gets the prompt as its acquisition
+            // probe — a dead pipe throws synchronously here and the turn transparently falls
+            // back to a cold spawn (whose --resume flags are already in `args`).
+            let acquired = null;
+            if (pooled) {
+                try {
+                    pooled.stdin.write(claudeUserMessage(input.prompt, input.attachments) + '\n');
+                    acquired = pooled;
+                    transport = 'warm';
+                    promptDelivered = true;
+                }
+                catch {
+                    sigterm(pooled);
+                }
             }
-            catch (err) {
-                finish({ ok: false, text: '', error: `spawn failed: ${err?.message || err}`, stopReason: 'error' });
-                return;
+            if (!acquired) {
+                try {
+                    acquired = spawn(this.bin, args, { cwd: input.workdir, env: { ...process.env, ...(input.env || {}) }, stdio: ['pipe', 'pipe', 'pipe'] });
+                }
+                catch (err) {
+                    finish({ ok: false, text: '', error: `spawn failed: ${err?.message || err}`, stopReason: 'error' });
+                    return;
+                }
             }
-            wireAbort(ctx.signal, () => sigterm(child));
+            child = acquired;
+            disposeAbort = wireAbort(ctx.signal, () => sigterm(child));
             if (steerable) {
                 ctx.registerSteer(async (prompt, attachments) => {
                     try {
@@ -220,7 +271,7 @@ export class ClaudeDriver {
             }
             const nextLines = createLineBuffer();
             let stderr = '';
-            child.stdout.on('data', (chunk) => {
+            const onStdout = (chunk) => {
                 if (settled)
                     return; // ignore the process's post-settle shutdown chatter
                 for (const line of nextLines(chunk)) {
@@ -299,8 +350,10 @@ export class ClaudeDriver {
                             // DELIVERED live but never lands in the transcript, so the next re-render erases
                             // it (the "对话结束之后就被吞了" shape, caught by the turn audit). Ending stdin
                             // lets the CLI finish writing and exit on its own; the leak-guard SIGTERM is the
-                            // backstop.
-                            settleResult({ kill: false });
+                            // backstop. park: this clean settle is the ONE warm-pool-eligible exit — the
+                            // process (stdin open, transcript flushing in its own time) is parked for the
+                            // session's next turn instead of being shut down; finish() re-checks health.
+                            settleResult({ kill: false, park: true });
                             return;
                         }
                         if (decision === 'hold') {
@@ -332,10 +385,10 @@ export class ClaudeDriver {
                     if (ev.type === 'user' && pending === 0 && claudeUserEventHasToolResult(ev))
                         armModelStall();
                 }
-            });
-            child.stderr.on('data', (c) => { stderr += c.toString('utf8'); });
-            child.on('error', (err) => finish({ ok: false, text: state.text, error: `claude spawn error: ${err.message}`, stopReason: 'error' }));
-            child.on('close', (code) => {
+            };
+            const onStderr = (c) => { stderr += c.toString('utf8'); };
+            const onError = (err) => finish({ ok: false, text: state.text, error: `claude spawn error: ${err.message}`, stopReason: 'error' });
+            const onClose = (code) => {
                 if (settled)
                     return;
                 if (ctx.signal.aborted) {
@@ -349,13 +402,27 @@ export class ClaudeDriver {
                 // dangling check must win over it.)
                 const stopReason = (ok && claudeTurnEndedDangling(state)) ? 'truncated' : state.stopReason;
                 finish({ ok, text: state.text, reasoning: state.reasoning || undefined, error: state.error || (ok ? null : `claude exited ${code}${stderr ? `: ${stderr.slice(0, 300)}` : ''}`), stopReason, sessionId: state.sessionId, anchor: state.anchor, usage: usageOf() }, false);
-            });
-            try {
-                // Send the prompt as a stream-json user message and keep stdin OPEN (do not end it here):
-                // closing it makes Claude exit at the first `result`, before any background task finishes.
-                child.stdin.write(claudeUserMessage(input.prompt, input.attachments) + '\n');
+            };
+            // Parking hands the process to the pool — these turn-scoped listeners must not
+            // outlive the turn (the pool installs its own drain + close bookkeeping).
+            detachTurnListeners = () => {
+                child.stdout?.off('data', onStdout);
+                child.stderr?.off('data', onStderr);
+                child.off('error', onError);
+                child.off('close', onClose);
+            };
+            child.stdout.on('data', onStdout);
+            child.stderr.on('data', onStderr);
+            child.on('error', onError);
+            child.on('close', onClose);
+            if (!promptDelivered) {
+                try {
+                    // Send the prompt as a stream-json user message and keep stdin OPEN (do not end it here):
+                    // closing it makes Claude exit at the first `result`, before any background task finishes.
+                    child.stdin.write(claudeUserMessage(input.prompt, input.attachments) + '\n');
+                }
+                catch { /* ignore */ }
             }
-            catch { /* ignore */ }
         });
     }
     usage(s) {
@@ -367,6 +434,38 @@ export class ClaudeDriver {
         return claudeTranscriptTailAnchor(opts.workdir, opts.sessionId);
     }
 }
+// The spawn-time facts that must still match for a parked warm process to serve a
+// continuation turn as if it were a fresh cold `--resume` — any drift (model switch,
+// effort change, new MCP config, different BYOK env, …) destroys the parked process so
+// the new configuration actually applies. `sessionId` is the pool key, not fingerprint
+// material, and `systemPrompt` is deliberately EXCLUDED: it is a first-turn-only input
+// (the parked process already carries it applied; a cold --resume would not re-send it
+// either), so including it would make every continuation miss the pool. Pure + exported
+// for hermetic testing.
+export function claudeProcessFingerprint(bin, input) {
+    return JSON.stringify([
+        bin, input.workdir, input.model ?? null, input.effort ?? null,
+        input.mcpConfigPath ?? null, input.permissionMode ?? null, !!input.steerable,
+        fingerprintExtraArgs(input.extraArgs),
+        Object.entries(input.env ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+    ]);
+}
+// `--session-id <uuid>` pins a FRESH session's native id and is contributed on the first
+// turn only (continuations resume instead) — it names the session, it doesn't configure
+// the process. Like sessionId itself it must not be fingerprint material, or every
+// continuation of a session born with it would miss the pool forever.
+function fingerprintExtraArgs(extraArgs) {
+    const args = extraArgs ?? [];
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--session-id') {
+            i++;
+            continue;
+        }
+        out.push(args[i]);
+    }
+    return out;
+}
 // The --resume flag family for one turn: plain resume appends to the session; a fork branches
 // a NEW session off it (--fork-session), optionally cut at an inclusive keep-boundary record
 // uuid (--resume-session-at); a rewind cuts at that boundary WITHOUT --fork-session, so claude

package/packages/kernel/dist/drivers/codex.d.ts

@@ -19,8 +19,15 @@ export declare function captureCodexAgentMessage(item: any, s: CodexContentState
 export declare function captureCodexReasoning(text: string, s: CodexContentState, emit: (e: DriverEvent) => void): void;
 export declare function codexFinalText(s: CodexContentState): string;
 export declare function codexFinalReasoning(s: CodexContentState): string;
+export interface CodexLivenessOptions {
+    /** Silence after an accepted steer before the turn is healed (interrupt + replay). */
+    steerStallMs?: number;
+    /** Idle silence (no running tool, no pending HITL request) before the turn is force-closed. */
+    turnStallMs?: number;
+}
 export declare class CodexDriver implements AgentDriver {
     private readonly bin;
+    private readonly liveness;
     readonly id = "codex";
     readonly capabilities: {
         steer: boolean;
@@ -29,7 +36,7 @@ export declare class CodexDriver implements AgentDriver {
         tui: boolean;
         fork: boolean;
     };
-    constructor(bin?: string);
+    constructor(bin?: string, liveness?: CodexLivenessOptions);
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     tui(input: TuiInput): TuiSpec;
     listNativeSessions(opts: {

package/packages/kernel/dist/drivers/codex.js

@@ -234,12 +234,53 @@ export function codexFinalText(s) {
 export function codexFinalReasoning(s) {
     return s.reasoning.trim() ? s.reasoning : s.thinkParts.join('\n\n');
 }
+// ── Turn liveness (steer race + silent-stall recovery) ──────────────────────────
+// codex app-server has a turn-boundary race: a `turn/steer` that lands in the instant an
+// item completes is ACCEPTED (recorded into the rollout) but never dispatched — the agent
+// loop goes idle, no further notifications arrive, and `turn/completed` never fires, so the
+// turn hangs forever while the process sits at 0% CPU (observed on codex-cli 0.144.x;
+// same family as openai/codex#15714 / #23807). Two defenses below:
+//
+// 1. A successful steer is treated as ACCEPTED, NOT CONSUMED: it stays pending until a
+//    progress notification proves the loop picked it up. If the turn instead goes silent
+//    (or completes without consuming it), the driver heals in place — interrupt the wedged
+//    turn and restart it with the same input. The steered text is already in the thread
+//    history, so the worst false-positive cost is one duplicated user message; the turn
+//    keeps running under the same run()/task, invisible to upper layers.
+// 2. A generic silence backstop: a turn with no notifications for a long stretch while
+//    nothing is visibly in flight (no running tool call, no server->client request awaiting
+//    a human) is declared stalled and force-closed, so the session ends as a visible error
+//    instead of spinning forever.
+// Thresholds are calibrated against measured rollouts: with reasoning summaries off, a
+// HEALTHY turn shows fully silent thinking stretches of up to ~320s (clustered just above
+// codex core's own 300s stream watchdog, whose retry produces the next event). 600s has
+// never been reached intra-turn in days of observed sessions, so a heal at that point is
+// near-certainly a real wedge — and even a misfire only costs one duplicated user message
+// plus the in-flight thinking (completed items live in the thread history).
+const CODEX_STEER_STALL_MS = 600_000;
+const CODEX_TURN_STALL_MS = 900_000;
+// Notifications that prove the agent loop is making forward progress AFTER a steer.
+// item/completed and tokenUsage are deliberately excluded — they can be the trailing edge
+// of work that finished before the steer landed (the exact race signature). Progress that
+// arrives within CODEX_STEER_CONSUMED_MS of the steer only refreshes the pending marker's
+// clock rather than clearing it: the app-server can flush pre-acceptance stream output in
+// the same write as the steer response, so near-simultaneous events are not proof the
+// loop survived the injection. Progress beyond that window is.
+const CODEX_STEER_CONSUMED_MS = 2_000;
+const CODEX_PROGRESS_METHODS = new Set([
+    'turn/started', 'item/started', 'item/agentMessage/delta',
+    'item/reasoning/textDelta', 'item/reasoning/summaryTextDelta',
+    'item/commandExecution/outputDelta', 'item/fileChange/outputDelta',
+    'item/fileChange/patchUpdated', 'turn/plan/updated', 'rawResponseItem/completed',
+]);
 export class CodexDriver {
     bin;
+    liveness;
     id = 'codex';
     capabilities = { steer: true, interact: false, resume: true, tui: true, fork: true };
-    constructor(bin = 'codex') {
+    constructor(bin = 'codex', liveness = {}) {
         this.bin = bin;
+        this.liveness = liveness;
     }
     async run(input, ctx) {
         // BYOK provider routing arrives as `-c key=value` overrides; pass them through so the
@@ -261,6 +302,15 @@ export class CodexDriver {
         const deltaItems = new Set();
         let lastTextItemId = null;
         let steerRegistered = false;
+        // Liveness state (see the CODEX_STEER_STALL_MS block comment above).
+        const steerStallMs = this.liveness.steerStallMs ?? CODEX_STEER_STALL_MS;
+        const turnStallMs = this.liveness.turnStallMs ?? CODEX_TURN_STALL_MS;
+        let lastEventAt = Date.now();
+        let pendingSteer = null;
+        let pendingServerRequests = 0;
+        let healing = false;
+        let stalled = false;
+        let livenessTimer = null;
         if (!srv.start())
             return { ok: false, text: '', error: 'failed to start codex app-server', stopReason: 'error' };
         let settled = false;
@@ -320,23 +370,78 @@ export class CodexDriver {
                 state.sessionId = threadId;
                 ctx.emit({ type: 'session', sessionId: threadId });
             }
+            // Heal a wedged/lost steer in place: (optionally) interrupt the dead turn, then restart
+            // it with the same input. Runs under the SAME run()/turnDone, so upper layers just see
+            // the turn continue. `healing` suppresses the interrupt's own turn/completed echo.
+            const heal = async (opts) => {
+                if (settled || healing || !pendingSteer)
+                    return;
+                healing = true;
+                const replayInput = pendingSteer.input;
+                pendingSteer = null;
+                if (opts.interrupt && state.sessionId && state.turnId) {
+                    await srv.request('turn/interrupt', { threadId: state.sessionId, turnId: state.turnId }, 5_000);
+                }
+                if (settled) {
+                    healing = false;
+                    return;
+                } // raced with abort / process death
+                const resp = await srv.request('turn/start', {
+                    threadId: state.sessionId,
+                    input: replayInput,
+                    model: input.model || undefined,
+                    effort: input.effort || undefined,
+                });
+                if (settled) {
+                    healing = false;
+                    return;
+                }
+                if (resp.error) {
+                    state.status = 'error';
+                    state.error = `steer recovery failed: ${resp.error.message || 'turn/start failed'}`;
+                    healing = false;
+                    settle();
+                    return;
+                }
+                state.turnId = resp.result?.turn?.id ?? state.turnId;
+                lastEventAt = Date.now();
+                healing = false;
+            };
             // Codex emits no explicit compaction event, so track peak occupancy: a sharp
             // mid-turn drop is an auto-compaction, surfaced as a live `compaction` signal.
             let compactPeakTokens = 0;
             srv.onNotification((method, params) => {
                 if (params?.threadId && params.threadId !== state.sessionId && method !== 'turn/started')
                     return;
+                lastEventAt = Date.now();
+                if (pendingSteer && CODEX_PROGRESS_METHODS.has(method)) {
+                    const now = Date.now();
+                    if (now - pendingSteer.at >= CODEX_STEER_CONSUMED_MS)
+                        pendingSteer = null; // loop provably alive post-steer
+                    else
+                        pendingSteer.progressAt = now; // maybe pre-acceptance flush — keep watching
+                }
                 switch (method) {
                     case 'turn/started':
                         state.turnId = params?.turn?.id ?? null;
                         if (!steerRegistered && state.turnId) {
                             steerRegistered = true;
                             ctx.registerSteer(async (prompt, attachments = []) => {
-                                if (!state.sessionId || !state.turnId)
+                                if (settled || !state.sessionId || !state.turnId)
                                     return false;
-                                const r = await srv.request('turn/steer', { threadId: state.sessionId, expectedTurnId: state.turnId, input: buildTurnInput(prompt, attachments) }, 30_000);
-                                if (r.error)
+                                const steerInput = buildTurnInput(prompt, attachments);
+                                // Arm BEFORE sending — accepted, not yet consumed. Arming after the response
+                                // would race the response's own microtask against progress notifications the
+                                // server flushed in the same write, mis-arming against already-consumed steers.
+                                // Back-to-back steers accumulate so a heal replays everything swallowed.
+                                const armed = { input: [...(pendingSteer?.input ?? []), ...steerInput], at: Date.now(), progressAt: null };
+                                pendingSteer = armed;
+                                const r = await srv.request('turn/steer', { threadId: state.sessionId, expectedTurnId: state.turnId, input: steerInput }, 30_000);
+                                if (r.error) {
+                                    if (pendingSteer === armed)
+                                        pendingSteer = null; // rejected — nothing to watch
                                     return false;
+                                }
                                 state.turnId = r.result?.turnId ?? state.turnId;
                                 return true;
                             });
@@ -466,11 +571,21 @@ export class CodexDriver {
                     }
                     case 'turn/completed': {
                         const turn = params?.turn || {};
+                        applyCodexTokenUsage(state, params?.tokenUsage || turn.tokenUsage || turn.usage);
+                        ctx.emit({ type: 'usage', usage: codexUsageOf(state) });
+                        if (healing)
+                            break; // completion echo of the turn heal() just interrupted
+                        if (pendingSteer && !pendingSteer.progressAt && !ctx.signal.aborted && (turn.status ?? 'completed') === 'completed') {
+                            // The other face of the steer race: the turn finished without ever consuming
+                            // the injected input. Replay it as a fresh turn instead of settling — the
+                            // upper layers already dequeued the message on steer-ok, so settling here
+                            // would silently drop it.
+                            void heal({ interrupt: false });
+                            break;
+                        }
                         state.status = turn.status ?? 'completed';
                         if (turn.error)
                             state.error = turn.error.message || turn.error.code || 'turn error';
-                        applyCodexTokenUsage(state, params?.tokenUsage || turn.tokenUsage || turn.usage);
-                        ctx.emit({ type: 'usage', usage: codexUsageOf(state) });
                         settle();
                         break;
                     }
@@ -480,6 +595,7 @@ export class CodexDriver {
             // accept approvals by default (parity with the legacy codex driver). Never throw —
             // an unanswerable request degrades to an empty response, not a JSON-RPC error.
             srv.onRequest(async (method, params, id) => {
+                pendingServerRequests++; // a request awaiting a human legitimately silences the turn
                 try {
                     if (method === 'item/tool/requestUserInput') {
                         const interaction = codexUserInputToInteraction(params, `codex-input-${id}`);
@@ -497,6 +613,9 @@ export class CodexDriver {
                 catch {
                     return {};
                 }
+                finally {
+                    pendingServerRequests--;
+                }
             });
             const turnResp = await srv.request('turn/start', {
                 threadId: state.sessionId,
@@ -506,6 +625,35 @@ export class CodexDriver {
             });
             if (turnResp.error)
                 return { ok: false, text: state.text, error: turnResp.error.message || 'turn/start failed', stopReason: 'error', sessionId: state.sessionId };
+            // Liveness checker: heals a stalled steer, force-closes a silently dead turn. The
+            // silence clock only accumulates while nothing is visibly in flight — a running tool
+            // call or a server->client request parked on a human keeps the turn alive forever.
+            const checkEveryMs = Math.max(25, Math.min(5_000, Math.floor(Math.min(steerStallMs, turnStallMs) / 4)));
+            livenessTimer = setInterval(() => {
+                if (settled || healing)
+                    return;
+                const now = Date.now();
+                if (pendingSteer) {
+                    if (now - (pendingSteer.progressAt ?? pendingSteer.at) >= steerStallMs)
+                        void heal({ interrupt: true });
+                    return;
+                }
+                const busy = pendingServerRequests > 0 || [...toolCalls.values()].some(c => c.status === 'running');
+                if (busy) {
+                    lastEventAt = now;
+                    return;
+                }
+                if (now - lastEventAt < turnStallMs)
+                    return;
+                stalled = true;
+                state.error = state.error || `codex app-server went silent mid-turn (no events for ${Math.round(turnStallMs / 1000)}s); closing the turn`;
+                if (state.sessionId && state.turnId) {
+                    srv.request('turn/interrupt', { threadId: state.sessionId, turnId: state.turnId }, 5_000).finally(() => settle());
+                }
+                else
+                    settle();
+            }, checkEveryMs);
+            livenessTimer.unref?.();
             await turnDone;
             const usage = codexUsageOf(state);
             const ok2 = (state.status === 'completed' || state.status == null) && !state.error && !ctx.signal.aborted;
@@ -515,7 +663,7 @@ export class CodexDriver {
                 text: codexFinalText(state),
                 reasoning: finalReasoning || undefined,
                 error: state.error || (ctx.signal.aborted ? 'Interrupted by user.' : null),
-                stopReason: ctx.signal.aborted ? 'interrupted' : (state.status || 'end_turn'),
+                stopReason: ctx.signal.aborted ? 'interrupted' : stalled ? 'stalled' : (state.status || 'end_turn'),
                 sessionId: state.sessionId,
                 // Fork anchor: the turn id is the inclusive keep-boundary thread/fork's lastTurnId takes.
                 anchor: state.turnId,
@@ -523,6 +671,8 @@ export class CodexDriver {
             };
         }
         finally {
+            if (livenessTimer)
+                clearInterval(livenessTimer);
             srv.kill();
         }
     }

package/packages/kernel/dist/drivers/shared.d.ts

@@ -10,10 +10,7 @@ export declare function parseJsonLine(line: string): any | undefined;
 export declare function wireAbort(signal: AbortSignal, fn: () => void): () => void;
 /** SIGTERM a child, swallowing the already-dead race. */
 export declare function sigterm(proc: ChildProcess | null | undefined): void;
-/** Mime type when the file is an inlineable image, else null. */
-export declare function imageMimeForFile(filePath: string): string | null;
-/** The text note substituted for a non-image attachment. */
-export declare function attachedFileNote(filePath: string): string;
+export { imageMimeForFile, attachedFileNote } from '../attachments.js';
 /**
  * Context-window occupancy as a display percent (one decimal, capped at 99.9).
  * Pass `used` as null when the caller wants "no data" rather than 0%.

package/packages/kernel/dist/drivers/shared.js

@@ -1,4 +1,3 @@
-import { extname } from 'node:path';
 // Driver-internal helpers shared by the concrete drivers (claude/codex/gemini/acp).
 // NOT part of the public API — nothing here is re-exported by any barrel. Each helper
 // exists because the same code appeared verbatim in 3+ drivers.
@@ -43,20 +42,9 @@ export function sigterm(proc) {
     }
     catch { /* ignore */ }
 }
-// Attachment vocabulary: every driver inlines the same image formats (the Anthropic
-// vision set, which the others accept too) and notes non-image files the same way.
-const IMAGE_MIME_BY_EXT = {
-    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
-    '.gif': 'image/gif', '.webp': 'image/webp',
-};
-/** Mime type when the file is an inlineable image, else null. */
-export function imageMimeForFile(filePath) {
-    return IMAGE_MIME_BY_EXT[extname(filePath).toLowerCase()] ?? null;
-}
-/** The text note substituted for a non-image attachment. */
-export function attachedFileNote(filePath) {
-    return `[Attached file: ${filePath}]`;
-}
+// Attachment vocabulary lives in ../attachments.ts (the Hub also normalizes oversized
+// images there); re-exported so drivers keep one import site for driver-internal helpers.
+export { imageMimeForFile, attachedFileNote } from '../attachments.js';
 /**
  * Context-window occupancy as a display percent (one decimal, capped at 99.9).
  * Pass `used` as null when the caller wants "no data" rather than 0%.

package/packages/kernel/dist/index.d.ts

@@ -9,7 +9,7 @@ export type { SessionStore, CoreSessionRecord, ModelResolver, ModelInjection, To
 export type { LoomIO, PromptInput, Surface, SurfaceCapabilities, Plugin, SpawnContribution, } from './contracts/surface.js';
 export { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, AutoCancelInteractionHandler, DeferToTerminalInteractionHandler, NoopCatalog, defaultBaseDir, } from './ports/defaults.js';
 export { EchoDriver } from './drivers/echo.js';
-export { ClaudeDriver } from './drivers/claude.js';
+export { ClaudeDriver, type ClaudeDriverOptions } from './drivers/claude.js';
 export { CodexDriver } from './drivers/codex.js';
 export { GeminiDriver } from './drivers/gemini.js';
 export { AcpDriver, type AcpDriverConfig } from './drivers/acp.js';

package/packages/kernel/dist/protocol/index.js

@@ -16,7 +16,7 @@ export function emptySnapshot() {
     return { phase: 'idle', updatedAt: 0 };
 }
 const APPEND_FIELDS = ['text', 'reasoning'];
-const STRUCT_FIELDS = ['plan', 'toolCalls', 'subAgents', 'usage', 'artifacts', 'interactions', 'queued'];
+const STRUCT_FIELDS = ['plan', 'toolCalls', 'subAgents', 'usage', 'artifacts', 'interactions', 'queued', 'compaction'];
 const SCALAR_FIELDS = ['phase', 'taskId', 'sessionId', 'agent', 'model', 'effort', 'prompt', 'activity', 'error', 'incomplete', 'startedAt', 'updatedAt', 'anchor'];
 export function diffSnapshot(prev, next) {
     const patch = {};

package/packages/kernel/dist/runtime/hub.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { diffSnapshot, emptySnapshot, makeSessionKey, splitSessionKey, } from '../protocol/index.js';
 import { SessionRunner } from './session-runner.js';
 import { buildForkSeed } from './fork.js';
+import { normalizeImageAttachments } from '../attachments.js';
 export class Hub {
     deps;
     sessions = new Map();
@@ -262,7 +263,9 @@ export class Hub {
         }
         const turnInput = {
             prompt: driverPrompt,
-            attachments: input.attachments,
+            // Oversized images are downscaled here and in steer() — the two dispatch chokepoints —
+            // so every driver (built-in or host-plugged) sends model-safe attachments.
+            attachments: await normalizeImageAttachments(input.attachments, this.deps.log),
             sessionId: driverSessionId,
             fork: driverFork,
             rewind: driverRewind,
@@ -467,7 +470,7 @@ export class Hub {
     }
     async steer(taskId, prompt, attachments) {
         const r = this.runnersByTask.get(taskId);
-        return r ? r.steer(prompt, attachments) : false;
+        return r ? r.steer(prompt, await normalizeImageAttachments(attachments, this.deps.log)) : false;
     }
     interact(promptId, action, value) {
         for (const r of this.runnersByTask.values()) {