@co0ontty/wand 4.56.0 → 4.56.1

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "commit": "a71d7db07de28e316d86d8a42c23c7a59a8dbace",
-  "builtAt": "2026-09-10T01:20:45.427Z",
-  "version": "4.56.0",
+  "commit": "477c21d747e18e9f4df6942ab0f47bd817f66ff0",
+  "builtAt": "2026-09-10T03:53:28.222Z",
+  "version": "4.56.1",
   "channel": "stable"
 }

package/dist/cli.js

@@ -93,6 +93,8 @@ async function main() {
             break;
         }
         case "terminald": {
+            const { ensureNodePtyHelperExecutable } = await import("./ensure-node-pty-helper.js");
+            ensureNodePtyHelperExecutable();
             const { runTerminalDaemon } = await import("./terminal-daemon-server.js");
             await runTerminalDaemon(configPath);
             break;

package/dist/ensure-node-pty-helper.d.ts

@@ -1 +1,10 @@
+export interface SpawnHelperRepair {
+    vendorPath: string;
+    helperPath: string;
+    copied: boolean;
+}
+/** Repair one spawn-helper file. Exported for tests. */
+export declare function repairSpawnHelperFile(vendorPath: string): SpawnHelperRepair;
 export declare function ensureNodePtyHelperExecutable(): void;
+export declare function resetNodePtyHelperStateForTests(): void;
+export declare function describePtySpawnFailure(error: unknown): string;

package/dist/ensure-node-pty-helper.js

@@ -5,64 +5,151 @@
 //
 // Locates node-pty wherever it actually lives (dev repo, hoisted global,
 // pnpm store …) via require.resolve, finds the per-arch prebuilds dir the
-// loaded binary is in, and ensures the helper next to it is +x. Idempotent
-// and best-effort: silent on the happy path, warns on failure but never
-// blocks startup.
+// loaded binary is in, and ensures the helper is actually executable.
 //
-// Called both once at server startup AND right before every PTY spawn. The
-// per-spawn call is what makes this self-heal: a self-update (`npm install
+// Two repair paths:
+//   1. chmod +x the vendor helper (works when we own the file).
+//   2. If chmod is denied (root-owned global install), copy the helper to a
+//      user-writable cache and rewrite node-pty's native `fork` helperPath.
+//      In-place chmod cannot fix a root-owned 644 file, and the native addon
+//      receives the helper path as an argument, so a writable copy is enough.
+//
+// Called both once at server/daemon startup AND right before every PTY spawn.
+// The per-spawn call is what makes this self-heal: a self-update (`npm install
 // -g`) reinstalls node-pty and re-drops the bit, and that extraction can
-// land *after* the relaunched server already ran its startup chmod — so a
-// startup-only fix leaves every subsequent PTY launch broken until the next
-// restart. Re-checking before each spawn closes that race (the resolve is
-// cached, the happy path is a single stat + early return).
-import { chmodSync, existsSync, statSync } from "node:fs";
+// land *after* the relaunched server already ran its startup chmod.
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, } from "node:fs";
+import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { getErrorMessage } from "./error-utils.js";
 const requireFromHere = createRequire(import.meta.url);
-// Cache the resolved helper path: `null` = not yet resolved, `""` = resolved
-// to "no helper on this platform/install" (don't retry).
-let cachedHelperPath = null;
-function resolveHelperPath() {
-    if (cachedHelperPath !== null)
-        return cachedHelperPath;
+// Cache the resolved vendor helper path: `null` = not yet resolved, `""` =
+// resolved to "no helper on this platform/install" (don't retry).
+let cachedVendorHelperPath = null;
+let nativeForkPatched = false;
+let patchedVendorHelperPath = null;
+let patchedExecutableHelperPath = null;
+function resolveVendorHelperPath() {
+    if (cachedVendorHelperPath !== null)
+        return cachedVendorHelperPath;
     // spawn-helper is only used on Unix-likes. Windows uses winpty / conpty.
     if (process.platform === "win32")
-        return (cachedHelperPath = "");
+        return (cachedVendorHelperPath = "");
     let nodePtyEntry;
     try {
         nodePtyEntry = requireFromHere.resolve("node-pty");
     }
     catch {
-        return (cachedHelperPath = "");
+        return (cachedVendorHelperPath = "");
     }
     // node-pty's lib/index.js sits at <pkg>/lib/index.js; helper lives at
     // <pkg>/prebuilds/<platform>-<arch>/spawn-helper.
     const pkgRoot = path.resolve(path.dirname(nodePtyEntry), "..");
     const arch = `${process.platform}-${process.arch}`;
-    return (cachedHelperPath = path.join(pkgRoot, "prebuilds", arch, "spawn-helper"));
+    return (cachedVendorHelperPath = path.join(pkgRoot, "prebuilds", arch, "spawn-helper"));
 }
-export function ensureNodePtyHelperExecutable() {
-    const helper = resolveHelperPath();
-    if (!helper || !existsSync(helper))
-        return;
-    let mode;
+function isExecutable(filePath) {
     try {
-        mode = statSync(helper).mode & 0o777;
+        return (statSync(filePath).mode & 0o111) === 0o111;
     }
     catch {
-        return;
+        return false;
+    }
+}
+function helperCacheDir() {
+    return path.join(os.tmpdir(), "wand-pty-helpers");
+}
+function copyHelperToWritableCache(source) {
+    const digest = createHash("sha256").update(readFileSync(source)).digest("hex").slice(0, 16);
+    const dir = helperCacheDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dest = path.join(dir, `${digest}-spawn-helper`);
+    if (!existsSync(dest)) {
+        copyFileSync(source, dest);
+    }
+    if (!isExecutable(dest)) {
+        chmodSync(dest, 0o755);
     }
-    if ((mode & 0o111) === 0o111)
+    return dest;
+}
+function installNativeHelperPathPatch(vendorPath, executablePath) {
+    patchedVendorHelperPath = vendorPath;
+    patchedExecutableHelperPath = executablePath;
+    if (nativeForkPatched || process.platform === "win32" || vendorPath === executablePath)
         return;
+    const utils = requireFromHere("node-pty/lib/utils.js");
+    const native = utils.loadNativeModule("pty");
+    const originalFork = native.module.fork.bind(native.module);
+    native.module.fork = (...args) => {
+        if (typeof args[9] === "string" && patchedVendorHelperPath && patchedExecutableHelperPath) {
+            const requested = args[9];
+            const resolvedRequested = path.resolve(requested);
+            if (requested === patchedVendorHelperPath
+                || resolvedRequested === patchedVendorHelperPath
+                || resolvedRequested === path.resolve(patchedVendorHelperPath)) {
+                args[9] = patchedExecutableHelperPath;
+            }
+        }
+        return originalFork(...args);
+    };
+    nativeForkPatched = true;
+    process.stderr.write(`[wand] Using writable node-pty spawn-helper copy at ${executablePath}\n`);
+}
+/** Repair one spawn-helper file. Exported for tests. */
+export function repairSpawnHelperFile(vendorPath) {
+    if (!vendorPath || !existsSync(vendorPath)) {
+        return { vendorPath, helperPath: vendorPath, copied: false };
+    }
+    if (isExecutable(vendorPath)) {
+        return { vendorPath, helperPath: vendorPath, copied: false };
+    }
     try {
-        chmodSync(helper, mode | 0o755);
-        process.stderr.write(`[wand] Restored +x on ${helper} (npm dropped the bit on install)\n`);
+        const mode = statSync(vendorPath).mode & 0o777;
+        chmodSync(vendorPath, mode | 0o755);
+        process.stderr.write(`[wand] Restored +x on ${vendorPath} (npm dropped the bit on install)\n`);
+        return { vendorPath, helperPath: vendorPath, copied: false };
     }
     catch (err) {
-        process.stderr.write(`[wand] Warning: could not chmod +x ${helper}: ${getErrorMessage(err)}\n`
-            + `[wand] PTY sessions may fail to start. Run: chmod +x ${JSON.stringify(helper)}\n`);
+        try {
+            const copiedPath = copyHelperToWritableCache(vendorPath);
+            process.stderr.write(`[wand] Warning: could not chmod +x ${vendorPath}: ${getErrorMessage(err)}\n`
+                + `[wand] Copied spawn-helper to ${copiedPath}\n`);
+            return { vendorPath, helperPath: copiedPath, copied: true };
+        }
+        catch (copyErr) {
+            process.stderr.write(`[wand] Warning: could not chmod +x ${vendorPath}: ${getErrorMessage(err)}\n`
+                + `[wand] Also failed to copy spawn-helper: ${getErrorMessage(copyErr)}\n`
+                + `[wand] PTY sessions may fail to start. Run: chmod +x ${JSON.stringify(vendorPath)}\n`);
+            return { vendorPath, helperPath: vendorPath, copied: false };
+        }
+    }
+}
+export function ensureNodePtyHelperExecutable() {
+    const vendorPath = resolveVendorHelperPath();
+    if (!vendorPath)
+        return;
+    const repaired = repairSpawnHelperFile(vendorPath);
+    if (repaired.copied) {
+        try {
+            installNativeHelperPathPatch(repaired.vendorPath, repaired.helperPath);
+        }
+        catch (err) {
+            process.stderr.write(`[wand] Warning: could not redirect node-pty spawn-helper: ${getErrorMessage(err)}\n`);
+        }
+    }
+}
+export function resetNodePtyHelperStateForTests() {
+    cachedVendorHelperPath = null;
+    patchedVendorHelperPath = null;
+    patchedExecutableHelperPath = null;
+}
+export function describePtySpawnFailure(error) {
+    const message = getErrorMessage(error, "无法启动终端。");
+    if (/posix_spawnp failed/i.test(message)) {
+        return "无法启动终端：node-pty 的 spawn-helper 不可执行。请重新安装 Wand，或对该文件执行 chmod +x。";
     }
+    return message;
 }

package/dist/process-manager.js

@@ -16,6 +16,7 @@ import { getProviderCommandSessionId, getProviderResumeCommandSessionId } from "
 import { normalizeThinkingEffort, thinkingEffortToClaudeCliEffort, thinkingEffortToClaudeSlashEffort, thinkingEffortToCodexReasoningEffort, thinkingEffortToOpenCodeVariant, thinkingEffortToPiLevel } from "./structured-provider-common.js";
 import { consumePtyInputForTopic, createPtyTopicLineBuffer, provisionalSessionTopic, SessionTopicCoordinator, sessionTopicBlocklistForSnapshot, shouldAcceptGeneratedSessionTitle, } from "./session-topic.js";
 import { getErrorMessage } from "./error-utils.js";
+import { describePtySpawnFailure } from "./ensure-node-pty-helper.js";
 import { resolveSystemAiContext } from "./session-ai-context.js";
 import { resolveSessionCwd } from "./session-cwd.js";
 import { PtyTerminalState } from "./pty-terminal-state.js";
@@ -1144,12 +1145,20 @@ export class ProcessManager extends EventEmitter {
         }
         catch (err) {
             console.error("[ProcessManager] terminal spawn failed", { sessionId: id, error: String(err) });
-            record.status = "failed";
-            record.exitCode = -1;
-            record.endedAt = new Date().toISOString();
-            record.ptyProcess = null;
-            this.persist(record, { forceFullSave: true, metadataDirty: true });
-            return this.snapshot(record);
+            this.cleanupRecord(record, false);
+            this.sessions.delete(id);
+            this.lastPersistedMessageState.delete(id);
+            this.dirtySessions.delete(id);
+            this.terminalHost.forget(id);
+            try {
+                this.storage.deleteSession(id);
+            }
+            catch { /* best-effort spawn-failure cleanup */ }
+            try {
+                this.logger.deleteSession(id);
+            }
+            catch { /* best-effort spawn-failure cleanup */ }
+            throw new Error(describePtySpawnFailure(err));
         }
         record.processId = child.pid;
         record.ptyProcess = child;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@co0ontty/wand",
-  "version": "4.56.0",
+  "version": "4.56.1",
   "description": "A web console for Claude Code, Codex, OpenCode, and other local CLI tools.",
   "type": "module",
   "bin": {