@co0ontty/wand 1.20.4 → 1.21.5

package/dist/pty-text-utils.js

@@ -1,6 +1,12 @@
 /**
  * Shared PTY text processing utilities for consistent ANSI stripping and noise filtering.
  */
+/**
+ * Hard cap on the in-memory PTY replay buffer. Shared between ProcessManager
+ * and ClaudePtyBridge so a session keeps the same amount of history regardless
+ * of which capture path is active.
+ */
+export const PTY_OUTPUT_MAX_SIZE = 200_000;
 /** Strip ANSI escape sequences and control characters from raw PTY output. */
 export function stripAnsi(text) {
     return text
@@ -115,10 +121,166 @@ export function isNoiseLine(line) {
         return true;
     return false;
 }
-/** Append text to a windowed buffer, trimming from start if over max size. */
+/**
+ * Append text to a windowed buffer, trimming from start if over max size.
+ *
+ * The cut point is chosen so it never lands inside:
+ * - a UTF-16 surrogate pair (would corrupt the leading codepoint)
+ * - an unterminated ANSI escape sequence (would feed orphan "[31m..."
+ *   text to a downstream terminal renderer)
+ *
+ * The returned buffer may be slightly shorter than maxSize.
+ */
 export function appendWindow(buffer, chunk, maxSize) {
     const next = buffer + chunk;
-    return next.length > maxSize ? next.slice(-maxSize) : next;
+    if (next.length <= maxSize)
+        return next;
+    return safeSliceTail(next, maxSize);
+}
+/** Slice keeping the last ~maxSize chars on a safe boundary. Exported for tests. */
+export function safeSliceTail(text, maxSize) {
+    if (text.length <= maxSize)
+        return text;
+    let start = text.length - maxSize;
+    // 1. Skip UTF-16 low surrogate half so we don't strand a high surrogate.
+    if (start > 0 && start < text.length) {
+        const code = text.charCodeAt(start);
+        if (code >= 0xdc00 && code <= 0xdfff)
+            start++;
+    }
+    // 2. Prefer cutting at the next newline within a small lookahead window.
+    //    Newlines are always safe boundaries (no ANSI sequence spans a newline
+    //    in well-formed terminal output) and keep lines aligned for replay.
+    const LOOKAHEAD = 4096;
+    const upper = Math.min(start + LOOKAHEAD, text.length);
+    for (let i = start; i < upper; i++) {
+        if (text.charCodeAt(i) === 0x0a)
+            return text.slice(i + 1);
+    }
+    // 3. No nearby newline. Detect whether `start` lands inside an open ANSI
+    //    escape sequence by scanning backward for an ESC (0x1b). If we find one
+    //    that is not yet terminated, advance past the sequence's final byte.
+    const lookback = Math.max(0, start - 256);
+    let escAt = -1;
+    for (let i = start - 1; i >= lookback; i--) {
+        const code = text.charCodeAt(i);
+        if (code === 0x1b) {
+            escAt = i;
+            break;
+        }
+        // If we hit a terminator before an ESC, the previous sequence is closed.
+        if (code === 0x07)
+            break;
+        if (code >= 0x40 && code <= 0x7e && i > 0 && isLikelyAnsiBody(text, i - 1))
+            break;
+    }
+    if (escAt !== -1) {
+        // OSC 序列以 `ESC ]` (0x1b 0x5d) 开头，必须用 BEL (0x07) 或
+        // ST (`ESC \\` = 0x1b 0x5c) 终止。其它范围内字节（包括裸 `\`）
+        // 都属于 payload，不能当终止符。CSI 等序列才用 0x40-0x7e final byte。
+        const isOsc = escAt + 1 < text.length && text.charCodeAt(escAt + 1) === 0x5d;
+        let terminated = false;
+        for (let i = escAt + 1; i < start; i++) {
+            const code = text.charCodeAt(i);
+            if (code === 0x07) {
+                terminated = true;
+                break;
+            }
+            if (isOsc) {
+                if (code === 0x1b && i + 1 < start && text.charCodeAt(i + 1) === 0x5c) {
+                    terminated = true;
+                    break;
+                }
+                continue;
+            }
+            if (code >= 0x40 && code <= 0x7e) {
+                terminated = true;
+                break;
+            }
+        }
+        if (!terminated) {
+            const ansiUpper = Math.min(start + 256, text.length);
+            for (let i = start; i < ansiUpper; i++) {
+                const code = text.charCodeAt(i);
+                if (code === 0x07)
+                    return text.slice(i + 1);
+                if (isOsc) {
+                    if (code === 0x1b && i + 1 < ansiUpper && text.charCodeAt(i + 1) === 0x5c) {
+                        return text.slice(i + 2);
+                    }
+                    continue;
+                }
+                if (code >= 0x40 && code <= 0x7e)
+                    return text.slice(i + 1);
+            }
+        }
+    }
+    return text.slice(start);
+}
+function isLikelyAnsiBody(text, idx) {
+    // CSI parameter/intermediate range covers most common ANSI bodies.
+    const code = text.charCodeAt(idx);
+    return code === 0x5b /* [ */ || code === 0x3f /* ? */ || (code >= 0x30 && code <= 0x3f);
+}
+/**
+ * Strip a string down to the printable codepoints used for echo matching.
+ * Removes control characters, whitespace and ANSI escapes; keeps all other
+ * visible characters (including `/`, `()`, `:`, CJK, emoji, etc.) so that
+ * echo alignment works for any user input.
+ */
+export function stripForEchoMatch(input) {
+    let out = "";
+    for (let i = 0; i < input.length; i++) {
+        const code = input.charCodeAt(i);
+        if (code === 0x1b) {
+            i = skipAnsiSequence(input, i) - 1;
+            continue;
+        }
+        if (code < 0x20 || code === 0x7f)
+            continue;
+        if (code === 0x20)
+            continue;
+        out += input[i];
+    }
+    return out;
+}
+/**
+ * Given an index pointing at ESC (0x1b), return the index of the first
+ * character AFTER the escape sequence. Handles CSI, OSC and simple ESC-
+ * letter forms. Returns idx+1 if nothing matches (best-effort skip).
+ */
+export function skipAnsiSequence(text, idx) {
+    if (text.charCodeAt(idx) !== 0x1b)
+        return idx;
+    const next = text.charCodeAt(idx + 1);
+    if (Number.isNaN(next))
+        return idx + 1;
+    // CSI: ESC [ ... final-byte (0x40-0x7E)
+    if (next === 0x5b /* [ */) {
+        let i = idx + 2;
+        while (i < text.length) {
+            const code = text.charCodeAt(i);
+            if (code >= 0x40 && code <= 0x7e)
+                return i + 1;
+            i++;
+        }
+        return text.length;
+    }
+    // OSC: ESC ] ... terminator (BEL or ESC \)
+    if (next === 0x5d /* ] */) {
+        let i = idx + 2;
+        while (i < text.length) {
+            const code = text.charCodeAt(i);
+            if (code === 0x07)
+                return i + 1;
+            if (code === 0x1b && text.charCodeAt(i + 1) === 0x5c)
+                return i + 2;
+            i++;
+        }
+        return text.length;
+    }
+    // Two-character ESC sequences (ESC = / ESC > / ESC M / etc.)
+    return idx + 2;
 }
 const EXPLICIT_CONFIRM_PATTERNS = [
     /(?:^|\b)(?:press\s+)?(?:y|yes)\s*(?:\/|\bor\b)\s*(?:n|no)(?:\b|$)/i,

package/dist/server-session-routes.d.ts

@@ -4,5 +4,5 @@ import { StructuredSessionManager } from "./structured-session-manager.js";
 import { WandStorage } from "./storage.js";
 import { ExecutionMode, WandConfig } from "./types.js";
 export declare function getErrorMessage(error: unknown, fallback: string): string;
-export declare function registerSessionRoutes(app: Express, processes: ProcessManager, structured: StructuredSessionManager, storage: WandStorage, defaultMode: ExecutionMode, config: WandConfig): void;
+export declare function registerSessionRoutes(app: Express, processes: ProcessManager, structured: StructuredSessionManager, storage: WandStorage, defaultMode: ExecutionMode, config: WandConfig, onSessionCreated?: (cwd: string | undefined | null) => void): void;
 export declare function registerClaudeHistoryRoutes(app: Express, processes: ProcessManager, storage: WandStorage): void;

package/dist/server-session-routes.js

@@ -136,7 +136,7 @@ function canMergeSession(snapshot) {
 function isMergeActionAllowed(snapshot) {
     return snapshot.status !== "running";
 }
-export function registerSessionRoutes(app, processes, structured, storage, defaultMode, config) {
+export function registerSessionRoutes(app, processes, structured, storage, defaultMode, config, onSessionCreated) {
     app.get("/api/sessions", (_req, res) => {
         const all = listAllSessionsSlim(processes, structured);
         console.log("[WAND] GET /api/sessions count:", all.length, "sessions:", all.map(s => ({ id: s.id.substring(0, 8), kind: s.sessionKind, runner: s.runner, status: s.status })));
@@ -146,19 +146,27 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
         const body = req.body;
         console.log("[WAND] POST /api/structured-sessions body:", JSON.stringify({ cwd: body.cwd, mode: body.mode, runner: body.runner, provider: body.provider, worktreeEnabled: body.worktreeEnabled === true, hasPrompt: !!body.prompt, model: body.model }));
         try {
-            if (body.provider && body.provider !== "claude") {
-                res.status(400).json({ error: "结构化会话当前仅支持 Claude provider。" });
+            if (body.provider && body.provider !== "claude" && body.provider !== "codex") {
+                res.status(400).json({ error: "结构化会话当前仅支持 Claude 或 Codex provider。" });
                 return;
             }
+            const provider = body.provider === "codex" ? "codex" : "claude";
             const snapshot = structured.createSession({
                 cwd: body.cwd?.trim() || process.cwd(),
                 mode: normalizeMode(body.mode, defaultMode),
-                prompt: body.prompt,
-                runner: body.runner ?? "claude-cli-print",
+                provider,
+                runner: body.runner ?? (provider === "codex" ? "codex-cli-exec" : "claude-cli-print"),
                 worktreeEnabled: body.worktreeEnabled === true,
                 model: typeof body.model === "string" ? body.model.trim() : undefined,
             });
             console.log("[WAND] structured session created:", JSON.stringify({ id: snapshot.id, sessionKind: snapshot.sessionKind, runner: snapshot.runner, status: snapshot.status }));
+            onSessionCreated?.(body.cwd ?? snapshot.cwd);
+            const prompt = body.prompt?.trim();
+            if (prompt) {
+                const finished = await structured.sendMessage(snapshot.id, prompt);
+                res.status(201).json(finished);
+                return;
+            }
             res.status(201).json(snapshot);
         }
         catch (error) {
@@ -199,13 +207,19 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
     app.post("/api/structured-sessions/:id/messages", express.json(), async (req, res) => {
         const input = String(req.body?.input ?? "");
         const interrupt = !!req.body?.interrupt;
-        console.log("[WAND] POST /api/structured-sessions/:id/messages id:", req.params.id, "input:", input.substring(0, 50), "interrupt:", interrupt);
+        const idempotencyKey = typeof req.body?.idempotencyKey === "string" ? req.body.idempotencyKey : undefined;
+        console.log("[WAND] POST /api/structured-sessions/:id/messages id:", req.params.id, "input:", input.substring(0, 50), "interrupt:", interrupt, "idempotencyKey:", idempotencyKey);
         try {
-            const snapshot = await structured.sendMessage(req.params.id, input, { interrupt });
+            const snapshot = await structured.sendMessage(req.params.id, input, { interrupt, idempotencyKey });
             res.json(snapshot);
         }
         catch (error) {
-            res.status(400).json({ error: getErrorMessage(error, "无法发送结构化消息。") });
+            const errorCode = error?.code;
+            const status = errorCode === "duplicate_idempotency_key" ? 409 : 400;
+            res.status(status).json({
+                error: getErrorMessage(error, "无法发送结构化消息。"),
+                errorCode,
+            });
         }
     });
     // ── Tool content lazy-load endpoint ──
@@ -472,7 +486,9 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
             }
             const newMode = body.mode ? normalizeMode(body.mode, defaultMode) : normalizeMode(existingSession.mode, defaultMode);
             const resumeCommand = `${command} --resume ${claudeSessionId}`;
-            const newSnapshot = processes.start(resumeCommand, existingSession.cwd, newMode, undefined, { reuseId: sessionId });
+            const reqCols = typeof body.cols === "number" && Number.isFinite(body.cols) ? body.cols : undefined;
+            const reqRows = typeof body.rows === "number" && Number.isFinite(body.rows) ? body.rows : undefined;
+            const newSnapshot = processes.start(resumeCommand, existingSession.cwd, newMode, undefined, { reuseId: sessionId, cols: reqCols, rows: reqRows });
             res.status(201).json(newSnapshot);
         }
         catch (error) {
@@ -509,7 +525,9 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
                 }
                 const newMode = body.mode ? normalizeMode(body.mode, defaultMode) : normalizeMode(existingSession.mode, defaultMode);
                 const resumeCommand = `${command} --resume ${claudeSessionId}`;
-                const newSnapshot = processes.start(resumeCommand, existingSession.cwd, newMode, undefined, { reuseId: existingSession.id });
+                const reqCols = typeof body.cols === "number" && Number.isFinite(body.cols) ? body.cols : undefined;
+                const reqRows = typeof body.rows === "number" && Number.isFinite(body.rows) ? body.rows : undefined;
+                const newSnapshot = processes.start(resumeCommand, existingSession.cwd, newMode, undefined, { reuseId: existingSession.id, cols: reqCols, rows: reqRows });
                 res.status(201).json({ resumedClaudeSessionId: claudeSessionId, ...newSnapshot });
             }
             else {
@@ -520,7 +538,9 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
                 }
                 const newMode = normalizeMode(body.mode, defaultMode);
                 const resumeCommand = `claude --resume ${claudeSessionId}`;
-                const newSnapshot = processes.start(resumeCommand, cwd, newMode);
+                const reqCols = typeof body.cols === "number" && Number.isFinite(body.cols) ? body.cols : undefined;
+                const reqRows = typeof body.rows === "number" && Number.isFinite(body.rows) ? body.rows : undefined;
+                const newSnapshot = processes.start(resumeCommand, cwd, newMode, undefined, { cols: reqCols, rows: reqRows });
                 res.status(201).json({ resumedClaudeSessionId: claudeSessionId, ...newSnapshot });
             }
         }

package/dist/server.d.ts

@@ -1,6 +1,9 @@
 import { ProcessManager } from "./process-manager.js";
 import { StructuredSessionManager } from "./structured-session-manager.js";
+import { WandStorage } from "./storage.js";
 import { WandConfig } from "./types.js";
+/** Persist a cwd to recent paths. Used by both REST and session creation hooks. */
+export declare function recordRecentPath(storage: WandStorage, cwd: string | undefined | null): void;
 export interface ServerUrl {
     url: string;
     scheme: "HTTP" | "HTTPS";

package/dist/server.js

@@ -16,6 +16,7 @@ import { ensureCertificates } from "./cert.js";
 import { isExecutionMode, normalizeCardDefaults, resolveConfigDir, saveConfig } from "./config.js";
 import { getCachedModels, refreshModels } from "./models.js";
 import { ProcessManager } from "./process-manager.js";
+import { SessionLogger } from "./session-logger.js";
 import { StructuredSessionManager } from "./structured-session-manager.js";
 import { generatePwaManifest, generateServiceWorker } from "./pwa.js";
 import { getErrorMessage, registerClaudeHistoryRoutes, registerSessionRoutes } from "./server-session-routes.js";
@@ -481,6 +482,33 @@ function parseStoredPathList(raw) {
     }
 }
 const MAX_RECENT_PATHS = 10;
+/** Persist a cwd to recent paths. Used by both REST and session creation hooks. */
+export function recordRecentPath(storage, cwd) {
+    if (!cwd)
+        return;
+    const trimmed = cwd.trim();
+    if (!trimmed)
+        return;
+    let resolved;
+    try {
+        resolved = normalizeFolderPath(trimmed);
+    }
+    catch {
+        return;
+    }
+    if (isBlockedFolderPath(resolved))
+        return;
+    const stored = storage.getConfigValue("recent_paths");
+    let recent = parseStoredPathList(stored);
+    recent = recent.filter((r) => normalizeFolderPath(r.path) !== resolved);
+    recent.unshift({
+        path: resolved,
+        name: path.basename(resolved),
+        lastUsedAt: new Date().toISOString(),
+    });
+    recent = recent.slice(0, MAX_RECENT_PATHS);
+    storage.setConfigValue("recent_paths", JSON.stringify(recent));
+}
 // ── File language detection ──
 function getLanguageFromExt(ext, filePath) {
     const map = {
@@ -514,7 +542,8 @@ export async function startServer(config, configPath) {
     const configDir = resolveConfigDir(configPath);
     const avatarSeed = await ensureAvatarSeed(configDir);
     const processes = new ProcessManager(config, storage, configDir);
-    const structuredSessions = new StructuredSessionManager(storage, config);
+    const structuredLogger = new SessionLogger(configDir, config.shortcutLogMaxBytes);
+    const structuredSessions = new StructuredSessionManager(storage, config, structuredLogger);
     const useHttps = config.https === true;
     const protocol = useHttps ? "https" : "http";
     const nodeModulesDir = path.join(RUNTIME_ROOT_DIR, "node_modules");
@@ -695,7 +724,11 @@ export async function startServer(config, configPath) {
             defaultMode: config.defaultMode,
             defaultCwd: config.defaultCwd,
             commandPresets: config.commandPresets,
-            structuredRunners: [{ label: "Claude Structured", runner: "claude-cli-print" }],
+            structuredRunner: config.structuredRunner ?? "cli",
+            structuredRunners: [
+                { label: "Claude Structured", runner: "claude-cli-print" },
+                { label: "Codex Structured", runner: "codex-cli-exec" },
+            ],
             structuredChatPersona,
             cardDefaults: config.cardDefaults,
             updateAvailable: cachedUpdateInfo?.updateAvailable ?? false,
@@ -783,7 +816,7 @@ export async function startServer(config, configPath) {
     });
     app.post("/api/settings/config", async (req, res) => {
         const body = req.body;
-        const allowedFields = ["host", "port", "https", "defaultMode", "defaultCwd", "shell", "language", "defaultModel"];
+        const allowedFields = ["host", "port", "https", "defaultMode", "defaultCwd", "shell", "language", "defaultModel", "structuredRunner"];
         let changed = false;
         for (const field of allowedFields) {
             if (field in body && body[field] !== undefined) {
@@ -820,6 +853,9 @@ export async function startServer(config, configPath) {
                 else if (field === "defaultModel") {
                     config.defaultModel = typeof body.defaultModel === "string" ? body.defaultModel.trim() : "";
                 }
+                else if (field === "structuredRunner") {
+                    config.structuredRunner = body.structuredRunner === "sdk" ? "sdk" : "cli";
+                }
                 changed = true;
             }
         }
@@ -847,6 +883,7 @@ export async function startServer(config, configPath) {
         const cached = getCachedModels();
         res.json({
             models: cached.models,
+            codexModels: cached.codexModels,
             claudeVersion: cached.claudeVersion,
             refreshedAt: cached.refreshedAt,
             defaultModel: config.defaultModel ?? "",
@@ -857,6 +894,7 @@ export async function startServer(config, configPath) {
             const refreshed = await refreshModels();
             res.json({
                 models: refreshed.models,
+                codexModels: refreshed.codexModels,
                 claudeVersion: refreshed.claudeVersion,
                 refreshedAt: refreshed.refreshedAt,
                 defaultModel: config.defaultModel ?? "",
@@ -919,7 +957,9 @@ export async function startServer(config, configPath) {
             updateInFlight = false;
         }
     });
-    registerSessionRoutes(app, processes, structuredSessions, storage, config.defaultMode, config);
+    registerSessionRoutes(app, processes, structuredSessions, storage, config.defaultMode, config, (cwd) => {
+        recordRecentPath(storage, cwd);
+    });
     registerClaudeHistoryRoutes(app, processes, storage);
     registerUploadRoutes(app, processes);
     app.post("/api/optimize-prompt", express.json({ limit: "256kb" }), async (req, res) => {
@@ -1098,18 +1138,12 @@ export async function startServer(config, configPath) {
             res.status(403).json({ error: "访问被拒绝：无法保存系统敏感目录。" });
             return;
         }
-        const stored = storage.getConfigValue("recent_paths");
-        let recent = parseStoredPathList(stored);
-        recent = recent.filter((r) => normalizeFolderPath(r.path) !== resolvedRecentPath);
-        const newRecent = {
+        recordRecentPath(storage, resolvedRecentPath);
+        res.json({
             path: resolvedRecentPath,
             name: path.basename(resolvedRecentPath),
             lastUsedAt: new Date().toISOString(),
-        };
-        recent.unshift(newRecent);
-        recent = recent.slice(0, MAX_RECENT_PATHS);
-        storage.setConfigValue("recent_paths", JSON.stringify(recent));
-        res.json(newRecent);
+        });
     });
     app.get("/api/validate-path", async (req, res) => {
         const inputPath = typeof req.query.path === "string" ? req.query.path : "";
@@ -1215,11 +1249,16 @@ export async function startServer(config, configPath) {
         try {
             const rawModel = typeof body.model === "string" ? body.model.trim() : "";
             const effectiveModel = rawModel || (config.defaultModel ?? "").trim() || undefined;
+            const reqCols = typeof body.cols === "number" && Number.isFinite(body.cols) ? body.cols : undefined;
+            const reqRows = typeof body.rows === "number" && Number.isFinite(body.rows) ? body.rows : undefined;
             const snapshot = processes.start(body.command, body.cwd, normalizeMode(body.mode, config.defaultMode), initialInput || undefined, {
                 worktreeEnabled: body.worktreeEnabled === true,
                 provider: body.provider,
                 model: effectiveModel,
+                cols: reqCols,
+                rows: reqRows,
             });
+            recordRecentPath(storage, body.cwd ?? snapshot.cwd);
             res.status(201).json(snapshot);
         }
         catch (error) {
@@ -1304,6 +1343,8 @@ export async function startServer(config, configPath) {
     }
     // Start configured background sessions after the server is already reachable.
     processes.runStartupCommands();
+    // Pre-warm model cache (probes claude --version + codex debug models).
+    refreshModels().catch(() => { });
     // ── Auto-update endpoints ──
     app.get("/api/auto-update", (_req, res) => {
         const web = storage.getConfigValue("autoUpdateWeb") === "true";

package/dist/session-logger.d.ts

@@ -24,14 +24,19 @@ export interface ShortcutLogContext {
  * SessionLogger saves raw session content to local files for debugging and analysis.
  *
  * Directory structure: .wand/sessions/{sessionId}/
- *   - pty-output.log       Raw PTY output (current, rotated when > 50 MB)
- *   - pty-output.log.1..3  Rotated PTY output backups
- *   - stream-events.jsonl  NDJSON events from native mode (append-only)
- *   - messages.json        Final structured messages (overwritten on each update)
+ *   - pty-output.log              Raw PTY output (current, rotated when > 50 MB)
+ *   - pty-output.log.1..3         Rotated PTY output backups
+ *   - stream-events.jsonl         NDJSON events from native mode (append-only)
+ *   - messages.json               Final structured messages (overwritten on each update)
+ *   - structured-stdout.log       Raw stdout from `codex exec` / `claude -p` child (append-only)
+ *   - structured-stderr.log       Raw stderr from the same child (append-only)
+ *   - structured-spawns.jsonl     One line per spawn: args/pid/cwd/exit/error metadata
  */
 export declare class SessionLogger {
     private readonly baseDir;
     private readonly dirs;
+    /** Cached on-disk size of hot-path log files so we can rotate without stat'ing on every chunk. */
+    private readonly logSizes;
     private readonly shortcutLogMaxBytes;
     constructor(configDir: string, shortcutLogMaxBytes?: number);
     private ensureDir;
@@ -48,6 +53,14 @@ export declare class SessionLogger {
     readPtyOutput(sessionId: string): string | null;
     /** Append a native mode NDJSON event */
     appendStreamEvent(sessionId: string, event: unknown): void;
+    /** Append raw stdout chunk from a structured-mode child process. */
+    appendStructuredStdout(sessionId: string, chunk: string): void;
+    /** Append raw stderr chunk from a structured-mode child process. */
+    appendStructuredStderr(sessionId: string, chunk: string): void;
+    /** Append a spawn metadata record (args, pid, cwd, exit, errors, …) for a structured run. */
+    appendStructuredSpawn(sessionId: string, meta: Record<string, unknown>): void;
+    /** Read recent stderr tail (for surfacing in failure messages). */
+    readStructuredStderrTail(sessionId: string, maxBytes?: number): string;
     /** Save the current structured messages snapshot */
     saveMessages(sessionId: string, messages: ConversationTurn[]): void;
     /** Save session metadata */
@@ -56,6 +69,6 @@ export declare class SessionLogger {
     deleteSession(sessionId: string): void;
     /** Append a shortcut key interaction log entry (for analyzing auto-confirm gaps) */
     appendShortcutLog(sessionId: string, shortcutKey: string, tailLines: string, ctx?: ShortcutLogContext): void;
-    /** Truncate shortcut log by keeping only the most recent half of entries */
+    /** Truncate shortcut log by keeping only the most recent half of entries. Returns the new on-disk size. */
     private truncateShortcutLog;
 }