leduo-patrol 2.0.0 → 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 时展示输入页
@@ -97,6 +97,7 @@
 - Node.js 22+
 - 已能正常运行 Claude Code
 - 服务器环境里已配置 `ANTHROPIC_API_KEY`
+- 若 `claude` 不在默认 `PATH` 中，请设置 `LEDUO_PATROL_CLAUDE_BIN=/absolute/path/to/claude`
 
 ## 启动
 
@@ -116,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`，端口冲突时会自动递增寻找可用端口）
@@ -148,15 +150,17 @@ LEDUO_PATROL_BIND_MODE=server
 LEDUO_PATROL_APP_NAME=乐多汪汪队
 LEDUO_PATROL_WORKSPACE_PATH=/absolute/workspace/path
 LEDUO_PATROL_ALLOWED_ROOTS=/absolute/workspace/path,/another/allowed/root
+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_PATROL_AGENT_BIN=/absolute/path/to/claude-code-acp
-LEDUO_ENABLE_SHELL=true
+LEDUO_ENABLE_SHELL=false
 ```
 
 如果设置了 `LEDUO_PATROL_ALLOWED_ROOTS`，网页中只能连接这些根目录之下的路径；未设置时默认只允许启动命令所在目录。
 如果未设置 `LEDUO_PATROL_WORKSPACE_PATH`，默认工作目录为启动命令所在目录（`process.cwd()`），并在启动日志中提示如何通过环境变量修改。
 如果未设置 `LEDUO_PATROL_ALLOWED_ROOTS`，默认允许根目录同样为启动命令所在目录，并会在启动日志中提示可配置项。
+如果发布安装后的内嵌终端无法启动，可通过 `LEDUO_PATROL_SHELL` 显式指定 shell 路径；例如 macOS 上常见的 `/bin/zsh`。
 
 ## 状态持久化
 
@@ -174,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` 资源，服务会给出错误提示页与启动日志提示。
@@ -187,7 +196,15 @@ LEDUO_ENABLE_SHELL=true
 
 ```bash
 LEDUO_PATROL_ACCESS_KEY=your-fixed-key
-LEDUO_PATROL_AGENT_BIN=/absolute/path/to/claude-code-acp
+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
 ```
 
 ## 已知限制

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

@@ -0,0 +1,41 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { claudeCliSessionTestables } from "../claude-cli-session.js";
+test("claudeCliSessionTestables.findExecutableOnPath resolves commands from PATH entries", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-claude-bin-"));
+    const binaryName = process.platform === "win32" ? "claude.cmd" : "claude";
+    const binaryPath = path.join(tempDir, binaryName);
+    writeFileSync(binaryPath, process.platform === "win32" ? "@echo off\r\n" : "#!/bin/sh\n");
+    const resolved = claudeCliSessionTestables.findExecutableOnPath("claude", tempDir);
+    assert.equal(resolved, binaryPath);
+});
+test("claudeCliSessionTestables.resolveClaudeBin accepts explicit executable paths", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-claude-explicit-"));
+    const binaryPath = path.join(tempDir, "claude");
+    writeFileSync(binaryPath, "#!/bin/sh\n");
+    const resolved = claudeCliSessionTestables.resolveClaudeBin(binaryPath, { PATH: "" });
+    assert.equal(resolved, binaryPath);
+});
+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/__tests__/server-helpers.test.js

@@ -1,7 +1,9 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import path from "node:path";
-import { formatError, resolveAllowedPath } from "../server-helpers.js";
+import os from "node:os";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { buildSpawnFailureMessage, ensureDirectoryExistsSync, formatError, resolveAllowedPath, } from "../server-helpers.js";
 test("server helpers formatError handles Error and primitives", () => {
     assert.equal(formatError(new Error("boom")), "boom");
     assert.equal(formatError("plain"), '"plain"');
@@ -16,3 +18,17 @@ test("server helpers resolveAllowedPath rejects outside roots", () => {
     const root = path.resolve("/tmp/repo");
     assert.throws(() => resolveAllowedPath("/etc", [root]), /outside allowed roots/);
 });
+test("server helpers ensureDirectoryExistsSync accepts existing directories", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-dir-"));
+    assert.equal(ensureDirectoryExistsSync(tempDir, "Workspace"), tempDir);
+});
+test("server helpers ensureDirectoryExistsSync rejects files and missing paths", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-file-"));
+    const filePath = path.join(tempDir, "file.txt");
+    writeFileSync(filePath, "hello");
+    assert.throws(() => ensureDirectoryExistsSync(filePath, "Workspace"), /is not a directory/);
+    assert.throws(() => ensureDirectoryExistsSync(path.join(tempDir, "missing"), "Workspace"), /does not exist/);
+});
+test("server helpers buildSpawnFailureMessage includes command cwd and hint", () => {
+    assert.equal(buildSpawnFailureMessage("shell", "/bin/zsh", "/repo", new Error("posix_spawnp failed"), "Try another shell."), 'Failed to start shell "/bin/zsh" in "/repo": posix_spawnp failed. Try another shell.');
+});

package/dist/server/__tests__/shell-session.test.js

@@ -0,0 +1,35 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { shellSessionTestables } from "../shell-session.js";
+test("shellSessionTestables.resolveShellLaunch prefers configured shell over defaults", () => {
+    const resolved = shellSessionTestables.resolveShellLaunch({
+        LEDUO_PATROL_SHELL: "/custom/bin/zsh",
+        SHELL: "/bin/bash",
+    }, (candidate) => candidate === "/custom/bin/zsh" || candidate === "/bin/bash");
+    assert.deepEqual(resolved, {
+        command: "/custom/bin/zsh",
+        args: ["-l"],
+    });
+});
+test("shellSessionTestables.resolveShellLaunch falls back to /bin/sh when bash and zsh are unavailable", () => {
+    const resolved = shellSessionTestables.resolveShellLaunch({
+        SHELL: "/missing/shell",
+    }, (candidate) => candidate === "/bin/sh");
+    assert.deepEqual(resolved, {
+        command: "/bin/sh",
+        args: [],
+    });
+});
+test("shellSessionTestables.resolveShellLaunch accepts plain configured shell names as a last resort", () => {
+    const resolved = shellSessionTestables.resolveShellLaunch({
+        LEDUO_PATROL_SHELL: "fish",
+        SHELL: "",
+    }, () => false);
+    assert.deepEqual(resolved, {
+        command: "fish",
+        args: ["-l"],
+    });
+});
+test("shellSessionTestables.resolveShellLaunch throws actionable error when no shell is available", () => {
+    assert.throws(() => shellSessionTestables.resolveShellLaunch({ SHELL: "" }, () => false), /LEDUO_PATROL_SHELL/);
+});

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

@@ -1,5 +1,9 @@
 import { spawn } from "node-pty";
 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.
  *
@@ -15,24 +19,34 @@ export class ClaudeCliSession extends EventEmitter {
     constructor(opts) {
         super();
         this.sessionId = opts.sessionId;
-        const bin = opts.claudeBin ?? "claude";
+        ensureDirectoryExistsSync(opts.workspacePath, "Session workspace");
+        ensureNodePtySpawnHelperExecutable();
+        const bin = resolveClaudeBin(opts.claudeBin);
         const args = opts.resume
             ? ["--resume", opts.sessionId]
             : ["--session-id", opts.sessionId];
         if (opts.allowSkipPermissions) {
             args.push("--allow-dangerously-skip-permissions");
         }
-        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",
-            },
-        });
+        const env = {
+            ...process.env,
+            TERM: "xterm-256color",
+            COLORTERM: "truecolor",
+        };
+        try {
+            this.pty = spawnClaudePty(buildDirectClaudeLaunch(bin, args), opts.workspacePath, opts.cols ?? 80, opts.rows ?? 24, env);
+        }
+        catch (error) {
+            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);
         });
@@ -61,3 +75,78 @@ 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;
+    const extensions = process.platform === "win32"
+        ? (process.env.PATHEXT?.split(";").filter(Boolean) ?? [".exe", ".cmd", ".bat"])
+        : [""];
+    for (const entry of envPath.split(path.delimiter).filter(Boolean)) {
+        for (const extension of extensions) {
+            const candidate = path.join(entry, `${command}${extension}`);
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    return null;
+}
+function resolveClaudeBin(configuredBin, env = process.env) {
+    const candidate = configuredBin?.trim() || "claude";
+    const hasExplicitPath = candidate.includes("/") || candidate.includes("\\");
+    if (hasExplicitPath) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        throw new Error(`Claude CLI not found at "${candidate}". Set LEDUO_PATROL_CLAUDE_BIN to a valid Claude executable path.`);
+    }
+    const resolved = findExecutableOnPath(candidate, env.PATH);
+    if (resolved) {
+        return resolved;
+    }
+    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;
@@ -27,14 +28,15 @@ const vscodeRemoteUri = process.env.LEDUO_PATROL_VSCODE_URI ??
     (sshHost ? `vscode://vscode-remote/ssh-remote+${encodeURIComponent(sshHost)}${sshPath}` : "");
 const requestedPort = Number(process.env.PORT ?? 3001);
 const devWebPort = Number(process.env.LEDUO_PATROL_WEB_PORT ?? 5173);
-const isDevServer = process.env.npm_lifecycle_event === "dev:server";
+const npmLifecycleEvent = process.env.npm_lifecycle_event ?? "";
+const isDevServer = npmLifecycleEvent === "dev:server" || npmLifecycleEvent === "dev:server:local";
 const bindMode = await resolveBindMode();
 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);
@@ -173,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));
@@ -214,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;
             }
         }
@@ -260,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);
@@ -285,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;
@@ -300,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;
+}