leduo-patrol 2.0.1 → 2.2.1

package/README.md

@@ -83,7 +83,7 @@
 - **目录浏览**：创建会话时可在允许根目录范围内浏览子目录，安全限制越权访问
 
 ### 工具与集成
-- **内置终端**：下方可展开终端抽屉，通过 xterm.js 提供完整 PTY 终端体验（需服务端开启 `LEDUO_ENABLE_SHELL=true`）
+- **内置终端**：下方可展开终端抽屉，通过 xterm.js 提供完整 PTY 终端体验；服务端默认开启，可通过 `LEDUO_ENABLE_SHELL=false` 显式关闭
 
 ### 界面与可访问性
 - **访问 Key 认证**：所有请求（HTTP / WebSocket）均需携带 key；浏览器检测到无效 key 时展示输入页
@@ -117,6 +117,7 @@ npm run dev:local
   - `local`：监听 `127.0.0.1`，仅本机可访问
 - 可通过命令行参数 `--mode=local|server` 或环境变量 `LEDUO_PATROL_BIND_MODE` 指定，命令行参数优先级更高
 - 若未显式指定，启动时会在终端提示选择模式；并可选择记住到 `~/.leduo-patrol/launch-preferences.json`，后续自动复用
+- 若未设置 `LEDUO_PATROL_ACCESS_KEY`，启动时会提示选择“手动输入自定义 key”或“随机生成 key”，并可选择是否记住到 `~/.leduo-patrol/launch-preferences.json`
 
 - 前端开发服务运行在自动探测到的可访问内网 IP（优先 `bond* / eth* / ens* / enp*` 网卡）上
 - 后端服务运行在 `PORT`（默认 `3001`，端口冲突时会自动递增寻找可用端口）
@@ -153,7 +154,7 @@ LEDUO_PATROL_CLAUDE_BIN=/absolute/path/to/claude
 LEDUO_PATROL_SHELL=/absolute/path/to/zsh
 ANTHROPIC_API_KEY=sk-...
 LEDUO_PATROL_ACCESS_KEY=your-fixed-key
-LEDUO_ENABLE_SHELL=true
+LEDUO_ENABLE_SHELL=false
 ```
 
 如果设置了 `LEDUO_PATROL_ALLOWED_ROOTS`，网页中只能连接这些根目录之下的路径；未设置时默认只允许启动命令所在目录。
@@ -177,7 +178,12 @@ LEDUO_ENABLE_SHELL=true
 
 ## 访问校验 Key
 
-服务启动时会自动生成一次性访问 key，并在控制台打印可直接打开的地址。
+服务启动时会优先按以下顺序确定访问 key，并在控制台打印可直接打开的地址：
+
+- `--access-key your-key`
+- `LEDUO_PATROL_ACCESS_KEY`
+- 已记住在 `~/.leduo-patrol/launch-preferences.json` 的 key
+- 若以上都没有：启动时交互选择“手动输入”或“随机生成”
 
 - 开发模式（`npm run dev`）下，`Access URL` 默认指向 Web 端口（默认 `5173`）。
 - 生产模式（`npm start`）下，Web 由同一个 Express 服务静态托管，因此不会出现独立的 Web 监听端口；`Access URL` 会指向 server 端口。若未找到打包后的 `dist/web` 资源，服务会给出错误提示页与启动日志提示。
@@ -193,6 +199,14 @@ LEDUO_PATROL_ACCESS_KEY=your-fixed-key
 LEDUO_PATROL_CLAUDE_BIN=/absolute/path/to/claude
 ```
 
+也可以直接通过命令行传入：
+
+```bash
+npm run dev:server -- --access-key your-fixed-key
+# 或生产模式
+npm start -- --access-key your-fixed-key
+```
+
 ## 已知限制
 
 - 当前只实现了 Claude Code

package/dist/server/__tests__/access-key-prompt.test.js

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { resolveAccessKey, accessKeyPromptTestables } from "../access-key-prompt.js";
+const NON_TTY_STREAM = {
+    isTTY: false,
+};
+const SILENT_STDOUT = {
+    isTTY: true,
+    write: () => true,
+};
+test("access key prompt normalizes values", () => {
+    assert.equal(accessKeyPromptTestables.normalizeAccessKey("  abc  "), "abc");
+    assert.equal(accessKeyPromptTestables.normalizeAccessKey(""), "");
+    assert.equal(accessKeyPromptTestables.normalizeAccessKey(undefined), "");
+});
+test("resolveAccessKey prefers argv over env and remembered key", async () => {
+    const result = await resolveAccessKey({
+        argv: ["--access-key", "cli-key"],
+        envKey: "env-key",
+        stdin: NON_TTY_STREAM,
+        stdout: SILENT_STDOUT,
+        loadRememberedKey: async () => "remembered-key",
+        createRandomKey: () => "random-key",
+    });
+    assert.equal(result, "cli-key");
+});
+test("resolveAccessKey falls back to env key", async () => {
+    const result = await resolveAccessKey({
+        argv: [],
+        envKey: "env-key",
+        stdin: NON_TTY_STREAM,
+        stdout: SILENT_STDOUT,
+        loadRememberedKey: async () => "remembered-key",
+        createRandomKey: () => "random-key",
+    });
+    assert.equal(result, "env-key");
+});
+test("resolveAccessKey falls back to remembered key", async () => {
+    const result = await resolveAccessKey({
+        argv: [],
+        envKey: "",
+        stdin: NON_TTY_STREAM,
+        stdout: SILENT_STDOUT,
+        loadRememberedKey: async () => "remembered-key",
+        createRandomKey: () => "random-key",
+    });
+    assert.equal(result, "remembered-key");
+});
+test("resolveAccessKey generates a random key when no tty prompt is available", async () => {
+    const result = await resolveAccessKey({
+        argv: [],
+        envKey: "",
+        stdin: NON_TTY_STREAM,
+        stdout: SILENT_STDOUT,
+        loadRememberedKey: async () => "",
+        createRandomKey: () => "random-key",
+    });
+    assert.equal(result, "random-key");
+});
+test("resolveAccessKey can save an interactively chosen key", async () => {
+    let savedKey = "";
+    const ttyStream = {
+        isTTY: true,
+    };
+    const result = await resolveAccessKey({
+        argv: [],
+        envKey: "",
+        stdin: ttyStream,
+        stdout: SILENT_STDOUT,
+        loadRememberedKey: async () => "",
+        saveRememberedKey: async (key) => {
+            savedKey = key;
+        },
+        createRandomKey: () => "random-key",
+        promptForAccessKey: async () => "custom-key",
+        promptShouldRememberKey: async () => true,
+    });
+    assert.equal(result, "custom-key");
+    assert.equal(savedKey, "custom-key");
+});

package/dist/server/__tests__/claude-cli-session.test.js

@@ -22,3 +22,20 @@ test("claudeCliSessionTestables.resolveClaudeBin accepts explicit executable pat
 test("claudeCliSessionTestables.resolveClaudeBin throws actionable error when claude is missing", () => {
     assert.throws(() => claudeCliSessionTestables.resolveClaudeBin(undefined, { PATH: "" }), /LEDUO_PATROL_CLAUDE_BIN/);
 });
+test("claudeCliSessionTestables.buildShellWrappedClaudeLaunch uses a shell exec wrapper", () => {
+    const launch = claudeCliSessionTestables.buildShellWrappedClaudeLaunch("/opt/claude/bin/claude", ["--session-id", "session-123"], (candidate) => candidate === "/bin/sh");
+    assert.deepEqual(launch, {
+        command: "/bin/sh",
+        args: ["-c", 'exec "$0" "$@"', "/opt/claude/bin/claude", "--session-id", "session-123"],
+    });
+});
+test("claudeCliSessionTestables.shouldRetryClaudeSpawnWithShell matches posix_spawnp failures", () => {
+    const shouldRetry = claudeCliSessionTestables.shouldRetryClaudeSpawnWithShell(new Error("posix_spawnp failed."));
+    assert.equal(typeof shouldRetry, "boolean");
+    if (process.platform === "win32") {
+        assert.equal(shouldRetry, false);
+    }
+    else {
+        assert.equal(shouldRetry, true);
+    }
+});

package/dist/server/__tests__/pty-runtime.test.js

@@ -0,0 +1,28 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtempSync, statSync, writeFileSync, chmodSync } from "node:fs";
+import { ensureExecutableBit } from "../pty-runtime.js";
+test("ensureExecutableBit adds execute permissions when missing", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-pty-runtime-"));
+    const helperPath = path.join(tempDir, "spawn-helper");
+    writeFileSync(helperPath, "#!/bin/sh\n");
+    chmodSync(helperPath, 0o644);
+    const beforeMode = statSync(helperPath).mode & 0o777;
+    const changed = ensureExecutableBit(helperPath);
+    const afterMode = statSync(helperPath).mode & 0o777;
+    assert.equal(beforeMode, 0o644);
+    assert.equal(changed, true);
+    assert.equal(afterMode, 0o755);
+});
+test("ensureExecutableBit is a no-op when execute permissions already exist", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-pty-runtime-"));
+    const helperPath = path.join(tempDir, "spawn-helper");
+    writeFileSync(helperPath, "#!/bin/sh\n");
+    chmodSync(helperPath, 0o755);
+    const changed = ensureExecutableBit(helperPath);
+    const mode = statSync(helperPath).mode & 0o777;
+    assert.equal(changed, false);
+    assert.equal(mode, 0o755);
+});

package/dist/server/access-key-prompt.js

@@ -0,0 +1,84 @@
+import readline from "node:readline/promises";
+import { createAccessKey } from "./access-key.js";
+import { loadStartupPreferences, saveStartupPreferences } from "./startup-preferences.js";
+import { readOptionValue } from "./launch-mode.js";
+export async function resolveAccessKey(options = {}) {
+    const argv = options.argv ?? process.argv.slice(2);
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const createRandomKey = options.createRandomKey ?? createAccessKey;
+    const loadRememberedKey = options.loadRememberedKey ?? loadRememberedAccessKey;
+    const saveRememberedKey = options.saveRememberedKey ?? saveRememberedAccessKey;
+    const promptForKey = options.promptForAccessKey ?? promptForAccessKey;
+    const promptShouldRemember = options.promptShouldRememberKey ?? promptShouldRememberKey;
+    const argvKey = normalizeAccessKey(readOptionValue(argv, "--access-key"));
+    if (argvKey) {
+        return argvKey;
+    }
+    const envKey = normalizeAccessKey(options.envKey ?? process.env.LEDUO_PATROL_ACCESS_KEY);
+    if (envKey) {
+        return envKey;
+    }
+    const rememberedKey = normalizeAccessKey(await loadRememberedKey());
+    if (rememberedKey) {
+        return rememberedKey;
+    }
+    const generatedKey = createRandomKey();
+    if (!stdin.isTTY || !stdout.isTTY) {
+        return generatedKey;
+    }
+    const selectedKey = await promptForKey(stdin, stdout, generatedKey);
+    const shouldRemember = await promptShouldRemember(stdin, stdout);
+    if (shouldRemember) {
+        await saveRememberedKey(selectedKey);
+        stdout.write("已记住访问 key，后续启动会自动复用。\n");
+    }
+    return selectedKey;
+}
+async function promptForAccessKey(stdin, stdout, generatedKey) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+        stdout.write("\n请选择访问 key 生成方式：\n");
+        stdout.write("  1) 手动输入自定义 key\n");
+        stdout.write("  2) 使用随机生成 key\n");
+        const answer = (await rl.question("输入 1/2，默认 2: ")).trim().toLowerCase();
+        if (answer === "1" || answer === "custom" || answer === "manual") {
+            const customAnswer = (await rl.question("请输入自定义访问 key: ")).trim();
+            const customKey = normalizeAccessKey(customAnswer);
+            if (customKey) {
+                return customKey;
+            }
+            stdout.write("未输入有效 key，已改用随机生成 key。\n");
+        }
+        stdout.write(`本次启动使用随机 key: ${generatedKey}\n`);
+        return generatedKey;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptShouldRememberKey(stdin, stdout) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = (await rl.question("是否记住此访问 key 用于后续启动？(y/N): ")).trim().toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+function normalizeAccessKey(raw) {
+    const normalized = raw?.trim() ?? "";
+    return normalized || "";
+}
+async function loadRememberedAccessKey() {
+    return normalizeAccessKey((await loadStartupPreferences()).accessKey);
+}
+async function saveRememberedAccessKey(key) {
+    await saveStartupPreferences({ accessKey: key });
+}
+export const accessKeyPromptTestables = {
+    normalizeAccessKey,
+    loadRememberedAccessKey,
+    saveRememberedAccessKey,
+};

package/dist/server/claude-cli-session.js

@@ -3,6 +3,7 @@ import { EventEmitter } from "node:events";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { buildSpawnFailureMessage, ensureDirectoryExistsSync } from "./server-helpers.js";
+import { ensureNodePtySpawnHelperExecutable } from "./pty-runtime.js";
 /**
  * A PTY-backed session that runs the native Claude Code CLI.
  *
@@ -19,6 +20,7 @@ export class ClaudeCliSession extends EventEmitter {
         super();
         this.sessionId = opts.sessionId;
         ensureDirectoryExistsSync(opts.workspacePath, "Session workspace");
+        ensureNodePtySpawnHelperExecutable();
         const bin = resolveClaudeBin(opts.claudeBin);
         const args = opts.resume
             ? ["--resume", opts.sessionId]
@@ -26,21 +28,24 @@ export class ClaudeCliSession extends EventEmitter {
         if (opts.allowSkipPermissions) {
             args.push("--allow-dangerously-skip-permissions");
         }
+        const env = {
+            ...process.env,
+            TERM: "xterm-256color",
+            COLORTERM: "truecolor",
+        };
         try {
-            this.pty = spawn(bin, args, {
-                name: "xterm-256color",
-                cols: opts.cols ?? 80,
-                rows: opts.rows ?? 24,
-                cwd: opts.workspacePath,
-                env: {
-                    ...process.env,
-                    TERM: "xterm-256color",
-                    COLORTERM: "truecolor",
-                },
-            });
+            this.pty = spawnClaudePty(buildDirectClaudeLaunch(bin, args), opts.workspacePath, opts.cols ?? 80, opts.rows ?? 24, env);
         }
         catch (error) {
-            throw new Error(buildSpawnFailureMessage("Claude CLI", bin, opts.workspacePath, error, "Check that the command is installed correctly, or override it with LEDUO_PATROL_CLAUDE_BIN."));
+            if (!shouldRetryClaudeSpawnWithShell(error)) {
+                throw new Error(buildSpawnFailureMessage("Claude CLI", bin, opts.workspacePath, error, "Check that the command is installed correctly, or override it with LEDUO_PATROL_CLAUDE_BIN."));
+            }
+            try {
+                this.pty = spawnClaudePty(buildShellWrappedClaudeLaunch(bin, args), opts.workspacePath, opts.cols ?? 80, opts.rows ?? 24, env);
+            }
+            catch (fallbackError) {
+                throw new Error(buildSpawnFailureMessage("Claude CLI", bin, opts.workspacePath, fallbackError, "Direct PTY spawn also failed, even after retrying through a shell wrapper. Check that Claude Code is installed correctly, or override it with LEDUO_PATROL_CLAUDE_BIN."));
+            }
         }
         this.pty.onData((data) => {
             this.emit("output", data);
@@ -70,6 +75,42 @@ export class ClaudeCliSession extends EventEmitter {
         }
     }
 }
+function spawnClaudePty(launch, workspacePath, cols, rows, env) {
+    return spawn(launch.command, launch.args, {
+        name: "xterm-256color",
+        cols,
+        rows,
+        cwd: workspacePath,
+        env,
+    });
+}
+function buildDirectClaudeLaunch(bin, args) {
+    return {
+        command: bin,
+        args,
+    };
+}
+function buildShellWrappedClaudeLaunch(bin, args, shellExists = existsSync) {
+    return {
+        command: resolveClaudeWrapperShell(shellExists),
+        args: ["-c", 'exec "$0" "$@"', bin, ...args],
+    };
+}
+function resolveClaudeWrapperShell(shellExists = existsSync) {
+    const candidates = ["/bin/sh", "/bin/bash", "/bin/zsh", "/usr/bin/sh"];
+    for (const candidate of candidates) {
+        if (shellExists(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error("No compatible shell was found for Claude CLI fallback launch.");
+}
+function shouldRetryClaudeSpawnWithShell(error) {
+    if (process.platform === "win32") {
+        return false;
+    }
+    return error instanceof Error && /posix_spawnp failed/i.test(error.message);
+}
 function findExecutableOnPath(command, envPath = process.env.PATH) {
     if (!envPath)
         return null;
@@ -102,6 +143,10 @@ function resolveClaudeBin(configuredBin, env = process.env) {
     throw new Error(`Claude CLI "${candidate}" was not found in PATH. Install Claude Code first, or set LEDUO_PATROL_CLAUDE_BIN=/absolute/path/to/claude.`);
 }
 export const claudeCliSessionTestables = {
+    buildDirectClaudeLaunch,
+    buildShellWrappedClaudeLaunch,
     findExecutableOnPath,
     resolveClaudeBin,
+    resolveClaudeWrapperShell,
+    shouldRetryClaudeSpawnWithShell,
 };

package/dist/server/index.js

@@ -10,9 +10,10 @@ import { SessionManager } from "./session-manager.js";
 import { formatError, resolveAllowedPath } from "./server-helpers.js";
 import { ShellSession } from "./shell-session.js";
 import { buildSingleFileDiff, buildWorkspaceDiffFilesSnapshot } from "./git-diff.js";
-import { buildAccessCookie, createAccessKey, hasAuthorizedAccessCookie, isAccessKeyAuthorized } from "./access-key.js";
+import { buildAccessCookie, hasAuthorizedAccessCookie, isAccessKeyAuthorized } from "./access-key.js";
 import { findAvailablePort, pickPreferredLanIp } from "./network.js";
 import { resolveBindMode } from "./launch-mode.js";
+import { resolveAccessKey } from "./access-key-prompt.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const launchCwd = process.cwd();
 const defaultWorkspacePath = process.env.LEDUO_PATROL_WORKSPACE_PATH ?? launchCwd;
@@ -34,8 +35,8 @@ const listenHost = bindMode === "local" ? "127.0.0.1" : "0.0.0.0";
 const launchHost = bindMode === "local" ? "127.0.0.1" : pickPreferredLanIp();
 const launchUser = userInfo().username;
 const claudeBin = process.env.LEDUO_PATROL_CLAUDE_BIN?.trim() || undefined;
-const accessKey = process.env.LEDUO_PATROL_ACCESS_KEY?.trim() || createAccessKey();
-const enableShell = process.env.LEDUO_ENABLE_SHELL === "true";
+const accessKey = await resolveAccessKey();
+const enableShell = parseBooleanFlag(process.env.LEDUO_ENABLE_SHELL, true);
 const allowSkipPermissions = process.env.LEDUO_PATROL_ALLOW_SKIP_PERMISSIONS === "true";
 const app = express();
 const server = createServer(app);
@@ -174,8 +175,17 @@ wss.on("connection", (socket, request) => {
         socket.close(1008, "Unauthorized");
         return;
     }
-    const unsubscribe = sessionManager.subscribe((event) => sendEvent(socket, event));
-    let shellSession = null;
+    const shellSessions = new Map();
+    const unsubscribe = sessionManager.subscribe((event) => {
+        if (event.type === "session_closed") {
+            const shellSession = shellSessions.get(event.payload.clientSessionId);
+            if (shellSession) {
+                shellSession.kill();
+                shellSessions.delete(event.payload.clientSessionId);
+            }
+        }
+        sendEvent(socket, event);
+    });
     socket.on("message", async (raw) => {
         try {
             const message = JSON.parse(String(raw));
@@ -215,40 +225,44 @@ wss.on("connection", (socket, request) => {
                     if (!enableShell) {
                         throw new Error("Shell feature is disabled. Set LEDUO_ENABLE_SHELL=true to enable it.");
                     }
-                    shellSession?.kill();
-                    shellSession = null;
+                    const clientSessionId = message.payload.clientSessionId;
+                    const existingShell = shellSessions.get(clientSessionId);
                     const cols = Math.max(2, message.payload.cols);
                     const rows = Math.max(2, message.payload.rows);
-                    const shellWorkspacePath = sessionManager.getSessionWorkspacePath(message.payload.clientSessionId);
+                    if (existingShell?.alive) {
+                        existingShell.resize(cols, rows);
+                        break;
+                    }
+                    const shellWorkspacePath = sessionManager.getSessionWorkspacePath(clientSessionId);
                     const newShell = new ShellSession(shellWorkspacePath, cols, rows);
-                    shellSession = newShell;
+                    shellSessions.set(clientSessionId, newShell);
                     newShell.on("output", (data) => {
                         if (socket.readyState === WebSocket.OPEN) {
-                            socket.send(JSON.stringify({ type: "shell_output", payload: { data } }));
+                            socket.send(JSON.stringify({ type: "shell_output", payload: { clientSessionId, data } }));
                         }
                     });
                     newShell.on("exit", (exitCode) => {
-                        if (shellSession === newShell) {
-                            shellSession = null;
+                        if (shellSessions.get(clientSessionId) === newShell) {
+                            shellSessions.delete(clientSessionId);
                         }
                         if (socket.readyState === WebSocket.OPEN) {
-                            socket.send(JSON.stringify({ type: "shell_exited", payload: { exitCode } }));
+                            socket.send(JSON.stringify({ type: "shell_exited", payload: { clientSessionId, exitCode } }));
                         }
                     });
                     break;
                 }
                 case "shell_input":
-                    if (!shellSession?.alive) {
+                    if (!shellSessions.get(message.payload.clientSessionId)?.alive) {
                         throw new Error("Shell is not running");
                     }
-                    shellSession.write(message.payload.data);
+                    shellSessions.get(message.payload.clientSessionId)?.write(message.payload.data);
                     break;
                 case "shell_resize":
-                    shellSession?.resize(message.payload.cols, message.payload.rows);
+                    shellSessions.get(message.payload.clientSessionId)?.resize(message.payload.cols, message.payload.rows);
                     break;
                 case "shell_stop":
-                    shellSession?.kill();
-                    shellSession = null;
+                    shellSessions.get(message.payload.clientSessionId)?.kill();
+                    shellSessions.delete(message.payload.clientSessionId);
                     break;
             }
         }
@@ -261,8 +275,10 @@ wss.on("connection", (socket, request) => {
     });
     socket.on("close", () => {
         unsubscribe();
-        shellSession?.kill();
-        shellSession = null;
+        for (const shellSession of shellSessions.values()) {
+            shellSession.kill();
+        }
+        shellSessions.clear();
     });
 });
 const listenPort = await findAvailablePort(requestedPort, listenHost);
@@ -286,6 +302,7 @@ else {
     console.log("Web UI is unavailable on this start because bundled assets are missing.");
 }
 console.log(`Access URL: http://${displayHost}:${accessPort}/?key=${accessKey}`);
+console.log(`Shell feature: ${enableShell ? "enabled" : "disabled"}`);
 function sendEvent(socket, event) {
     if (socket.readyState !== WebSocket.OPEN) {
         return;
@@ -301,3 +318,16 @@ async function hasReadableFile(filePath) {
         return false;
     }
 }
+function parseBooleanFlag(rawValue, defaultValue) {
+    if (rawValue == null || rawValue.trim() === "") {
+        return defaultValue;
+    }
+    const normalized = rawValue.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized)) {
+        return true;
+    }
+    if (["0", "false", "no", "off"].includes(normalized)) {
+        return false;
+    }
+    return defaultValue;
+}

package/dist/server/launch-mode.js

@@ -1,9 +1,6 @@
-import os from "node:os";
-import path from "node:path";
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import readline from "node:readline/promises";
+import { loadStartupPreferences, saveStartupPreferences } from "./startup-preferences.js";
 const DEFAULT_MODE = "server";
-const PREFS_FILE_PATH = path.join(os.homedir(), ".leduo-patrol", "launch-preferences.json");
 export async function resolveBindMode(options = {}) {
     const argv = options.argv ?? process.argv.slice(2);
     const stdin = options.stdin ?? process.stdin;
@@ -41,7 +38,7 @@ function parseBindMode(raw) {
     }
     return null;
 }
-function readOptionValue(argv, optionName) {
+export function readOptionValue(argv, optionName) {
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === optionName) {
@@ -77,12 +74,8 @@ async function promptShouldRemember(stdin, stdout) {
     }
 }
 async function loadRememberedMode() {
-    if (!(await isReadable(PREFS_FILE_PATH))) {
-        return null;
-    }
     try {
-        const raw = await readFile(PREFS_FILE_PATH, "utf8");
-        const parsed = JSON.parse(raw);
+        const parsed = (await loadStartupPreferences());
         return parseBindMode(parsed.bindMode ?? "");
     }
     catch {
@@ -90,18 +83,7 @@ async function loadRememberedMode() {
     }
 }
 async function saveRememberedMode(mode) {
-    await mkdir(path.dirname(PREFS_FILE_PATH), { recursive: true });
-    const payload = { bindMode: mode };
-    await writeFile(PREFS_FILE_PATH, JSON.stringify(payload, null, 2), "utf8");
-}
-async function isReadable(filePath) {
-    try {
-        await access(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    await saveStartupPreferences({ bindMode: mode });
 }
 export const launchModeTestables = {
     parseBindMode,

package/dist/server/pty-runtime.js

@@ -0,0 +1,28 @@
+import { chmodSync, existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+export function ensureNodePtySpawnHelperExecutable() {
+    if (process.platform !== "darwin") {
+        return;
+    }
+    const helperPath = resolveNodePtySpawnHelperPath();
+    if (!helperPath) {
+        return;
+    }
+    ensureExecutableBit(helperPath);
+}
+export function resolveNodePtySpawnHelperPath() {
+    const packageJsonPath = require.resolve("node-pty/package.json");
+    const packageRoot = path.dirname(packageJsonPath);
+    const helperPath = path.join(packageRoot, "prebuilds", `${process.platform}-${process.arch}`, "spawn-helper");
+    return existsSync(helperPath) ? helperPath : null;
+}
+export function ensureExecutableBit(filePath) {
+    const stats = statSync(filePath);
+    if ((stats.mode & 0o111) === 0o111) {
+        return false;
+    }
+    chmodSync(filePath, stats.mode | 0o755);
+    return true;
+}

package/dist/server/shell-session.js

@@ -3,6 +3,7 @@ import { EventEmitter } from "node:events";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { buildSpawnFailureMessage, ensureDirectoryExistsSync } from "./server-helpers.js";
+import { ensureNodePtySpawnHelperExecutable } from "./pty-runtime.js";
 function buildShellLoginArgs(command) {
     const shellName = path.basename(command).toLowerCase();
     if (["bash", "zsh", "ksh", "fish"].includes(shellName)) {
@@ -55,6 +56,7 @@ export class ShellSession extends EventEmitter {
     constructor(workspacePath, cols = 80, rows = 24) {
         super();
         ensureDirectoryExistsSync(workspacePath, "Shell workspace");
+        ensureNodePtySpawnHelperExecutable();
         const shellLaunch = resolveShellLaunch();
         const env = {
             ...Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] != null)),

package/dist/server/startup-preferences.js

@@ -0,0 +1,45 @@
+import os from "node:os";
+import path from "node:path";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+const PREFS_FILE_PATH = path.join(os.homedir(), ".leduo-patrol", "launch-preferences.json");
+export async function loadStartupPreferences() {
+    if (!(await isReadable(PREFS_FILE_PATH))) {
+        return {};
+    }
+    try {
+        const raw = await readFile(PREFS_FILE_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function saveStartupPreferences(updates) {
+    const current = await loadStartupPreferences();
+    const next = {
+        ...current,
+        ...updates,
+    };
+    for (const key of Object.keys(next)) {
+        const value = next[key];
+        if (value == null || value === "") {
+            delete next[key];
+        }
+    }
+    await mkdir(path.dirname(PREFS_FILE_PATH), { recursive: true });
+    await writeFile(PREFS_FILE_PATH, JSON.stringify(next, null, 2), "utf8");
+    return next;
+}
+async function isReadable(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const startupPreferencesTestables = {
+    PREFS_FILE_PATH,
+};