@michelj/context-guard 0.4.3 → 0.6.1

package/scripts/workbench/projections.mjs

@@ -0,0 +1,68 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { entries } from '../shared/map-model.mjs';
+import { atomicWrite, encode, readJSON } from '../shared/io.mjs';
+const start = '<!-- context-guard:generated:start -->', end = '<!-- context-guard:generated:end -->';
+const fields = text => Object.fromEntries(text.split(/\r?\n/).filter(x => /^- [^:]+:/.test(x)).map(x => { const i = x.indexOf(':'); return [x.slice(2, i).trim(), x.slice(i + 1).trim()]; }));
+async function markdownIndex(ctx, folder, make) {
+  const result = {};
+  for (const file of await fs.readdir(path.join(ctx, folder)).catch(e => e.code === 'ENOENT' ? [] : Promise.reject(e))) {
+    if (!file.endsWith('.md')) continue;
+    const text = await fs.readFile(path.join(ctx, folder, file), 'utf8');
+    const id = file.slice(0, -3), f = fields(text);
+    result[id] = make(id, f, text.split(/\r?\n/)[0].replace(/^#\s*/, '').replace(new RegExp(`^${id}\\s+`), ''));
+  }
+  return result;
+}
+export async function generateProjections(root, doc, version, isCurrent = () => true, { sessionId = '' } = {}) {
+  if (!doc?.root) return false;
+  const ctx = path.join(root, '.codex/context'), cards = path.join(ctx, 'cards');
+  const statusFile = path.join(ctx, 'projection-status.json');
+  await atomicWrite(statusFile, encode({ status: 'building', sourceVersion: version }));
+  await fs.mkdir(cards, { recursive: true });
+  const index = entries(doc.root), owns = [];
+  let bugs = await markdownIndex(ctx, 'bugs', (id, f, title) => ({ title, keys: (f.keys || '').split(/[,，]/).map(x => x.trim()).filter(Boolean), status: f.status || 'open', bug: `.codex/context/bugs/${id}.md`, fix: `.codex/context/fixes/${id}.md`, card: f.card || (f.node ? `.codex/context/cards/${f.node}.md` : '') }));
+  let tasks = await markdownIndex(ctx, 'tasks', (id, f, title) => ({ title, keys: (f.keys || '').split(/[,，]/).map(x => x.trim()).filter(Boolean), task: `.codex/context/tasks/${id}.md`, chain: (f.chain || '').split('>').map(x => x.trim()).filter(Boolean), card: f.card || '' }));
+  if (sessionId) {
+    const visibleBugs = new Set(), visibleTasks = new Set();
+    for (const { node } of entries(doc.root).values()) {
+      for (const item of node.bugs || []) visibleBugs.add(item.id);
+      for (const item of node.todos || []) visibleTasks.add(item.id);
+    }
+    bugs = Object.fromEntries(Object.entries(bugs).filter(([id]) => visibleBugs.has(id)));
+    tasks = Object.fromEntries(Object.entries(tasks).filter(([id]) => visibleTasks.has(id)));
+  }
+  for (const [id, { node, parent }] of index) {
+    if (!isCurrent()) return false;
+    if (node.proposal === 'cancelled') continue;
+    const chain = [id]; let ancestor = parent;
+    while (ancestor) { chain.unshift(ancestor.id); ancestor = index.get(ancestor.id).parent; }
+    for (const owned of node.owns || []) owns.push({ path: owned, node: id, title: node.title, kind: node.kind, card: `.codex/context/cards/${id}.md`, chain });
+    const memories = [], ideas = [], nodeTodos = [], nodeBugs = [];
+    for (const { node: source } of index.values()) {
+      if (source.proposal === 'cancelled') continue;
+      const applies = item => source.id === id || (Array.isArray(item.also) ? item.also : String(item.also || '').split(/[,，]/).map(x => x.trim())).includes(id);
+      for (const item of source.memories || []) if (applies(item)) memories.push(`- ${item.text || ''}${source.id === id ? '' : ` (from ${source.id})`}`);
+      for (const item of source.todos || []) if (applies(item)) nodeTodos.push(`- ${item.id}: ${item.title || ''} [${item.status || 'pending'}]${source.id === id ? '' : ` (from ${source.id})`}`);
+      for (const item of source.bugs || []) if (applies(item)) nodeBugs.push(`- ${item.id}: ${item.title || ''} [${item.status || 'open'}] → .codex/context/bugs/${item.id}.md`);
+    }
+    for (const item of node.ideas || []) ideas.push(`- ${item.text || ''}`);
+    const body = `${start}\n# ${id} ${node.title}\n\n- sourceVersion: ${version}\n- kind: ${node.kind || ''}\n- state: ${node.state || ''}\n- proposal: ${node.proposal || ''}\n- origin: ${node.origin || ''}\n- parent: ${parent?.id || '(root)'}\n- chain: ${chain.join(' > ')}\n- purpose: ${node.purpose || ''}\n- owns: ${(node.owns || []).join(', ')}\n\n## 记忆\n${memories.join('\n')}\n\n## Idea\n${ideas.join('\n')}\n\n## TODO\n${nodeTodos.join('\n')}\n\n## Bug\n${nodeBugs.join('\n')}\n\n## 孩子\n${[...(node.children || []), ...(node._inbox || [])].filter(x => x.proposal !== 'cancelled').map(x => `- ${x.id} ${x.title}`).join('\n')}\n${end}`;
+    const file = path.join(cards, id + '.md');
+    const old = await fs.readFile(file, 'utf8').catch(e => e.code === 'ENOENT' ? '' : Promise.reject(e));
+    const a = old.indexOf(start), b = old.indexOf(end);
+    const content = a >= 0 && b > a ? old.slice(0, a) + body + old.slice(b + end.length) : body + '\n' + (old ? '\n## 保留的旧卡片／人工补充（非当前地图状态）\n\n' + old : '');
+    await atomicWrite(file, content);
+  }
+  if (!isCurrent()) return false;
+  await atomicWrite(path.join(ctx, 'owns-index.json'), encode({ sourceVersion: version, owns }));
+  await atomicWrite(path.join(ctx, 'bugs-index.json'), encode(bugs));
+  await atomicWrite(path.join(ctx, 'tasks-index.json'), encode(tasks));
+  await atomicWrite(path.join(ctx, 'jump-index.json'), encode({ sourceVersion: version, owns, bugs, tasks }));
+  if (isCurrent()) await atomicWrite(statusFile, encode({ status: 'ready', sourceVersion: version }));
+  return isCurrent();
+}
+export async function projectionStatus(root, version) {
+  const status = await readJSON(path.join(root, '.codex/context/projection-status.json'), {});
+  return { ...status, current: status.status === 'ready' && status.sourceVersion === version };
+}

package/scripts/workbench/protocol-client.mjs

@@ -0,0 +1,165 @@
+import { randomUUID } from 'node:crypto';
+import { errorReply, fail, MAX_MESSAGE_BYTES, ProtocolError, validateMessage } from '../shared/protocol.mjs';
+
+// Never interpret a legacy HTML/JSON response as successful v2 delivery.
+export async function sendMessage(origin, credential, message, { fetcher = fetch, timeoutMs = 10000, allowLoopback = false, receiveCredential, ciSessionId } = {}) {
+  validateMessage(message);
+  if (ciSessionId && (typeof ciSessionId !== 'string' || !/^[a-zA-Z0-9._:-]{1,128}$/.test(ciSessionId))) fail('INVALID_ARGUMENT', 'Invalid CI Session identity');
+  const base = new URL(origin);
+  if (base.protocol !== 'https:' && !(allowLoopback && base.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(base.hostname))) fail('FORBIDDEN', 'Cloud transport requires HTTPS');
+  if (base.username || base.password) fail('INVALID_ARGUMENT', 'Credentials must not be part of the URL');
+  let response;
+  try {
+    response = await fetcher(new URL('/api/v2/messages', base), {
+      method: 'POST', redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${credential}`, ...(ciSessionId ? { 'X-Context-Guard-CI-Session': ciSessionId } : {}) }, body: JSON.stringify(message),
+    });
+  } catch { fail('UNAVAILABLE', 'Connection failed; keep the pending message and retry with the same ID'); }
+  const possibleLegacy = [404, 405, 426].includes(response.status);
+  const invalidReceipt = message => fail(possibleLegacy ? 'INVALID_ARGUMENT' : 'UNAVAILABLE', possibleLegacy ? 'Server does not support this protocol; upgrade is required' : message);
+  // Authentication can fail before the server reads an ID. This is not a
+  // definitive rejection of a previously uncertain business operation.
+  if ([401, 403].includes(response.status)) fail(response.status === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN', 'Connection is not authorized');
+  if (!response.headers.get('content-type')?.includes('application/json')) invalidReceipt('Expected a v2 JSON receipt');
+  let result;
+  try {
+    let size = 0; const chunks = [];
+    for await (const chunk of response.body) {
+      size += chunk.length;
+      if (size > MAX_MESSAGE_BYTES) fail('TOO_LARGE', 'Reply exceeds 256 KiB');
+      chunks.push(chunk);
+    }
+    result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch (error) { if (error instanceof ProtocolError) throw error; invalidReceipt('Incomplete protocol receipt'); }
+  if (result?.id !== message.id || typeof result.ok !== 'boolean' || (result.ok && (!response.ok || !Object.hasOwn(result, 'data')))) invalidReceipt('Receipt does not match this request');
+  if (!result.ok) {
+    if (typeof result.error?.code !== 'string' || typeof result.error?.message !== 'string') fail('UNAVAILABLE', 'Malformed error receipt');
+    const error = new ProtocolError(result.error.code, result.error.message, result.error.details);
+    error.confirmedRejection = result.error.retryable === false && !['UNAUTHORIZED', 'FORBIDDEN', 'UNAVAILABLE'].includes(error.code);
+    throw error;
+  }
+  if (message.type === 'auth.open' && receiveCredential) {
+    const issued = response.headers.get('x-context-guard-credential');
+    if (!issued || issued.length < 32) fail('UNAVAILABLE', 'Login did not return a connection credential');
+    await receiveCredential(issued);
+  }
+  return result.data;
+}
+
+// Hosts supply a verified principal. This boundary never trusts a role in JSON.
+export function messageHandler({ authenticate, handle, allowedOrigin }) {
+  return async (req, res) => {
+    let id = '', reply, status = 200;
+    try {
+      if (req.method !== 'POST') fail('INVALID_ARGUMENT', 'Use POST');
+      if (req.headers.origin && req.headers.origin !== allowedOrigin) fail('FORBIDDEN', 'Untrusted browser origin');
+      const principal = await authenticate(req);
+      if (!principal) fail('UNAUTHORIZED', 'Authentication required');
+      if (!req.headers['content-type']?.startsWith('application/json')) fail('INVALID_ARGUMENT', 'Expected application/json');
+      let size = 0; const chunks = [];
+      for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_MESSAGE_BYTES) fail('TOO_LARGE', 'Message exceeds 256 KiB');
+        chunks.push(chunk);
+      }
+      let message;
+      try { message = JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+      catch { fail('INVALID_ARGUMENT', 'Invalid JSON'); }
+      if (typeof message?.id === 'string' && message.id.length <= 128) id = message.id;
+      validateMessage(message);
+      reply = await handle(principal, message);
+    } catch (error) {
+      reply = errorReply(id, error);
+      status = error instanceof ProtocolError ? error.status : 503;
+    }
+    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify(reply));
+  };
+}
+
+// One scheduler per project, not one timer per Session. Persist/apply/ack are host
+// callbacks so both online and offline backends can retain their own storage.
+export class ProjectMessagePump {
+  constructor({ send, sessions, apply, heartbeatMs = 10000, onError = () => {}, onSession = async () => {} }) {
+    this.send = send; this.sessions = sessions; this.apply = apply; this.heartbeatMs = heartbeatMs; this.onError = onError;
+    this.running = null; this.observing = null; this.timer = null; this.closed = false;
+    this.mapJobs = new Map(); this.deliveryJobs = new Map();
+    this.onSession = onSession;
+  }
+  request(type, payload, session) { return { v: 2, id: randomUUID(), type, ...(session ? { session } : {}), payload }; }
+  async poll(observation) {
+    if (this.closed) return;
+    if (observation) return this.drain(observation);
+    if (this.running) return this.running;
+    this.running = this.drain(observation).finally(() => { this.running = null; });
+    return this.running;
+  }
+  async drain(observation = null) {
+    observation ||= await this.observe();
+    if (!observation) return;
+    const { sessions, beat } = observation;
+    const results = await Promise.allSettled(beat.sessions.map(remote => this.drainSession(sessions, remote)));
+    const errors = results.filter(result => result.status === 'rejected').map(result => result.reason);
+    if (errors.length) throw new AggregateError(errors, 'Some Sessions could not synchronize');
+  }
+  // Liveness never waits for Map I/O, task delivery or an acknowledgement.
+  // Coalesce only the heartbeat request itself, not the downstream work.
+  observe() {
+    if (this.closed) return Promise.resolve(null);
+    if (!this.observing) this.observing = this.heartbeat().finally(() => { this.observing = null; });
+    return this.observing;
+  }
+  async heartbeat() {
+    const sessions = await this.sessions();
+    if (!sessions.length) return;
+    const beat = await this.send(this.request('sync.heartbeat', { sessions }));
+    for (const rejected of beat.rejected || []) this.onError(new ProtocolError(rejected.code, 'Session heartbeat rejected', { sessionId: rejected.id, generation: rejected.generation }));
+    return { sessions, beat };
+  }
+  async drainSession(sessions, remote) {
+      const local = sessions.find(s => s.id === remote.id && s.generation === remote.generation);
+      if (!local) fail('STALE_SESSION', 'Heartbeat returned an unknown binding');
+      // Map reconciliation and durable notification delivery are independent.
+      // A failed or stalled Map must not suppress receipt of queued tasks.
+      const key = `${local.id}:${local.generation}`;
+      const run = (jobs, operation) => {
+        if (jobs.has(key)) return;
+        const job = Promise.resolve().then(operation).finally(() => { jobs.delete(key); });
+        jobs.set(key, job); return job;
+      };
+      const results = await Promise.allSettled([
+        run(this.mapJobs, () => this.onSession(remote)),
+        run(this.deliveryJobs, () => this.drainNotifications(local, remote)),
+      ]);
+      const errors = results.filter(result => result.status === 'rejected').map(result => result.reason);
+      if (errors.length) throw new AggregateError(errors, 'Session synchronization failed');
+  }
+  async drainNotifications(local, remote) {
+      const session = { id: local.id, generation: local.generation };
+      let cursor = remote.ackedSeq;
+      // Bound a pass so one large Session cannot monopolize the project worker.
+      for (let page = 0; page < 10 && cursor < remote.latestSeq && !this.closed; page++) {
+        const data = await this.send(this.request('sync.read', { afterSeq: cursor, limit: 50 }, session));
+        if (!data.messages?.length || data.nextSeq <= cursor) fail('UNAVAILABLE', 'Queue did not advance');
+        const items = [];
+        for (const item of data.messages) {
+          validateMessage(item.message);
+          if (item.seq !== cursor + 1 || item.message.session?.id !== session.id || item.message.session.generation !== session.generation) fail('UNAVAILABLE', 'Queue sequence or Session mismatch');
+          // apply must persist the effect AND its ID receipt together before returning.
+          const result = await this.apply(item.message);
+          items.push({ ...result, seq: item.seq }); cursor = item.seq;
+        }
+        if (cursor !== data.nextSeq) fail('UNAVAILABLE', 'Read cursor mismatch');
+        const ack = this.request('sync.ack', { items }, session);
+        validateMessage(ack);
+        await this.send(ack);
+      }
+  }
+  start() {
+    if (this.timer || this.closed) return;
+    const tick = () => this.observe().then(observation => observation && this.poll(observation)).catch(this.onError);
+    this.timer = setInterval(tick, this.heartbeatMs); this.timer.unref?.(); tick();
+  }
+  wake() { return this.poll(); }
+  async close() { this.closed = true; clearInterval(this.timer); this.timer = null; await Promise.allSettled([this.running, this.observing, ...this.mapJobs.values(), ...this.deliveryJobs.values()]); }
+}

package/scripts/workbench/protocol-delivery.mjs

@@ -0,0 +1,133 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { atomicWrite, encode, hash, readJSON, withFileLock } from '../shared/io.mjs';
+import { canonical, fail, validateMessage } from '../shared/protocol.mjs';
+
+export const executionNotifications = new Set(['task.assign', 'task.message', 'task.rework', 'task.control', 'ci.request']);
+export function controlReport(message) {
+  validateMessage(message);
+  if (message.type !== 'task.control' || !['resume', 'complete'].includes(message.payload.action)) fail('INVALID_ARGUMENT', 'A resume or complete control is required');
+  const closed = message.payload.action === 'complete';
+  return { v: 2, id: hash(`${closed ? 'close' : 'resume'}:${message.id}`), type: 'task.report', session: message.session,
+    payload: { taskId: message.payload.taskId, stage: closed ? 'closed' : 'resumed',
+      data: { controlId: message.id, ...(closed ? { closeReceiptId: message.id } : {}) } } };
+}
+const reviewedRetry = 'reviewed 任务不使用 map task start/finish。回复未知时保留原 operationId；收到明确 CONFLICT 后先核对状态，条件已恢复时用新的 operationId 提交 Plan，旧编号会重放旧拒绝。不得因报错跳过审核或报告完成。';
+export async function executionPrompt(message, readObject) {
+  validateMessage(message);
+  const p = message.payload;
+  if (message.type === 'ci.request') return ['Context Guard：执行独立 CI，只测试指定提交，不修改业务源码、不提交开发 Plan。',
+    `任务：${p.taskId}`, `准确 SHA：${p.sourceSha}`, `CI TODO：${p.ciTodoRef}`, `开发证据：${p.unitTestRefs.join(', ')}`,
+    '用 map ci context 读取当前授权，用 map ci exchange --input -（stdin，优先）或当前 Session 工作树内文件读取引用、上传证据并提交 ci.result；不要使用共享 /tmp 文件。',
+    '如实报告失败和复现证据；没有执行的测试不得标为通过。'].join('\n');
+  if (message.type === 'task.assign') {
+    const brief = await readObject(p.briefRef, p.briefVersion);
+    if (brief.kind !== 'brief' || brief.version !== p.briefVersion || brief.content?.taskId !== p.taskId || typeof brief.content.text !== 'string' || brief.content.text.length > 2000) fail('CONFLICT', 'Approved brief reference differs');
+    if (p.mode === 'session') {
+      return [brief.content.text,
+        '通过已安装 Context Guard Skill 执行以下命令（当前 Session，遵守仓库规则）：',
+        `开始：map task start ${message.id}`,
+        `完成：map task finish ${message.id} --summary "实际结果、验证证据与可复用经验"`,
+        '完成时一并提交总结，之后等待人类验收；不要等待勾选后再生成总结。',
+        '失败或取消时加 --outcome failed/cancelled。重试使用同一编号；完成不代表发布 Main。'].join('\n');
+    }
+    return ['Context Guard：已确认的任务，请先读代码并提交 Plan，收到审核通过后再执行。',
+      `任务：${p.taskId}`, `节点：${p.nodeIds.join(', ')}`, `Main 记忆版本（不是 Git SHA）：${p.mainVersion}`, brief.content.text,
+      '优先使用 map task plan --input -（stdin），或 --input <JSON文件路径>（文件必须位于当前 Session 工作树内）提交 {operationId,content:{paths,steps}}；不要使用 /tmp/plan.json 等共享临时文件，可能被并行 Session 覆盖。不清楚时先读 map task plan --help。审核前只读，不启动开发 Plan。',
+      '执行边界：Coordinator 已经创建并绑定本任务的独立执行 Session；不得手工创建、选择、分配或替换 Session，不得直接改写 Main、.codex/context/main/map.json 或任何服务器状态。若这是链路验证任务，只读核对任务、Session、回执和状态，不要把验证动作变成业务开发。map task plan 成功返回 awaiting-plan-review 后，立即结束本轮并等待 review.result；不要继续调用工具、修改文件、提交 handoff 或自行派发。',
+      reviewedRetry,
+      `交付编号：${message.id}；同一编号不得重复执行。`].join('\n');
+  }
+  if (message.type === 'review.result' && p.kind === 'plan') {
+    const receipt = await readObject(p.receiptId, p.receiptId);
+    if (receipt.kind !== 'reviewReceipt' || receipt.content?.ref !== p.ref || receipt.content?.version !== p.version || receipt.content?.decision !== p.decision) fail('CONFLICT', 'Plan review receipt differs');
+    return `Context Guard：Plan ${p.ref}@${p.version} 审核${p.decision === 'approved' ? '通过，可继续执行' : '未通过，请修改 Plan'}。\n${p.reason}\n回执：${p.receiptId}\n` +
+      (p.decision === 'approved' ? '用 map execution 读取当前审核身份，再按 Skill 的 plan-start 开发；提交代码后用 map task handoff --input -（stdin，优先）或 --input <JSON文件路径>（仅当前 Session 工作树内）交付 CI TODO、测试证据和经验。若原任务是链路验证或明确要求不修改业务文件，只做只读核对（Session、任务、回执、git status），不要改 Main/map.json 或业务文件；随后用只读证据提交 handoff，不要自行创建或分配 Session。' : '保持只读；用新的 operationId 和 map task plan 提交修订版，等待审核；使用 stdin 或当前工作树内文件，不要使用共享 /tmp 文件。');
+  }
+  if (message.type === 'task.rework') return `Context Guard：原任务 ${p.taskId} 返工，不创建新任务。\n${p.reason ? `返工原因：${p.reason}\n` : ''}代码：${p.sourceSha}\nCI：${p.ciResultRef}\n失败测试：${p.failedTestIds.join(', ')}\n交付编号：${message.id}`;
+  if (message.type === 'task.message') return [
+    `Context Guard：Coordinator 对原任务 ${p.taskId} 的指导。保留本任务、当前执行 Session 和已批准的 Plan。`,
+    p.text,
+    '先用 map execution 核对权威任务、Plan 与现有文件；不要重复已完成操作。此消息不批准新范围、不代替人工验收。',
+    '若代码已实现并验证，先提交准确文件，再用 map task handoff --input - 交出代码 SHA、CI TODO 与真实证据；handoff 在 Tester 和人工验收之前，不需要先 archive-session 或 plan-finish。人工验收后再归档并结束计划。',
+    `指导编号：${message.id}`,
+  ].join('\n');
+  if (message.type === 'task.control' && p.action === 'resume') return [
+    `Context Guard：任务 ${p.taskId} 已收到恢复控制，原因：${p.data?.reason || '用户要求继续'}。`,
+    '这是原任务的受控恢复，不是新任务；先用 map execution 读取当前授权 Plan、任务和已有证据，不重复已完成操作。',
+    ...(p.data?.reason === 'CLAUDE_TURN_LIMIT' || p.data?.reason === 'CLAUDE_TIMEOUT_OR_INTERRUPTED' || p.data?.reason === 'CLAUDE_OUTPUT_LIMIT'
+      ? ['上一轮因执行时限或输出量中断。不要重跑同一批探索性检查；先盘点已有改动和验证证据，优先完成已批准范围内的交付。若仍不能满足验收，明确回报阻塞与未验证项，不要声称测试通过。'] : []),
+    '如果原任务是链路验证或明确要求不修改业务文件：只读核对 Session、任务、回执和 git status；不得读取或改写 Main、map.json 或业务文件，也不得自行创建/分配 Session。回报 resumed 后，使用只读证据提交 map task handoff（--input - 通过 stdin），让流程进入 CI/验收；不要再次等待或触发自动恢复。',
+    '确认可以继续后，用 map exchange --input -（stdin）回报 resumed；消息必须保留原控制编号：',
+    JSON.stringify(controlReport(message)),
+    '回报后按已批准 Plan 继续；若 Plan 未批准或范围仍不清楚，保持只读并通过 ask_user 请求确认。',
+    reviewedRetry,
+  ].join('\n');
+  if (message.type === 'task.control' && p.action === 'complete') return [
+    `Context Guard：任务 ${p.taskId} 已通过服务端合并与归档校验。保留证据，结束该任务。`,
+    '使用 map exchange --input <JSON文件> 回报关闭；不要重新执行开发或再次合并。',
+    JSON.stringify(controlReport(message)),
+  ].join('\n');
+  if (message.type === 'task.control') return `Context Guard：任务 ${p.taskId} 控制请求 ${p.action}。完成对应操作后，使用原控制编号回报；收到不等于完成，不得擅自删除记录。\n${JSON.stringify(p.data)}\n控制编号：${message.id}`;
+  return null;
+}
+
+// A host may accept a message just before the caller crashes. A durable intent
+// prevents a second model invocation when acceptance cannot be established.
+export class ProtocolDelivery {
+  constructor(directory, adapters) { this.directory = directory; this.adapters = adapters; }
+  async retryBusy(canRetry, limit = 4) {
+    const names = await fs.readdir(this.directory).catch(error => {
+      if (error.code === 'ENOENT') return [];
+      throw error;
+    });
+    const candidates = (await Promise.all(names.filter(value => value.endsWith('.json')).map(async name => ({
+      name, mtimeMs: await fs.stat(path.join(this.directory, name)).then(stat => stat.mtimeMs, () => 0),
+    })))).sort((a, b) => b.mtimeMs - a.mtimeMs);
+    let attempted = 0;
+    for (const { name, mtimeMs } of candidates) {
+      if (attempted >= limit) break;
+      if (!mtimeMs || Date.now() - mtimeMs > 24 * 60 * 60 * 1000) continue;
+      const file = path.join(this.directory, name);
+      const previous = await readJSON(file, null);
+      if (previous?.state !== 'failed' || previous.errorCode !== 'RUNTIME_BUSY' || !previous.input) continue;
+      if (!await canRetry(previous.input)) continue;
+      attempted++;
+      await this.deliver(previous.input).catch(error => {
+        if (error.code !== 'UNAVAILABLE') throw error;
+      });
+    }
+    return attempted;
+  }
+  async deliver(input) {
+    const adapter = this.adapters[input.platform];
+    const invoke = typeof adapter === 'function' ? adapter : adapter?.deliver;
+    if (typeof invoke !== 'function') fail('INVALID_ARGUMENT', 'This host does not support task delivery');
+    if (!input.id || !input.sessionId || typeof input.message !== 'string' || !input.message.trim()) fail('INVALID_ARGUMENT', 'Delivery identity and message are required');
+    const file = path.join(this.directory, `${hash(input.id)}.json`), fingerprint = hash(canonical(input));
+    return withFileLock(`${file}.lock`, async () => {
+      const previous = await readJSON(file, null);
+      if (previous && previous.fingerprint !== fingerprint) fail('ID_REUSED', 'Delivery ID differs from the saved intent');
+      if (previous?.state === 'received') return previous.result;
+      if (previous?.state === 'dispatching' || previous?.state === 'uncertain') {
+        if (await adapter.received?.(input)) {
+          const result = { deliveryId: input.id, state: 'received', sessionId: input.sessionId };
+          await atomicWrite(file, encode({ fingerprint, state: 'received', input, result }));
+          return result;
+        }
+        fail('UNAVAILABLE', 'Host acceptance is uncertain; do not dispatch again', { deliveryId: input.id, deliveryState: 'uncertain' });
+      }
+      await atomicWrite(file, encode({ fingerprint, state: 'dispatching', attempts: (previous?.attempts || 0) + 1, input }));
+      try {
+        await invoke.call(adapter, input);
+        const result = { deliveryId: input.id, state: 'received', sessionId: input.sessionId };
+        await atomicWrite(file, encode({ fingerprint, state: 'received', input, result }));
+        return result;
+      } catch (error) {
+        const uncertain = error?.deliveryUncertain === true || error?.killed === true || error?.code === 'ETIMEDOUT';
+        await atomicWrite(file, encode({ fingerprint, state: uncertain ? 'uncertain' : 'failed', attempts: (previous?.attempts || 0) + 1, input, errorCode: String(error?.code || 'DELIVERY_FAILED').slice(0, 128) }));
+        fail('UNAVAILABLE', uncertain ? 'Host acceptance is uncertain; do not dispatch again' : 'Host rejected delivery; it will be retried', { deliveryId: input.id, deliveryState: uncertain ? 'uncertain' : 'failed' });
+      }
+    });
+  }
+}