@co0ontty/wand 4.72.2 → 4.73.0

package/dist/render-host.d.ts

@@ -0,0 +1,64 @@
+import { type RenderDaemonClient } from "./render-daemon-client.js";
+import { TerminalDaemonClient } from "./terminal-daemon-client.js";
+import { type TerminalAttachResult, type TerminalHost, type TerminalSpawnRequest } from "./terminal-host.js";
+import type { RenderEngine } from "./types.js";
+export interface RenderHostOptions {
+    /** 配置里显式指定的引擎；环境变量 WAND_RENDER_ENGINE 优先。 */
+    engine?: RenderEngine;
+    /** 配置里显式指定的二进制路径。 */
+    binaryPath?: string;
+    /** DB 中仍在运行的 PTY，用于旧版 Render 的超大 list 失败时逐个 attach。 */
+    knownSessionIds?: readonly string[];
+}
+export interface UpgradeAwareTerminalHost {
+    host: TerminalHost;
+    renderHost: TerminalHost | null;
+    legacyHost: TerminalDaemonClient | null;
+}
+export interface RoutedTerminalHosts {
+    legacy: TerminalHost | null;
+    render: TerminalHost;
+}
+/**
+ * 升级期无损路由：旧会话留在 legacy terminald，新会话一律进 Render。
+ * MIGRATION-COMPAT: 旧 PTY/Render v1 路由须保留到用户另行要求删除；
+ * 不能因为新 Render 负责新会话就杀掉或丢弃旧 owner。
+ *
+ * 所有权判断只能靠 legacy 自己的 inventory —— Server 无法从 DB 倒推
+ * 「这个 PTY 现在归谁」，因为升级前建的会话进程就在旧 daemon 里。
+ */
+export declare class CompositeTerminalHost implements TerminalHost {
+    readonly persistent = true;
+    private readonly legacy;
+    private readonly render;
+    constructor(hosts: RoutedTerminalHosts);
+    attach(sessionId: string, afterSeq?: number): TerminalAttachResult | null;
+    createOrAttach(request: TerminalSpawnRequest, afterSeq?: number): Promise<TerminalAttachResult>;
+    forget(sessionId: string): void;
+    /**
+     * 两侧都只是解绑：legacy daemon 可能还持有升级前的旧 PTY，Render 更是必须
+     * 跨 Server 重启继续活着。**这里绝不能 kill 任何东西。**
+     */
+    disconnect(): void;
+    /**
+     * legacy 查询失败（socket 抖动）时按「不属于它」处理：宁可让 Render 侧查一遍，
+     * 也不能在会话恢复路径上抛异常 —— 那会让服务器重启后旧会话全部恢复失败。
+     */
+    private attachFromLegacy;
+    private legacyOwns;
+}
+/** 环境变量优先于 config；非法值忽略并告警。 */
+export declare function resolveRenderEngine(envValue: string | undefined, configEngine: RenderEngine | undefined): RenderEngine;
+export declare function createUpgradeAwareTerminalHost(configPath: string, options?: RenderHostOptions): Promise<UpgradeAwareTerminalHost>;
+/**
+ * adopt 已存在的 Render，不存在则 spawn 后等待就绪。
+ *
+ * 协议（docs/render-protocol.md §6）：pid 活着但 socket 不可用 → 等待就绪，
+ * 不另起第二个 daemon；协议版本不符 → 明确抛错，**不做降级运行**。
+ */
+export declare function createRenderTerminalHost(configPath: string, options?: {
+    binaryPath?: string;
+    knownSessionIds?: readonly string[];
+}): Promise<RenderDaemonClient>;
+/** detached spawn（stdio 忽略、unref），并等 socket + token 就绪。 */
+export declare function spawnDetachedRender(configPath: string, binaryPath: string, knownSessionIds?: readonly string[]): Promise<RenderDaemonClient>;

package/dist/render-host.js

@@ -0,0 +1,301 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import net from "node:net";
+import process from "node:process";
+import { getErrorMessage } from "./error-utils.js";
+import { isExecutableFile, readRenderBinaryVersion, resolveRenderBinaryPath } from "./render-binary.js";
+import { connectExistingRenderClient } from "./render-daemon-client.js";
+import { renderPaths } from "./render-protocol.js";
+import { connectExistingTerminalHost, createTerminalHost, TerminalDaemonClient } from "./terminal-daemon-client.js";
+import { InProcessTerminalHost, } from "./terminal-host.js";
+/** Render 的 socket/token 就绪等待窗口，与 legacy daemon 保持一致。 */
+const RENDER_READY_TIMEOUT_MS = 5_000;
+/**
+ * 升级期无损路由：旧会话留在 legacy terminald，新会话一律进 Render。
+ * MIGRATION-COMPAT: 旧 PTY/Render v1 路由须保留到用户另行要求删除；
+ * 不能因为新 Render 负责新会话就杀掉或丢弃旧 owner。
+ *
+ * 所有权判断只能靠 legacy 自己的 inventory —— Server 无法从 DB 倒推
+ * 「这个 PTY 现在归谁」，因为升级前建的会话进程就在旧 daemon 里。
+ */
+export class CompositeTerminalHost {
+    persistent = true;
+    legacy;
+    render;
+    constructor(hosts) {
+        this.legacy = hosts.legacy;
+        this.render = hosts.render;
+    }
+    attach(sessionId, afterSeq = 0) {
+        // legacy 命中就直接用；返回 null 说明这条会话不属于它（新会话在 Render）。
+        const fromLegacy = this.attachFromLegacy(sessionId, afterSeq);
+        if (fromLegacy)
+            return fromLegacy;
+        return this.render.attach(sessionId, afterSeq);
+    }
+    async createOrAttach(request, afterSeq = 0) {
+        if (this.legacyOwns(request.sessionId)) {
+            return this.legacy.createOrAttach(request, afterSeq);
+        }
+        return this.render.createOrAttach(request, afterSeq);
+    }
+    forget(sessionId) {
+        this.legacy?.forget(sessionId);
+        this.render.forget(sessionId);
+    }
+    /**
+     * 两侧都只是解绑：legacy daemon 可能还持有升级前的旧 PTY，Render 更是必须
+     * 跨 Server 重启继续活着。**这里绝不能 kill 任何东西。**
+     */
+    disconnect() {
+        this.legacy?.disconnect();
+        this.render.disconnect();
+    }
+    /**
+     * legacy 查询失败（socket 抖动）时按「不属于它」处理：宁可让 Render 侧查一遍，
+     * 也不能在会话恢复路径上抛异常 —— 那会让服务器重启后旧会话全部恢复失败。
+     */
+    attachFromLegacy(sessionId, afterSeq) {
+        if (!this.legacy)
+            return null;
+        try {
+            return this.legacy.attach(sessionId, afterSeq) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    legacyOwns(sessionId) {
+        if (!this.legacy)
+            return false;
+        try {
+            return this.legacy.attach(sessionId) !== null;
+        }
+        catch {
+            // 查询失败按「不属于 legacy」处理：宁可让 Render 建新会话，也不要把请求丢进坏掉的 daemon。
+            return false;
+        }
+    }
+}
+/** 环境变量优先于 config；非法值忽略并告警。 */
+export function resolveRenderEngine(envValue, configEngine) {
+    const raw = (envValue ?? "").trim().toLowerCase();
+    if (raw) {
+        if (raw === "rust" || raw === "legacy" || raw === "auto")
+            return raw;
+        process.stderr.write(`[wand] WAND_RENDER_ENGINE=${envValue} is invalid (expected rust|legacy|auto); ignoring it.\n`);
+    }
+    return configEngine === "rust" || configEngine === "legacy" ? configEngine : "auto";
+}
+export async function createUpgradeAwareTerminalHost(configPath, options = {}) {
+    if (process.env.WAND_TEST_MODE === "1" || process.env.NODE_TEST_CONTEXT) {
+        // 与 legacy 缝隙一致：测试进程不拉起任何常驻 daemon。
+        return { host: new InProcessTerminalHost(), renderHost: null, legacyHost: null };
+    }
+    const engine = resolveRenderEngine(process.env.WAND_RENDER_ENGINE, options.engine);
+    // engine=legacy 等价于当前行为：adopt 已有 terminald，不存在才 spawn。
+    if (engine === "legacy") {
+        const legacy = await createTerminalHost(configPath);
+        return { host: legacy, renderHost: null, legacyHost: asTerminalDaemonClient(legacy) };
+    }
+    // 先 adopt 升级前的 terminald，以它的 inventory 判定旧 PTY 的 owner。
+    const legacy = await connectExistingTerminalHost(configPath);
+    const configuredBinary = options.binaryPath?.trim();
+    const binaryPath = configuredBinary || resolveRenderBinaryPath(configPath);
+    if (!binaryPath) {
+        if (engine === "rust") {
+            throw new Error("render.engine=rust but no wand-render binary was found (checked WAND_RENDER_BIN, render/target/{release,debug}, " +
+                "<configDir>/bin, dist/native/<platform>-<arch>, PATH). " +
+                "Build it with `npm run build:render-native` (cargo build --release in render/), " +
+                "or set render.engine=auto/legacy to fall back.");
+        }
+        process.stderr.write("[wand] WARNING: render.engine=auto but no wand-render binary was found; PTYs stay on the legacy terminald. " +
+            "Build it with `npm run build:render-native`, stage a published build with `npm run build:render-bin`, or set WAND_RENDER_BIN.\n");
+        const fallback = legacy ?? await createTerminalHost(configPath);
+        return { host: fallback, renderHost: null, legacyHost: asTerminalDaemonClient(fallback) };
+    }
+    if (configuredBinary && !isExecutableFile(configuredBinary)) {
+        // 显式配置指向不可执行文件属于配置错误，静默回退 legacy 会让人以为 Rust 引擎在跑。
+        throw new Error(`render.binaryPath points at ${configuredBinary}, which is not an executable file.`);
+    }
+    let render;
+    try {
+        render = await createRenderTerminalHost(configPath, {
+            binaryPath,
+            knownSessionIds: options.knownSessionIds,
+        });
+    }
+    catch (error) {
+        if (engine === "rust")
+            throw error;
+        // auto 模式下把失败讲清楚再回退：这种情况用户最需要知道 Rust 引擎没生效。
+        process.stderr.write(`[wand] WARNING: render.engine=auto could not bring up Render (${getErrorMessage(error)}); falling back to the legacy terminald.\n`);
+        const fallback = legacy ?? await createTerminalHost(configPath);
+        return { host: fallback, renderHost: null, legacyHost: asTerminalDaemonClient(fallback) };
+    }
+    // MIGRATION-COMPAT: Render v1 only owns PTYs. Keep terminald as the owner
+    // of existing structured runs during the v2 migration, even if new runs
+    // eventually use Rust. Remove this path only on a later explicit request.
+    // Structured CLI runs still need a daemon-backed host to survive a web restart,
+    // including on a fresh installation where no
+    // pre-upgrade terminald exists. The composite routes new PTYs to Render.
+    let structuredHost;
+    try {
+        const daemon = legacy ?? await createTerminalHost(configPath);
+        const client = asTerminalDaemonClient(daemon);
+        if (!client)
+            throw new Error("A persistent terminal daemon is required for structured CLI runs.");
+        structuredHost = client;
+    }
+    catch (error) {
+        render.disconnect();
+        throw error;
+    }
+    const version = await readRenderBinaryVersion(binaryPath);
+    process.stderr.write(`[wand] Render engine active (${version ? `wand-render ${version}` : "version unknown"}, ${binaryPath}); ` +
+        "terminald available for structured CLI runs and pre-upgrade PTYs.\n");
+    return {
+        host: new CompositeTerminalHost({ legacy: structuredHost, render }),
+        renderHost: render,
+        legacyHost: structuredHost,
+    };
+}
+/**
+ * adopt 已存在的 Render，不存在则 spawn 后等待就绪。
+ *
+ * 协议（docs/render-protocol.md §6）：pid 活着但 socket 不可用 → 等待就绪，
+ * 不另起第二个 daemon；协议版本不符 → 明确抛错，**不做降级运行**。
+ */
+export async function createRenderTerminalHost(configPath, options = {}) {
+    const paths = renderPaths(configPath);
+    const endpointExists = process.platform !== "win32" && existsSync(paths.socketPath);
+    if (endpointExists) {
+        const adopted = await connectExistingRenderClient(configPath, options.knownSessionIds);
+        if (adopted)
+            return adopted;
+        if (await isSocketListening(paths.socketPath)) {
+            // 有人监听却拒绝 adopt（协议版本不符 / token 不符）：这是错误配置，必须报出来而不是绕开。
+            const starting = await waitForRender(configPath, RENDER_READY_TIMEOUT_MS, options.knownSessionIds);
+            if (starting)
+                return starting;
+            throw new Error(`A Render daemon is listening on ${paths.socketPath} but rejected adoption. Refusing to spawn a competing Render; ` +
+                "check the protocol version/token of the running binary, or stop it first.");
+        }
+        // 没人在监听，且没有活着的 pid = 上一次 renderd 崩溃留下的孤儿 socket 文件。
+        // 清掉它再 spawn，否则会永久卡在「等一个永远不会就绪的 socket」。
+        if (readLiveRenderPid(paths.pidPath) === null) {
+            try {
+                unlinkSync(paths.socketPath);
+            }
+            catch { /* 已被别处清掉即可 */ }
+        }
+    }
+    // 进程活着但 socket 还没就绪（启动竞态 / 正在 drain）：等它就绪，
+    // 绝不另起第二个 daemon（协议 §6 single instance）。
+    const livePid = readLiveRenderPid(paths.pidPath);
+    if (livePid !== null) {
+        const starting = await waitForRender(configPath, RENDER_READY_TIMEOUT_MS, options.knownSessionIds);
+        if (starting)
+            return starting;
+        throw new Error(`Render process ${livePid} is alive but its socket ${paths.socketPath} is unavailable; refusing to spawn a second daemon.`);
+    }
+    const binaryPath = options.binaryPath ?? resolveRenderBinaryPath(configPath);
+    if (!binaryPath)
+        throw new Error("wand-render binary is required to start Render");
+    return spawnDetachedRender(configPath, binaryPath, options.knownSessionIds);
+}
+/** detached spawn（stdio 忽略、unref），并等 socket + token 就绪。 */
+export async function spawnDetachedRender(configPath, binaryPath, knownSessionIds) {
+    const paths = renderPaths(configPath);
+    // `-c <configPath>` 是按 config 隔离的既定约定（docs/render-protocol.md §6）：
+    // socket / token / pid / meta 全部由它派生。
+    const child = spawn(binaryPath, ["-c", configPath], {
+        detached: true,
+        stdio: "ignore",
+        cwd: process.cwd(),
+        env: process.env,
+    });
+    child.on("error", (error) => {
+        process.stderr.write(`[wand] Failed to spawn wand-render: ${getErrorMessage(error)}\n`);
+    });
+    child.unref();
+    const client = await waitForRender(configPath, RENDER_READY_TIMEOUT_MS, knownSessionIds);
+    if (!client) {
+        // 自己生的进程自己收：就位超时（选错了二进制、二进制是 stub、或者它卡在启动）
+        // 时如果不回收，就会留下一个永久孤儿 daemon —— 它占着 socket 名字、下次启动会被
+        // 当成「活着但不接受领养」而直接阻塞启动。收尾是 best-effort，失败不影响报错。
+        reapUnreadyRender(child.pid);
+        throw new Error(`Spawned ${binaryPath} but its socket/token (${paths.socketPath}) did not become ready within ${RENDER_READY_TIMEOUT_MS}ms.`);
+    }
+    return client;
+}
+async function waitForRender(configPath, timeoutMs, knownSessionIds) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const client = await connectExistingRenderClient(configPath, knownSessionIds);
+        if (client)
+            return client;
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    return null;
+}
+/**
+ * 回收一个「已 spawn 但始终没就绪」的 Render 进程。
+ *
+ * 不回收会留下孤儿 daemon：它占着按 config 派生的 socket 名字，下次启动会被判成
+ * 「进程活着但 socket 不可达」，于是启动直接失败而不是重建 —— 一个失败的启动不该
+ * 破坏后续所有启动。先 SIGTERM 给它清理 socket/token 的机会，短暂等待后 SIGKILL。
+ */
+function reapUnreadyRender(pid) {
+    if (typeof pid !== "number" || pid <= 0)
+        return;
+    const signal = (name) => {
+        try {
+            process.kill(pid, name);
+        }
+        catch { /* 已经退出 */ }
+    };
+    signal("SIGTERM");
+    const timer = setTimeout(() => signal("SIGKILL"), 500);
+    timer.unref?.();
+}
+/** 对端是否真的在监听：区分「活着但拒绝 adopt」与「上一轮崩溃留下的孤儿 socket 文件」。 */ function isSocketListening(socketPath) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection(socketPath);
+        let settled = false;
+        const finish = (alive) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(alive);
+        };
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+        const timer = setTimeout(() => finish(false), 300);
+        timer.unref?.();
+    });
+}
+function readLiveRenderPid(pidPath) {
+    let pid;
+    try {
+        pid = Number(readFileSync(pidPath, "utf8").trim());
+    }
+    catch {
+        return null;
+    }
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    try {
+        process.kill(pid, 0);
+        return pid;
+    }
+    catch {
+        return null;
+    }
+}
+/** structuredExecHost 只认 daemon 客户端；测试注入的 in-process host 不算。 */
+function asTerminalDaemonClient(host) {
+    return host instanceof TerminalDaemonClient ? host : null;
+}

package/dist/render-protocol.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Render 协议 v1 的 TS 镜像。Rust 单一真源在
+ * `render/crates/wand-render-protocol/src/lib.rs`，契约文档在
+ * `render/docs/render-protocol.md`（本仓库 `docs/render-protocol.md` 只是指针）。
+ *
+ * 两侧常量与字段名必须逐一对齐；任一侧改动都要同时提升版本号并更新文档。
+ */
+export declare const RENDER_PROTOCOL_VERSION = 1;
+/** 单帧上限：`u32` 大端长度前缀 + UTF-8 JSON。 */
+export declare const MAX_FRAME_BYTES: number;
+/** 与 `PTY_OUTPUT_MAX_SIZE` 对齐（chunk 窗口 / output 有界）。 */
+export declare const RENDER_PTY_OUTPUT_MAX_CHARS = 200000;
+export type RenderErrorCode = "unauthorized" | "badRequest" | "notFound" | "conflict" | "unsupportedMethod" | "protocolMismatch" | "internal";
+export interface RenderRequest {
+    id: number;
+    token: string;
+    protocolVersion: number;
+    method: RenderMethod;
+    params?: Record<string, unknown>;
+}
+export type RenderMethod = "hello" | "ping" | "list" | "attach" | "createOrAttach" | "write" | "resize" | "kill" | "forget" | "stats" | "shutdown";
+export interface RenderResponse {
+    id: number;
+    ok: boolean;
+    result?: unknown;
+    error?: {
+        code: RenderErrorCode;
+        message: string;
+    };
+}
+export type RenderEvent = {
+    event: "data";
+    sessionId: string;
+    incarnationId: string;
+    data: string;
+    seq: number;
+} | {
+    event: "exit";
+    sessionId: string;
+    incarnationId: string;
+    exitCode: number | null;
+    signal: number | null;
+} | {
+    event: "reconcile";
+    sessionIds: string[];
+};
+export interface RenderHelloResult {
+    version: string;
+    protocolVersion: number;
+    pid: number;
+    startedAt: string;
+    sessions: number;
+}
+export interface RenderSessionState {
+    sessionId: string;
+    incarnationId: string;
+    pid: number;
+    status: "running" | "exited";
+    exitCode: number | null;
+    cols: number;
+    rows: number;
+    seq: number;
+    output: string;
+    chunks: {
+        data: string;
+        seq: number;
+    }[];
+    terminalSnapshot: {
+        version: number;
+        data: string;
+        cols: number;
+        rows: number;
+        pending: ({
+            type: "data";
+            data: string;
+        } | {
+            type: "resize";
+            cols: number;
+            rows: number;
+        })[];
+    } | null;
+    launchMarkerToken: string | null;
+}
+export interface RenderCreateOrAttachParams {
+    sessionId: string;
+    file: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    name: string;
+    cols: number;
+    rows: number;
+    launchMarkerToken?: string;
+    afterSeq?: number;
+}
+export interface RenderStatsResult {
+    uptimeMs: number;
+    sessions: number;
+    liveBytes: number;
+    rssBytes: number;
+}
+export interface RenderPaths {
+    socketPath: string;
+    tokenPath: string;
+    pidPath: string;
+    metaPath: string;
+}
+/**
+ * Render 的按 config 隔离寻址。
+ *
+ * 与 legacy `terminald`（`wand-terminald-<uid>-<suffix>.sock` /
+ * `.terminald-<suffix>.token`）**刻意使用不同文件名**：升级期两套并存，
+ * 但永不互相领养。
+ */
+export declare function renderPaths(configPath: string): RenderPaths;
+/** 编码一帧：`u32` 大端长度 + UTF-8 JSON。 */
+export declare function encodeRenderFrame(value: unknown): Buffer;
+/**
+ * 从累积缓冲区解出所有完整帧。
+ *
+ * 返回剩余（不完整）字节。长度越界时抛错，调用方应关闭连接。
+ */
+export declare function decodeRenderFrames<T>(buffer: Buffer): {
+    frames: T[];
+    rest: Buffer;
+};
+/** 是否为 protocol v1 事件帧（无 `id`，带 `event`）。 */
+export declare function isRenderEvent(value: unknown): value is RenderEvent;

package/dist/render-protocol.js

@@ -0,0 +1,99 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Render 协议 v1 的 TS 镜像。Rust 单一真源在
+ * `render/crates/wand-render-protocol/src/lib.rs`，契约文档在
+ * `render/docs/render-protocol.md`（本仓库 `docs/render-protocol.md` 只是指针）。
+ *
+ * 两侧常量与字段名必须逐一对齐；任一侧改动都要同时提升版本号并更新文档。
+ */
+export const RENDER_PROTOCOL_VERSION = 1;
+/** 单帧上限：`u32` 大端长度前缀 + UTF-8 JSON。 */
+export const MAX_FRAME_BYTES = 64 * 1024 * 1024;
+/** 与 `PTY_OUTPUT_MAX_SIZE` 对齐（chunk 窗口 / output 有界）。 */
+export const RENDER_PTY_OUTPUT_MAX_CHARS = 200_000;
+/**
+ * config 路径的 canonical 形式：`realpathSync` 解析符号链接，失败（文件尚未创建）
+ * 才回退纯词法的 `path.resolve`。
+ *
+ * 两侧必须对同一 config 派生出**同一套**路径，而「同一份 config」在用户那里常常是
+ * 经过符号链接的路径（`~/.wand` → 别的卷、`/tmp` → `/private/tmp`、容器挂载点）。
+ * 一侧做 realpath、另一侧只做 resolve，就会算出两个 suffix：同一个 config 出现两个
+ * Render、两套 PTY 所有权 —— 这正是要靠寻址归一化防住的故障。
+ */
+function canonicalConfigPath(configPath) {
+    const resolved = path.resolve(configPath);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+/**
+ * Render 的按 config 隔离寻址。
+ *
+ * 与 legacy `terminald`（`wand-terminald-<uid>-<suffix>.sock` /
+ * `.terminald-<suffix>.token`）**刻意使用不同文件名**：升级期两套并存，
+ * 但永不互相领养。
+ */
+export function renderPaths(configPath) {
+    const resolved = canonicalConfigPath(configPath);
+    const suffix = createHash("sha256").update(resolved).digest("hex").slice(0, 12);
+    const dir = path.dirname(resolved);
+    const uid = (() => {
+        try {
+            return os.userInfo().uid;
+        }
+        catch {
+            return 0;
+        }
+    })();
+    return {
+        // macOS 的 Unix socket 路径上限约 100 字节，所以 socket 放 /tmp 保持短。
+        socketPath: path.join("/tmp", `wand-render-${uid}-${suffix}.sock`),
+        tokenPath: path.join(dir, `.render-${suffix}.token`),
+        pidPath: path.join(dir, `.render-${suffix}.pid`),
+        metaPath: path.join(dir, `.render-${suffix}.json`),
+    };
+}
+/** 编码一帧：`u32` 大端长度 + UTF-8 JSON。 */
+export function encodeRenderFrame(value) {
+    const body = Buffer.from(JSON.stringify(value), "utf8");
+    if (body.length > MAX_FRAME_BYTES) {
+        throw new Error(`Render frame of ${body.length} bytes exceeds the ${MAX_FRAME_BYTES} byte limit`);
+    }
+    const header = Buffer.allocUnsafe(4);
+    header.writeUInt32BE(body.length, 0);
+    return Buffer.concat([header, body]);
+}
+/**
+ * 从累积缓冲区解出所有完整帧。
+ *
+ * 返回剩余（不完整）字节。长度越界时抛错，调用方应关闭连接。
+ */
+export function decodeRenderFrames(buffer) {
+    const frames = [];
+    let offset = 0;
+    while (buffer.length - offset >= 4) {
+        const length = buffer.readUInt32BE(offset);
+        if (length > MAX_FRAME_BYTES) {
+            throw new Error(`Render frame length ${length} exceeds the ${MAX_FRAME_BYTES} byte limit`);
+        }
+        if (buffer.length - offset - 4 < length)
+            break;
+        const body = buffer.subarray(offset + 4, offset + 4 + length);
+        frames.push(JSON.parse(body.toString("utf8")));
+        offset += 4 + length;
+    }
+    return { frames, rest: offset === 0 ? buffer : buffer.subarray(offset) };
+}
+/** 是否为 protocol v1 事件帧（无 `id`，带 `event`）。 */
+export function isRenderEvent(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return typeof record.event === "string" && record.id === undefined;
+}

package/dist/render-structured-client.d.ts

@@ -0,0 +1,80 @@
+import { type StructuredRenderEvent, type StructuredRenderMethod } from "./render-structured-protocol.js";
+import type { StructuredExecHost, StructuredExecProcess, StructuredExitEvent, StructuredRunState, StructuredSpawnRequest, StructuredStreamEvent } from "./structured-exec-host.js";
+type RunEvent = Extract<StructuredRenderEvent, {
+    event: "stream" | "exit";
+}>;
+declare class RemoteRun implements StructuredExecProcess {
+    readonly runId: string;
+    readonly incarnationId: string;
+    readonly pid: number;
+    private readonly client;
+    private readonly streamListeners;
+    private readonly exitListeners;
+    private readonly beforeListener;
+    private pendingExit;
+    readonly seq: {
+        stdout: number;
+        stderr: number;
+    };
+    readonly queued: RunEvent[];
+    syncing: boolean;
+    overflow: boolean;
+    get exited(): boolean;
+    constructor(runId: string, incarnationId: string, pid: number, client: RenderStructuredClient);
+    interrupt(signal?: string): void;
+    onStream(listener: (event: StructuredStreamEvent) => void): {
+        dispose(): void;
+    };
+    onExit(listener: (event: StructuredExitEvent) => void): {
+        dispose(): void;
+    };
+    acceptStream(event: StructuredStreamEvent): void;
+    acceptExit(event: StructuredExitEvent): void;
+    fail(): void;
+}
+/** v2-only StructuredExecHost. It never accesses the PTY v1 or terminald sockets. */
+export declare class RenderStructuredClient implements StructuredExecHost {
+    private readonly configPath;
+    readonly persistent = true;
+    private socket;
+    private buffer;
+    private token;
+    private requestId;
+    private readonly pending;
+    private readonly inventory;
+    private readonly observed;
+    private readonly handles;
+    private readonly orphanEvents;
+    private readonly orphanOverflow;
+    private connecting;
+    private reconnectTimer;
+    private disposed;
+    private connected;
+    private fatalProtocol;
+    private stopHeartbeat;
+    private reconnectDelayMs;
+    constructor(configPath: string);
+    connect(): Promise<void>;
+    private open;
+    request(method: StructuredRenderMethod, params?: Record<string, unknown>): Promise<unknown>;
+    private consume;
+    private acceptEvent;
+    private queue;
+    private catchUp;
+    private replayStream;
+    private collect;
+    /** Events can overtake the spawn response. Feed the contiguous prefix before
+     * paging so a fast >8 MiB child does not falsely lose its already-received head. */
+    private primeBuffered;
+    spawnStructured(request: StructuredSpawnRequest): Promise<StructuredExecProcess>;
+    attachRun(runId: string): Promise<StructuredRunState | null>;
+    adoptRun(runId: string): Promise<StructuredExecProcess | null>;
+    listRuns(): Promise<StructuredRunState[]>;
+    forgetRun(runId: string): void;
+    dropHandle(runId: string, handle: RemoteRun): void;
+    disconnect(): void;
+    private onDisconnect;
+    private scheduleReconnect;
+    private rejectPending;
+}
+export {};