@co0ontty/wand 4.72.2 → 4.75.0-beta.g1d477a2

package/dist/process-manager.js

@@ -13,7 +13,7 @@ import { buildChildEnv, isRunningAsRoot } from "./env-utils.js";
 import { buildLanguageDirective, buildManagedAutonomyDirective } from "./language-prompt.js";
 import { prepareSessionWorktree } from "./git-worktree.js";
 import { getProviderCommandSessionId, getProviderResumeCommandSessionId } from "./resume-policy.js";
-import { normalizeThinkingEffort, thinkingEffortToClaudeCliEffort, thinkingEffortToClaudeSlashEffort, thinkingEffortToCodexReasoningEffort, thinkingEffortToOpenCodeVariant, thinkingEffortToPiLevel } from "./structured-provider-common.js";
+import { normalizeThinkingEffort, thinkingEffortToClaudeCliEffort, thinkingEffortToClaudeSlashEffort, thinkingEffortToCodexReasoningEffort, thinkingEffortToGrokEffort, thinkingEffortToPiLevel, thinkingEffortToQoderEffort } from "./structured-provider-common.js";
 import { consumePtyInputForTopic, createPtyTopicLineBuffer, provisionalSessionTopic, SessionTopicCoordinator, sessionTopicBlocklistForSnapshot, shouldAcceptGeneratedSessionTitle, shouldGenerateSessionTopicFromInput, } from "./session-topic.js";
 import { getErrorMessage } from "./error-utils.js";
 import { recordIterationPrompt } from "./iteration-log.js";
@@ -150,6 +150,15 @@ export class SessionInputError extends Error {
         this.name = "SessionInputError";
     }
 }
+/** Write outcome is unknown to the caller; do not record this as accepted input. */
+export class PtyInputDeliveryError extends Error {
+    sessionId;
+    constructor(sessionId, cause) {
+        super("PTY input delivery could not be confirmed.", { cause });
+        this.sessionId = sessionId;
+        this.name = "PtyInputDeliveryError";
+    }
+}
 const REAL_CONVERSATION_MIN_LINES = 2;
 const DISCOVERY_RECENT_WINDOW_MS = 10 * 60 * 1000;
 const START_TIME_SKEW_MS = 30 * 1000;
@@ -736,8 +745,9 @@ export class ProcessManager extends EventEmitter {
         });
     }
     bindTerminalProcess(record, child, onVisibleChunk) {
-        child.onExit(({ exitCode }) => this.handleTerminalExit(record, child, exitCode));
+        child.onResync?.((state) => this.handleTerminalResync(record, child, state));
         child.onData((event) => this.handleTerminalData(record, child, event, onVisibleChunk));
+        child.onExit(({ exitCode }) => this.handleTerminalExit(record, child, exitCode));
         if (record.ptyBridge) {
             record.ptyBridge.setPtyWrite((input) => {
                 if (this.sessions.get(record.id) !== record || record.ptyProcess !== child)
@@ -746,6 +756,31 @@ export class ProcessManager extends EventEmitter {
             });
         }
     }
+    handleTerminalResync(record, child, state) {
+        const current = this.sessions.get(record.id);
+        if (current !== record || current.ptyProcess !== child)
+            return;
+        current.terminalState?.dispose();
+        current.terminalState = restoreTerminalState(state);
+        current.output = state.output;
+        current.storedOutput = state.output;
+        current.ptyOutputSeq = state.seq;
+        current.ptyCols = state.cols;
+        current.ptyRows = state.rows;
+        current.ptyLaunchMarkerToken = state.launchMarkerToken;
+        current.providerShellMarker = state.launchMarkerToken
+            ? new PtyCliExitMarker(state.launchMarkerToken)
+            : null;
+        if (current.ptyBridge)
+            current.messages = current.ptyBridge.getMessages();
+        this.initializeClaudeBridge(current, state.output);
+        current.ptyBridge?.setPtyWrite((input) => {
+            if (this.sessions.get(record.id) === current && current.ptyProcess === child)
+                child.write(input);
+        });
+        this.flushPersist(current, true);
+        this.emitEvent({ type: "resync", sessionId: record.id, data: { reason: "render_replay_gap" } });
+    }
     handleTerminalExit(record, child, exitCode) {
         const current = this.sessions.get(record.id);
         // A stopped session can be resumed under the same public id before the old
@@ -1426,7 +1461,7 @@ export class ProcessManager extends EventEmitter {
         return result;
     }
     getPtyTranscript(id) {
-        return this.logger.readPtyOutput(id);
+        return this.logger.readPtyOutputTail(id);
     }
     /**
      * Set the Claude model for an existing PTY session. Persists the selection
@@ -1483,6 +1518,39 @@ export class ProcessManager extends EventEmitter {
         return this.snapshot(record);
     }
     sendInput(id, input, view, shortcutKey, trackUserInput = true) {
+        const record = this.preparePtyInput(id, input, view, shortcutKey, trackUserInput);
+        record.ptyProcess.write(input);
+        this.persist(record);
+        return this.snapshot(record);
+    }
+    async sendInputConfirmed(id, input, view, shortcutKey, trackUserInput = true) {
+        const record = this.validatePtyInput(id);
+        const terminal = record.ptyProcess;
+        try {
+            if (terminal.writeConfirmed)
+                await terminal.writeConfirmed(input);
+            else
+                terminal.write(input);
+        }
+        catch (cause) {
+            throw new PtyInputDeliveryError(id, cause);
+        }
+        const current = this.sessions.get(id);
+        if (current !== record || record.ptyProcess !== terminal) {
+            // The write reached an old PTY, but the caller cannot treat it as input
+            // accepted by the current incarnation or persist the stale record.
+            throw new PtyInputDeliveryError(id, new Error("PTY incarnation changed during write"));
+        }
+        this.trackPtyInput(record, input, view, shortcutKey, trackUserInput);
+        this.persist(record);
+        return this.snapshot(record);
+    }
+    preparePtyInput(id, input, view, shortcutKey, trackUserInput = true) {
+        const record = this.validatePtyInput(id);
+        this.trackPtyInput(record, input, view, shortcutKey, trackUserInput);
+        return record;
+    }
+    validatePtyInput(id) {
         if (this.disposed)
             throw new Error("ProcessManager has been disposed.");
         const record = this.mustGet(id);
@@ -1495,6 +1563,10 @@ export class ProcessManager extends EventEmitter {
             console.error(`[ProcessManager] Rejecting input: session ${id} has no PTY`);
             throw new SessionInputError("Session is not running.", "SESSION_NO_PTY", id, record.status);
         }
+        return record;
+    }
+    trackPtyInput(record, input, view, shortcutKey, trackUserInput = true) {
+        const id = record.id;
         if (!record.ptyTopicDraft)
             record.ptyTopicDraft = createPtyTopicLineBuffer();
         const topicInput = consumePtyInputForTopic(record.ptyTopicDraft, input, view, shortcutKey);
@@ -1516,9 +1588,6 @@ export class ProcessManager extends EventEmitter {
         if (record.ptyBridge && trackUserInput) {
             record.ptyBridge.onUserInput(input);
         }
-        record.ptyProcess.write(input);
-        this.persist(record);
-        return this.snapshot(record);
     }
     resize(id, cols, rows) {
         const record = this.mustGet(id);
@@ -1553,6 +1622,14 @@ export class ProcessManager extends EventEmitter {
         }
         return record.terminalState.snapshot();
     }
+    async getTerminalHistoryPage(id, before, revision) {
+        const record = this.sessions.get(id);
+        if (!record)
+            return null;
+        if (!record.terminalState)
+            this.getTerminalState(id);
+        return record.terminalState?.historyPage(before, revision) ?? null;
+    }
     /**
      * Finalize provider-only state while leaving the owning PTY shell alive. The
      * session itself remains running so terminal input can continue normally.
@@ -2405,7 +2482,7 @@ export class ProcessManager extends EventEmitter {
             if (trimmedModel && trimmedModel !== "default" && !/--model(?:\s|=)/.test(result) && !/(?:^|\s)-m(?:\s|$)/.test(result)) {
                 result += ` --model '${trimmedModel.replace(/'/g, "'\\''")}'`;
             }
-            const effort = thinkingEffortToOpenCodeVariant(thinkingEffort ?? null);
+            const effort = thinkingEffortToGrokEffort(thinkingEffort ?? null);
             if (effort && !/--(?:reasoning-)?effort(?:\s|=)/.test(result)) {
                 result += ` --effort '${effort.replace(/'/g, "'\\''")}'`;
             }
@@ -2425,6 +2502,10 @@ export class ProcessManager extends EventEmitter {
             if (!/--(?:yolo|dangerously-skip-permissions|permission-mode)(?:\s|=|$)/.test(result)) {
                 result += " --permission-mode bypass_permissions";
             }
+            const qoderEffort = thinkingEffortToQoderEffort(thinkingEffort ?? null);
+            if (qoderEffort && !/--reasoning-effort(?:\s|=)/.test(result)) {
+                result += ` --reasoning-effort '${qoderEffort.replace(/'/g, "'\\''")}'`;
+            }
             return result;
         }
         if (provider === "pi") {

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

@@ -12,7 +12,19 @@ export interface PtyTerminalSnapshot {
     cols: number;
     rows: number;
     pending: PtyTerminalOperation[];
+    /** Web scrollback cursor, absent from the Render wire protocol. */
+    historyBefore?: number;
+    historyRevision?: number;
 }
+export interface PtyHistoryPage {
+    data: string;
+    separator: string;
+    start: number;
+    before: number;
+    revision: number;
+}
+export declare const PTY_INITIAL_HISTORY_ROWS = 80;
+export declare const PTY_HISTORY_PAGE_ROWS = 80;
 /**
  * Server-side xterm screen model used only for reconnect snapshots. Live PTY
  * bytes still travel unchanged from node-pty to the browser terminal.
@@ -31,11 +43,16 @@ export declare class PtyTerminalState {
     private committedData;
     private committedCols;
     private committedRows;
+    private committedHistoryBefore;
+    private committedRevision;
+    private revision;
     private disposed;
     constructor(cols: number, rows: number, initialData?: string);
     write(data: string): void;
     resize(cols: number, rows: number): void;
     snapshot(): PtyTerminalSnapshot;
+    /** A bounded ANSI range preceding the committed baseline, never a cumulative snapshot. */
+    historyPage(before: number, revision: number, limit?: number): Promise<PtyHistoryPage | null>;
     dispose(): void;
     private addPending;
     private scheduleFlush;

package/dist/pty-terminal-state.js

@@ -2,6 +2,10 @@ import headless from "@xterm/headless";
 import { SerializeAddon } from "@xterm/addon-serialize";
 import { Unicode11Addon } from "@xterm/addon-unicode11";
 const { Terminal } = headless;
+export const PTY_INITIAL_HISTORY_ROWS = 80;
+const PTY_INITIAL_HISTORY_MAX_BYTES = 256 * 1024;
+export const PTY_HISTORY_PAGE_ROWS = 80;
+const PTY_HISTORY_PAGE_MAX_BYTES = 192 * 1024;
 /**
  * Incoming PTY chunks are coalesced into one xterm write per flush. xterm's
  * write callback costs a timer turn per call, so one write per node-pty chunk
@@ -63,6 +67,9 @@ export class PtyTerminalState {
     committedData = "";
     committedCols;
     committedRows;
+    committedHistoryBefore = 0;
+    committedRevision = 0;
+    revision = 0;
     disposed = false;
     constructor(cols, rows, initialData = "") {
         this.committedCols = cols;
@@ -77,6 +84,7 @@ export class PtyTerminalState {
     write(data) {
         if (this.disposed || !data)
             return;
+        this.revision++;
         this.buffered += data;
         if (this.buffered.length >= WRITE_BATCH_MAX_CHARS)
             this.flushBuffered();
@@ -86,6 +94,7 @@ export class PtyTerminalState {
     resize(cols, rows) {
         if (this.disposed)
             return;
+        this.revision++;
         // Bytes that arrived before the resize must land before it.
         this.flushBuffered();
         this.addPending({ type: "resize", cols, rows });
@@ -105,6 +114,37 @@ export class PtyTerminalState {
             cols: this.committedCols,
             rows: this.committedRows,
             pending: coalesceOperations(this.pending),
+            historyBefore: this.committedHistoryBefore,
+            historyRevision: this.committedRevision,
+        };
+    }
+    /** A bounded ANSI range preceding the committed baseline, never a cumulative snapshot. */
+    async historyPage(before, revision, limit = PTY_HISTORY_PAGE_ROWS) {
+        if (this.disposed || !Number.isSafeInteger(before) || !Number.isSafeInteger(revision)
+            || !Number.isSafeInteger(limit) || limit < 1 || limit > PTY_HISTORY_PAGE_ROWS)
+            return null;
+        // Wait for buffered writes/checkpoints. If output or resize changed the row indices,
+        // the caller must resync rather than concatenate unrelated lines.
+        await this.tail;
+        if (this.revision !== revision || before > this.committedHistoryBefore || before <= 0)
+            return null;
+        const count = Math.min(before, limit);
+        let start = before - count;
+        let data = "";
+        while (start < before) {
+            data = this.serializer.serialize({ range: { start, end: before - 1 } });
+            if (Buffer.byteLength(data, "utf8") <= PTY_HISTORY_PAGE_MAX_BYTES)
+                break;
+            if (start === before - 1)
+                return null;
+            start = Math.min(before - 1, start + Math.max(1, Math.ceil((before - start) / 2)));
+        }
+        return {
+            data,
+            separator: this.terminal.buffer.normal.getLine(before)?.isWrapped ? "" : "\r\n",
+            start,
+            before,
+            revision,
         };
     }
     dispose() {
@@ -186,14 +226,24 @@ export class PtyTerminalState {
         const cutoff = this.pending.at(-1)?.id ?? 0;
         if (!cutoff)
             return;
+        const revision = this.revision;
         this.checkpointQueued = true;
         this.tail = this.tail.then(() => {
             if (this.disposed)
                 return;
             try {
-                this.committedData = this.serializer.serialize({ scrollback: 5000 });
+                let historyRows = PTY_INITIAL_HISTORY_ROWS;
+                this.committedData = this.serializer.serialize({ scrollback: historyRows });
+                while (historyRows > 0 && Buffer.byteLength(this.committedData) > PTY_INITIAL_HISTORY_MAX_BYTES) {
+                    historyRows = Math.floor(historyRows / 2);
+                    this.committedData = this.serializer.serialize({ scrollback: historyRows });
+                }
                 this.committedCols = this.terminal.cols;
                 this.committedRows = this.terminal.rows;
+                this.committedHistoryBefore = Math.max(0, this.terminal.buffer.normal.baseY - historyRows);
+                // A newer write can arrive while the queued checkpoint drains. Only the
+                // operations through cutoff are represented by this baseline.
+                this.committedRevision = revision;
                 this.pending = this.pending.filter((entry) => entry.id > cutoff);
             }
             catch {

package/dist/render-binary.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 支持的分发三元组。
+ *
+ * 与 `render-bin/manifest.json` 的版本条目键、`render/release.json` 的
+ * `supportedTriples` 必须一致；新增平台要同时改这三处与 CI 矩阵。
+ */
+export declare const SUPPORTED_RENDER_TRIPLES: readonly ["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"];
+/** `uname -m` 的输出归一成 Node 的 arch 名；认不出返回 null（调用方回退 process.arch）。 */
+export declare function normalizeMachineArch(machine: string | null | undefined): string | null;
+/**
+ * 平台三元组（`darwin-arm64` 等）。
+ *
+ * 为什么不直接用 `process.arch`：macOS 上 Node 跑在 Rosetta 里时它报 `x64`，
+ * 而机器其实是 arm64 —— 于是会去找一个不存在（或架构不符）的产物，最后表现成
+ * 「自动模式下 Rust 引擎莫名其妙不生效」。`uname -m` 才反映真实硬件；只有
+ * `uname` 不可用（PATH 被清空、Windows）时才回退 `process.arch`。
+ *
+ * `rosettaTranslated` 是反向兜底：翻译态下 `uname -m` 同样报 `x86_64`，
+ * 只有 `sysctl.proc_translated` 能说明「这个 x64 进程跑在 arm64 机器上」。
+ * 少了它，上面那条规则在它最该生效的场景里形同虚设。
+ */
+export declare function resolveRenderTriple(platform: string, nodeArch: string, unameMachine: string | null, rosettaTranslated?: boolean): string;
+interface PlatformArchProbe {
+    unameMachine: string | null;
+    rosettaTranslated: boolean;
+}
+/**
+ * 真实架构探测（进程级缓存）：`resolveRenderBinaryPath` 在一次启动里会被调用多次，
+ * 不该每次都 spawn 两个进程。
+ */
+export declare function probePlatformArch(): PlatformArchProbe;
+/** 当前进程应使用的三元组。 */
+export declare function currentRenderTriple(): string;
+/**
+ * 约定候选路径（不含 `WAND_RENDER_BIN` 与 `PATH`，调用方单独处理）。
+ *
+ * 顺序刻意把「刚 cargo build 出来的」排在分发位置之前：开发机上调 Rust 引擎时
+ * 期望立刻生效，而不是被上一次安装的旧二进制盖住。
+ *
+ * 旧布局（`wand-rs/`、仓库根 `native/`）已不存在，候选里不留兼容分支：
+ * 留着只会让「引擎没生效」这类问题多一个静默的假来源。
+ */
+export declare function renderBinaryCandidates(configDir: string, triple: string): string[];
+/**
+ * 解析 wand-render 可执行文件。
+ *
+ * 顺序：`WAND_RENDER_BIN` → `<repo>/render/target/{release,debug}` → `<configDir>/bin`
+ * → `<repo>/dist/native/<triple>` → `PATH`。返回 null 表示「这台机器没有」，由调用方
+ * 按 engine 决定告警还是报错。
+ */
+export declare function resolveRenderBinaryPath(configPath: string): string | null;
+/**
+ * 读取 wand-render 的版本。
+ *
+ * 先读二进制旁边的 `wand-render.version` sidecar（就位脚本会写），读不到才去跑
+ * `wand-render --version` —— 启动路径上不该无谓地执行一个进程。
+ * 两种方式都失败时返回 null：调用方只要一个展示用版本号，拿不到不能影响启动。
+ */
+export declare function readRenderBinaryVersion(binaryPath: string): Promise<string | null>;
+export declare function isExecutableFile(candidate: string): boolean;
+export {};

package/dist/render-binary.js

@@ -0,0 +1,204 @@
+import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
+import { execFile, spawnSync } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+/** 仓库根：src/ 与 dist/ 都在根下一层，所以两种运行方式解析结果一致。 */
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const VERSION_PROBE_TIMEOUT_MS = 2_000;
+const ARCH_PROBE_TIMEOUT_MS = 1_000;
+/**
+ * 支持的分发三元组。
+ *
+ * 与 `render-bin/manifest.json` 的版本条目键、`render/release.json` 的
+ * `supportedTriples` 必须一致；新增平台要同时改这三处与 CI 矩阵。
+ */
+export const SUPPORTED_RENDER_TRIPLES = ["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"];
+/** `uname -m` 的架构别名 → Node 的 `process.arch` 命名（两个生态叫法不同）。 */
+const MACHINE_ARCH_ALIASES = {
+    arm64: "arm64",
+    aarch64: "arm64",
+    x86_64: "x64",
+    amd64: "x64",
+    x64: "x64",
+};
+/** `uname -m` 的输出归一成 Node 的 arch 名；认不出返回 null（调用方回退 process.arch）。 */
+export function normalizeMachineArch(machine) {
+    if (typeof machine !== "string")
+        return null;
+    return MACHINE_ARCH_ALIASES[machine.trim().toLowerCase()] ?? null;
+}
+/**
+ * 平台三元组（`darwin-arm64` 等）。
+ *
+ * 为什么不直接用 `process.arch`：macOS 上 Node 跑在 Rosetta 里时它报 `x64`，
+ * 而机器其实是 arm64 —— 于是会去找一个不存在（或架构不符）的产物，最后表现成
+ * 「自动模式下 Rust 引擎莫名其妙不生效」。`uname -m` 才反映真实硬件；只有
+ * `uname` 不可用（PATH 被清空、Windows）时才回退 `process.arch`。
+ *
+ * `rosettaTranslated` 是反向兜底：翻译态下 `uname -m` 同样报 `x86_64`，
+ * 只有 `sysctl.proc_translated` 能说明「这个 x64 进程跑在 arm64 机器上」。
+ * 少了它，上面那条规则在它最该生效的场景里形同虚设。
+ */
+export function resolveRenderTriple(platform, nodeArch, unameMachine, rosettaTranslated = false) {
+    let arch = normalizeMachineArch(unameMachine) ?? nodeArch;
+    if (platform === "darwin" && arch === "x64" && rosettaTranslated)
+        arch = "arm64";
+    return `${platform}-${arch}`;
+}
+let cachedPlatformArchProbe = null;
+/**
+ * 真实架构探测（进程级缓存）：`resolveRenderBinaryPath` 在一次启动里会被调用多次，
+ * 不该每次都 spawn 两个进程。
+ */
+export function probePlatformArch() {
+    if (!cachedPlatformArchProbe) {
+        cachedPlatformArchProbe = {
+            unameMachine: runUnameMachine(),
+            rosettaTranslated: isRosettaTranslated(),
+        };
+    }
+    return cachedPlatformArchProbe;
+}
+/** 当前进程应使用的三元组。 */
+export function currentRenderTriple() {
+    const probe = probePlatformArch();
+    return resolveRenderTriple(process.platform, process.arch, probe.unameMachine, probe.rosettaTranslated);
+}
+function runUnameMachine() {
+    if (process.platform === "win32")
+        return null;
+    try {
+        const result = spawnSync("uname", ["-m"], {
+            encoding: "utf8",
+            timeout: ARCH_PROBE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (result.error || result.status !== 0)
+            return null;
+        return (result.stdout ?? "").trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `sysctl.proc_translated` == 1 表示当前进程被 Rosetta 翻译（只在 darwin 上有意义）。 */
+function isRosettaTranslated() {
+    if (process.platform !== "darwin")
+        return false;
+    try {
+        const result = spawnSync("sysctl", ["-n", "sysctl.proc_translated"], {
+            encoding: "utf8",
+            timeout: ARCH_PROBE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (result.error || result.status !== 0)
+            return false;
+        return (result.stdout ?? "").trim() === "1";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 约定候选路径（不含 `WAND_RENDER_BIN` 与 `PATH`，调用方单独处理）。
+ *
+ * 顺序刻意把「刚 cargo build 出来的」排在分发位置之前：开发机上调 Rust 引擎时
+ * 期望立刻生效，而不是被上一次安装的旧二进制盖住。
+ *
+ * 旧布局（`wand-rs/`、仓库根 `native/`）已不存在，候选里不留兼容分支：
+ * 留着只会让「引擎没生效」这类问题多一个静默的假来源。
+ */
+export function renderBinaryCandidates(configDir, triple) {
+    const binaryName = process.platform === "win32" ? "wand-render.exe" : "wand-render";
+    return [
+        path.join(REPO_ROOT, "render", "target", "release", binaryName),
+        path.join(REPO_ROOT, "render", "target", "debug", binaryName),
+        path.join(configDir, "bin", binaryName),
+        // npm 包内嵌的正式位置：scripts/stage-render-binaries.js 把 render-bin 的产物写在这里，
+        // dist/ 在 package.json 的 files 里，所以全局安装后也有二进制。
+        path.join(REPO_ROOT, "dist", "native", triple, binaryName),
+    ];
+}
+/**
+ * 解析 wand-render 可执行文件。
+ *
+ * 顺序：`WAND_RENDER_BIN` → `<repo>/render/target/{release,debug}` → `<configDir>/bin`
+ * → `<repo>/dist/native/<triple>` → `PATH`。返回 null 表示「这台机器没有」，由调用方
+ * 按 engine 决定告警还是报错。
+ */
+export function resolveRenderBinaryPath(configPath) {
+    const binaryName = process.platform === "win32" ? "wand-render.exe" : "wand-render";
+    const fromEnv = process.env.WAND_RENDER_BIN?.trim();
+    if (fromEnv) {
+        if (isExecutableFile(fromEnv))
+            return fromEnv;
+        // 显式配置但不存在属于配置错误，必须可见，不能静默滑到仓库构建产物。
+        process.stderr.write(`[wand] WAND_RENDER_BIN points at ${fromEnv}, which is not an executable file; falling back to discovery.\n`);
+    }
+    const configDir = path.dirname(path.resolve(configPath));
+    const triple = currentRenderTriple();
+    for (const candidate of renderBinaryCandidates(configDir, triple)) {
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, binaryName);
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * 读取 wand-render 的版本。
+ *
+ * 先读二进制旁边的 `wand-render.version` sidecar（就位脚本会写），读不到才去跑
+ * `wand-render --version` —— 启动路径上不该无谓地执行一个进程。
+ * 两种方式都失败时返回 null：调用方只要一个展示用版本号，拿不到不能影响启动。
+ */
+export function readRenderBinaryVersion(binaryPath) {
+    const sidecar = readVersionSidecar(binaryPath);
+    if (sidecar)
+        return Promise.resolve(sidecar);
+    return new Promise((resolve) => {
+        execFile(binaryPath, ["--version"], { timeout: VERSION_PROBE_TIMEOUT_MS }, (error, stdout) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            const firstLine = stdout.split("\n").map((line) => line.trim()).find((line) => line.length > 0) ?? "";
+            const version = /(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.]+)?)/.exec(firstLine);
+            resolve(version ? version[1] : null);
+        });
+    });
+}
+function readVersionSidecar(binaryPath) {
+    try {
+        const raw = readFileSync(path.join(path.dirname(binaryPath), "wand-render.version"), "utf8").trim();
+        const version = /^(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.]+)?)$/.exec(raw);
+        return version ? version[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function isExecutableFile(candidate) {
+    try {
+        if (!existsSync(candidate) || !statSync(candidate).isFile())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    if (process.platform === "win32")
+        return true;
+    try {
+        accessSync(candidate, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}