@co0ontty/wand 4.102.0 → 4.103.0

package/dist/pi-event-projection.js

@@ -1,3 +1,4 @@
+import { projectPiToolResult } from "./pi-tool-result-preview.js";
 /** Fields consumed by Wand's Pi reducer. Context/entries are CLI-owned history,
  * not new output. Never journal repeated copies of that history in native mode. */
 export const PI_PROTOCOL_FIELDS = new Set([
@@ -24,5 +25,17 @@ export function projectPiProtocolEvent(event) {
         const last = lastPiAssistantMessage(event);
         projected.messages = last ? [last] : [];
     }
+    const message = event.message;
+    if (message && typeof message === "object" && !Array.isArray(message)
+        && ["user", "toolResult"].includes(String(message.role))) {
+        // These are duplicate transcript snapshots. tool_execution_end already
+        // carries the result; do not serialize its image/body a second time.
+        projected.message = { role: message.role };
+    }
+    if (event.type === "tool_execution_end" || event.type === "tool_execution_update") {
+        const key = event.type === "tool_execution_end" ? "result" : "partialResult";
+        if (key in projected)
+            projected[key] = projectPiToolResult(projected[key]);
+    }
     return projected;
 }

package/dist/pi-execution.js

@@ -79,7 +79,8 @@ export function projectPiExecution(raw, source, fallbackState) {
         version: 1, source, mode: text(d.mode) ?? "workflow", name: text(d.name),
         runId: text(d.runId ?? children.workflowRunId ?? d.asyncId),
         state: state(children.workflowState ?? d.state ?? (d.asyncId ? "background" : fallbackState)),
-        inventoryComplete: typeof children.inventoryComplete === "boolean" ? children.inventoryComplete : source === "tool-result" && !d.asyncId,
+        inventoryComplete: d.inventoryComplete === false ? false
+            : typeof children.inventoryComplete === "boolean" ? children.inventoryComplete : source === "tool-result" && !d.asyncId,
         updatedAt: number(d.lastUpdate ?? d.updatedAt), nodes: rows.slice(0, MAX_NODES),
         trace: trace.slice(-MAX_TRACE).map(t => ({ key: text(t.key) ?? "", operation: text(t.operation) ?? "", state: text(t.state) ?? "unknown",
             phase: text(t.phase), durationMs: number(t.durationMs), error: text(t.error, 1000) })),

package/dist/pi-protocol-reader.d.ts

@@ -2,8 +2,9 @@
  * no regex/type-prefix guessing and no JSON truncation. Field order and chunk
  * boundaries do not matter. The only retained history member is the latest
  * assistant, which reconciles the streamed reply and preserves terminal errors.
- * Genuine oversized payloads still fail closed; other providers keep their
- * original 8 MiB line limit. */
+ * Tool results get a bounded display preview when their exact value is too
+ * large; Pi retains the original for its own model context. Assistant payloads
+ * and other providers retain their strict safety limits. */
 export declare class PiProtocolReader {
     private readonly onLine;
     private parser;
@@ -13,6 +14,7 @@ export declare class PiProtocolReader {
     private key;
     private inKey;
     private field;
+    private toolPreview;
     private fieldDepth;
     private messages;
     private latestAssistant;
@@ -25,6 +27,8 @@ export declare class PiProtocolReader {
     });
     push(text: string): void;
     finish(): void;
+    /** Checkpoints may only advance after complete records, never mid-string. */
+    get atBoundary(): boolean;
     private tokenize;
     private consume;
     private token;

package/dist/pi-protocol-reader.js

@@ -3,12 +3,13 @@ import * as streamJson from "stream-json/core/parser.js";
 import Assembler from "stream-json/core/assembler.js";
 import { MAX_PROTOCOL_LINE_BYTES } from "./bounded-process-output.js";
 import { PI_PROTOCOL_FIELDS } from "./pi-event-projection.js";
+import { PiToolResultPreview, projectPiToolResult } from "./pi-tool-result-preview.js";
 const { jsonParser } = streamJson;
 const CHUNK_CHARS = 16 * 1024;
 const MAX_DEPTH = 128;
 const MAX_KEY_CHARS = 1024;
-const MAX_ENVELOPE_BYTES = 256 * 1024 * 1024;
 const HISTORY_EVENTS = new Set(["agent_end", "turn_end", "message_start", "message_end", "message_update"]);
+const TOOL_RESULT_EVENTS = new Set(["tool_execution_end", "tool_execution_update"]);
 const failure = (reason) => new Error(`Pi CLI 协议${reason}；本轮已停止，送达结果未知，不自动重试。`);
 /** A single retained value, never the entire history array. Both strings and
  * structural tokens count toward the budget; overflow releases partial objects.
@@ -24,7 +25,7 @@ class BoundedValue {
     role = "";
     overflow = false;
     consume(token) {
-        this.bytes += "value" in token && typeof token.value === "string" ? Buffer.byteLength(token.value) + 16 : 16;
+        this.bytes += "value" in token && typeof token.value === "string" ? Buffer.byteLength(JSON.stringify(token.value)) + 16 : 16;
         if (this.bytes > MAX_PROTOCOL_LINE_BYTES) {
             this.overflow = true;
             this.assembler = null;
@@ -72,8 +73,9 @@ class BoundedValue {
  * no regex/type-prefix guessing and no JSON truncation. Field order and chunk
  * boundaries do not matter. The only retained history member is the latest
  * assistant, which reconciles the streamed reply and preserves terminal errors.
- * Genuine oversized payloads still fail closed; other providers keep their
- * original 8 MiB line limit. */
+ * Tool results get a bounded display preview when their exact value is too
+ * large; Pi retains the original for its own model context. Assistant payloads
+ * and other providers retain their strict safety limits. */
 export class PiProtocolReader {
     onLine;
     parser = null;
@@ -83,6 +85,7 @@ export class PiProtocolReader {
     key = "";
     inKey = false;
     field = null;
+    toolPreview = null;
     fieldDepth = 0;
     messages = false;
     latestAssistant;
@@ -118,8 +121,8 @@ export class PiProtocolReader {
                     }
                     else {
                         this.parser ??= jsonParser({ packValues: false });
-                        if (this.rawBytes > MAX_ENVELOPE_BYTES)
-                            throw failure("事件封套超过安全容量");
+                        // SAX validates discarded bodies without retaining them. Envelope
+                        // size is not a memory budget; retained fields have their own caps.
                         this.tokenize(part);
                     }
                 }
@@ -129,6 +132,8 @@ export class PiProtocolReader {
         }
     }
     finish() { this.endLine(); }
+    /** Checkpoints may only advance after complete records, never mid-string. */
+    get atBoundary() { return !this.parser && this.noise === null && !this.discardHead; }
     tokenize(input) {
         let tokens;
         try {
@@ -167,8 +172,11 @@ export class PiProtocolReader {
             this.inKey = false;
             if (this.depth === 1)
                 this.rootKey = this.key;
-            else
-                this.field?.consume({ name: "keyValue", value: this.key });
+            else {
+                const keyToken = { name: "keyValue", value: this.key };
+                this.field?.consume(keyToken);
+                this.toolPreview?.consume(keyToken);
+            }
             return;
         }
         const opening = token.name === "startObject" || token.name === "startArray";
@@ -186,6 +194,8 @@ export class PiProtocolReader {
             }
             else if (PI_PROTOCOL_FIELDS.has(this.rootKey)) {
                 this.field = new BoundedValue();
+                if (this.rootKey === "result" || this.rootKey === "partialResult")
+                    this.toolPreview = new PiToolResultPreview();
                 this.fieldDepth = 1;
             }
         }
@@ -194,6 +204,7 @@ export class PiProtocolReader {
             this.fieldDepth = 2;
         }
         this.field?.consume(token);
+        this.toolPreview?.consume(token);
         if (opening) {
             this.depth++;
             if (this.depth > MAX_DEPTH)
@@ -212,12 +223,15 @@ export class PiProtocolReader {
                 }
             }
             else {
-                if (this.field.overflow && !(this.rootKey === "message" && ["user", "toolResult"].includes(this.field.role))) {
+                const transcriptOnly = this.rootKey === "message" && ["user", "toolResult"].includes(this.field.role);
+                if (this.field.overflow && !this.toolPreview && !transcriptOnly) {
                     throw failure(`有效载荷 ${this.rootKey} 超过 8 MiB 安全容量`);
                 }
-                this.event[this.rootKey] = this.field.overflow ? { role: this.field.role } : this.field.value;
+                this.event[this.rootKey] = transcriptOnly ? { role: this.field.role }
+                    : this.field.overflow ? this.toolPreview?.value ?? { role: this.field.role } : this.field.value;
             }
             this.field = null;
+            this.toolPreview = null;
         }
         if (this.messages && closing && this.depth === 1) {
             this.event.messages = this.latestAssistant ? [this.latestAssistant] : [];
@@ -248,10 +262,19 @@ export class PiProtocolReader {
                 throw failure("事件不完整");
             if (typeof this.event.type !== "string")
                 throw failure("事件缺少类型");
-            if (this.rawBytes > MAX_PROTOCOL_LINE_BYTES && !HISTORY_EVENTS.has(this.event.type)) {
+            if (this.rawBytes > MAX_PROTOCOL_LINE_BYTES && !HISTORY_EVENTS.has(this.event.type) && !TOOL_RESULT_EVENTS.has(this.event.type)) {
                 throw failure("非汇总事件超过 8 MiB 安全容量");
             }
-            const line = JSON.stringify(this.event);
+            let line = JSON.stringify(this.event);
+            if (Buffer.byteLength(line) > MAX_PROTOCOL_LINE_BYTES && TOOL_RESULT_EVENTS.has(this.event.type)) {
+                // The aggregate may exceed the transport budget even when each field
+                // fits (or when JSON escapes expand a string). Keep the event whole.
+                for (const key of ["result", "partialResult"]) {
+                    if (key in this.event)
+                        this.event[key] = projectPiToolResult(this.event[key], true);
+                }
+                line = JSON.stringify(this.event);
+            }
             if (Buffer.byteLength(line) > MAX_PROTOCOL_LINE_BYTES)
                 throw failure("有效载荷超过 8 MiB 安全容量");
             this.onLine(line);
@@ -271,6 +294,7 @@ export class PiProtocolReader {
         this.rootKey = this.key = "";
         this.inKey = this.messages = false;
         this.field = null;
+        this.toolPreview = null;
         this.latestAssistant = undefined;
         this.rawBytes = 0;
     }

package/dist/pi-tmux-host.d.ts

@@ -36,7 +36,7 @@ export declare class PiTmuxHost implements StructuredExecHost {
     state(job: NativeJob): WorkerState;
     private snapshot;
     spawnStructured(request: StructuredSpawnRequest): Promise<StructuredExecProcess>;
-    attachRun(runId: string): Promise<StructuredRunState | null>;
+    attachRun(runId: string, checkpoint?: import("./pi-cli-checkpoint.js").PiCliCheckpoint): Promise<StructuredRunState | null>;
     adoptRun(runId: string): Promise<StructuredExecProcess | null>;
     listRuns(): Promise<StructuredRunState[]>;
     kill(job: NativeJob): Promise<void>;

package/dist/pi-tmux-host.js

@@ -49,6 +49,9 @@ class NativeProcess {
             this.offsets.stderr = after.stderrSeq;
         }
     }
+    get protocolSource() {
+        return { file: this.job.events, ...this.identities.stdout };
+    }
     get pid() { return this.host.state(this.job).pid; }
     interrupt() { void this.host.kill(this.job).catch((error) => logInfo(`Pi native stop failed: ${error instanceof Error ? error.message : String(error)}`)); }
     onStream(listener) {
@@ -177,25 +180,42 @@ export class PiTmuxHost {
         }
         return value;
     }
-    snapshot(job) {
+    snapshot(job, checkpoint) {
         const state = this.state(job);
+        let stdoutFrom;
         const log = (file) => {
             const fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
             try {
-                const size = fstatSync(fd).size;
-                const count = Math.min(size, REPLAY_BYTES);
+                const stat = fstatSync(fd);
+                const size = stat.size;
+                const matched = file === job.events && checkpoint?.incarnationId === job.incarnationId
+                    && checkpoint.source.file === file && checkpoint.source.dev === stat.dev && checkpoint.source.ino === stat.ino
+                    && checkpoint.offset <= size && size - checkpoint.offset <= REPLAY_BYTES;
+                // A checkpoint is usable only if it ends at a real source record
+                // boundary. Never splice an arbitrary byte position into JSON.
+                let boundary = checkpoint?.offset === 0;
+                if (matched && checkpoint.offset > 0) {
+                    const byte = Buffer.alloc(1);
+                    boundary = readSync(fd, byte, 0, 1, checkpoint.offset - 1) === 1 && byte[0] === 10;
+                }
+                const start = matched && boundary ? checkpoint.offset : Math.max(0, size - REPLAY_BYTES);
+                if (matched && boundary)
+                    stdoutFrom = start;
+                const count = size - start;
                 const bytes = Buffer.alloc(count);
                 let read = 0;
                 while (read < count) {
-                    const n = readSync(fd, bytes, read, count - read, size - count + read);
+                    const n = readSync(fd, bytes, read, count - read, start + read);
                     if (!n)
                         break;
                     read += n;
                 }
+                if (read !== count)
+                    throw new Error("Pi 原生事件文件读取不完整。");
                 let begin = 0;
                 while (begin < read && (bytes[begin] & 0xc0) === 0x80)
                     begin++;
-                return { text: bytes.subarray(begin, read).toString("utf8"), size, truncated: size > count };
+                return { text: bytes.subarray(begin, read).toString("utf8"), size, truncated: (file !== job.events || stdoutFrom === undefined) && size > count };
             }
             finally {
                 closeSync(fd);
@@ -208,7 +228,7 @@ export class PiTmuxHost {
             signal: state.signal ? signalNumberFromName(state.signal) : null,
             stdoutSeq: stdout.size, stderrSeq: stderr.size, stdoutLog: stdout.text, stderrLog: stderr.text,
             stdoutTruncated: stdout.truncated, stderrTruncated: stderr.truncated,
-            nativeFile: job.events };
+            nativeFile: job.events, ...(stdoutFrom !== undefined ? { stdoutFrom } : {}) };
     }
     async spawnStructured(request) {
         if (!request.nativePi) {
@@ -327,10 +347,10 @@ export class PiTmuxHost {
             rmSync(launchDir, { recursive: true, force: true });
         }
     }
-    async attachRun(runId) {
+    async attachRun(runId, checkpoint) {
         const job = this.job(runId);
         if (job && !existsSync(job.ack)) {
-            const state = this.snapshot(job);
+            const state = this.snapshot(job, checkpoint);
             this.observed.set(runId, state);
             this.owners.set(runId, "native");
             return state;

package/dist/pi-tool-result-preview.d.ts

@@ -0,0 +1,23 @@
+import type { Token } from "stream-json/core/parser.js";
+/** A display-only fallback, built alongside the exact bounded value. It never
+ * changes Pi's own tool result/model context. Independent root-field budgets
+ * keep a large content body from swallowing later execution details (or vice
+ * versa). All tokens, including omitted subtrees, still pass the JSON parser. */
+export declare class PiToolResultPreview {
+    private readonly budgets;
+    private readonly stack;
+    private root;
+    private scalar;
+    private tail;
+    private scalarOmitted;
+    private scalarLimit;
+    private detailsOmitted;
+    private budget;
+    private attach;
+    consume(token: Token): void;
+    private keep;
+    get value(): Record<string, unknown>;
+}
+/** Native extension events already exist as objects. Walk them in small scalar
+ * slices instead of allocating a second giant JSON string before projection. */
+export declare function projectPiToolResult(value: unknown, forcePreview?: boolean): unknown;

package/dist/pi-tool-result-preview.js

@@ -0,0 +1,185 @@
+import { MAX_PROTOCOL_LINE_BYTES } from "./bounded-process-output.js";
+const GROUP_BYTES = 192 * 1024;
+const STRING_CHARS = 16 * 1024;
+const NOTICE = "[工具结果较大，Wand 仅展示有界预览；工具执行与后续答复继续。]";
+const OMITTED_IMAGE = "[大图片未内嵌到工具结果预览中]";
+/** A display-only fallback, built alongside the exact bounded value. It never
+ * changes Pi's own tool result/model context. Independent root-field budgets
+ * keep a large content body from swallowing later execution details (or vice
+ * versa). All tokens, including omitted subtrees, still pass the JSON parser. */
+export class PiToolResultPreview {
+    budgets = new Map();
+    stack = [];
+    root;
+    scalar = "";
+    tail = "";
+    scalarOmitted = false;
+    scalarLimit = STRING_CHARS;
+    detailsOmitted = false;
+    budget() {
+        const field = this.stack[0]?.key;
+        const group = field === "content" || field === "details" ? field : "other";
+        let budget = this.budgets.get(group);
+        if (!budget)
+            this.budgets.set(group, budget = { remaining: GROUP_BYTES });
+        return this.stack.length > 1 ? this.stack.at(-1).budget : budget;
+    }
+    attach(value, omitted) {
+        const parent = this.stack.at(-1);
+        if (!parent) {
+            this.root = value;
+            return;
+        }
+        parent.omitted ||= omitted;
+        if (this.stack.length === 1 && parent.key === "details")
+            this.detailsOmitted ||= omitted;
+        if (!parent.retained || value === undefined)
+            return;
+        if (Array.isArray(parent.value))
+            parent.value.push(value);
+        else
+            Object.defineProperty(parent.value, parent.key, { value, enumerable: true, configurable: true, writable: true });
+    }
+    consume(token) {
+        if (token.name === "keyValue") {
+            const parent = this.stack.at(-1);
+            if (parent)
+                parent.key = token.value;
+            return;
+        }
+        if (token.name === "startObject" || token.name === "startArray") {
+            const budget = this.budget();
+            const key = this.stack.at(-1)?.key ?? "";
+            const cost = 32 + Buffer.byteLength(JSON.stringify(key));
+            const retained = (this.stack.at(-1)?.retained ?? true) && budget.remaining >= cost;
+            if (retained)
+                budget.remaining -= cost;
+            this.stack.push({ value: token.name === "startArray" ? [] : {}, key: "", budget, retained, omitted: !retained });
+            return;
+        }
+        if (token.name === "endObject" || token.name === "endArray") {
+            const frame = this.stack.pop();
+            let value = frame.retained ? frame.value : undefined;
+            // A shortened base64/data URL is not a valid image. Replace its complete
+            // part with readable text rather than sending corrupted image data.
+            if (frame.omitted && !Array.isArray(value) && (value?.type === "image" || value?.type === "image_url")) {
+                value = { type: "text", text: OMITTED_IMAGE };
+            }
+            this.attach(value, frame.omitted);
+            return;
+        }
+        if (token.name === "startString" || token.name === "startNumber") {
+            this.scalar = this.tail = "";
+            this.scalarOmitted = false;
+            // Worst-case JSON escaping costs six bytes per character. Leave room
+            // for the omission marker and key so the assembled fallback stays small.
+            this.scalarLimit = Math.min(STRING_CHARS, Math.max(0, Math.floor((this.budget().remaining - 512) / 6)));
+            return;
+        }
+        if (token.name === "stringChunk" || token.name === "numberChunk") {
+            const room = this.scalarLimit - this.scalar.length;
+            this.scalar += token.value.slice(0, room);
+            if (token.value.length > room) {
+                this.scalarOmitted = true;
+                this.tail = this.scalarLimit ? (this.tail + token.value.slice(room)).slice(-this.scalarLimit) : "";
+            }
+            return;
+        }
+        if (token.name === "endString" || token.name === "endNumber") {
+            // Prefix/tail cuts may land between the two UTF-16 halves of a scalar.
+            const head = this.scalarOmitted && /[\uD800-\uDBFF]$/.test(this.scalar) ? this.scalar.slice(0, -1) : this.scalar;
+            const tail = /^[\uDC00-\uDFFF]/.test(this.tail) ? this.tail.slice(1) : this.tail;
+            const value = token.name === "endNumber" ? (this.scalarOmitted ? null : Number(this.scalar))
+                : this.scalarOmitted ? head + "\n[…预览省略…]\n" + tail : this.scalar;
+            this.keep(value, this.scalarOmitted);
+            this.scalar = this.tail = "";
+            return;
+        }
+        if (token.name === "trueValue" || token.name === "falseValue" || token.name === "nullValue") {
+            this.keep(token.name === "nullValue" ? null : token.name === "trueValue", false);
+        }
+    }
+    keep(value, omitted) {
+        const budget = this.budget();
+        const key = this.stack.at(-1)?.key ?? "";
+        const bytes = Buffer.byteLength(JSON.stringify(value)) + Buffer.byteLength(JSON.stringify(key)) + 2;
+        if (bytes > budget.remaining) {
+            this.attach(undefined, true);
+            return;
+        }
+        budget.remaining -= bytes;
+        this.attach(value, omitted);
+    }
+    get value() {
+        const result = this.root && typeof this.root === "object" && !Array.isArray(this.root)
+            ? this.root : {};
+        const raw = result.content ?? result.output ?? this.root;
+        const text = typeof raw === "string" ? raw : raw === undefined ? "" : JSON.stringify(raw);
+        const content = Array.isArray(raw) ? [...raw, { type: "text", text: NOTICE }]
+            : [{ type: "text", text: (text ? text + "\n" : "") + NOTICE }];
+        // Partial execution inventories must not be advertised as complete.
+        const details = result.details && typeof result.details === "object" && !Array.isArray(result.details)
+            ? this.detailsOmitted ? { ...result.details, inventoryComplete: false } : result.details : undefined;
+        return { content, ...(details ? { details } : {}) };
+    }
+}
+/** Native extension events already exist as objects. Walk them in small scalar
+ * slices instead of allocating a second giant JSON string before projection. */
+export function projectPiToolResult(value, forcePreview = false) {
+    const preview = new PiToolResultPreview();
+    const seen = new Set();
+    let bytes = 0;
+    const emit = (token) => {
+        bytes += "value" in token && typeof token.value === "string" ? Buffer.byteLength(JSON.stringify(token.value)) + 16 : 16;
+        preview.consume(token);
+    };
+    function visit(raw, depth) {
+        if (depth > 128)
+            throw new Error("Pi 工具结果嵌套超过安全深度");
+        if (typeof raw === "string" || typeof raw === "number") {
+            const string = typeof raw === "string";
+            const text = string ? raw : String(raw);
+            if (!string && !Number.isFinite(raw)) {
+                emit({ name: "nullValue", value: null });
+                return;
+            }
+            emit({ name: string ? "startString" : "startNumber" });
+            for (let offset = 0; offset < text.length; offset += STRING_CHARS) {
+                emit({ name: string ? "stringChunk" : "numberChunk", value: text.slice(offset, offset + STRING_CHARS) });
+            }
+            emit({ name: string ? "endString" : "endNumber" });
+        }
+        else if (typeof raw === "boolean")
+            emit(raw ? { name: "trueValue", value: true } : { name: "falseValue", value: false });
+        else if (!raw || typeof raw !== "object") {
+            if (typeof raw === "bigint")
+                throw new TypeError("Pi 工具结果包含不可序列化的 bigint");
+            emit({ name: "nullValue", value: null });
+        }
+        else {
+            if (seen.has(raw))
+                throw new TypeError("Pi 工具结果包含循环引用");
+            seen.add(raw);
+            if (Array.isArray(raw)) {
+                emit({ name: "startArray" });
+                for (const item of raw)
+                    visit(item, depth + 1);
+                emit({ name: "endArray" });
+            }
+            else {
+                emit({ name: "startObject" });
+                for (const key of Object.keys(raw)) {
+                    const item = raw[key];
+                    if (item === undefined || typeof item === "function" || typeof item === "symbol")
+                        continue;
+                    emit({ name: "keyValue", value: key });
+                    visit(item, depth + 1);
+                }
+                emit({ name: "endObject" });
+            }
+            seen.delete(raw);
+        }
+    }
+    visit(value, 0);
+    return forcePreview || bytes > MAX_PROTOCOL_LINE_BYTES ? preview.value : value;
+}

package/dist/render-daemon-client.js

@@ -867,7 +867,7 @@ export class RenderDaemonClient {
                 return;
             // 端点本身没了（socket 文件被临时目录清理器删掉，或 daemon 崩了没留下 socket）：
             // 重试同一个路径永远不会成功，先把 daemon 拉回来再连一次。只要 pid 文件里还有
-            // 活进程，回调就不会动手 —— 那个 daemon 会自己重建端点（docs/render-protocol.md §6）。
+            // 活进程，回调就不会动手 —— 那个 daemon 会自己重建端点（render/docs/render-protocol.md §6）。
             if (await this.reviveDaemonForRetry()) {
                 try {
                     await this.connect();

package/dist/render-host.d.ts

@@ -19,7 +19,7 @@ export interface RenderHostOptions {
  * - daemon 被 kill -9 / 崩溃，socket 文件作为陈留文件留了下来（没有监听者）。
  *
  * 保守之处：pid 文件里还有活进程就不插手（那个 daemon 会自己重建端点，
- * docs/render-protocol.md §6 single instance）；能连上监听者也不插手；同一个窗口只 spawn 一次。
+ * render/docs/render-protocol.md §6 single instance）；能连上监听者也不插手；同一个窗口只 spawn 一次。
  */
 export declare function createRenderDaemonReviver(configPath: string, binaryPath: string | null): RenderDaemonReviver;
 export interface UpgradeAwareTerminalHost {
@@ -63,7 +63,7 @@ export declare function createUpgradeAwareTerminalHost(configPath: string, optio
 /**
  * adopt 已存在的 Render，不存在则 spawn 后等待就绪。
  *
- * 协议（docs/render-protocol.md §6）：pid 活着但 socket 不可用 → 等待就绪，
+ * 协议（render/docs/render-protocol.md §6）：pid 活着但 socket 不可用 → 等待就绪，
  * 不另起第二个 daemon；协议版本不符 → 明确抛错，**不做降级运行**。
  */
 export declare function createRenderTerminalHost(configPath: string, options?: {
@@ -78,7 +78,7 @@ export declare function shouldUpgradeRenderDaemon(daemonVersion: string | null,
 /**
  * detached spawn（stdio 忽略、unref），返回子进程 pid。
  *
- * `-c <configPath>` 是按 config 隔离的既定约定（docs/render-protocol.md §6）：
+ * `-c <configPath>` 是按 config 隔离的既定约定（render/docs/render-protocol.md §6）：
  * socket / token / pid / meta 全部由它派生。
  */
 export declare function spawnDetachedRenderProcess(configPath: string, binaryPath: string): number | null;

package/dist/render-host.js

@@ -25,7 +25,7 @@ const RENDER_STALE_PROBE_DELAY_MS = 250;
  * - daemon 被 kill -9 / 崩溃，socket 文件作为陈留文件留了下来（没有监听者）。
  *
  * 保守之处：pid 文件里还有活进程就不插手（那个 daemon 会自己重建端点，
- * docs/render-protocol.md §6 single instance）；能连上监听者也不插手；同一个窗口只 spawn 一次。
+ * render/docs/render-protocol.md §6 single instance）；能连上监听者也不插手；同一个窗口只 spawn 一次。
  */
 export function createRenderDaemonReviver(configPath, binaryPath) {
     let inFlight = null;
@@ -214,7 +214,7 @@ export async function createUpgradeAwareTerminalHost(configPath, options = {}) {
 /**
  * adopt 已存在的 Render，不存在则 spawn 后等待就绪。
  *
- * 协议（docs/render-protocol.md §6）：pid 活着但 socket 不可用 → 等待就绪，
+ * 协议（render/docs/render-protocol.md §6）：pid 活着但 socket 不可用 → 等待就绪，
  * 不另起第二个 daemon；协议版本不符 → 明确抛错，**不做降级运行**。
  */
 export async function createRenderTerminalHost(configPath, options = {}) {
@@ -274,7 +274,7 @@ export function shouldUpgradeRenderDaemon(daemonVersion, binaryVersion, sessionC
 /**
  * detached spawn（stdio 忽略、unref），返回子进程 pid。
  *
- * `-c <configPath>` 是按 config 隔离的既定约定（docs/render-protocol.md §6）：
+ * `-c <configPath>` 是按 config 隔离的既定约定（render/docs/render-protocol.md §6）：
  * socket / token / pid / meta 全部由它派生。
  */
 export function spawnDetachedRenderProcess(configPath, binaryPath) {

package/dist/server-apns-routes.d.ts

@@ -0,0 +1,12 @@
+import { type Express } from "express";
+import type { ApnsService } from "./apns-service.js";
+import type { LiveActivityService } from "./live-activity-service.js";
+import type { WandStorage } from "./storage.js";
+import type { WandConfig } from "./types.js";
+/** Mount before the global API auth gate: PUT requires the app bearer; DELETE has revoke-only authority. */
+export declare function registerApnsRoutes(app: Express, deps: {
+    storage: WandStorage;
+    config: WandConfig;
+    service: ApnsService;
+    liveActivity?: LiveActivityService;
+}): void;