pi-web-ui 0.94.1 → 0.96.0

package/dist/server/attachment-store.js

@@ -0,0 +1,129 @@
+/**
+ * attachment-store.ts — 基于 SHA-256 内容寻址（CAS）的附件存储。
+ *
+ * 借鉴 DSH 的 dsh-attachment 机制：
+ *  - 图片与大二进制附件以 sha256 哈希落盘到 `<dataDir>/attachments/<hash>.<ext>`；
+ *  - WebSocket 快照与会话转录中仅传递紧凑的 hash 引用与 URL；
+ *  - 浏览器通过 `/api/attachment/:hash` 经 HTTP 访问，带永久强缓存（immutable）；
+ *  - 避免快照和消息列表随会话进行出现数兆字节 base64 的膨胀。
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, existsSync, readdirSync } from "node:fs";
+import { readFile, rename, rm, writeFile, stat } from "node:fs/promises";
+import { join, extname } from "node:path";
+let storeDir = "";
+/** 初始化附件存储目录（服务启动时调用）。 */
+export function initAttachmentStore(dataDir) {
+    storeDir = join(dataDir, "attachments");
+    if (!existsSync(storeDir)) {
+        mkdirSync(storeDir, { recursive: true });
+    }
+    return storeDir;
+}
+const MIME_EXT_MAP = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/jpg": ".jpg",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+    "image/svg+xml": ".svg",
+    "image/bmp": ".bmp",
+    "application/pdf": ".pdf",
+};
+const EXT_MIME_MAP = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    ".pdf": "application/pdf",
+};
+/**
+ * 将二进制内容写入附件存储（内容寻址，幂等）：
+ * 已存在同哈希文件则直接返回元数据，不重复写盘。
+ */
+export async function saveAttachment(buffer, mimeType = "application/octet-stream", preferredExt) {
+    if (!storeDir) {
+        throw new Error("AttachmentStore has not been initialized with initAttachmentStore(dataDir)");
+    }
+    const hash = createHash("sha256").update(buffer).digest("hex");
+    const ext = preferredExt || MIME_EXT_MAP[mimeType] || ".bin";
+    const fileName = `${hash}${ext}`;
+    const filePath = join(storeDir, fileName);
+    if (!existsSync(filePath)) {
+        // 原地 writeFile 有两个问题：a) 同 hash 并发写时两个 writeFileSync
+        // 交错会留下半个文件；b) 读方（/api/attachment/:hash）可能在写完前就命中。
+        // 因此先写私有 tmp 再 rename（同目录内原子生效）。POSIX rename 原子覆盖；
+        // Windows 目标已存在时报 EEXIST/EPERM —— 内容寻址同 hash 即同内容，
+        // 并发对手落盘视为成功。tmp 命名带 uuid，绝不与真实附件名冲突。
+        const tmpPath = `${filePath}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(tmpPath, buffer);
+            await rename(tmpPath, filePath);
+        }
+        catch (err) {
+            await rm(tmpPath, { force: true }).catch(() => { });
+            const code = err.code;
+            if (code !== "EEXIST" && code !== "EPERM")
+                throw err;
+        }
+    }
+    return {
+        hash,
+        size: buffer.length,
+        mimeType,
+        ext,
+        url: `/api/attachment/${hash}`,
+        filePath,
+    };
+}
+/**
+ * 根据哈希查找已存储的附件文件路径及元数据。
+ */
+export async function findAttachment(hash) {
+    if (!storeDir || !existsSync(storeDir))
+        return null;
+    // 校验 hash 必须是 64 位十六进制字符串（防止目录遍历）
+    if (!/^[a-f0-9]{64}$/i.test(hash))
+        return null;
+    try {
+        const files = readdirSync(storeDir);
+        // 跳过原子写（tmp + rename）崩溃时可能残留的 .tmp —— 前缀同为 hash，
+        // 若被命中会拿到错误的后缀与 MIME。
+        const match = files.find((f) => f.startsWith(hash) && !f.endsWith(".tmp"));
+        if (!match)
+            return null;
+        const filePath = join(storeDir, match);
+        const st = await stat(filePath);
+        const ext = extname(match).toLowerCase();
+        const mimeType = EXT_MIME_MAP[ext] || "application/octet-stream";
+        return {
+            hash,
+            size: st.size,
+            mimeType,
+            ext,
+            url: `/api/attachment/${hash}`,
+            filePath,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 读取附件二进制数据。
+ */
+export async function readAttachment(hash) {
+    const record = await findAttachment(hash);
+    if (!record)
+        return null;
+    try {
+        const buffer = await readFile(record.filePath);
+        return { buffer, mimeType: record.mimeType };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server/attachments.js

@@ -1,10 +1,23 @@
-import { countLines, decodeText, looksLikeText, sniffImageMime } from "./text-sniff.js";
+import { sniffImageMime } from "./text-sniff.js";
 import { saveUpload, uploadsRoot } from "./uploads.js";
 import { isAbsoluteWirePath, wireToAbs } from "./files-service.js";
 import { buildVisionBridgePrompt, findVisionModels, transcribeImages } from "./vision-bridge.js";
+import { saveAttachment } from "./attachment-store.js";
 /** 跨快照的视觉转写缓存：批次 hash（名称 + base64 头 + 提示词）→ 转写文本。
- *  编辑重问重发相同图片不再重复耗视觉 token。进程级共享即可。 */
+ *  编辑重问重发相同图片不再重复耗视觉 token。进程级共享即可。
+ *  长驻进程下无界 Map 会随图片种类缓慢吃内存（单条转写可达数十 KB），
+ *  超过 VISION_BRIDGE_CACHE_MAX 按插入序 FIFO 淘汰最旧。 */
+const VISION_BRIDGE_CACHE_MAX = 256;
 const visionBridgeCache = new Map();
+function cacheVisionTranscript(key, value) {
+    visionBridgeCache.set(key, value);
+    if (visionBridgeCache.size > VISION_BRIDGE_CACHE_MAX) {
+        // Map 迭代序 = 插入序，第一个 key 即最旧。
+        const oldest = visionBridgeCache.keys().next().value;
+        if (oldest !== undefined)
+            visionBridgeCache.delete(oldest);
+    }
+}
 /** "provider/id" 解析；非法格式返回 null。 */
 export function parseModelSpec(spec) {
     if (!spec)
@@ -25,9 +38,6 @@ export async function buildAttachmentMessages(ctx, attachments) {
     const { resolve, sep, relative, extname, basename } = await import("node:path");
     const root = resolve(ctx.cwd);
     const MAX_ATTACHMENT_BYTES = 200 * 1024;
-    // Files at or below this size are inlined; larger files are referenced by
-    // path only (the model reads them on demand — saves tokens for small edits).
-    const MAX_INLINE_BYTES = Number(process.env.PI_WEB_INLINE_FILE_MAX ?? 12 * 1024);
     const IMAGE_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".svg"]);
     const MIME = {
         ".png": "image/png",
@@ -40,55 +50,30 @@ export async function buildAttachmentMessages(ctx, attachments) {
     };
     const out = [];
     /** Push the aside for a raw uploaded file (fresh fileData or a restored
-     *  uploadPath re-read from disk). Small text files are inlined so the
-     *  model sees them immediately; everything else becomes a path reference.
+     *  uploadPath re-read from disk). Uploads are NEVER inlined: the model gets
+     *  the persisted absolute path and reads it on demand with its read tool.
      *  `upload: true` marks the card as a restorable upload — the browser
      *  re-sends it by path when editing & re-asking a question. */
     const pushUploadAside = (name, wirePath, buf) => {
-        if (buf.length <= MAX_INLINE_BYTES && looksLikeText(buf)) {
-            const lines = countLines(buf);
-            out.push({
-                message: {
-                    customType: "file",
-                    content: [
-                        {
-                            type: "text",
-                            text: `\n<file path="${wirePath}">\n\`\`\`\n${decodeText(buf)}\n\`\`\`\n</file>`,
-                        },
-                    ],
-                    display: true,
-                    details: {
-                        name,
-                        path: wirePath,
-                        mode: "inline",
-                        size: buf.length,
-                        lines,
-                        upload: true,
-                    },
-                },
-            });
-        }
-        else {
-            out.push({
-                message: {
-                    customType: "file",
-                    content: [
-                        {
-                            type: "text",
-                            text: `<file path="${wirePath}" size="${buf.length}" />`,
-                        },
-                    ],
-                    display: true,
-                    details: {
-                        name,
-                        path: wirePath,
-                        mode: "reference",
-                        size: buf.length,
-                        upload: true,
+        out.push({
+            message: {
+                customType: "file",
+                content: [
+                    {
+                        type: "text",
+                        text: `<file path="${wirePath}" size="${buf.length}" />`,
                     },
+                ],
+                display: true,
+                details: {
+                    name,
+                    path: wirePath,
+                    mode: "reference",
+                    size: buf.length,
+                    upload: true,
                 },
-            });
-        }
+            },
+        });
     };
     // -- Vision bridge ------------------------------------------------------
     // When the active model can't accept images (DeepSeek, GLM, …), pasted
@@ -221,7 +206,7 @@ export async function buildAttachmentMessages(ctx, attachments) {
                             systemPrompt: buildVisionBridgePrompt(ctx.settings.visionBridgePromptMode, ctx.settings.visionBridgePrompt, vLang),
                             lang: vLang,
                         });
-                        visionBridgeCache.set(batchHash, transcript);
+                        cacheVisionTranscript(batchHash, transcript);
                         ctx.emit({
                             type: "notice",
                             level: "info",
@@ -244,8 +229,6 @@ export async function buildAttachmentMessages(ctx, attachments) {
             }
         }
     }
-    /** Cap for reading a file in "lines" mode (selected slice is inlined). */
-    const MAX_LINES_READ_BYTES = 2 * 1024 * 1024;
     for (const [idx, att] of attachments.entries()) {
         // Quoted conversation (left-panel right-click / global-search quote):
         // `path` is unused — the reference travels in conversationId (running
@@ -343,6 +326,16 @@ export async function buildAttachmentMessages(ctx, attachments) {
                 });
                 continue;
             }
+            let attachmentUrl;
+            let attachmentHash;
+            try {
+                const rec = await saveAttachment(Buffer.from(raw, "base64"), mimeType);
+                attachmentUrl = rec.url;
+                attachmentHash = rec.hash;
+            }
+            catch {
+                /* CAS 保存失败不阻断流程 */
+            }
             const transcript = bridgeTranscripts.get(idx);
             if (transcript) {
                 // Bridged: the text-only main model can't see images, so it gets the
@@ -356,7 +349,12 @@ export async function buildAttachmentMessages(ctx, attachments) {
                                 type: "text",
                                 text: `\n<vision-bridge>\n${transcript}\n</vision-bridge>`,
                             },
-                            { type: "image", data: raw, mimeType },
+                            {
+                                type: "image",
+                                data: raw,
+                                mimeType,
+                                ...(attachmentUrl ? { source: { type: "url", url: attachmentUrl } } : {}),
+                            },
                         ],
                         display: true,
                         details: {
@@ -364,6 +362,8 @@ export async function buildAttachmentMessages(ctx, attachments) {
                             path: undefined,
                             mode: "bridged",
                             size: bytes,
+                            attachmentUrl,
+                            attachmentHash,
                         },
                     },
                 });
@@ -372,7 +372,14 @@ export async function buildAttachmentMessages(ctx, attachments) {
             out.push({
                 message: {
                     customType: "file",
-                    content: [{ type: "image", data: raw, mimeType }],
+                    content: [
+                        {
+                            type: "image",
+                            data: raw,
+                            mimeType,
+                            ...(attachmentUrl ? { source: { type: "url", url: attachmentUrl } } : {}),
+                        },
+                    ],
                     display: true,
                     details: {
                         name: att.name ?? "image.png",
@@ -380,6 +387,8 @@ export async function buildAttachmentMessages(ctx, attachments) {
                         path: undefined,
                         mode: "image",
                         size: bytes,
+                        attachmentUrl,
+                        attachmentHash,
                     },
                 },
             });
@@ -388,9 +397,7 @@ export async function buildAttachmentMessages(ctx, attachments) {
         // Raw uploaded file (base64) — no workspace path involved. The bytes are
         // persisted under <dataDir>/uploads/<clientId>/ so the model can read
         // them on demand with its read tool (absolute path, no traversal guard
-        // needed — the path is server-generated). Small text uploads are inlined
-        // so the model sees them immediately; everything else becomes a path
-        // reference.
+        // needed — the path is server-generated). Always a path reference.
         if (att.fileData) {
             const buf = Buffer.from(att.fileData, "base64");
             const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
@@ -415,7 +422,22 @@ export async function buildAttachmentMessages(ctx, attachments) {
             // Uploaded files live in a GLOBAL per-user dir (not inside the project
             // or the per-client session store) so browsing a repo never picks up
             // uploaded junk: <dataDir>/uploads/<clientId>/（保留期自动清理，见 uploads.ts）。
-            const { abs, displayName: safeName } = saveUpload(ctx.clientId, att.name ?? "file", buf);
+            // saveUpload 对非法 clientId/displayName 抛错（消毒失败整条拒绝，绝不
+            // 落到别的目录）—— 这里报错跳过该附件，不让一条坏附件中断整条消息。
+            let saved;
+            try {
+                saved = saveUpload(ctx.clientId, att.name ?? "file", buf);
+            }
+            catch (err) {
+                ctx.emit({
+                    type: "notice",
+                    level: "error",
+                    text: `上传文件保存失败，已跳过：${err.message}`,
+                    textEn: `Failed to save uploaded file, skipped: ${err.message}`,
+                });
+                continue;
+            }
+            const { abs, displayName: safeName } = saved;
             // Wire format: forward-slash absolute path (the read tool accepts
             // absolute paths; Windows uses "C:/..." — safe inside the XML-ish tag).
             const wirePath = abs.split(sep).join("/");
@@ -601,6 +623,7 @@ ${transcript}
             });
             continue;
         }
+        /** Path-only aside — no file content is read or injected. */
         const makeReference = () => ({
             message: {
                 customType: "file",
@@ -614,36 +637,12 @@ ${transcript}
                 details: { name, path: rel, mode: "reference", size: stat.size },
             },
         });
-        const makeInline = (buf) => {
-            const lines = countLines(buf);
-            return {
-                message: {
-                    customType: "file",
-                    content: [
-                        {
-                            type: "text",
-                            text: `\n<file path="${rel}">\n\`\`\`\n${decodeText(buf)}\n\`\`\`\n</file>`,
-                        },
-                    ],
-                    display: true,
-                    details: {
-                        name,
-                        path: rel,
-                        mode: "inline",
-                        size: stat.size,
-                        lines,
-                    },
-                },
-            };
-        };
-        // Reference mode is always honored and never reads the file.
-        if (att.mode === "reference") {
-            out.push(makeReference());
-            continue;
-        }
-        // Line-range mode: inline only the selected 1-based inclusive range.
-        // Reading is capped so a huge file can't exhaust memory even though
-        // the selected slice is small.
+        // Everything else is a PATH REFERENCE: the file content is never injected
+        // into the prompt (small files included) — the model reads what it needs
+        // with its own read tool (built-in truncation/pagination).
+        // Line-range mode adds the `lines` attribute so the model knows which
+        // slice the user picked and only reads that part.
+        // A legacy `mode: "inline"` (old client / persisted draft) lands here too.
         if (att.mode === "lines") {
             const range = att.lines;
             if (!range || range.start < 1 || range.end < range.start) {
@@ -656,52 +655,13 @@ ${transcript}
                 out.push(makeReference());
                 continue;
             }
-            if (stat.size > MAX_LINES_READ_BYTES) {
-                ctx.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `文件过大，已改为仅引用：${att.path}`,
-                    textEn: `File too large, switched to reference-only: ${att.path}`,
-                });
-                out.push(makeReference());
-                continue;
-            }
-            const buf = await fs.readFile(abs);
-            if (buf.includes(0)) {
-                ctx.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `二进制文件已改为仅引用：${att.path}`,
-                    textEn: `Binary file, switched to reference-only: ${att.path}`,
-                });
-                out.push(makeReference());
-                continue;
-            }
-            const parts = decodeText(buf).split("\n");
-            // A trailing newline yields an empty phantom line — drop it so line
-            // numbers match the preview panel.
-            if (parts.length > 0 && parts[parts.length - 1] === "")
-                parts.pop();
-            const start = Math.min(range.start, parts.length);
-            const end = Math.min(range.end, parts.length);
-            if (start < 1 || end < start) {
-                ctx.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `选中行超出文件范围，已改为仅引用：${att.path}`,
-                    textEn: `Selected lines out of range, switched to reference-only: ${att.path}`,
-                });
-                out.push(makeReference());
-                continue;
-            }
-            const selected = parts.slice(start - 1, end).join("\n");
             out.push({
                 message: {
                     customType: "file",
                     content: [
                         {
                             type: "text",
-                            text: `\n<file path="${rel}" lines="${start}-${end}">\n\`\`\`\n${selected}\n\`\`\`\n</file>`,
+                            text: `<file path="${rel}" lines="${range.start}-${range.end}" size="${stat.size}" />`,
                         },
                     ],
                     display: true,
@@ -710,57 +670,15 @@ ${transcript}
                         path: rel,
                         mode: "lines",
                         size: stat.size,
-                        lines: end - start + 1,
-                        startLine: start,
-                        endLine: end,
+                        lines: range.end - range.start + 1,
+                        startLine: range.start,
+                        endLine: range.end,
                     },
                 },
             });
             continue;
         }
-        // Forced inline has a hard cap to protect the model context.
-        if (att.mode === "inline") {
-            if (stat.size > MAX_INLINE_BYTES) {
-                ctx.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `文件过大，已改为仅引用：${att.path}`,
-                    textEn: `File too large, switched to reference-only: ${att.path}`,
-                });
-                out.push(makeReference());
-                continue;
-            }
-            const buf = await fs.readFile(abs);
-            if (buf.includes(0)) {
-                ctx.emit({
-                    type: "notice",
-                    level: "warning",
-                    text: `二进制文件已改为仅引用：${att.path}`,
-                    textEn: `Binary file, switched to reference-only: ${att.path}`,
-                });
-                out.push(makeReference());
-                continue;
-            }
-            out.push(makeInline(buf));
-            continue;
-        }
-        // Auto: small files inline, large files reference by path.
-        if (stat.size > MAX_INLINE_BYTES) {
-            out.push(makeReference());
-            continue;
-        }
-        const buf = await fs.readFile(abs);
-        if (buf.includes(0)) {
-            ctx.emit({
-                type: "notice",
-                level: "warning",
-                text: `二进制文件已跳过（仅引用路径）：${att.path}`,
-                textEn: `Binary file skipped (path referenced only): ${att.path}`,
-            });
-            out.push(makeReference());
-            continue;
-        }
-        out.push(makeInline(buf));
+        out.push(makeReference());
     }
     return out;
 }

package/dist/server/bg-servers.js

@@ -66,7 +66,13 @@ export function shouldTrackBackgroundServer(pid, parents, newPids, serverPid, na
 export class BgServerTracker {
     opts;
     servers = new Map();
-    /** bash 工具开始执行前拍的监听端口快照（tool_execution_start 时设置）。 */
+    /**
+     * bash 工具开始执行前拍的监听端口快照（tool_execution_start 时设置）。
+     * 槽位存「in-flight Promise」而非已解析的 Map：并发 bash 同时开跑时不互相
+     * 覆盖（??= 保住最早的一份——更早的基线只会多算新增，落库有去重兜底），
+     * 也修掉 fire-and-forget 时序竞态（bash 先于快照返回结束 → trackAfterBash
+     * 读到 null 直接漏记，延迟解析的旧快照还会污染下一轮）。
+     */
     listenBefore = null;
     refreshTimer = null;
     constructor(opts) {
@@ -83,20 +89,21 @@ export class BgServerTracker {
             this.refreshTimer = null;
         }
     }
-    /** tool_execution_start(bash)：先记下「前」快照。 */
+    /** tool_execution_start(bash)：先记下「前」快照（快照在途时保留最早的一份）。 */
     snapshotBefore() {
-        void snapshotListeningPorts().then((m) => {
-            this.listenBefore = m;
-        });
+        this.listenBefore ??= snapshotListeningPorts();
     }
     /** After a bash tool run, wait briefly for background servers to bind,
      *  then diff the listening-port snapshot against the pre-run one and
      *  remember anything new — those are servers the agent left running. */
     async trackAfterBash() {
-        const before = this.listenBefore;
+        // 读后清槽：await in-flight 快照（消除 fire-and-forget 的时序竞态），
+        // 并发 bash 共用这份最早的基线，各自结束都能对得上。
+        const beforePromise = this.listenBefore;
         this.listenBefore = null;
-        if (!before)
+        if (!beforePromise)
             return;
+        const before = await beforePromise;
         await new Promise((r) => setTimeout(r, BG_BIND_WAIT_MS));
         const after = await snapshotListeningPorts();
         const fresh = [];
@@ -198,6 +205,22 @@ export class BgServerTracker {
         await this.refresh();
         this.push();
     }
+    /** 杀前复核端口→pid 归属（与 refresh() 同一判定：端口与 pid 都对得上才算我们的）。
+     *  缓存的 pid 可能已过期——原进程退出后端口被无关进程复用时，按缓存 pid 直接
+     *  killPidTree 会误伤无辜进程树。不符的条目剔除并推送，绝不对其开杀。 */
+    async verifyBeforeKill() {
+        const now = await snapshotListeningPorts();
+        let changed = false;
+        // eslint-disable-next-line unicorn/no-useless-spread -- snapshot: handlers may unsubscribe mid-emit
+        for (const [port, v] of [...this.servers]) {
+            if (now.get(port) !== v.pid) {
+                this.servers.delete(port);
+                changed = true;
+            }
+        }
+        if (changed)
+            this.push();
+    }
     /** Kill ONE background server (by port); returns whether anything was killed. */
     async killOne(port) {
         const entry = this.servers.get(port);
@@ -211,6 +234,18 @@ export class BgServerTracker {
             this.opts.flushSnapshot();
             return false;
         }
+        await this.verifyBeforeKill();
+        const verified = this.servers.get(port);
+        if (!verified || verified.pid !== entry.pid) {
+            this.opts.emit({
+                type: "notice",
+                level: "warning",
+                text: `端口 ${port} 已不在原进程（原 pid ${entry.pid}）监听，已跳过并刷新列表`,
+                textEn: `Port ${port} is no longer held by the original process (pid ${entry.pid}); skipped and list refreshed`,
+            });
+            this.opts.flushSnapshot();
+            return false;
+        }
         killPidTree(entry.pid);
         this.servers.delete(port);
         this.push();
@@ -225,6 +260,9 @@ export class BgServerTracker {
     }
     /** Kill every background server the agent started; returns the freed ports. */
     async killAll() {
+        if (this.servers.size === 0)
+            return [];
+        await this.verifyBeforeKill();
         if (this.servers.size === 0)
             return [];
         const killed = [];

package/dist/server/claim-files-tool.js

@@ -12,7 +12,7 @@
 // ---------------------------------------------------------------------------
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { bilingual, pick } from "./i18n.js";
+import { pick } from "./i18n.js";
 import { CLAIM_FILES_TOOL_NAME } from "./tool-manager.js";
 import { CLAIM_TTL_MS, resolveClaimPath } from "./claim-store.js";
 /** 工具名（唯一定义在 tool-manager.ts，本模块 re-export 供单测沿用，模式同 present-files-tool.ts）。 */
@@ -30,13 +30,9 @@ export function makeClaimFilesTool(host, lang) {
     return defineTool({
         name: CLAIM_FILES_TOOL_NAME,
         label: "Claim files to avoid parallel conflicts",
-        description: bilingual("Declare which files you are about to edit so parallel runs in the same project can steer clear (advisory only — it never blocks edits). " +
-            "action=claim reserves paths for THIS conversation (first wins; already claimed by others is reported, not overridden); action=release frees yours (no paths = all yours); action=list shows this project's claim table. " +
-            "Claims expire after ~30 min idle (each of your prompts refreshes them) and are released when the conversation closes. " +
-            "Paths must stay inside the project directory. Only pi-engine conversations can claim (no customTool surface on DSH).", "声明你要改哪些文件，让同项目的并行对话绕行（纯建议，不拦任何编辑）。" +
-            "action=claim 把路径记到本对话名下（先到先得；别人已认领的会告诉你，不抢占）；action=release 放掉你自己的（不给 paths = 全放）；action=list 看本项目的认领表。" +
-            "认领闲置约 30 分钟过期（你每次发 prompt 自动续期），对话关闭时释放。" +
-            "路径必须在项目目录内。只有 pi 引擎对话能认领（DSH 无 customTool 注册面）。"),
+        description: "Declare files you are about to edit so parallel runs in the same project steer clear (advisory only — never blocks edits). " +
+            "claim reserves paths for THIS conversation (first wins; conflicts reported, not overridden); release frees yours (no paths = all yours); list shows the project's claim table. " +
+            "Claims expire after ~30 min idle (your prompts refresh them) and release when the conversation closes. Paths must stay inside the project.",
         promptSnippet: "claim files you are about to edit (advisory, first-wins) so parallel runs steer clear",
         parameters: Type.Object({
             action: Type.Optional(Type.String({ description: 'claim = reserve paths; release = free yours; list = show table. Default "list".' })),

package/dist/server/claim-store.js

@@ -212,7 +212,8 @@ export class ClaimStore {
     save() {
         try {
             mkdirSync(dirname(this.file), { recursive: true });
-            const tmp = `${this.file}.tmp`;
+            // tmp 带进程唯一后缀：同机多实例（多 worktree/多开）写同一文件不互踩
+            const tmp = `${this.file}.${process.pid}.tmp`;
             writeFileSync(tmp, JSON.stringify({ version: CLAIMS_FILE_VERSION, tables: Object.fromEntries(this.tables) }));
             renameSync(tmp, this.file);
         }
@@ -280,7 +281,8 @@ export async function mergeTouchSidecar(sessionFile, fresh) {
         return;
     try {
         const merged = unionTouchLists(readTouchSidecar(sessionFile) ?? [], fresh).slice(0, SIDECAR_MAX_ENTRIES);
-        const tmp = `${sidecarPath(sessionFile)}.tmp`;
+        // tmp 带进程唯一后缀（同 client-state.ts 惯例）：避免并发进程互踩
+        const tmp = `${sidecarPath(sessionFile)}.${process.pid}.tmp`;
         writeFileSync(tmp, JSON.stringify({ version: 1, updatedAt: Date.now(), files: merged }));
         renameSync(tmp, sidecarPath(sessionFile));
     }