@co0ontty/wand 1.72.0 → 1.74.1

package/dist/git-quick-commit.js

@@ -1,12 +1,17 @@
 import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
 import { ClaudeRunError, runClaudePrint } from "./claude-sdk-runner.js";
+import { buildChildEnv } from "./env-utils.js";
 import { runGit as runGitBase, runGitRaw as runGitRawBase, getGitErrorMessage } from "./git-utils.js";
+import { applyThinkingEffortToPrompt, thinkingEffortToCodexReasoningEffort } from "./structured-session-manager.js";
 const GIT_TIMEOUT_MS = 1500;
 const GIT_PUSH_TIMEOUT_MS = 30_000;
 const MAX_FILE_ENTRIES = 200;
 // AI 生成 message/tag 的超时。SDK 链路 = spawn claude + API 调用（带自动重试），
 // 30s 在 API 抖动时不够用，放宽到 60s。
 const CLAUDE_MESSAGE_TIMEOUT_MS = 60_000;
+const CODEX_MESSAGE_TIMEOUT_MS = 60_000;
+const QUICK_COMMIT_CLI_TIMEOUT_MS = 120_000;
 const MAX_DIFF_FOR_AI = 100_000;
 const GIT_MAX_BUFFER = 16 * 1024 * 1024;
 function runGit(args, cwd, timeoutMs = GIT_TIMEOUT_MS) {
@@ -257,9 +262,9 @@ export class QuickCommitError extends Error {
     }
 }
 // ── AI commit message generation ──
-async function callClaudeText(prompt, cwd, language) {
+async function callClaudeText(prompt, cwd, language, model) {
     try {
-        return await runClaudePrint(prompt, { cwd, timeoutMs: CLAUDE_MESSAGE_TIMEOUT_MS, language });
+        return await runClaudePrint(prompt, { cwd, timeoutMs: CLAUDE_MESSAGE_TIMEOUT_MS, language, model: model ?? undefined });
     }
     catch (error) {
         if (error instanceof ClaudeRunError) {
@@ -275,6 +280,106 @@ async function callClaudeText(prompt, cwd, language) {
         throw error;
     }
 }
+function normalizeProvider(provider) {
+    return provider === "codex" ? "codex" : "claude";
+}
+function stripFences(raw) {
+    return raw.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();
+}
+function normalizeAiText(raw) {
+    return stripFences(raw).replace(/^["'`]+|["'`]+$/g, "").trim();
+}
+function extractCodexText(stdout) {
+    let lastAgentText = "";
+    for (const line of stdout.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("{"))
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed.type === "item.completed" && parsed.item?.type === "agent_message" && typeof parsed.item.text === "string") {
+                lastAgentText = parsed.item.text;
+            }
+        }
+        catch {
+            // ignore non-JSON diagnostics mixed into stdout
+        }
+    }
+    if (lastAgentText)
+        return lastAgentText.trim();
+    const lines = stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    const noise = /^(OpenAI Codex|[-]+$|workdir:|model:|provider:|approval:|sandbox:|reasoning|session id:|user$|codex$|tokens used$|[0-9,]+$)/i;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (!noise.test(lines[i]))
+            return lines[i];
+    }
+    return "";
+}
+function runCliText(command, args, prompt, opts) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: opts.cwd,
+            env: buildChildEnv(opts.inheritEnv !== false),
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timeout = setTimeout(() => {
+            settled = true;
+            child.kill("SIGTERM");
+            reject(new QuickCommitError(`${command} 调用超时。`, "CLAUDE_TIMEOUT"));
+        }, opts.timeoutMs);
+        child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
+        child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            const code = error.code === "ENOENT" ? "CLAUDE_CLI_MISSING" : "CLAUDE_CLI_FAILED";
+            reject(new QuickCommitError(error.code === "ENOENT" ? `未找到 ${command} CLI。` : `${command} CLI 失败：${error.message}`, code));
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (code === 0) {
+                resolve(stdout);
+                return;
+            }
+            reject(new QuickCommitError(`${command} CLI 失败：${(stderr || stdout).trim() || `exit ${code}`}`, "CLAUDE_CLI_FAILED"));
+        });
+        child.stdin?.end(prompt);
+    });
+}
+async function callCodexText(prompt, cwd, opts) {
+    const args = ["exec", "--json", "--color", "never", "--skip-git-repo-check", "--sandbox", "read-only"];
+    const model = opts.model?.trim();
+    if (model && model !== "default")
+        args.push("--model", model);
+    const reasoningEffort = thinkingEffortToCodexReasoningEffort(opts.thinkingEffort ?? "off");
+    if (reasoningEffort)
+        args.push("-c", `model_reasoning_effort=${reasoningEffort}`);
+    args.push("-");
+    const stdout = await runCliText("codex", args, prompt, {
+        cwd,
+        timeoutMs: CODEX_MESSAGE_TIMEOUT_MS,
+        inheritEnv: opts.inheritEnv,
+    });
+    const text = extractCodexText(stdout);
+    if (!text) {
+        throw new QuickCommitError("Codex 返回了空的 commit message。", "EMPTY_AI_MESSAGE");
+    }
+    return text;
+}
+async function callAiText(prompt, cwd, language, opts) {
+    if (normalizeProvider(opts.provider) === "codex") {
+        return callCodexText(prompt, cwd, opts);
+    }
+    return callClaudeText(prompt, cwd, language, opts.model);
+}
 function collectStagedDiff(cwd) {
     let diff;
     try {
@@ -296,14 +401,14 @@ function collectStagedDiff(cwd) {
     }
     return diff;
 }
-async function generateCommitMessage(cwd, language) {
+async function generateCommitMessage(cwd, language, ai = {}) {
     const diff = collectStagedDiff(cwd);
     const lang = language.trim() || "中文";
     const prompt = `阅读以下 git diff，用${lang}写一条简洁的 commit message。要求：祈使句，不超过 50 字，描述「做了什么」。只输出 message 本身，不要引号、不要 Markdown 格式、不要任何额外说明。\n\n${diff}`;
-    const raw = await callClaudeText(prompt, cwd, language);
-    const message = raw.replace(/^["'`]+|["'`]+$/g, "").trim();
+    const raw = await callAiText(prompt, cwd, language, ai);
+    const message = normalizeAiText(raw);
     if (!message) {
-        throw new QuickCommitError("Claude 返回了空的 commit message。", "EMPTY_AI_MESSAGE");
+        throw new QuickCommitError("AI 返回了空的 commit message。", "EMPTY_AI_MESSAGE");
     }
     return message;
 }
@@ -334,7 +439,7 @@ function sanitizeSuggestedTag(value) {
         return undefined;
     return cleaned;
 }
-async function generateCommitMessageWithTag(cwd, language) {
+async function generateCommitMessageWithTag(cwd, language, ai = {}) {
     const diff = collectStagedDiff(cwd);
     let latestTag;
     try {
@@ -356,25 +461,25 @@ async function generateCommitMessageWithTag(cwd, language) {
 
 git diff:
 ${diff}`;
-    const raw = await callClaudeText(prompt, cwd, language);
+    const raw = await callAiText(prompt, cwd, language, ai);
     const parsed = tryParseJson(raw);
     let message;
     let suggestedTag;
     if (parsed && typeof parsed.message === "string") {
-        message = parsed.message.replace(/^["'`]+|["'`]+$/g, "").trim();
+        message = normalizeAiText(parsed.message);
         suggestedTag = sanitizeSuggestedTag(parsed.tag);
     }
     else {
         // Fallback: treat whole output as message, no tag suggestion
-        message = raw.replace(/^["'`]+|["'`]+$/g, "").trim();
+        message = normalizeAiText(raw);
         suggestedTag = undefined;
     }
     if (!message) {
-        throw new QuickCommitError("Claude 返回了空的 commit message。", "EMPTY_AI_MESSAGE");
+        throw new QuickCommitError("AI 返回了空的 commit message。", "EMPTY_AI_MESSAGE");
     }
     return { message, suggestedTag };
 }
-export async function generateCommitMessageOnly(cwd, language) {
+export async function generateCommitMessageOnly(cwd, language, ai = {}) {
     if (!cwd || !existsSync(cwd)) {
         throw new QuickCommitError("工作目录不存在。", "CWD_MISSING");
     }
@@ -384,13 +489,13 @@ export async function generateCommitMessageOnly(cwd, language) {
     catch {
         // best-effort staging so the diff is complete
     }
-    return generateCommitMessageWithTag(cwd, language);
+    return generateCommitMessageWithTag(cwd, language, ai);
 }
 /**
  * Ask Claude for a single tag string. Called from `runQuickCommit` after the commit has
  * already landed, so we look at `git show HEAD` and use `HEAD~1` for the previous tag.
  */
-async function generateTagAfterCommit(cwd, language, commitMessage) {
+async function generateTagAfterCommit(cwd, language, commitMessage, ai = {}) {
     let diff;
     try {
         diff = runGit(["show", "HEAD", "--no-color", "--submodule=log"], cwd, 5000);
@@ -430,7 +535,7 @@ commit message：${commitMessage}
 
 git diff：
 ${diff}`;
-    const raw = await callClaudeText(prompt, cwd, language);
+    const raw = await callAiText(prompt, cwd, language, ai);
     const parsed = tryParseJson(raw);
     let suggested;
     if (parsed && typeof parsed.tag === "string") {
@@ -766,8 +871,145 @@ function collectSubmodulesForPush(cwd) {
     }
     return { base, infos };
 }
+function buildFallbackPrompt(opts, priorError) {
+    const lang = opts.language.trim() || "中文";
+    const messageLine = opts.autoMessage === false
+        ? `- 使用这个 commit message：${(opts.customMessage || "").trim()}`
+        : `- 先根据当前 staged/unstaged diff 生成一条简洁的 ${lang} commit message（祈使句，不超过 50 字）`;
+    const tagLine = opts.tag?.trim()
+        ? `- 提交后创建 tag：${opts.tag.trim()}`
+        : opts.autoTag
+            ? "- 提交后根据改动幅度创建下一个语义化版本 tag"
+            : "- 不创建 tag";
+    const pushLine = opts.push ? "- 提交完成后推送当前分支；如果创建了 tag，也推送该 tag" : "- 不执行 push";
+    const submoduleLine = opts.submodule
+        ? "- 如果 submodule 内部也有改动，先在对应 submodule 内 add/commit，再提交父仓库里的 submodule 指针"
+        : "- 不进入 submodule 内部提交，只提交父仓库自身已纳入的改动";
+    return [
+        "你正在作为 Wand 的快捷提交兜底执行器运行。前置的内置快捷提交流程失败了，现在请直接用 CLI 工具完成同一件事。",
+        "",
+        "约束：",
+        "- 只允许执行与 git 快捷提交直接相关的命令，例如 git status、git diff、git add、git commit、git tag、git push、git submodule status。",
+        "- 不要修改源代码内容，不要运行测试，不要安装依赖，不要重构文件。",
+        "- 如果没有可提交改动，明确说明并停止，不要创建空 commit。",
+        "- commit message 和自然语言输出使用 " + lang + "。",
+        "",
+        "任务：",
+        "- 执行 git add -A 纳入当前改动。",
+        messageLine,
+        tagLine,
+        pushLine,
+        submoduleLine,
+        "",
+        `内置流程失败原因：${priorError}`,
+        "",
+        "完成后只输出一行 JSON：{\"ok\":true,\"message\":\"...\",\"tag\":\"...\"}。失败时输出一行 JSON：{\"ok\":false,\"error\":\"...\"}。",
+    ].join("\n");
+}
+function getHead(cwd) {
+    try {
+        return runGit(["rev-parse", "HEAD"], cwd);
+    }
+    catch {
+        return null;
+    }
+}
+function getHeadSummary(cwd) {
+    try {
+        const raw = runGit(["log", "-1", "--pretty=format:%h%x09%s"], cwd);
+        const parts = raw.split("\t");
+        return { hash: parts[0] ?? "", message: parts.slice(1).join("\t") };
+    }
+    catch {
+        return { hash: "", message: "" };
+    }
+}
+function getLatestTagAtHead(cwd) {
+    try {
+        return runGit(["describe", "--tags", "--exact-match", "HEAD"], cwd) || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function runQuickCommitFallbackCli(opts, priorError) {
+    assertGitWorkTree(opts.cwd);
+    const beforeHead = getHead(opts.cwd);
+    const prompt = buildFallbackPrompt(opts, priorError);
+    const provider = normalizeProvider(opts.provider);
+    if (provider === "codex") {
+        const args = ["exec", "--json", "--color", "never", "--skip-git-repo-check", "--dangerously-bypass-approvals-and-sandbox"];
+        const model = opts.model?.trim();
+        if (model && model !== "default")
+            args.push("--model", model);
+        const reasoningEffort = thinkingEffortToCodexReasoningEffort(opts.thinkingEffort ?? "off");
+        if (reasoningEffort)
+            args.push("-c", `model_reasoning_effort=${reasoningEffort}`);
+        args.push("-");
+        await runCliText("codex", args, prompt, {
+            cwd: opts.cwd,
+            timeoutMs: QUICK_COMMIT_CLI_TIMEOUT_MS,
+            inheritEnv: opts.inheritEnv,
+        });
+    }
+    else {
+        const args = ["-p", "--verbose", "--output-format", "stream-json"];
+        const model = opts.model?.trim();
+        if (model && model !== "default")
+            args.push("--model", model);
+        args.push("--permission-mode", "bypassPermissions");
+        const effectivePrompt = applyThinkingEffortToPrompt(prompt, opts.thinkingEffort ?? "off");
+        await runCliText("claude", args, effectivePrompt, {
+            cwd: opts.cwd,
+            timeoutMs: QUICK_COMMIT_CLI_TIMEOUT_MS,
+            inheritEnv: opts.inheritEnv,
+        });
+    }
+    const afterHead = getHead(opts.cwd);
+    if (!afterHead || afterHead === beforeHead) {
+        throw new QuickCommitError("CLI 兜底没有创建新的 commit。", "GIT_COMMIT_FAILED");
+    }
+    const commit = getHeadSummary(opts.cwd);
+    const tag = getLatestTagAtHead(opts.cwd);
+    return {
+        ok: true,
+        commit,
+        tag: tag ? { name: tag } : undefined,
+        pushed: false,
+    };
+}
+function shouldFallbackToCli(error) {
+    return ![
+        "CWD_MISSING",
+        "NO_CWD",
+        "NOT_A_GIT_REPO",
+        "NO_COMMIT",
+        "NOTHING_TO_COMMIT",
+        "NOTHING_TO_PUSH",
+        "EMPTY_MESSAGE",
+        "EMPTY_TAG",
+        "TAG_EXISTS",
+    ].includes(error.code);
+}
+export async function runQuickCommitWithFallback(opts) {
+    try {
+        return await runQuickCommit(opts);
+    }
+    catch (error) {
+        if (error instanceof QuickCommitError && shouldFallbackToCli(error)) {
+            return runQuickCommitFallbackCli(opts, error.message);
+        }
+        throw error;
+    }
+}
 export async function runQuickCommit(opts) {
     const { cwd, language, autoMessage, customMessage, tag, autoTag, push, submodule } = opts;
+    const ai = {
+        provider: opts.provider,
+        model: opts.model,
+        thinkingEffort: opts.thinkingEffort,
+        inheritEnv: opts.inheritEnv,
+    };
     assertGitWorkTree(cwd);
     // 先 add 一次让我们能在 collectStagedDiff 看到完整改动（包含 submodule 指针），
     // AI 生成 message 时也基于这个 staged diff。
@@ -802,7 +1044,7 @@ export async function runQuickCommit(opts) {
     }
     let message;
     if (autoMessage) {
-        message = await generateCommitMessage(cwd, language);
+        message = await generateCommitMessage(cwd, language, ai);
     }
     else {
         message = (customMessage || "").trim();
@@ -855,7 +1097,7 @@ export async function runQuickCommit(opts) {
     // Tag: explicit `tag` wins; if empty + autoTag, ask Claude; otherwise skip.
     let tagName = (tag || "").trim();
     if (!tagName && autoTag) {
-        tagName = await generateTagAfterCommit(cwd, language, message);
+        tagName = await generateTagAfterCommit(cwd, language, message, ai);
     }
     if (tagName) {
         try {

package/dist/models.js

@@ -3,7 +3,7 @@ import { promisify } from "node:util";
 import { extractSemver } from "./version-utils.js";
 const execAsync = promisify(exec);
 const CLAUDE_MODELS = [
-    { id: "default", label: "default（跟随 Claude Code 默认）", alias: true },
+    { id: "default", label: "Sonnet 4.6 · claude-sonnet-4-6（Claude Code 默认）", alias: true },
     { id: "opus", label: "opus（最新 Opus）", alias: true },
     { id: "sonnet", label: "sonnet（最新 Sonnet）", alias: true },
     { id: "haiku", label: "haiku（最新 Haiku）", alias: true },
@@ -13,7 +13,7 @@ const CLAUDE_MODELS = [
     { id: "claude-haiku-4-5-20251001", label: "Haiku 4.5 · claude-haiku-4-5-20251001" },
 ];
 const CODEX_FALLBACK_MODELS = [
-    { id: "default", label: "default（跟随 Codex 默认）", alias: true },
+    { id: "default", label: "GPT-5.5 · gpt-5.5（Codex 默认）", alias: true },
 ];
 let cache = null;
 function cloneClaudeModels() {
@@ -37,15 +37,15 @@ async function probeCodexModels() {
             .sort((a, b) => (a.priority ?? 99) - (b.priority ?? 99));
         if (!visible.length)
             return CODEX_FALLBACK_MODELS.map((m) => ({ ...m }));
+        const defaultModel = visible[0];
+        const defaultLabel = formatCodexModelLabel(defaultModel);
         const result = [
-            { id: "default", label: "default（跟随 Codex 默认）", alias: true },
+            { id: "default", label: `${defaultLabel}（Codex 默认）`, alias: true },
         ];
         for (const m of visible) {
             result.push({
                 id: m.slug,
-                label: m.display_name && m.display_name !== m.slug
-                    ? `${m.display_name} · ${m.slug}`
-                    : m.slug,
+                label: formatCodexModelLabel(m),
             });
         }
         return result;
@@ -54,6 +54,11 @@ async function probeCodexModels() {
         return CODEX_FALLBACK_MODELS.map((m) => ({ ...m }));
     }
 }
+function formatCodexModelLabel(model) {
+    return model.display_name && model.display_name !== model.slug
+        ? `${model.display_name} · ${model.slug}`
+        : model.slug;
+}
 export function getCachedModels() {
     if (!cache) {
         cache = {

package/dist/pidfile.js

@@ -11,7 +11,7 @@
  * - Linux / macOS 使用 Unix domain socket。
  * - Windows 不支持，attach 模式直接跳过；新启的 `wand web` 仍会按老逻辑启动（端口冲突时报错）。
  */
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, chownSync, existsSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 export function pidfilePath(configPath) {
@@ -28,6 +28,7 @@ export function writePidfile(configPath, info) {
     const tmp = `${file}.tmp`;
     writeFileSync(tmp, JSON.stringify(info, null, 2) + "\n", { mode: 0o600 });
     renameSync(tmp, file);
+    applyConfigDirOwnership(file, configPath, 0o600);
 }
 /** 读取并校验。文件不存在 / 损坏 / 进程不在 → 返回 null。 */
 export function readPidfile(configPath) {
@@ -115,3 +116,18 @@ export function readLiveInstance(configPath) {
         return null;
     return info;
 }
+function applyConfigDirOwnership(filePath, configPath, mode) {
+    try {
+        const owner = statSync(path.dirname(configPath));
+        chownSync(filePath, owner.uid, owner.gid);
+    }
+    catch {
+        /* best effort: non-root processes cannot chown, and usually already own the file */
+    }
+    try {
+        chmodSync(filePath, mode);
+    }
+    catch {
+        /* noop */
+    }
+}

package/dist/server-session-routes.js

@@ -4,7 +4,7 @@ import { normalizeMode } from "./config.js";
 import { blockWindowMessagesForTransport, sliceTurnBlocksForTransport, truncateMessagesForTransport, windowMessagesForTransport } from "./message-truncator.js";
 import { checkSessionWorktreeMergeability, cleanupSessionWorktree, getWorktreeMergeErrorCode, mergeSessionWorktree, WorktreeMergeError } from "./git-worktree.js";
 import { resolveSessionCwd } from "./session-cwd.js";
-import { getGitStatus, QuickCommitError, runQuickCommit, runTagHead, runPush, generateCommitMessageOnly, } from "./git-quick-commit.js";
+import { getGitStatus, QuickCommitError, runQuickCommitWithFallback, runTagHead, runPush, generateCommitMessageOnly, } from "./git-quick-commit.js";
 import { getErrorMessage } from "./error-utils.js";
 export { getErrorMessage };
 function getInputErrorResponse(error, sessionId) {
@@ -470,9 +470,13 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
         }
         const body = (req.body ?? {});
         try {
-            const result = await runQuickCommit({
+            const result = await runQuickCommitWithFallback({
                 cwd: snapshot.cwd,
                 language: config.language ?? "",
+                provider: snapshot.provider,
+                model: snapshot.selectedModel ?? snapshot.structuredState?.model ?? config.defaultModel,
+                thinkingEffort: snapshot.thinkingEffort ?? config.defaultThinkingEffort,
+                inheritEnv: config.inheritEnv,
                 autoMessage: body.autoMessage !== false,
                 customMessage: typeof body.customMessage === "string" ? body.customMessage : undefined,
                 tag: typeof body.tag === "string" ? body.tag : undefined,
@@ -502,7 +506,12 @@ export function registerSessionRoutes(app, processes, structured, storage, defau
             return;
         }
         try {
-            const result = await generateCommitMessageOnly(snapshot.cwd, config.language ?? "");
+            const result = await generateCommitMessageOnly(snapshot.cwd, config.language ?? "", {
+                provider: snapshot.provider,
+                model: snapshot.selectedModel ?? snapshot.structuredState?.model ?? config.defaultModel,
+                thinkingEffort: snapshot.thinkingEffort ?? config.defaultThinkingEffort,
+                inheritEnv: config.inheritEnv,
+            });
             res.json(result);
         }
         catch (error) {

package/dist/server.d.ts

@@ -22,4 +22,11 @@ export interface ServerHandle {
     pathRepair: PathRepairResult;
     close(): Promise<void>;
 }
+export declare class PortInUseError extends Error {
+    readonly port: number;
+    readonly host: string;
+    readonly code = "EADDRINUSE";
+    constructor(port: number, host: string);
+}
+export declare function isPortInUseError(error: unknown): error is PortInUseError;
 export declare function startServer(config: WandConfig, configPath: string): Promise<ServerHandle>;

package/dist/server.js

@@ -978,6 +978,23 @@ function streamFileWithRange(req, res, options) {
     });
     stream.pipe(res);
 }
+export class PortInUseError extends Error {
+    port;
+    host;
+    code = "EADDRINUSE";
+    constructor(port, host) {
+        super(`Port ${port} is already in use`);
+        this.port = port;
+        this.host = host;
+        this.name = "PortInUseError";
+    }
+}
+export function isPortInUseError(error) {
+    return error instanceof PortInUseError
+        || (!!error
+            && typeof error === "object"
+            && error.code === "EADDRINUSE");
+}
 export async function startServer(config, configPath) {
     // 关键：在创建 ProcessManager / 任何 spawn 之前先修 PATH。
     // 服务被注册为 systemd / launchd 时，unit 文件里的 PATH 是安装那一刻烧死的，
@@ -2146,6 +2163,11 @@ export async function startServer(config, configPath) {
     });
     const wsManager = new WsBroadcastManager(wss, () => config.cardDefaults ?? {}, useHttps);
     wsManager.setup((id) => structuredSessions.get(id) ?? processes.get(id));
+    wss.on("error", (err) => {
+        if (err.code === "EADDRINUSE")
+            return;
+        wandError("WebSocket 异常", err.message);
+    });
     // Wire process events to WebSocket broadcast
     processes.on("process", (event) => {
         wsManager.emitEvent(event);
@@ -2219,7 +2241,32 @@ export async function startServer(config, configPath) {
     let bindAddr = config.host === "0.0.0.0" ? "0.0.0.0" : config.host;
     const collectedUrls = [];
     await new Promise((resolve, reject) => {
+        const cleanupFailedListen = () => {
+            try {
+                wss.close();
+            }
+            catch { /* noop */ }
+            try {
+                server.close();
+            }
+            catch { /* noop */ }
+            try {
+                storage.close();
+            }
+            catch { /* noop */ }
+        };
+        const onListenError = (err) => {
+            server.off("error", onListenError);
+            cleanupFailedListen();
+            if (err.code === "EADDRINUSE") {
+                reject(new PortInUseError(config.port, config.host));
+                return;
+            }
+            reject(err);
+        };
+        server.once("error", onListenError);
         server.listen(config.port, config.host, () => {
+            server.off("error", onListenError);
             bindAddr = `${config.host}:${config.port}`;
             const scheme = useHttps ? "HTTPS" : "HTTP";
             // 主 URL：本机回环；若绑定 0.0.0.0 再补一个对外提示。
@@ -2232,13 +2279,6 @@ export async function startServer(config, configPath) {
             }
             resolve();
         });
-        server.on("error", (err) => {
-            if (err.code === "EADDRINUSE") {
-                wandError(`端口 ${config.port} 已被占用`, `可能有另一个 Wand 进程正在运行。`, `解决方法（二选一）：\n1. 在浏览器中访问当前运行的 Wand\n2. 或者终止占用端口的进程：\n   kill $(lsof -ti :${config.port})\n\n如果你确定没有其他实例在运行，可能是有程序意外占用了端口。`);
-                process.exit(1);
-            }
-            reject(err);
-        });
     });
     if (!storage.hasCustomPassword() && config.password === "change-me") {
         wandWarn("正在使用默认密码（change-me），任何能访问本机的人都可以登录。", "修改方法：在界面右上角「设置」中修改密码，或运行：node dist/cli.js config:set password <你的新密码>");