@co0ontty/wand 4.36.0 → 4.37.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "commit": "dfc9840aeb82784c80bb15e43c8d880dce64437f",
-  "builtAt": "2026-08-07T05:32:46.753Z",
-  "version": "4.36.0",
+  "commit": "d3936dc2066c7077fe5dca5947e4773f6672b5dc",
+  "builtAt": "2026-08-08T00:17:10.949Z",
+  "version": "4.37.0",
   "channel": "stable"
 }

package/dist/npm-update-utils.js

@@ -271,7 +271,7 @@ const REQUIRED_RUNTIME_FILES = [
     path.join("dist", "web-ui", "styles.js"),
     path.join("dist", "web-ui", "content", "scripts.js"),
     path.join("dist", "web-ui", "content", "styles.css"),
-    path.join("dist", "web-ui", "content", "vendor", "wterm", "wterm.bundle.js"),
+    path.join("dist", "web-ui", "content", "vendor", "xterm", "xterm.bundle.js"),
     path.join("dist", "web-ui", "content", "vendor", "qrcode", "qrcode.bundle.js"),
 ];
 function getGlobalPackageDir() {

package/dist/process-manager.d.ts

@@ -2,6 +2,7 @@ import { EventEmitter } from "node:events";
 import { WandStorage } from "./storage.js";
 import { ExecutionMode, ProcessEventHandler, SessionProvider, SessionSnapshot, SessionSource, WandConfig } from "./types.js";
 import { type PermissionResolution } from "./claude-pty-bridge.js";
+import { type PtyTerminalSnapshot } from "./pty-terminal-state.js";
 import { type ClaudeHistorySession, type CodexHistorySession, type OpenCodeHistorySession, type QoderHistorySession } from "./provider-history-scanner.js";
 export type { ClaudeHistorySession, CodexHistorySession, OpenCodeHistorySession, QoderHistorySession, } from "./provider-history-scanner.js";
 /** Exported for focused policy tests. */
@@ -95,8 +96,16 @@ export declare class ProcessManager extends EventEmitter {
      * Mirrors setSessionModel/setSessionThinkingEffort.
      */
     setSessionMode(id: string, mode: ExecutionMode): SessionSnapshot;
-    sendInput(id: string, input: string, view?: "chat" | "terminal", shortcutKey?: string): SessionSnapshot;
+    sendInput(id: string, input: string, view?: "chat" | "terminal", shortcutKey?: string, trackUserInput?: boolean): SessionSnapshot;
     resize(id: string, cols: number, rows: number): SessionSnapshot;
+    getTerminalState(id: string): PtyTerminalSnapshot | null;
+    pauseOutput(id: string): void;
+    resumeOutput(id: string): void;
+    /**
+     * Finalize provider-only state while leaving the owning PTY shell alive. The
+     * session itself remains running so terminal input can continue normally.
+     */
+    private finishProviderCli;
     stop(id: string): SessionSnapshot;
     private cleanupRecord;
     delete(id: string): void;
@@ -160,7 +169,6 @@ export declare class ProcessManager extends EventEmitter {
         sessionSource?: SessionSource;
         automationId?: string;
     }): SessionSnapshot;
-    private buildShellArgs;
     private shouldAutoApprovePermissions;
     private processCommandForMode;
 }

package/dist/process-manager.js

@@ -20,6 +20,8 @@ import { SessionTopicCoordinator } from "./session-topic.js";
 import { getErrorMessage } from "./error-utils.js";
 import { resolveSystemAiContext } from "./session-ai-context.js";
 import { resolveSessionCwd } from "./session-cwd.js";
+import { PtyTerminalState } from "./pty-terminal-state.js";
+import { buildPtyShellLaunchPlan } from "./pty-shell-launch.js";
 import { ProviderHistoryScanner, } from "./provider-history-scanner.js";
 function resolveProviderFromCommand(command) {
     if (/^(?:claude|npx\s+claude|[^\s]+\/claude)(?:\s|$)/.test(command.trim()))
@@ -600,6 +602,10 @@ export class ProcessManager extends EventEmitter {
                     provider,
                     processId: null,
                     ptyProcess: null,
+                    terminalState: null,
+                    providerShellMarker: null,
+                    providerCliActive: false,
+                    providerCliExitCode: snapshot.providerCliExitCode ?? null,
                     stopRequested: false,
                     confirmWindow: "",
                     ptyPermissionBlocked: false,
@@ -648,6 +654,10 @@ export class ProcessManager extends EventEmitter {
                     provider,
                     processId: null,
                     ptyProcess: null,
+                    terminalState: null,
+                    providerShellMarker: null,
+                    providerCliActive: false,
+                    providerCliExitCode: snapshot.providerCliExitCode ?? null,
                     stopRequested: false,
                     confirmWindow: "",
                     ptyPermissionBlocked: false,
@@ -853,6 +863,12 @@ export class ProcessManager extends EventEmitter {
             : null;
         const initialClaudeSessionId = existingProviderSessionId ?? assignedProviderSessionId;
         const startedAt = new Date().toISOString();
+        const launchPlan = buildPtyShellLaunchPlan({
+            shell: this.config.shell,
+            command: processedCommand,
+            bareShell: opts?.interactiveShell === true,
+            providerCommand: provider !== undefined,
+        });
         const record = {
             id,
             sessionSource: opts?.sessionSource ?? inheritedSessionSource ?? "interactive",
@@ -879,6 +895,10 @@ export class ProcessManager extends EventEmitter {
             claudeSessionId: initialClaudeSessionId,
             processId: null,
             ptyProcess: null,
+            terminalState: new PtyTerminalState(opts?.cols !== undefined ? clampDimension(opts.cols, 20, 1000) : 120, opts?.rows !== undefined ? clampDimension(opts.rows, 5, 500) : 36),
+            providerShellMarker: launchPlan.cliExitMarker,
+            providerCliActive: provider !== undefined,
+            providerCliExitCode: null,
             stopRequested: false,
             confirmWindow: "",
             ptyPermissionBlocked: false,
@@ -902,11 +922,8 @@ export class ProcessManager extends EventEmitter {
             approvalStats: { tool: 0, command: 0, file: 0, total: 0 },
             selectedModel: selectedModel ?? null,
             thinkingEffort: initialThinkingEffort,
-            // cols 上限 256：与 @wterm/dom WASM grid 的 maxCols 硬编码一致，
-            // 防止服务端按 >256 cols 让 Claude 用 CSI 绝对列定位写到 wterm 实际
-            // 渲染不到的列上（表现为"内容神奇复制下行"）。
-            ptyCols: opts?.cols !== undefined ? clampDimension(opts.cols, 20, 256) : 120,
-            ptyRows: opts?.rows !== undefined ? clampDimension(opts.rows, 10, 160) : 36,
+            ptyCols: opts?.cols !== undefined ? clampDimension(opts.cols, 20, 1000) : 120,
+            ptyRows: opts?.rows !== undefined ? clampDimension(opts.rows, 5, 500) : 36,
         };
         if (isClaudeProvider) {
             record.ptyBridge = new ClaudePtyBridge({
@@ -927,21 +944,20 @@ export class ProcessManager extends EventEmitter {
             this.providerHistory.invalidate(provider);
         }
         this.cleanupOldSessions();
-        const shellArgs = this.buildShellArgs(processedCommand, opts?.interactiveShell === true);
         // Self-heal node-pty's spawn-helper +x bit before every spawn: a self-update
         // can re-drop it after this server already ran its startup chmod, which would
         // otherwise make every PTY launch throw "posix_spawnp failed." until restart.
         ensureNodePtyHelperExecutable();
         let child;
         try {
-            child = pty.spawn(this.config.shell, shellArgs, {
+            child = pty.spawn(this.config.shell, launchPlan.shellArgs, {
                 cwd: resolvedCwd,
                 env: buildChildEnv(this.config.inheritEnv !== false, {
                     WAND_MODE: effectiveMode,
                     WAND_AUTO_CONFIRM: record.autoApprovePermissions ? "1" : "0",
                     WAND_AUTO_EDIT: effectiveMode === "auto-edit" ? "1" : "0"
                 }),
-                name: "xterm-color",
+                name: "xterm-256color",
                 // 使用 record 上由前端协商好的真实尺寸，避免"先 120 列、几百毫秒后再 resize"
                 // 期间 provider TUI 用错列宽渲染出 \x1b[120G 这类绝对列定位序列。
                 cols: record.ptyCols,
@@ -987,6 +1003,11 @@ export class ProcessManager extends EventEmitter {
                 current.ptyBridge.onExit(exitCode);
                 current.ptyBridge.removeAllListeners();
             }
+            current.providerShellMarker = null;
+            if (current.providerCliActive) {
+                current.providerCliActive = false;
+                current.providerCliExitCode = exitCode;
+            }
             current.pendingEscalation = null;
             current.ptyPermissionBlocked = false;
             this.captureClaudeSessionId(current, { allowTimeWindowFallback: true });
@@ -1026,22 +1047,27 @@ export class ProcessManager extends EventEmitter {
             child.write(initialInput);
             child.write("\r");
         };
-        child.onData((chunk) => {
+        child.onData((rawChunk) => {
             const rec = this.sessions.get(id);
             // PTYs may still drain data after kill(). A replacement session can use
             // the same id, so both record identity and the concrete PTY handle must
             // match before accepting the chunk.
             if (rec !== record || rec.ptyProcess !== child)
                 return;
-            if (rec.ptyBridge) {
+            const boundary = rec.providerShellMarker?.consume(rawChunk) ?? { data: rawChunk, exitCode: null };
+            const chunk = boundary.data;
+            if (chunk)
+                rec.terminalState?.write(chunk);
+            if (chunk && rec.ptyBridge) {
                 rec.ptyBridge.processChunk(chunk);
                 rec.output = rec.ptyBridge.getRawOutput();
             }
-            else {
+            else if (chunk) {
                 rec.output = appendWindow(rec.output, chunk, PTY_OUTPUT_MAX_SIZE);
             }
-            this.logger.appendPtyOutput(id, chunk);
-            if (!rec.ptyBridge) {
+            if (chunk)
+                this.logger.appendPtyOutput(id, chunk);
+            if (chunk && !rec.ptyBridge) {
                 this.emitEvent({
                     type: "output",
                     sessionId: id,
@@ -1059,7 +1085,7 @@ export class ProcessManager extends EventEmitter {
                 this.providerHistory.invalidate("claude");
                 process.stderr.write(`[wand] Captured Claude session ID: ${bridgeSessionId}\n`);
             }
-            if (!rec.claudeSessionId && rec.knownClaudeTaskIds) {
+            if (rec.providerCliActive && boundary.exitCode === null && !rec.claudeSessionId && rec.knownClaudeTaskIds) {
                 rec.messages = snapshotMessages(rec);
                 const discoveredTaskId = getLatestClaudeProjectSessionId({
                     cwd: rec.cwd,
@@ -1074,14 +1100,21 @@ export class ProcessManager extends EventEmitter {
                     process.stderr.write(`[wand] Captured Claude project session ID: ${discoveredTaskId}\n`);
                 }
             }
-            if (rec.autoApprovePermissions && !rec.ptyBridge && rec.provider === "claude") {
+            if (chunk && rec.providerCliActive && rec.autoApprovePermissions && !rec.ptyBridge && rec.provider === "claude") {
                 this.autoConfirmWithRecord(rec, chunk, child);
             }
-            if (initialInput && !initialInputSent && (chunk.includes("❯") || chunk.includes("›"))) {
+            if (chunk && boundary.exitCode === null && initialInput && !initialInputSent && (chunk.includes("❯") || chunk.includes("›"))) {
                 sendInitialInput();
             }
+            if (boundary.exitCode !== null) {
+                this.finishProviderCli(record, boundary.exitCode);
+            }
             this.schedulePersist(rec);
         });
+        if (launchPlan.commandToWrite) {
+            child.write(launchPlan.commandToWrite);
+            child.write("\r");
+        }
         if (initialInput) {
             record.initialInputTimer = setTimeout(() => {
                 record.initialInputTimer = null;
@@ -1339,7 +1372,7 @@ export class ProcessManager extends EventEmitter {
         const record = this.mustGet(id);
         const normalized = model?.trim() || null;
         record.selectedModel = normalized;
-        if (record.provider === "claude" && record.status === "running" && record.ptyProcess) {
+        if (record.providerCliActive && record.provider === "claude" && record.status === "running" && record.ptyProcess) {
             const value = normalized && normalized !== "default" ? normalized : "default";
             record.ptyProcess.write(`/model ${value}\r`);
         }
@@ -1355,7 +1388,7 @@ export class ProcessManager extends EventEmitter {
         const record = this.mustGet(id);
         const normalized = normalizeThinkingEffort(effort);
         record.thinkingEffort = normalized;
-        if (record.provider === "claude" && record.status === "running" && record.ptyProcess) {
+        if (record.providerCliActive && record.provider === "claude" && record.status === "running" && record.ptyProcess) {
             record.ptyProcess.write(`/effort ${thinkingEffortToClaudeSlashEffort(normalized)}\r`);
         }
         this.persist(record);
@@ -1384,7 +1417,7 @@ export class ProcessManager extends EventEmitter {
         });
         return this.snapshot(record);
     }
-    sendInput(id, input, view, shortcutKey) {
+    sendInput(id, input, view, shortcutKey, trackUserInput = true) {
         if (this.disposed)
             throw new Error("ProcessManager has been disposed.");
         const record = this.mustGet(id);
@@ -1412,7 +1445,7 @@ export class ProcessManager extends EventEmitter {
             this.logger.appendShortcutLog(id, shortcutKey, tailLines, ctx);
         }
         // Track user input via bridge for Chat mode
-        if (record.ptyBridge) {
+        if (record.ptyBridge && trackUserInput) {
             record.ptyBridge.onUserInput(input);
         }
         record.ptyProcess.write(input);
@@ -1424,24 +1457,95 @@ export class ProcessManager extends EventEmitter {
         if (!record.ptyProcess || record.status !== "running") {
             return this.snapshot(record);
         }
-        const safeCols = clampDimension(cols, 20, 256);
-        const safeRows = clampDimension(rows, 10, 160);
+        const safeCols = clampDimension(cols, 20, 1000);
+        const safeRows = clampDimension(rows, 5, 500);
         const changed = safeCols !== record.ptyCols || safeRows !== record.ptyRows;
+        if (!changed)
+            return this.snapshot(record);
         record.ptyProcess.resize(safeCols, safeRows);
+        record.terminalState?.resize(safeCols, safeRows);
         record.ptyCols = safeCols;
         record.ptyRows = safeRows;
-        if (changed) {
-            // Notify every subscribed client of the new authoritative dimensions so
-            // any other tab/device can re-fit its terminal instead of rendering
-            // wrap-broken output sized for someone else's viewport.
-            this.emitEvent({
-                type: "status",
-                sessionId: id,
-                data: { ptyCols: safeCols, ptyRows: safeRows },
-            });
-        }
+        // Notify every subscribed client of the new authoritative dimensions so
+        // any other tab/device can re-fit its terminal instead of rendering
+        // wrap-broken output sized for someone else's viewport.
+        this.emitEvent({
+            type: "status",
+            sessionId: id,
+            data: { ptyCols: safeCols, ptyRows: safeRows },
+        });
         return this.snapshot(record);
     }
+    getTerminalState(id) {
+        const record = this.sessions.get(id);
+        if (!record)
+            return null;
+        if (!record.terminalState) {
+            record.terminalState = new PtyTerminalState(record.ptyCols, record.ptyRows, record.output || record.storedOutput);
+        }
+        return record.terminalState.snapshot();
+    }
+    pauseOutput(id) {
+        const record = this.sessions.get(id);
+        if (record?.ptyProcess && record.status === "running")
+            record.ptyProcess.pause();
+    }
+    resumeOutput(id) {
+        const record = this.sessions.get(id);
+        if (record?.ptyProcess && record.status === "running")
+            record.ptyProcess.resume();
+    }
+    /**
+     * Finalize provider-only state while leaving the owning PTY shell alive. The
+     * session itself remains running so terminal input can continue normally.
+     */
+    finishProviderCli(record, exitCode) {
+        if (!record.providerCliActive)
+            return;
+        record.providerCliActive = false;
+        record.providerCliExitCode = exitCode;
+        record.providerShellMarker = null;
+        if (record.claudeTaskDiscoveryTimer) {
+            clearTimeout(record.claudeTaskDiscoveryTimer);
+            record.claudeTaskDiscoveryTimer = null;
+        }
+        if (record.codexSessionDiscoveryTimer) {
+            clearTimeout(record.codexSessionDiscoveryTimer);
+            record.codexSessionDiscoveryTimer = null;
+        }
+        if (record.openCodeSessionDiscoveryTimer) {
+            clearTimeout(record.openCodeSessionDiscoveryTimer);
+            record.openCodeSessionDiscoveryTimer = null;
+        }
+        if (record.initialInputTimer) {
+            clearTimeout(record.initialInputTimer);
+            record.initialInputTimer = null;
+        }
+        if (record.ptyBridge) {
+            record.ptyBridge.onExit(exitCode);
+            record.messages = record.ptyBridge.getMessages();
+        }
+        record.pendingEscalation = null;
+        record.ptyPermissionBlocked = false;
+        this.captureClaudeSessionId(record, { allowTimeWindowFallback: true });
+        this.captureCodexSessionId(record, { allowTimeWindowFallback: true });
+        this.captureOpenCodeSessionId(record, { allowTimeWindowFallback: true });
+        if (record.ptyBridge) {
+            record.output = record.ptyBridge.getRawOutput();
+            record.ptyBridge.removeAllListeners();
+            record.ptyBridge = null;
+        }
+        this.flushPersist(record);
+        this.emitEvent({
+            type: "status",
+            sessionId: record.id,
+            data: {
+                providerCliActive: false,
+                providerCliExitCode: exitCode,
+                permissionBlocked: false,
+            },
+        });
+    }
     stop(id) {
         const record = this.mustGet(id);
         if (record.status !== "running") {
@@ -1464,6 +1568,8 @@ export class ProcessManager extends EventEmitter {
             record.initialInputTimer = null;
         }
         record.stopRequested = true;
+        record.providerCliActive = false;
+        record.providerShellMarker = null;
         // Kill any running child process (from JSON chat turns)
         if (record.childProcess) {
             record.childProcess.kill();
@@ -1533,6 +1639,8 @@ export class ProcessManager extends EventEmitter {
             record.ptyBridge.removeAllListeners();
             record.ptyBridge = null;
         }
+        record.terminalState?.dispose();
+        record.terminalState = null;
     }
     delete(id) {
         const record = this.mustGet(id);
@@ -1582,6 +1690,8 @@ export class ProcessManager extends EventEmitter {
             record.ptyBridge.removeAllListeners();
             record.ptyBridge = null;
         }
+        record.terminalState?.dispose();
+        record.terminalState = null;
         // Delete from persistent storage BEFORE removing from in-memory map,
         // so a storage failure doesn't leave orphan records in the database.
         this.storage.deleteSession(id);
@@ -1639,6 +1749,8 @@ export class ProcessManager extends EventEmitter {
             sessionSource: record.sessionSource ?? "interactive",
             automationId: record.automationId,
             provider: record.provider,
+            providerCliActive: record.providerCliActive,
+            providerCliExitCode: record.providerCliExitCode,
             runner: "pty",
             command: record.command,
             cwd: record.cwd,
@@ -2134,21 +2246,6 @@ export class ProcessManager extends EventEmitter {
             interactiveShell: true,
         });
     }
-    buildShellArgs(command, interactiveShell = false) {
-        if (interactiveShell) {
-            return os.platform() === "win32" ? [] : ["-l"];
-        }
-        if (os.platform() === "win32") {
-            return ["/d", "/s", "/c", command];
-        }
-        // -l: login shell — sources ~/.bash_profile, ~/.profile, etc., ensuring PATH
-        //      and other env vars set by profile files are available.
-        // -c: run the following command.
-        // Using -ic (interactive + command) skips login-shell initialization on many
-        // platforms, which causes commands that depend on profile-set env vars to fail
-        // immediately with "command not found" — a silent exit before onExit is ready.
-        return ["-lc", command];
-    }
     shouldAutoApprovePermissions(command, mode, provider) {
         if (provider !== "claude") {
             return false;

package/dist/pty-shell-launch.d.ts

@@ -0,0 +1,36 @@
+export interface PtyShellLaunchPlan {
+    shellArgs: string[];
+    /** Fallback for shells whose command language Wand cannot safely wrap. */
+    commandToWrite?: string;
+    cliExitMarker: PtyCliExitMarker | null;
+}
+export interface PtyCliExitChunk {
+    data: string;
+    exitCode: number | null;
+}
+/**
+ * Removes Wand's private CLI/shell boundary marker even when a PTY splits it
+ * across chunks. The marker never reaches terminal rendering, transcripts, or
+ * Claude's PTY parser.
+ */
+export declare class PtyCliExitMarker {
+    readonly token: string;
+    private readonly prefix;
+    private pending;
+    private completed;
+    constructor(token?: string);
+    consume(chunk: string): PtyCliExitChunk;
+}
+/**
+ * Build the PTY process shape without conflating three different lifecycles:
+ * a bare interactive shell, a provider CLI that falls back to a shell, and a
+ * one-shot non-provider command.
+ */
+export declare function buildPtyShellLaunchPlan(options: {
+    shell: string;
+    command: string;
+    bareShell: boolean;
+    providerCommand: boolean;
+    platform?: NodeJS.Platform;
+    markerToken?: string;
+}): PtyShellLaunchPlan;

package/dist/pty-shell-launch.js

@@ -0,0 +1,116 @@
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+const CLI_EXIT_MARKER_START = "\x1eWAND_CLI_EXIT:";
+const CLI_EXIT_MARKER_END = "\x1f";
+const POSIX_SHELLS = new Set(["ash", "bash", "dash", "ksh", "ksh93", "mksh", "sh", "zsh"]);
+function quotePosixShell(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function isKnownPosixShell(shell) {
+    return POSIX_SHELLS.has(path.basename(shell).toLowerCase());
+}
+function longestMarkerPrefixSuffix(value, markerPrefix) {
+    const maxLength = Math.min(value.length, markerPrefix.length - 1);
+    for (let length = maxLength; length > 0; length -= 1) {
+        if (value.endsWith(markerPrefix.slice(0, length)))
+            return length;
+    }
+    return 0;
+}
+/**
+ * Removes Wand's private CLI/shell boundary marker even when a PTY splits it
+ * across chunks. The marker never reaches terminal rendering, transcripts, or
+ * Claude's PTY parser.
+ */
+export class PtyCliExitMarker {
+    token;
+    prefix;
+    pending = "";
+    completed = false;
+    constructor(token = randomUUID()) {
+        this.token = token;
+        this.prefix = `${CLI_EXIT_MARKER_START}${token}:`;
+    }
+    consume(chunk) {
+        if (this.completed)
+            return { data: chunk, exitCode: null };
+        const combined = this.pending + chunk;
+        this.pending = "";
+        const markerStart = combined.indexOf(this.prefix);
+        if (markerStart >= 0) {
+            const markerEnd = combined.indexOf(CLI_EXIT_MARKER_END, markerStart + this.prefix.length);
+            if (markerEnd < 0) {
+                this.pending = combined.slice(markerStart);
+                return { data: combined.slice(0, markerStart), exitCode: null };
+            }
+            const statusText = combined.slice(markerStart + this.prefix.length, markerEnd);
+            if (/^\d{1,3}$/.test(statusText)) {
+                this.completed = true;
+                return {
+                    data: combined.slice(0, markerStart) + combined.slice(markerEnd + CLI_EXIT_MARKER_END.length),
+                    exitCode: Number(statusText),
+                };
+            }
+        }
+        const partialLength = longestMarkerPrefixSuffix(combined, this.prefix);
+        if (partialLength > 0) {
+            this.pending = combined.slice(-partialLength);
+            return { data: combined.slice(0, -partialLength), exitCode: null };
+        }
+        return { data: combined, exitCode: null };
+    }
+}
+function buildPosixProviderShellCommand(command, shell, marker) {
+    // The non-default SIGINT trap keeps the launcher shell alive when Ctrl+C
+    // terminates its foreground CLI. External commands reset caught traps to the
+    // default disposition, so the provider still receives SIGINT normally.
+    // Running the CLI as an `if` condition also prevents a user-set `errexit`
+    // option from skipping the marker and fallback shell after a non-zero exit.
+    return [
+        "trap ':' INT",
+        `if ${command}; then __wand_cli_status=0; else __wand_cli_status=$?; fi`,
+        `printf '\\036WAND_CLI_EXIT:${marker.token}:%s\\037' "$__wand_cli_status"`,
+        `exec ${quotePosixShell(shell)} -l`,
+    ].join("; ");
+}
+/**
+ * Build the PTY process shape without conflating three different lifecycles:
+ * a bare interactive shell, a provider CLI that falls back to a shell, and a
+ * one-shot non-provider command.
+ */
+export function buildPtyShellLaunchPlan(options) {
+    const platform = options.platform ?? os.platform();
+    if (options.bareShell) {
+        return {
+            shellArgs: platform === "win32" ? [] : ["-l"],
+            cliExitMarker: null,
+        };
+    }
+    if (!options.providerCommand) {
+        return {
+            shellArgs: platform === "win32"
+                ? ["/d", "/s", "/c", options.command]
+                : ["-lc", options.command],
+            cliExitMarker: null,
+        };
+    }
+    if (platform !== "win32" && isKnownPosixShell(options.shell)) {
+        const marker = new PtyCliExitMarker(options.markerToken);
+        return {
+            // Interactive + login initialization matches a real terminal before the
+            // provider starts; `exec <shell> -l` becomes the persistent prompt after it exits.
+            shellArgs: ["-lic", buildPosixProviderShellCommand(options.command, options.shell, marker)],
+            cliExitMarker: marker,
+        };
+    }
+    // cmd.exe/PowerShell and uncommon Unix shells have incompatible scripting
+    // syntaxes. Starting them interactively and typing the command still provides
+    // the requested Ctrl+C-to-shell behavior; only the precise CLI-exit marker is
+    // unavailable on this compatibility path.
+    return {
+        shellArgs: platform === "win32" ? [] : ["-l"],
+        commandToWrite: options.command,
+        cliExitMarker: null,
+    };
+}

package/dist/pty-terminal-state.d.ts

@@ -0,0 +1,39 @@
+export type PtyTerminalOperation = {
+    type: "data";
+    data: string;
+} | {
+    type: "resize";
+    cols: number;
+    rows: number;
+};
+export interface PtyTerminalSnapshot {
+    version: 1;
+    data: string;
+    cols: number;
+    rows: number;
+    pending: PtyTerminalOperation[];
+}
+/**
+ * Server-side xterm screen model used only for reconnect snapshots. Live PTY
+ * bytes still travel unchanged from node-pty to the browser terminal.
+ */
+export declare class PtyTerminalState {
+    private readonly terminal;
+    private readonly serializer;
+    private readonly unicode;
+    private pending;
+    private tail;
+    private checkpointTimer?;
+    private nextId;
+    private committedData;
+    private committedCols;
+    private committedRows;
+    private disposed;
+    constructor(cols: number, rows: number, initialData?: string);
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    snapshot(): PtyTerminalSnapshot;
+    dispose(): void;
+    private addPending;
+    private scheduleCheckpoint;
+}