dsh-session-messenger 0.4.2

package/tools.js

@@ -0,0 +1,290 @@
+/**
+ * 四个 agent 工具的定义（裸定义对象 + 生成的 JSON Schema，零外部导入）。
+ * 所有 execute 永不抛出：错误以结构化结果返回；render 把模型需要的信息全部带出
+ * （模型只看得到 render 文本，detail 字段本身不进上下文——v0.3.1 真机验收教训）。
+ */
+import { randomUUID } from 'node:crypto';
+import * as S from './schemas.generated.js';
+import { callerInfo, iso, labelFor, normalizePaths, oneLine, shortId } from './util.js';
+import { Delivery, isDirectory } from './delivery.js';
+
+const MAX_PATHS = 50;
+const MAX_CONTENT_CHARS = 20000;
+const DEFAULT_TTL_SECONDS = 1800;
+
+function clampTtl(seconds) {
+  const n = Number(seconds);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_TTL_SECONDS;
+  return Math.min(Math.max(Math.round(n), 30), 86400);
+}
+
+export function buildTools({ registry, negotiations, delivery, coordinator, metrics }) {
+  const notReady = () => !registry.ready || (negotiations && !negotiations.ready);
+  const NOT_READY = 'session-messenger is still loading its state; retry in a moment';
+
+  const claimFiles = {
+    name: 'claim_files',
+    description:
+      'Register a claim on files you are about to modify so other live DSH sessions in this workspace can see it before editing. All-or-nothing: when another session already holds a live claim on ANY requested path, nothing is registered and the conflicts are returned (then use negotiate, or pick other files). Claims auto-expire after ttl_seconds (default 1800). Writes also auto-register short claims, but only a manual claim declares intent early and survives your own writes. Run release_files when done.',
+    parameters: S.CLAIM_FILES_PARAMETERS,
+    output: {
+      schema: S.CLAIM_FILES_OUTPUT,
+      render: (_args, v) => {
+        if (!v.ok) return [{ type: 'text', text: `claim_files failed: ${v.hint}` }];
+        if (!v.registered) {
+          const rows = v.conflicts.map((c) => `- ${c.path} ← ${c.ownerLabel} (session ${c.ownerSessionId}, ${c.ownerOrigin}, until ${iso(c.expiresAt)}, note: ${c.note || 'n/a'})`);
+          return [{ type: 'text', text: `CONFLICT: nothing registered.\n${rows.join('\n')}\n${v.hint}` }];
+        }
+        return [{ type: 'text', text: v.hint }];
+      }
+    },
+    execute: async (args, exec) => {
+      const now = Date.now();
+      const fail = (sessionId, hint) => ({ ok: false, sessionId, registered: false, expiresAt: 0, conflicts: [], hint });
+      try {
+        const caller = callerInfo(exec, args && args.cwd);
+        if (notReady()) return fail(caller.sessionId, NOT_READY);
+        const rawPaths = Array.isArray(args && args.paths) ? args.paths : [];
+        if (rawPaths.length === 0) return fail(caller.sessionId, 'paths must be a non-empty array');
+        if (rawPaths.length > MAX_PATHS) return fail(caller.sessionId, `too many paths (${rawPaths.length}); split into chunks of at most ${MAX_PATHS}`);
+        const { entries, unresolvable } = normalizePaths(rawPaths, caller.cwd);
+        if (unresolvable.length > 0) {
+          return fail(caller.sessionId, `cannot resolve relative path(s) without a cwd: ${unresolvable.slice(0, 5).join(', ')}; pass absolute paths or cwd`);
+        }
+        const dirs = entries.filter((e) => isDirectory(e.path)).map((e) => e.path);
+        if (dirs.length > 0) return fail(caller.sessionId, `claims are per file; these are directories: ${dirs.slice(0, 5).join(', ')}`);
+        const result = registry.claim({
+          sessionId: caller.sessionId,
+          parent: caller.parent,
+          label: labelFor(caller.sessionId, caller.cwd),
+          cwd: caller.cwd,
+          sessionOrigin: caller.origin,
+          entries,
+          ttlSeconds: clampTtl(args && args.ttl_seconds),
+          note: oneLine(args && args.note, 300),
+          origin: 'manual',
+          now
+        });
+        if (!result.registered) {
+          return {
+            ok: true,
+            sessionId: caller.sessionId,
+            registered: false,
+            expiresAt: 0,
+            conflicts: result.conflicts,
+            hint: 'Do not edit these files now. Open a negotiation as the writer, e.g. negotiate({action:"offer", path:"<path>", terms:{action:"wait-until", at:"<ISO within 60m>"}}), or work on other files.'
+          };
+        }
+        await coordinator.persistClaims();
+        return {
+          ok: true,
+          sessionId: caller.sessionId,
+          registered: true,
+          expiresAt: result.expiresAt,
+          conflicts: [],
+          hint: `Claim registered for ${entries.length} path(s) until ${iso(result.expiresAt)}. Run release_files when done.${
+            result.overlaps && result.overlaps.length
+              ? ` Note: recently edited by other session(s) without a claim: ${result.overlaps
+                  .slice(0, 5)
+                  .map((o) => `${o.path} ← ${o.ownerLabel} (session ${o.ownerSessionId})`)
+                  .join('; ')}.`
+              : ''
+          }`
+        };
+      } catch (error) {
+        return fail('', String((error && error.message) || error));
+      }
+    }
+  };
+
+  const releaseFiles = {
+    name: 'release_files',
+    description: "Release file claims held by THIS session. Omit paths to release all of this session's claims.",
+    parameters: S.RELEASE_FILES_PARAMETERS,
+    output: {
+      schema: S.RELEASE_FILES_OUTPUT,
+      render: (_args, v) => [{ type: 'text', text: v.ok ? `Released ${v.released} claim(s). ${v.hint}` : `release_files failed: ${v.hint}` }]
+    },
+    execute: async (args, exec) => {
+      try {
+        const caller = callerInfo(exec, args && args.cwd);
+        if (notReady()) return { ok: false, sessionId: caller.sessionId, released: 0, hint: NOT_READY };
+        const hasPaths = Array.isArray(args && args.paths) && args.paths.length > 0;
+        const { entries, unresolvable } = normalizePaths(hasPaths ? args.paths : [], caller.cwd);
+        if (hasPaths && entries.length === 0) {
+          return { ok: false, sessionId: caller.sessionId, released: 0, hint: `no resolvable paths: ${unresolvable.slice(0, 5).join(', ')}` };
+        }
+        const now = Date.now();
+        const keys = hasPaths
+          ? entries.map((e) => e.key)
+          : registry.listLive(now).filter((c) => c.sessionId === caller.sessionId).map((c) => c.key);
+        const released = registry.release(caller.sessionId, hasPaths ? keys : null);
+        if (released > 0) {
+          // 有人排队的文件直接交给队首（v0.4.2），不留「谁抢到算谁的」窗口。
+          coordinator.handleReleased(caller.sessionId, keys, now);
+          await coordinator.persistClaims();
+        }
+        return {
+          ok: true,
+          sessionId: caller.sessionId,
+          released,
+          hint: released > 0 ? 'Files with queued writers were handed to the next one in line; other negotiations resolve at the next watchdog tick.' : 'no matching claims'
+        };
+      } catch (error) {
+        return { ok: false, sessionId: '', released: 0, hint: String((error && error.message) || error) };
+      }
+    }
+  };
+
+  const sendToSession = {
+    name: 'send_to_session',
+    description:
+      "Send a message to ANOTHER live DSH session working in the same workspace. It arrives as a peer message (not a user instruction) in the target's chat. mode 'queue' (default) waits for the target's current turn to end; 'steer' inserts it into the target's current step. Either mode starts a turn when the target is idle, so send only when you need a reply. Rate limited. Use negotiate (not this tool) to settle a claim conflict.",
+    parameters: S.SEND_TO_SESSION_PARAMETERS,
+    output: {
+      schema: S.SEND_TO_SESSION_OUTPUT,
+      render: (_args, v) => [
+        { type: 'text', text: v.ok ? `Message ${v.mode === 'steer' ? 'steered into' : 'queued into'} session ${v.target} (${v.detail}).` : `send_to_session failed: ${v.detail}` }
+      ]
+    },
+    execute: async (args, exec) => {
+      const mode = args && args.mode === 'steer' ? 'steer' : 'queue';
+      const rawTarget = String((args && args.target) || '').trim();
+      const respond = (ok, target, delivered, detail) => ({ ok, target, mode, delivered, detail });
+      try {
+        const caller = callerInfo(exec);
+        const content = String((args && args.content) || '').trim();
+        if (!rawTarget) return respond(false, '', false, 'target is required');
+        if (!content) return respond(false, rawTarget, false, 'content is required');
+        if (content.length > MAX_CONTENT_CHARS) return respond(false, rawTarget, false, `content too long (${content.length} > ${MAX_CONTENT_CHARS} chars)`);
+        const live = delivery.liveSessions();
+        let match = live.find((s) => s.id === rawTarget);
+        if (!match && rawTarget.length >= 4) {
+          const prefixed = live.filter((s) => s.id.startsWith(rawTarget) || s.id.replace(/^session-/, '').startsWith(rawTarget));
+          if (prefixed.length > 1) {
+            return respond(false, rawTarget, false, `ambiguous id prefix; candidates: ${JSON.stringify(delivery.candidates(caller.sessionId, caller.cwd).filter((c) => prefixed.some((p) => p.id === c.sessionId)))}`);
+          }
+          match = prefixed[0];
+        }
+        if (!match || !delivery.reachable(caller.cwd, match.cwd)) {
+          return respond(false, rawTarget, false, `no reachable live session matches "${rawTarget}". Reachable sessions: ${JSON.stringify(delivery.candidates(caller.sessionId, caller.cwd))}`);
+        }
+        if (match.id === caller.sessionId) return respond(false, match.id, false, 'target resolves to the calling session; self-send is a no-op');
+        const limited = delivery.checkRate(caller.sessionId, match.id);
+        if (limited) return respond(false, match.id, false, limited);
+        const corr = randomUUID().slice(0, 8);
+        const text = Delivery.manualEnvelope({ fromId: caller.sessionId, fromCwd: caller.cwd, corr, topic: args && args.topic, mode, content });
+        await delivery.prompt(match.id, mode, text, exec && exec.signal);
+        return respond(true, match.id, true, `corr=${corr}; the target replies via its own send_to_session`);
+      } catch (error) {
+        return respond(false, rawTarget, false, String((error && error.message) || error));
+      }
+    }
+  };
+
+  const negotiate = {
+    name: 'negotiate',
+    description:
+      "Settle a file-claim conflict with another session through structured, multi-round offers. While a negotiation is open the writer's writes to that file are frozen. 'offer'/'counter' propose terms (only the current claim HOLDER may offer release-now / release-at; the WRITER may offer wait-until); 'accept' accepts the peer's pending offer and the plugin executes it; 'decline' ends it; 'escalate' asks for human arbitration; 'status' shows the negotiations on a path. Silence is NOT consent: without a reply before the deadline it escalates to the user and the holder keeps the claim.",
+    parameters: S.NEGOTIATE_PARAMETERS,
+    output: {
+      schema: S.NEGOTIATE_OUTPUT,
+      render: (_args, v) => [
+        { type: 'text', text: `negotiate ${v.ok ? 'ok' : 'rejected'}${v.negId ? ` [neg ${v.negId}]` : ''}: ${v.detail}` }
+      ]
+    },
+    execute: async (args, exec) => {
+      const now = Date.now();
+      const respond = (ok, neg, released, detail) => ({
+        ok,
+        negId: neg ? neg.id : '',
+        path: neg ? neg.path : String((args && args.path) || ''),
+        state: neg ? neg.state : '',
+        rounds: neg ? neg.rounds : 0,
+        deadline: neg ? neg.deadline : 0,
+        released: !!released,
+        detail
+      });
+      if (!negotiations) return respond(false, null, false, 'negotiation layer is disabled (env DSH_SESSION_MESSENGER_NEGOTIATE=0)');
+      try {
+        const caller = callerInfo(exec);
+        if (notReady()) return respond(false, null, false, NOT_READY);
+        const action = String((args && args.action) || '').trim();
+        const { entries } = normalizePaths([args && args.path], caller.cwd);
+        const entry = entries[0];
+        if (!entry) return respond(false, null, false, 'path could not be resolved to an absolute path');
+
+        if (action === 'status') return respond(true, null, false, statusDetail(caller, entry, now));
+
+        let neg;
+        const corr = String((args && args.corr) || '').trim();
+        if (corr) {
+          neg = negotiations.byId(corr);
+          if (!neg) return respond(false, null, false, `unknown corr "${corr}"`);
+          if (neg.key !== entry.key) return respond(false, neg, false, `corr ${neg.id} belongs to ${neg.path}, not ${entry.path}`);
+        } else {
+          const open = negotiations.openForSession(caller.sessionId).filter((n) => n.key === entry.key);
+          if (open.length > 1) return respond(false, null, false, `multiple open negotiations for this path; pass corr (${open.map((n) => n.id).join(', ')})`);
+          neg = open[0];
+        }
+        if (!neg && (action === 'offer' || action === 'counter')) {
+          const holder = registry.othersOn(entry.key, caller.sessionId, now, caller.parent).find((c) => c.origin === 'manual');
+          if (!holder) return respond(false, null, false, `no manual claim by another session on ${entry.path}; nothing to negotiate (recent edits by others do not block you — claim_files it yourself)`);
+          neg = coordinator.openNegotiation(entry, holder.sessionId, holder.label, caller.sessionId, labelFor(caller.sessionId, caller.cwd), now, {
+            parent: caller.parent,
+            cwd: caller.cwd,
+            origin: caller.origin
+          }).neg;
+          if (!neg) return respond(false, null, false, 'could not open a negotiation');
+          // 不在此处单独通知持有方：下面的 offer 转移会带着条款通知一次，避免重复打扰。
+        }
+        if (!neg) return respond(false, null, false, `no open negotiation for ${entry.path}; use status, or wait for a conflict notice`);
+        if (neg.a !== caller.sessionId && neg.b !== caller.sessionId) return respond(false, neg, false, 'you are not a party of this negotiation');
+
+        const waitMs = negotiations.rateLimited(neg.id, caller.sessionId, now);
+        if (waitMs > 0) return respond(false, neg, false, `rate limited: one intent per ${negotiations.rateMs}ms per party; retry in ${Math.ceil(waitMs / 1000)}s`);
+        const result = negotiations.transition(neg, { by: caller.sessionId, action, terms: args && args.terms, message: args && args.message, now });
+        if (!result.ok) {
+          negotiations.refundRate(neg.id, caller.sessionId);
+          return respond(false, neg, false, result.reason || 'transition rejected');
+        }
+        const effects = result.effects || {};
+        const released = coordinator.applyEffects(neg, effects, now);
+        coordinator.persistNegotiations();
+        if (effects.notifyPeer) coordinator.notifyNegotiation(neg, effects.notifyPeer);
+        return respond(true, neg, released, summaryOf(neg, released));
+      } catch (error) {
+        return respond(false, null, false, String((error && error.message) || error));
+      }
+    }
+  };
+
+  const summaryOf = (neg, released) => {
+    const queueNote = neg.state === 'queued' ? ` queue-position=${negotiations.positionOf(neg, Date.now())}` : '';
+    const handoff = neg.handoffTo ? ` handoff-to=${shortId(neg.handoffTo)}` : '';
+    const offer = neg.lastOffer && neg.lastOffer.terms ? ` lastOffer=${neg.lastOffer.terms.action}${neg.lastOffer.terms.at ? '@' + iso(neg.lastOffer.terms.at) : ''} by ${shortId(neg.lastOffer.by)}` : '';
+    const pending = neg.pendingReleaseAt ? ` scheduled-handoff=${iso(neg.pendingReleaseAt)}` : neg.pendingWakeAt ? ` writer-wake=${iso(neg.pendingWakeAt)}` : '';
+    return `state=${neg.state}${queueNote} round=${neg.rounds}/${negotiations.maxRounds}${neg.resolution ? ` (${neg.resolution})` : ''}${offer}${handoff}${released ? ' claim-handed-over' : ''}${pending} deadline=${iso(neg.deadline)}`;
+  };
+
+  const statusDetail = (caller, entry, now) => {
+    const mine = [...negotiations.negotiations.values()].filter((n) => n.key === entry.key && (n.a === caller.sessionId || n.b === caller.sessionId));
+    const rows = mine
+      .sort((x, y) => y.updatedAt - x.updatedAt)
+      .slice(0, 5)
+      .map((n) => {
+        const peer = n.a === caller.sessionId ? n.b : n.a;
+        const you = caller.sessionId === n.holder ? 'holder' : 'writer';
+        return `${n.id} you=${you} peer=${(n.labels && n.labels[peer]) || shortId(peer)} (session ${peer}) ${summaryOf(n, false)}`;
+      });
+    const others = registry.othersOn(entry.key, caller.sessionId, now, caller.parent);
+    const claimLine = others.length
+      ? `live claims by others: ${others.map((c) => `${c.label} (session ${c.sessionId}, ${c.origin}, until ${iso(c.expiresAt)})`).join('; ')}`
+      : 'no live claim by another session';
+    const plugin = typeof coordinator.statusText === 'function' ? ` [${coordinator.statusText()}]` : '';
+    return `${rows.length ? rows.join(' | ') : 'no negotiation on this path involving you'}; ${claimLine}${plugin}`;
+  };
+
+  void metrics;
+  return [claimFiles, releaseFiles, sendToSession, negotiate];
+}

package/util.js

@@ -0,0 +1,227 @@
+/**
+ * 纯工具函数：身份/标签、路径归一化与身份键、调用方解析、节流、信封转义。
+ * 本文件零副作用、零宿主依赖，便于单测直接覆盖。
+ */
+import path from 'node:path';
+import os from 'node:os';
+import { realpathSync } from 'node:fs';
+
+export const ENVELOPE_TAG = '[[DSH session-messenger';
+
+/** 会话 id 形如 "session-<uuid>"（持久会话）或裸 "<uuid>"（子代理会话）；剥前缀再截。 */
+export function shortId(id) {
+  return String(id || '')
+    .replace(/^session-/, '')
+    .slice(0, 8);
+}
+
+export function labelFor(id, cwd) {
+  const base = cwd ? path.basename(String(cwd)) : '';
+  return base ? `${shortId(id)} @ ${base}` : shortId(id);
+}
+
+/** 旧版 label 的已知坏形状（"session- @ x"）需要按当前规则重算。 */
+export function isLegacyLabel(label) {
+  return typeof label !== 'string' || !label || /^session-(\s|$)/.test(label);
+}
+
+/**
+ * 路径身份键：与宿主 dsh-fs-local 的 targetKey 同算法——存在则 realpath，
+ * 不存在则「最近存在祖先的 realpath + 缺失后缀」。用于跨符号链接（如 /tmp → /private/tmp）
+ * 识别同一文件。任何异常都回退为规范化的绝对路径，绝不抛出。
+ */
+export function pathKey(absPath) {
+  const normalized = path.normalize(String(absPath || ''));
+  if (!path.isAbsolute(normalized)) return normalized;
+  try {
+    return realpathSync.native(normalized);
+  } catch {
+    /* fall through to ancestor walk */
+  }
+  const missing = [path.basename(normalized)];
+  let ancestor = path.dirname(normalized);
+  for (let guard = 0; guard < 256; guard += 1) {
+    try {
+      return path.join(realpathSync.native(ancestor), ...missing);
+    } catch {
+      const parent = path.dirname(ancestor);
+      if (parent === ancestor) return normalized;
+      missing.unshift(path.basename(ancestor));
+      ancestor = parent;
+    }
+  }
+  return normalized;
+}
+
+/** 把用户给的路径（绝对 / ~/ / 相对 cwd）解析为绝对路径；无法解析返回 ''。 */
+export function toAbsolute(raw, cwd) {
+  const value = String(raw || '').trim();
+  if (!value) return '';
+  if (value === '~' || value.startsWith('~/')) return path.normalize(path.join(os.homedir(), value.slice(1)));
+  if (path.isAbsolute(value)) return path.normalize(value);
+  if (cwd && path.isAbsolute(String(cwd))) return path.resolve(String(cwd), value);
+  return '';
+}
+
+/** 批量归一化并去重（按身份键去重）。 */
+export function normalizePaths(rawPaths, cwd) {
+  const out = [];
+  const seen = new Set();
+  const unresolvable = [];
+  for (const raw of rawPaths || []) {
+    const abs = toAbsolute(raw, cwd);
+    if (!abs) {
+      if (String(raw || '').trim()) unresolvable.push(String(raw));
+      continue;
+    }
+    const key = pathKey(abs);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ path: abs, key });
+  }
+  return { entries: out, unresolvable };
+}
+
+/** abs 是否位于 root 之内（含 root 本身）。 */
+export function isWithin(abs, root) {
+  if (!abs || !root) return false;
+  const rel = path.relative(String(root), String(abs));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/** 从会话对象读 header。 */
+export function headerOf(session) {
+  return (session && session.header) || {};
+}
+
+/** 会话来源：'subagent'（宿主子代理路由所有，可被证明已销毁）或 'session'（持久会话）。 */
+export function originOfHeader(header, id) {
+  if (header && (header.origin === 'subagent' || header.parentSession !== undefined)) return 'subagent';
+  if (header && (header.origin !== undefined || header.cwd !== undefined)) return 'session';
+  // 无 header 时按 id 形状推断：持久会话带 "session-" 前缀，子代理为裸 uuid（本机实测）。
+  return /^session-/.test(String(id || '')) ? 'session' : 'subagent';
+}
+
+/** 调用方身份：sessionId 必须可解析，否则明确报错（不静默猜）。 */
+export function callerInfo(exec, cwdOverride) {
+  const agent = exec && exec.agent;
+  const header = headerOf(agent && agent.session);
+  const sessionId = (agent && agent.id) || header.id || (exec && exec.sessionId);
+  if (!sessionId) throw new Error('caller session id unavailable (tool executed without an agent context)');
+  const override = cwdOverride ? String(cwdOverride) : '';
+  const cwd =
+    (override && path.isAbsolute(override) ? override : '') ||
+    header.cwd ||
+    (agent && agent.options && agent.options.cwd) ||
+    '';
+  return {
+    sessionId: String(sessionId),
+    cwd: cwd ? String(cwd) : '',
+    origin: originOfHeader(header, sessionId),
+    parent: header.parentSession ? String(header.parentSession) : ''
+  };
+}
+
+/**
+ * 父子会话视为同一协作单元：父会话占用的文件委派给子代理改（或反之、或兄弟子代理之间）
+ * 都不算冲突——否则争议冻结会把被委派的子代理挡在自己的任务之外。
+ */
+export function sameFamily(aId, aParent, bId, bParent) {
+  if (!aId || !bId) return false;
+  if (aId === bId) return true;
+  if (aParent && aParent === bId) return true;
+  if (bParent && bParent === aId) return true;
+  return !!aParent && aParent === bParent;
+}
+
+/**
+ * fs 意图事件信息（形状依据宿主源码）：target = FsTarget { targetKey, displayPath }，
+ * displayPath 相对 cwd 优先（工作区内 posix 相对 / "~/" / 绝对）；actor = ToolExecution（.agent）。
+ */
+export function intentInfo(target, actor) {
+  if (!target || typeof target !== 'object') return undefined;
+  const display = typeof target.displayPath === 'string' ? target.displayPath.trim() : '';
+  if (!display) return undefined;
+  const agent = actor && typeof actor === 'object' ? actor.agent : undefined;
+  const sessionId = agent && typeof agent.id === 'string' ? agent.id : '';
+  const header = headerOf(agent && agent.session);
+  const cwd = header.cwd || '';
+  const abs = toAbsolute(display, cwd);
+  if (!abs) return undefined; // 无 cwd 无法定位：宁缺毋滥
+  return {
+    absPath: abs,
+    key: pathKey(abs),
+    sessionId,
+    cwd,
+    origin: originOfHeader(header, sessionId),
+    parent: header.parentSession ? String(header.parentSession) : ''
+  };
+}
+
+/**
+ * 时间窗节流：同一 key 在 windowMs 内只放行第一次。
+ * 容量超限时淘汰过期项（而非整表清空——整表清空会让去重/冷却在突发时失效）。
+ */
+export function createThrottle({ max = 1024, now = Date.now } = {}) {
+  const map = new Map();
+  const evict = (t) => {
+    for (const [key, entry] of map) {
+      if (t - entry.at >= entry.window) map.delete(key);
+    }
+    while (map.size >= max) map.delete(map.keys().next().value);
+  };
+  const allow = (key, windowMs) => {
+    const t = now();
+    const entry = map.get(key);
+    if (entry && t - entry.at < windowMs) return false;
+    if (map.size >= max) evict(t);
+    map.delete(key);
+    map.set(key, { at: t, window: windowMs });
+    return true;
+  };
+  allow.size = () => map.size;
+  return allow;
+}
+
+/** 滑动窗口计数限速：windowMs 内最多 limit 次。返回 { ok, retryInMs }。 */
+export function createWindowLimiter({ max = 1024, now = Date.now } = {}) {
+  const map = new Map();
+  return (key, limit, windowMs) => {
+    const t = now();
+    const hits = (map.get(key) || []).filter((at) => t - at < windowMs);
+    if (hits.length >= limit) {
+      map.set(key, hits);
+      return { ok: false, retryInMs: windowMs - (t - hits[0]) };
+    }
+    hits.push(t);
+    map.delete(key);
+    map.set(key, hits);
+    if (map.size > max) map.delete(map.keys().next().value);
+    return { ok: true, retryInMs: 0 };
+  };
+}
+
+/**
+ * 中和正文里的信封标记：对方可能在正文伪造 "[[DSH session-messenger · auto]]"
+ * 冒充插件自动告警。任何出现都改写为不可混淆的引用形态。
+ */
+export function neutralizeEnvelope(text) {
+  return String(text || '').replace(/\[\[\s*DSH\s+session-messenger/gi, '[quoted: DSH session-messenger');
+}
+
+/** 单行化：topic/label 等头部字段禁止换行（否则可伪造头部行）。 */
+export function oneLine(text, maxLen) {
+  const flat = neutralizeEnvelope(String(text || '')).replace(/[\r\n\u2028\u2029]+/g, ' ').trim();
+  return maxLen ? flat.slice(0, maxLen) : flat;
+}
+
+export function iso(ms) {
+  return Number.isFinite(ms) && ms > 0 ? new Date(ms).toISOString() : 'n/a';
+}
+
+export function envNumber(name, fallback, { min = 0 } = {}) {
+  const raw = process.env[name];
+  if (raw == null || raw === '') return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= min ? n : fallback;
+}

package/write-guard.js

@@ -0,0 +1,82 @@
+/**
+ * 写入守卫（H1 + M1）：用宿主 ctx.tools.guard()（同步、单调、与注册顺序无关）拦截写入，
+ * 取代原先返回非契约形状 {action:'deny'} 的 tools/pre-execute 全局闸门。
+ *
+ * 冻结策略（最小误伤面）：
+ * - 默认模式 'dispute'：只冻结「争议中」的单个路径——存在 open 协商，或冷静期内 escalated 的协商；
+ *   持有方本人永不被冻结。未发生争议的普通 claim 不拦（第一次撞册仍是 写入+开协商桌）。
+ * - 'claims'：额外冻结他人的手动 claim（origin=manual）——更强，适合明确要求「先谈后改」的团队。
+ * - 'off'：不拦。
+ * - 自动 claim（origin=auto）永不作为拦截依据：写过一次就锁住别人 = 误伤。v0.4.1 起由
+ *   registry 保证协商只对手动 claim 开桌，这里再以 holdsManual 兜底（旧版遗留的协商记录也不生效）。
+ *
+ * 覆盖面：write / edit / str_replace_editor（create/str_replace/insert）。
+ * 路径解析：相对路径按调用会话 cwd 解析，统一 realpath 身份键比对（与宿主 targetKey 同算法），
+ * 符号链接无法绕过。bash 子进程直写不经文件服务，仍是已知盲区（README 已声明）。
+ */
+import { callerInfo, pathKey, toAbsolute, iso, sameFamily } from './util.js';
+
+const WRITE_TOOLS = new Set(['write', 'edit']);
+const SRE_MUTATING = new Set(['create', 'str_replace', 'insert']);
+
+/** 从一次工具调用里取出将被写入的绝对路径与调用方；非写入调用返回 undefined。 */
+export function writeTargetOf(exec) {
+  if (!exec || typeof exec.name !== 'string') return undefined;
+  const args = exec.arguments && typeof exec.arguments === 'object' ? exec.arguments : {};
+  let raw = '';
+  if (WRITE_TOOLS.has(exec.name)) raw = args.file_path;
+  else if (exec.name === 'str_replace_editor' && SRE_MUTATING.has(args.command)) raw = args.path;
+  if (typeof raw !== 'string' || !raw.trim()) return undefined;
+  let caller;
+  try {
+    caller = callerInfo(exec);
+  } catch {
+    return undefined; // 无 agent 上下文的调用不归属任何会话，不拦
+  }
+  const abs = toAbsolute(raw, caller.cwd);
+  return abs ? { abs, caller } : undefined;
+}
+
+export function createWriteGuard({ registry, negotiations, mode, metrics, logger, onDeny }) {
+  return (exec) => {
+    try {
+      if (mode === 'off') return undefined;
+      const target = writeTargetOf(exec);
+      if (!target) return undefined;
+      const { abs, caller } = target;
+      const callerId = caller.sessionId;
+      const key = pathKey(abs);
+      const now = Date.now();
+      // 只有持有方仍持有**手动** claim 时争议才冻结写入：自动 claim 只是「最近写过」，不是占用声明。
+      const holderHolds = (holderId, k) => registry.holdsManual(holderId, k, now);
+      const found = negotiations ? negotiations.frozenFor(key, callerId, now, holderHolds) : undefined;
+      const neg = found && !sameFamily(callerId, caller.parent, found.holder, (registry.own(found.holder, key) || {}).parent) ? found : undefined;
+      if (neg) {
+        metrics.denies += 1;
+        if (onDeny) onDeny();
+        const holder = (neg.labels && neg.labels[neg.holder]) || neg.holder;
+        return `"${abs}" is FROZEN while a claim dispute is ${neg.state} (neg ${neg.id}, holder ${holder}). Do not write it now: reply with negotiate({action:"status", path:"${abs}"}) to see the terms, or work on other files. The freeze lifts when the holder releases or the negotiation is accepted.`;
+      }
+      if (mode === 'claims') {
+        const hit = registry.othersOn(key, callerId, now, caller.parent).find((c) => c.origin === 'manual');
+        if (hit) {
+          metrics.denies += 1;
+          if (onDeny) onDeny();
+          return `"${abs}" is claimed by ${hit.label} (session ${hit.sessionId}, until ${iso(hit.expiresAt)}, note: ${hit.note || 'n/a'}). Negotiate first: negotiate({action:"offer", path:"${abs}", terms:{action:"wait-until", at:"<ISO within 60m>"}}), or work on other files.`;
+        }
+      }
+      return undefined;
+    } catch (error) {
+      // 守卫绝不能因自身缺陷拦截或打断宿主：任何异常一律放行并记录。
+      logger?.warn?.(`[session-messenger] write guard failed (allowing): ${(error && error.message) || error}`);
+      return undefined;
+    }
+  };
+}
+
+export function guardMode(config) {
+  const env = process.env.DSH_SESSION_MESSENGER_GUARD;
+  const legacy = process.env.DSH_SESSION_MESSENGER_HARD_GATE;
+  const pick = env || (config && typeof config.guard === 'string' ? config.guard : '') || (legacy === '1' ? 'claims' : legacy === '0' ? 'off' : '');
+  return pick === 'off' || pick === 'claims' || pick === 'dispute' ? pick : 'dispute';
+}