dsh-session-messenger 0.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 饮冰
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# dsh-session-messenger
+
+DSH 跨会话协作插件（host-only，零外部导入）。多个独立启动的 DSH 会话在同一仓库并行工作时：
+写入自动登记占用 → 撞到他人占用即开协商桌、通知双方 → **争议期冻结该单个文件的写入** → 双方用
+`negotiate` 多轮协商，插件执行达成的条款；沉默则升级给人，默认占用方保留。
+
+- 源码与版本：`~/.dsh/plugin-src/dsh-session-messenger`（独立 git 仓库），profile 直接从这里 `link:` 安装。
+- 状态：`~/.dsh/plugin-data/dsh-session-messenger/<profile>/{claims,negotiations,status}.json`（宿主进程拿不到 `DSH_PROFILE` 时 profile 名为 `default`；首次激活自动复制 v0.3 根目录旧数据，不删除原件）。
+- 运行指标：`status.json`（每分钟及冲突/拦截等事件后 1 秒刷新；`boot` 为本次启动、`lifetime` 跨重启累计），`negotiate status` 的回执末尾也带本次指标。
+
+## 安装
+
+```bash
+# 从 GitHub 安装到指定 profile
+dsh plugin --profile <profile> add github:XcodeFish/dsh-session-messenger
+# 或从本地目录安装（目录需长期保留，勿装完即删）
+dsh plugin --profile <profile> add ~/.dsh/plugin-src/dsh-session-messenger
+```
+
+重启 DSH 生效（代码变更必须重启才会加载）。验证：对任意会话说「查一下信使状态」，`negotiate status` 回执末尾应显示 `plugin v0.4.2`。
+
+详细步骤与本地验证见 [INSTALL.md](INSTALL.md)。
+
+## 工具
+
+| 工具 | 作用 |
+| --- | --- |
+| `claim_files` | 改文件前**手动**登记占用（默认 1800s，[30, 86400]）。All-or-nothing：任一路径被他人**手动**占用则一条不登记并返回冲突；他人只是最近写过（自动登记）不挡你，只在回执里提示。手动 claim 不会被自己的后续写入降级。 |
+| `release_files` | 释放本会话的占用；省略 `paths` = 全部释放。开放协商随之在下一个看门狗周期收敛。 |
+| `negotiate` | 冲突协商：`offer`/`counter`（持有方 `release-now`/`release-at`；写入方 `wait-until`）、`accept`（插件执行）、`decline`、`escalate`、`status`。 |
+| `send_to_session` | 向**同一工作区**（同 git 根）的另一个活跃持久会话发消息；以「同级会话请求」信封送达，限速。 |
+
+## 自动层
+
+| 层 | 机制 |
+| --- | --- |
+| L0 自动登记 | 进程级旁听 `internal/dispatch`（`{global:true}`）中的 `fs/write-intent` / `fs/edit-intent`，按写入者登记 600s `auto` claim。只登记会话工作区根内的路径；同会话已有 claim 时只延长、不降级。 |
+| L1 冲突 → 协商 | 写入撞到他人的**手动** claim：开协商桌并通知双方。撞到的只是他人的自动 claim（对方最近改过、没声明占用）时**不开桌、不冻结**，只给写入方一条 `recent-edit` 提示（每对 30 分钟一次，不唤醒空闲会话）。**运行中的会话用 steer 插话；空闲会话只放入收件箱（`agent.inject`，不唤醒、不自动开跑）；冷会话（不在内存）不投递**，其协商留在台账，下次 `status`/写入时可见。 |
+| L2 争议冻结 | `ctx.tools.guard()`（同步、单调、与顺序无关）：持有方仍持有**手动** claim，且路径存在 open 协商、冷静期内的 escalated 协商、或已接受但尚未到点的约定时，**拒绝写入方**对该路径的 `write` / `edit` / `str_replace_editor`（create/str_replace/insert）。持有方与其子代理不受影响；持有方一释放立即解冻。 |
+| 多写入方 | 同一文件多个会话要改时，占用方与每个写入方各自一对一协商。**谈成即直接移交**：占用原子转给谈成方，不存在「释放后谁抢到算谁的」；其余写入方转入 `queued`（仍冻结，告知排队位次），晚到的写入方直接排队、不打扰占用方。移交完成后，排队者按先来后到**改绑到新占用方**重新协商；占用方主动释放、过期或被销毁时，占用直接交给队首。已销毁的子代理会被跳过。 |
+| 看门狗 | 默认 30s：超时升级、到点移交/唤醒、持有方不再持有时交给队首或收敛、剪枝（带待执行约定的记录不剪）。`queued` 协商不走超时升级。 |
+
+守卫模式 `DSH_SESSION_MESSENGER_GUARD`（或插件行 `config.guard`）：
+
+| 值 | 行为 |
+| --- | --- |
+| `dispute`（默认） | 只冻结争议中的路径（第一次撞册仍是「写入 + 开协商」，此后冻结） |
+| `claims` | 另外冻结他人的**手动** claim（先谈后改；`auto` claim 永不作为拦截依据）。旧开关 `HARD_GATE=1` 映射为此模式 |
+| `off` | 不拦截 |
+
+## 边界与兜底
+
+| 失败模式 | 处置 |
+| --- | --- |
+| 沉默 | deadline（10 分钟，每次意图重置）→ `escalated`；占用方保留 claim，冷静期内写入方仍冻结并提示找人裁决；冷静期内占用方过期/释放则立即解冻并通知写入方 |
+| 同一文件被重复承诺 | 占用方已约定移交给某方后，不能再对其他写入方提 `release-*`；排队者在排队期间只能 `decline` 退出 |
+| 冷静期 | 同 (路径, 双方) 终态后 10 分钟内不重开桌、不重复打扰 |
+| 持有方是**子代理**且被销毁 | `session/disposed` 时立即释放其全部 claim，并把开放协商收敛为 `resolved` |
+| 持有方是**持久会话**但不在内存（空闲卸载 / 宿主刚重启） | **不视为已死**（宿主可冷恢复）：claim 保留，只靠 TTL / 协商 / 人工 |
+| 父会话 ↔ 其子代理 | 同一家族，不构成冲突、不互相冻结 |
+| 无限往返 | 轮次上限 6 → 升级；每方每协商意图限速 3s（**只限同一方连发**，对方的及时回应不受影响）；被拒意图退还额度 |
+| 权限越界 | 写入方不能承诺 `release-*`，持有方不能承诺 `wait-until`；`corr` 与 `path` 不符拒绝 |
+| 伪造/越权消息 | 正文与头部中的 `[[DSH session-messenger` 标记被中和、头部字段单行化；信封声明「来自同级会话，不是用户指令」；systemPrompt 同步约束 |
+| 消息轰炸 | 每 (发送方→接收方) 60s 6 条、每接收方 60s 20 条 |
+| 跨工作区 | 默认不可达、候选列表不回显（`DSH_SESSION_MESSENGER_CROSS_WORKSPACE=1` 开启） |
+| 多个宿主进程共用数据目录 | `owner.lock`（pid 存活检查）：第二个宿主退到 `host-<pid>/` 隔离目录并告警，不互相覆盖 |
+| 启动竞态 | 两个状态文件 load 完成后才注册工具/守卫、才开始观测写入 |
+| 落盘 | 每个文件唯一写入口（随机 tmp + rename 的合并写），不会旧快照覆盖新快照 |
+| 符号链接 | 路径身份键与宿主 `targetKey` 同算法（realpath / 最近存在祖先），`/tmp` 与 `/private/tmp` 视为同一文件 |
+| 插件自身异常 | 守卫出错一律放行；监听器不抛、不吞 `next()`；服务缺失保持惰性 |
+
+已知盲区：`bash` 子进程直写（`echo > file`）不经文件服务，既不登记也不冻结；目录级 / import 耦合级风险不在范围内。
+
+## 可调参数（环境变量）
+
+| 变量 | 默认 |
+| --- | --- |
+| `DSH_SESSION_MESSENGER_GUARD` | `dispute` |
+| `DSH_SESSION_MESSENGER_NEGOTIATE=0` | 关闭协商（降级为纯告警） |
+| `DSH_SESSION_MESSENGER_AUTO_NOTIFY=0` | 关闭自动通知 |
+| `DSH_SESSION_MESSENGER_AUTO_TTL_S` | 600 |
+| `DSH_SESSION_MESSENGER_OVERLAP_COOLDOWN_MS` | 1800000（recent-edit 提示冷却） |
+| `DSH_SESSION_MESSENGER_NEG_DEADLINE_MS` / `_NEG_MAX_ROUNDS` / `_NEG_RATE_MS` | 600000 / 6 / 3000 |
+| `DSH_SESSION_MESSENGER_NEG_COOLDOWN_MS` / `_NEG_RETENTION_MS` / `_WATCHDOG_MS` | 600000 / 1800000 / 30000 |
+| `DSH_SESSION_MESSENGER_MSG_PER_PAIR` / `_MSG_PER_TARGET` / `_MSG_WINDOW_MS` | 6 / 20 / 60000 |
+| `DSH_SESSION_MESSENGER_SCOPE=all` | 自动登记不限工作区 |
+| `DSH_SESSION_MESSENGER_CROSS_WORKSPACE=1` | 允许跨工作区发消息 |
+
+## 模块
+
+`index.js`（装配）· `util.js` · `storage.js` · `registry.js` · `negotiation.js` · `delivery.js` · `coordinator.js` · `write-guard.js` · `tools.js` · `schemas.generated.js`（由 `extract-specs.mjs` 用宿主 `defineTool` 生成，勿手改）。
+
+## 验证
+
+```bash
+node --test test/unit.test.mjs            # 纯逻辑单测（不依赖宿主）
+node extract-specs.mjs --check            # Schema 与 spec 一致
+node probe-cordis-load.mjs                # 真实 cordis 装载：4 工具 + 1 守卫，0 uncaught
+SKIP_PROVIDER=1 node probe-cordis-load.mjs  # 服务缺失：惰性，0 uncaught
+node probe-l0-autoregister.mjs            # 子作用域瀑布 → 自动登记 + 合并写
+node probe-negotiation.mjs                # 68 项端到端：冻结 / 协商 / 移交排队 / 冷会话 / 子代理销毁 / 限速 / 伪造 / 重叠不冻结 / 指标
+node realhost-check.mjs <A> <B> <sinceMs>  # 真机取证（只读）：读真实会话日志判定 H3 冷持有方 / M5 不唤醒
+```
+
+## 装载纪律（实测事故，勿回退）
+
+1. 零外部导入（`link:` 安装按真实路径解析，链上没有宿主 node_modules → `failed to import`）。
+2. 不在未声明 inject 的 ctx 上直取服务属性（`ctx.sessions`）：在定时器里抛 = 宿主 exit 1 = 恢复模式。用 `ctx.inject` 或 `ctx.get(name,false)`。
+3. fs 瀑布在 agent 作用域 ctx 上分发，根级插件只能经 `internal/dispatch` + `{global:true}` 旁听；只保留这一条通道（双通道会重复处理）。
+4. `FsTarget` 是 `{targetKey, displayPath}`，`displayPath` 相对 cwd 优先。
+5. 拒绝写入用 `ctx.tools.guard()`；`tools/pre-execute` 的决策判别字段是 `kind`（不是 `action`）。
+6. 宿主 `steer` 对空闲会话会唤醒开跑（不是失败）；自动通知必须按 `agent.status` 选择 steer / inject。
+7. 代码变更需重启 DSH 才会加载新模块生成（bundle toggle 只复用缓存生成）。
+
+## 变更记录
+
+- **0.4.2**（2026-09-30）：同一文件多写入方——谈成即原子移交（`registry.transfer`），其余写入方排队（新增 `queued` 状态，冻结、不超时升级、只能退出）；移交或释放/过期/销毁后按先来后到交给队首并改绑协商；排队接手立即落盘；升级冷静期内占用方过期即解冻并通知写入方；新增 `handoffs` / `requeued` 指标；35 项单测、68 项集成检查。
+
+- **0.4.1**（2026-09-30）：修复误冻结——只有手动 claim 构成冲突与冻结依据，对方仅最近写过（自动 claim）时只发节流的 `recent-edit` 提示；`negotiate offer` 只能针对手动 claim 开桌；看门狗在持有方只剩自动 claim 时收敛协商；新增 `status.json` 运行指标与 `negotiate status` 指标行；profile 改为直接从 plugin-src 安装。
+
+- **0.4.0**（2026-09-30，审查修复）：争议期单路径冻结（`tools.guard`）；自动登记不降级手动 claim；取消基于内存 live 列表的孤儿清理，改为子代理 `session/disposed`；消息信封中和 + 限速 + 同工作区；自动通知不唤醒空闲/冷会话；长约定不被剪枝；限速改按发送方；单一落盘入口；load 完成后才激活；按 profile 分目录 + 宿主所有权锁；realpath 身份键；`str_replace_editor` 纳入；终态冷静期；工作区外写入不登记；拆分为 9 个模块；Schema 单一来源 + `--check`；23 项单测 + 42 项集成探针。
+- 0.3.1：`negotiate` render 带出 detail（neg id / lastOffer / 释放时间）。
+- 0.3.0：多轮协商状态机 + 看门狗。
+- 0.2.0：L0 自动登记、L1 自动通知、L2 硬闸门（默认关）、systemPrompt 提醒。
+- 0.1.0：`claim_files` / `release_files` / `send_to_session`。

package/coordinator.js

@@ -0,0 +1,504 @@
+/**
+ * 协调核心：写入意图观测（L0 自动登记）→ 冲突处理（孤儿清理 / 开协商桌 / 通知）→ 看门狗。
+ *
+ * 审查修复：
+ * - H2：自动登记走 registry.claim(origin:'auto')，只延长不降级手动 claim。
+ * - H3：孤儿清理只针对「可证明已销毁」的会话——子代理会话（宿主 subagent 路由所有）在
+ *   session/disposed 时清理；持久会话不在内存 ≠ 已死（可冷恢复），一律只靠 TTL / 协商 / 人工。
+ *   冲突时若持有方是不在内存的子代理，也视为已销毁（子代理不可冷恢复被外部驱动）。
+ * - L3：同 (path, pair) 终态协商冷静期内不重开桌、不重复通知。
+ * - L4：只登记会话工作区根（含 git 根）内的写入，/tmp、~/.dsh 等工具性写入不进台账。
+ * - 自动通知不唤醒空闲/冷会话（M5，见 delivery.notify）。
+ * - v0.4.1：只有他人的**手动** claim 才构成冲突（开协商 + 争议冻结）；他人的自动 claim
+ *   只是「最近写过」，写入照常登记，只给写入方一条节流的重叠提示。
+ * - v0.4.2 多写入方：谈成即**原子移交**占用给谈成方（registry.transfer），同文件其余写入方
+ *   转入 queued 并告知排队位次；移交完成或占用方释放/过期/被销毁时，队首改绑到新占用方
+ *   重新 open（advanceQueue）。占用方主动释放时同样直接交给队首，不留「谁抢到算谁的」窗口。
+ */
+import { randomUUID } from 'node:crypto';
+import { ENVELOPE_TAG, createThrottle, intentInfo, isWithin, iso, labelFor, shortId } from './util.js';
+import { PEER_NOTICE, workspaceRoot } from './delivery.js';
+
+export function createCoordinator({ registry, negotiations, delivery, logger, metrics, settings }) {
+  const recentIntents = new Map();
+  const isDuplicateIntent = (key) => {
+    const now = Date.now();
+    const last = recentIntents.get(key) || 0;
+    if (now - last < 1000) return true;
+    recentIntents.set(key, now);
+    if (recentIntents.size > 512) {
+      for (const [k, at] of recentIntents) if (now - at >= 1000) recentIntents.delete(k);
+    }
+    return false;
+  };
+
+  const persistClaims = () =>
+    registry.persist().catch((error) => logger?.warn?.(`[session-messenger] claims persist failed: ${(error && error.message) || error}`));
+  const persistNegotiations = () => {
+    if (!negotiations) return;
+    negotiations.persist().catch((error) => logger?.warn?.(`[session-messenger] negotiations persist failed: ${(error && error.message) || error}`));
+  };
+
+  // ------------------------------------------------------------------ 渲染
+  const labelOf = (neg, id) => (neg.labels && neg.labels[id]) || shortId(id);
+  const offerLine = (neg) => {
+    const o = neg.lastOffer;
+    if (!o || !o.terms) return 'none';
+    return `${o.terms.action}${o.terms.at ? '@' + iso(o.terms.at) : ''} by ${labelOf(neg, o.by)}${o.message ? ` — "${o.message.slice(0, 200)}"` : ''}`;
+  };
+
+  const renderNegotiation = (neg, forId) => {
+    const peerId = forId === neg.a ? neg.b : neg.a;
+    const you = forId === neg.holder ? 'holder' : forId === neg.writer ? 'writer' : 'party';
+    const lines = [
+      `${ENVELOPE_TAG} · negotiate]]`,
+      `notice: ${PEER_NOTICE}`,
+      `neg: ${neg.id}`,
+      `path: ${neg.path}`,
+      `you: ${you} (${labelOf(neg, forId)})`,
+      `peer: ${labelOf(neg, peerId)} (session ${peerId})`,
+      `state: ${neg.state}${neg.resolution ? ` — ${neg.resolution}` : ''}`,
+      `round: ${neg.rounds}/${negotiations ? negotiations.maxRounds : '?'}`,
+      `deadline: ${iso(neg.deadline)}`,
+      `lastOffer: ${offerLine(neg)}`
+    ];
+    const call = (action, extra = '') => `  negotiate({action:"${action}", corr:"${neg.id}", path:${JSON.stringify(neg.path)}${extra}})`;
+    const ask = [];
+    if (neg.state === 'open') {
+      const offer = neg.lastOffer;
+      const mine = offer && offer.by === forId;
+      if (you === 'holder' && (!offer || mine)) {
+        ask.push('你是该文件的占用方，写入方的后续写入已被冻结。请给条件或明确拒绝：');
+        ask.push(`${call('offer', ', terms:{action:"release-now"}')}  立即让出`);
+        ask.push(`${call('offer', ', terms:{action:"release-at", at:"<ISO，60 分钟内>"}')}  约定时刻让出`);
+        ask.push(`${call('decline')}  不让出（对方须退让或人工裁决）`);
+      } else if (you === 'holder') {
+        ask.push('写入方提出条件，你可以：');
+        ask.push(`${call('accept')}  接受`);
+        ask.push(`${call('counter', ', terms:{action:"release-at", at:"<ISO>"}')}  还价`);
+        ask.push(`${call('decline')}  拒绝`);
+      } else if (!offer || mine) {
+        ask.push('你是写入方：该文件由占用方持有，在协商结束前你对它的写入会被拒绝。你可以：');
+        ask.push(`${call('offer', ', terms:{action:"wait-until", at:"<ISO，60 分钟内>"}')}  承诺等到某刻再改`);
+        ask.push(`${call('decline')}  放弃该文件，先做别的`);
+      } else {
+        ask.push('占用方提出条件，你可以：');
+        ask.push(`${call('accept')}  接受`);
+        ask.push(`${call('counter', ', terms:{action:"wait-until", at:"<ISO>"}')}  还价`);
+        ask.push(`${call('decline')}  拒绝（请改别的文件）`);
+      }
+    } else if (neg.state === 'queued') {
+      const pending = negotiations && negotiations.pendingHandoff(neg.key);
+      const pos = negotiations ? negotiations.positionOf(neg, Date.now()) : 0;
+      const to = pending ? labelOf(pending, pending.handoffTo) : '下一位';
+      ask.push(
+        `排队中${pos ? `（第 ${pos} 位）` : ''}：占用方已约定把该文件移交给 ${to}${pending ? `（${iso(pending.pendingReleaseAt)}）` : ''}。` +
+          '在此期间你对该文件的写入仍被冻结；移交完成后你会收到通知，届时改与新占用方协商。不想等可以：'
+      );
+      ask.push(`${call('decline')}  退出排队，先做别的`);
+    } else if (neg.state === 'escalated') {
+      ask.push('协商未收敛，已请求人工裁决。默认结论：占用方保留 claim（写入方在冷静期内对该文件的写入仍被冻结）。请向用户说明情况，或改做别的文件。');
+    } else if (neg.state === 'accepted') {
+      const toMe = neg.handoffTo && neg.handoffTo === forId;
+      if (neg.pendingReleaseAt && neg.handoffTo) {
+        ask.push(toMe ? `已达成：占用将在 ${iso(neg.pendingReleaseAt)} 直接移交给你，届时可直接写入（无需再 claim）。` : `已达成：你将在 ${iso(neg.pendingReleaseAt)} 把该文件的占用移交给 ${labelOf(neg, neg.handoffTo)}。`);
+      } else if (neg.pendingWakeAt) {
+        ask.push(`已达成：写入方等待至 ${iso(neg.pendingWakeAt)}，到点会收到重试提醒。`);
+      } else if (neg.handoffTo) {
+        ask.push(toMe ? '已达成：该文件的占用已移交给你，可以直接写入；用完请 release_files（排队的会话会自动接手）。' : `已达成：该文件的占用已移交给 ${labelOf(neg, neg.handoffTo)}。`);
+      } else {
+        ask.push('已达成：占用已释放，可继续。');
+      }
+    } else {
+      ask.push(`协商已结束（${neg.resolution || neg.state}）。`);
+    }
+    return [...lines, '', ...ask].join('\n');
+  };
+
+  const notifyNegotiation = (neg, sessionId) => {
+    if (!sessionId) return;
+    const outcome = delivery.notify(sessionId, renderNegotiation(neg, sessionId));
+    metrics.notifies += 1;
+    if (outcome === 'skipped-cold') metrics.notifySkippedCold += 1;
+  };
+
+  const autoEnvelope = (type, lines) =>
+    [`${ENVELOPE_TAG} · auto]]`, `notice: ${PEER_NOTICE}`, `corr: ${randomUUID().slice(0, 8)}`, `type: ${type}`, ...lines].join('\n');
+
+  // --------------------------------------------------------------- 协商动作
+  const openNegotiation = (entry, holderId, holderLabel, writerId, writerLabel, now, writerMeta = {}) => {
+    if (!negotiations) return { neg: null, created: false };
+    const res = negotiations.open({
+      writerMeta,
+      id: randomUUID().slice(0, 8),
+      path: entry.path,
+      key: entry.key,
+      a: holderId,
+      b: writerId,
+      labels: { [holderId]: holderLabel, [writerId]: writerLabel },
+      holder: holderId,
+      writer: writerId,
+      now
+    });
+    if (res.created) {
+      metrics.negotiationsOpened += 1;
+      persistNegotiations();
+    }
+    return res;
+  };
+
+  const releaseClaim = (sessionId, key) => {
+    const count = registry.release(sessionId, [key]);
+    if (count > 0) {
+      metrics.releases += 1;
+      persistClaims();
+    }
+    return count > 0;
+  };
+
+  /** 队列中某一方作为 claim 接收方的身份。 */
+  const recipientOf = (neg) => {
+    const meta = neg.writerMeta || {};
+    return {
+      sessionId: neg.writer,
+      parent: meta.parent || '',
+      label: labelOf(neg, neg.writer),
+      cwd: meta.cwd || delivery.sessionCwd(neg.writer),
+      sessionOrigin: meta.origin === 'subagent' ? 'subagent' : 'session'
+    };
+  };
+
+  /**
+   * 队列推进：key 的占用刚交到 holderId 手上（移交完成）或刚空出来（holderId 为空），
+   * 把其余排队者改绑到新占用方并重新 open；路径空出时由队首直接接手。
+   * @param doneId - 刚完成的那份协商（不再参与）
+   */
+  const advanceQueue = (key, holderId, holderLabel, now, doneId = '') => {
+    if (!negotiations) return;
+    let queue = negotiations.queueFor(key, now, doneId).filter((n) => n.writer !== holderId);
+    // 已被销毁的子代理不能接手
+    queue = queue.filter((n) => {
+      if ((n.writerMeta || {}).origin !== 'subagent' || delivery.liveAgent(n.writer)) return true;
+      negotiations.mark(n, 'resolved', 'writer subagent is gone', now);
+      return false;
+    });
+    let currentHolder = holderId;
+    let currentLabel = holderLabel;
+    if (!currentHolder && queue.length > 0) {
+      // 路径空出：队首直接接手（先登记 claim，再通知）。
+      const head = queue.shift();
+      const who = recipientOf(head);
+      // 接手者可能已经转去做别的：给短 TTL（同自动登记），它真要长期改再自行 claim_files 延长。
+      const got = registry.claim({ ...who, entries: [{ path: head.path, key }], ttlSeconds: settings.autoClaimTtlSeconds, note: 'took over from the queue', origin: 'manual', now });
+      if (got.registered) {
+        // 接手必须立刻落盘：看门狗路径（占用过期）不经过任何工具，没有别处会替它 persist，
+        // 否则重启后接手记录丢失、队首又变回「等待」。
+        persistClaims();
+        negotiations.mark(head, 'accepted', `${who.label} took over the file from the queue`, now);
+        head.handoffTo = head.writer;
+        head.pendingWakeAt = 0;
+        metrics.handoffs += 1;
+        notifyNegotiation(head, head.writer);
+        currentHolder = head.writer;
+        currentLabel = who.label;
+      } else {
+        queue.unshift(head);
+        const other = got.conflicts[0];
+        currentHolder = other ? other.ownerSessionId : '';
+        currentLabel = other ? other.ownerLabel : '';
+      }
+    }
+    if (!currentHolder) return;
+    for (const n of queue) {
+      if (n.writer === currentHolder) continue;
+      negotiations.rebind(n, currentHolder, currentLabel, now);
+      metrics.requeued += 1;
+      notifyNegotiation(n, n.writer);
+    }
+    if (queue.length > 0) {
+      const first = queue.find((n) => n.writer !== currentHolder);
+      if (first) notifyNegotiation(first, currentHolder);
+    }
+  };
+
+  /** 执行一次约定的移交：claim 原子转给谈成方，队列改绑到新占用方。返回是否已移交。 */
+  const executeHandoff = (neg, now) => {
+    const who = recipientOf(neg);
+    const moved = registry.transfer(neg.holder, neg.key, who, now);
+    if (!moved) {
+      // 占用方已经不持有（提前释放/过期）：按路径空出处理，谈成方排在最前。
+      advanceQueue(neg.key, '', '', now, '');
+      persistClaims();
+      return false;
+    }
+    metrics.handoffs += 1;
+    persistClaims();
+    advanceQueue(neg.key, who.sessionId, who.label, now, neg.id);
+    return true;
+  };
+
+  /** 协商副作用执行。供 negotiate 工具与看门狗共用。 */
+  const applyEffects = (neg, effects, now) => {
+    if (!effects) return false;
+    if (effects.handoff) {
+      if (effects.releaseAt && effects.releaseAt <= now) return executeHandoff(neg, now);
+      // 约定到点移交：其余写入方先转入排队并告知位次。
+      for (const other of negotiations ? negotiations.queueOthers(neg, now) : []) notifyNegotiation(other, other.writer);
+      return false;
+    }
+    if (effects.releaseSessionId && effects.releaseAt && effects.releaseAt <= now) {
+      return releaseClaim(effects.releaseSessionId, neg.key);
+    }
+    return false;
+  };
+
+  /** 占用方主动释放（release_files）后：该路径上若有人排队，直接交给队首。 */
+  const handleReleased = (sessionId, keys, now) => {
+    if (!negotiations) return;
+    for (const key of keys) {
+      if (registry.othersOn(key, '', now).some((c) => c.origin === 'manual')) continue;
+      const waiting = negotiations.queueFor(key, now).filter((n) => n.holder === sessionId || n.state === 'queued');
+      if (waiting.length === 0) continue;
+      for (const n of waiting) if (n.state === 'open' && n.holder === sessionId) n.state = 'queued';
+      advanceQueue(key, '', '', now);
+    }
+    persistNegotiations();
+  };
+
+  // ------------------------------------------------------------------ L0/L1
+  const inScope = (info) => {
+    if (!settings.scopeToWorkspace) return true;
+    const root = workspaceRoot(info.cwd);
+    return !!root && isWithin(info.absPath, root);
+  };
+
+  const handleWriteIntent = (kind, target, actor) => {
+    const info = intentInfo(target, actor);
+    if (!info || !info.sessionId) {
+      metrics.unattributed += 1;
+      return;
+    }
+    if (!inScope(info)) {
+      metrics.outOfScope += 1;
+      return;
+    }
+    if (isDuplicateIntent(`${kind}|${info.sessionId}|${info.key}`)) return;
+    const writerId = info.sessionId;
+    const writerCwd = info.cwd || delivery.sessionCwd(writerId);
+    const writerLabel = labelFor(writerId, writerCwd);
+    const entry = { path: info.absPath, key: info.key };
+    const now = Date.now();
+    const result = registry.claim({
+      sessionId: writerId,
+      parent: info.parent,
+      label: writerLabel,
+      cwd: writerCwd,
+      sessionOrigin: info.origin,
+      entries: [entry],
+      ttlSeconds: settings.autoClaimTtlSeconds,
+      note: `auto:${kind}`,
+      origin: 'auto',
+      now
+    });
+    if (result.registered) {
+      metrics.autoClaims += 1;
+      persistClaims();
+      if (result.overlaps && result.overlaps.length > 0) notifyOverlap(entry, result.overlaps[0], writerId, writerLabel);
+      return;
+    }
+    const conflict = result.conflicts[0];
+    if (!conflict) return;
+    metrics.conflicts += 1;
+    significant();
+    logger?.warn?.(
+      `[session-messenger] CONFLICT(auto): ${writerLabel} writing ${entry.path} claimed by ${conflict.ownerLabel} (session ${conflict.ownerSessionId}, ${conflict.ownerOrigin})`
+    );
+
+    // H3：只有「可证明已销毁」的持有方才清理——子代理会话且已不在内存。
+    const holderClaim = registry.own(conflict.ownerSessionId, entry.key);
+    const holderIsSubagent = holderClaim && holderClaim.sessionOrigin === 'subagent';
+    if (holderIsSubagent && !delivery.liveAgent(conflict.ownerSessionId) && !safeSessionLive(conflict.ownerSessionId)) {
+      if (releaseClaim(conflict.ownerSessionId, entry.key)) {
+        metrics.orphanCleared += 1;
+        logger?.warn?.(`[session-messenger] orphan claim cleared: subagent ${conflict.ownerLabel} is disposed; ${entry.path} is free`);
+        // 被清的是已销毁子代理的 claim：写入方本次写入已放行，补登记它的自动 claim。
+        registry.claim({ sessionId: writerId, parent: info.parent, label: writerLabel, cwd: writerCwd, sessionOrigin: info.origin, entries: [entry], ttlSeconds: settings.autoClaimTtlSeconds, note: `auto:${kind}`, origin: 'auto', now });
+        persistClaims();
+        return;
+      }
+    }
+
+    if (!settings.autoNotify) return;
+    if (negotiations) {
+      // L3：冷静期内对同一对不重开桌（沉默/拒绝后反复打扰持有方是这类协议的经典死法）。
+      if (negotiations.recentTerminalForPair(entry.key, conflict.ownerSessionId, writerId, now)) {
+        metrics.cooldownSuppressed += 1;
+        return;
+      }
+      const { neg, created } = openNegotiation(entry, conflict.ownerSessionId, conflict.ownerLabel, writerId, writerLabel, now, {
+        parent: info.parent,
+        cwd: writerCwd,
+        origin: info.origin
+      });
+      if (neg && created) {
+        // 已约定移交时新来者直接排队：只通知它本人，不打扰占用方。
+        if (neg.state !== 'queued') notifyNegotiation(neg, neg.holder);
+        notifyNegotiation(neg, neg.writer);
+      }
+      return;
+    }
+    // 协商层关闭时的降级：纯告警（同样不唤醒空闲/冷会话）。
+    delivery.notify(
+      conflict.ownerSessionId,
+      autoEnvelope('conflict-alert', [
+        `path: ${entry.path}`,
+        `holder: ${conflict.ownerLabel} (session ${conflict.ownerSessionId}) — this is you`,
+        `writer: ${writerLabel} (session ${writerId})`,
+        '',
+        `会话 ${writerLabel} 正在写入你占用的文件（claim note: ${conflict.note || 'n/a'}）。如需协调，请用 send_to_session 回复写入方。`
+      ])
+    );
+    delivery.notify(
+      writerId,
+      autoEnvelope('conflict-alert', [
+        `path: ${entry.path}`,
+        `holder: ${conflict.ownerLabel} (session ${conflict.ownerSessionId})`,
+        `writer: ${writerLabel} — this is you`,
+        '',
+        `你正在写入的文件已被会话 ${conflict.ownerLabel} claim（note: ${conflict.note || 'n/a'}，至 ${iso(conflict.expiresAt)}）。请先与对方协商，或调整改动范围。`
+      ])
+    );
+    metrics.notifies += 2;
+  };
+
+  /**
+   * 重叠提示（v0.4.1）：对方只是最近写过同一文件（自动 claim，无占用声明）。
+   * 不开协商、不冻结，只给写入方一条低优先级提示，让它知道有人刚动过这个文件；
+   * 每 (写入方, 路径, 对方) 冷却窗口内最多一次，且不唤醒空闲/冷会话（delivery.notify）。
+   */
+  const overlapThrottle = createThrottle();
+  const significant = () => {
+    try {
+      if (typeof api.onSignificant === 'function') api.onSignificant();
+    } catch {
+      /* status is best-effort */
+    }
+  };
+  const notifyOverlap = (entry, other, writerId, writerLabel) => {
+    metrics.overlaps += 1;
+    significant();
+    if (!settings.autoNotify) return;
+    if (!overlapThrottle(`${writerId}|${entry.key}|${other.ownerSessionId}`, settings.overlapCooldownMs)) return;
+    delivery.notify(
+      writerId,
+      autoEnvelope('recent-edit', [
+        `path: ${entry.path}`,
+        `other: ${other.ownerLabel} (session ${other.ownerSessionId}) — edited it recently (no claim), until ${iso(other.expiresAt)}`,
+        `writer: ${writerLabel} — this is you`,
+        '',
+        '提示：另一个会话最近改过这个文件（它没有声明占用，你的写入已正常完成、不会被拦）。如果你们可能在改同一处逻辑，可用 send_to_session 知会对方，或先 claim_files 声明意图。无需回复。'
+      ])
+    );
+    metrics.notifies += 1;
+  };
+
+  const safeSessionLive = (sessionId) => {
+    try {
+      return delivery.liveSessions().some((s) => s.id === sessionId);
+    } catch {
+      return true; // 未知 = 视为存活，绝不据未知做删除
+    }
+  };
+
+  /** H3：子代理会话被宿主销毁时，其 claim 与开放协商立即收尾。持久会话的 disposed 只是卸载，不清理。 */
+  const handleSessionDisposed = (session) => {
+    const header = (session && session.header) || {};
+    const id = (session && session.id) || header.id;
+    if (!id || !(header.origin === 'subagent' || header.parentSession !== undefined)) return;
+    const count = registry.release(String(id), null);
+    if (count > 0) {
+      metrics.orphanCleared += count;
+      persistClaims();
+      logger?.info?.(`[session-messenger] subagent ${shortId(id)} disposed; released ${count} claim(s)`);
+    }
+    if (!negotiations) return;
+    const now = Date.now();
+    const freedKeys = new Set();
+    for (const neg of negotiations.openForSession(String(id))) {
+      if (neg.holder === id) {
+        freedKeys.add(neg.key); // 占用方没了：交给队列，不直接结束对方的等待
+        continue;
+      }
+      negotiations.mark(neg, 'resolved', `party ${labelOf(neg, id)} was disposed`, now);
+      notifyNegotiation(neg, neg.a === id ? neg.b : neg.a);
+    }
+    for (const neg of negotiations.negotiations.values()) {
+      if (neg.state === 'accepted' && neg.pendingReleaseAt && (neg.holder === id || neg.handoffTo === id)) {
+        neg.pendingReleaseAt = 0;
+        negotiations.mark(neg, 'resolved', `party ${labelOf(neg, id)} was disposed before the handoff`, now);
+        freedKeys.add(neg.key);
+      }
+    }
+    for (const key of freedKeys) {
+      for (const n of negotiations.queueFor(key, now)) if (n.holder === id && n.state === 'open') n.state = 'queued';
+      advanceQueue(key, '', '', now);
+    }
+    persistNegotiations();
+  };
+
+  // ------------------------------------------------------------------ 看门狗
+  const runWatchdogOnce = () => {
+    if (!negotiations || !negotiations.ready || !registry.ready) return;
+    const now = Date.now();
+    try {
+      const { escalate, dueReleases, dueWakes } = negotiations.scan(now);
+      for (const neg of escalate) {
+        metrics.escalations += 1;
+        logger?.warn?.(`[session-messenger] negotiation ${neg.id} escalated (${neg.resolution}) on ${neg.path}`);
+        notifyNegotiation(neg, neg.holder);
+        notifyNegotiation(neg, neg.writer);
+      }
+      for (const neg of dueReleases) {
+        if (neg.handoffTo) executeHandoff(neg, now);
+        else releaseClaim(neg.holder, neg.key);
+        logger?.info?.(`[session-messenger] negotiation ${neg.id} applied scheduled ${neg.handoffTo ? 'handoff' : 'release'} for ${neg.path}`);
+        notifyNegotiation(neg, neg.holder);
+        notifyNegotiation(neg, neg.writer);
+      }
+      for (const neg of dueWakes) notifyNegotiation(neg, neg.writer);
+      // 持有方已不再持有**手动** claim（释放/过期/只剩自动登记）的开放协商收敛为 resolved——冻结随之解除。
+      const heldKeys = new Set(
+        registry
+          .listLive(now)
+          .filter((c) => c.origin === 'manual')
+          .map((c) => `${c.sessionId}\u0000${c.key}`)
+      );
+      let resolved = 0;
+      const vacated = new Set();
+      for (const neg of negotiations.negotiations.values()) {
+        if (neg.state !== 'open' || heldKeys.has(`${neg.holder}\u0000${neg.key}`)) continue;
+        // 占用方不再持有（过期 / 只剩自动登记）：与主动释放同一语义——交给等待中的队首。
+        vacated.add(neg.key);
+        neg.state = 'queued';
+      }
+      for (const key of vacated) {
+        advanceQueue(key, '', '', now);
+        resolved += 1;
+      }
+      // 升级后仍在冷静期的协商：占用方已不再持有（过期/释放）时，告诉写入方可以写了。
+      for (const neg of negotiations.negotiations.values()) {
+        if (neg.state !== 'escalated' || heldKeys.has(`${neg.holder}\u0000${neg.key}`)) continue;
+        negotiations.mark(neg, 'resolved', 'holder no longer holds the claim after escalation; path is free', now);
+        resolved += 1;
+        notifyNegotiation(neg, neg.writer);
+      }
+      const removed = negotiations.prune(now, settings.negRetentionMs);
+      if (escalate.length || dueReleases.length || dueWakes.length || resolved || removed) persistNegotiations();
+    } catch (error) {
+      logger?.warn?.(`[session-messenger] watchdog failed: ${(error && error.message) || error}`);
+    }
+  };
+
+  const api = { handleWriteIntent, handleSessionDisposed, handleReleased, runWatchdogOnce, renderNegotiation, notifyNegotiation, openNegotiation, applyEffects, persistClaims, persistNegotiations, onSignificant: undefined, statusText: undefined };
+  return api;
+}

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-session-messenger: host-only bundle; agent tools for cross-session coordination.
+- insert:
+    - id: session-messenger
+      name: 'dsh-session-messenger'
+      config: {}