xuym-codex-collab 0.3.1 → 0.4.1

package/packages/peer/service.mjs

@@ -3,17 +3,86 @@ import { randomUUID } from 'node:crypto';
 import { digest } from './config.mjs';
 import { canClaimDesktop, Conflict, Denied, eligible, leaseToken, validRefs } from './protocol.mjs';
 import { git } from './store.mjs';
+import { inboxIdPattern, inboxMessageKey, inboxTaskId } from './inbox.mjs';
+const validText = (value, max) => typeof value === 'string' && !!value.trim() && value.length <= max;
+const validList = (value, maxItems, maxText) => Array.isArray(value) && value.length > 0 && value.length <= maxItems && value.every((item) => validText(item, maxText));
+const plainFields = (value, allowed) => !!value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).every((key) => allowed.includes(key));
 export class PeerService {
   constructor(store, { notify = async () => {} } = {}) { this.store = store; this.agentId = store.agentId; this.notify = notify; }
   get team() { return this.store.team; }
   list() { return this.store.list(); }
   read(id) { return this.store.read(id); }
   async publish(task, type) { if (task) { try { await this.notify(task, type); } catch { console.error('peer notification failed; Git task event is committed'); } } return task; }
+  listRequests() { return this.store.listInbox(); }
+  async pendingRequests({ chatIds } = {}) {
+    return (await this.listRequests()).filter((request) => request.spec.target_agent === this.agentId && request.state.status === 'pending' && (!chatIds || chatIds.includes(request.spec.chat_id)))
+      .sort((a, b) => a.events[0].occurred_at.localeCompare(b.events[0].occurred_at)).slice(0, 8);
+  }
+  async receiveRequest(input) {
+    const { chatId, messageId, senderId, content, allowAdmin = false } = input || {};
+    if (!plainFields(input, ['chatId', 'messageId', 'senderId', 'content', 'allowAdmin']) || !validText(chatId, 200) || !validText(messageId, 200) || !validText(senderId, 200) || !validText(content, 4000) || typeof allowAdmin !== 'boolean') throw new Conflict('invalid group request');
+    const key = inboxMessageKey(this.agentId, chatId, messageId);
+    return this.store.transactInbox(key, (requests) => {
+      const owner = this.team.agents[this.agentId]?.wecom_userid === senderId;
+      const admin = allowAdmin && Object.values(this.team.agents).some((agent) => agent.role === 'admin' && agent.wecom_userid === senderId);
+      if (!senderId || !owner && !admin) throw new Denied('sender is not authorized for this bot');
+      const referencedId = content.match(/\bN-[A-F0-9]{32}\b/)?.[0];
+      const mine = requests.filter((request) => request.spec.target_agent === this.agentId && request.spec.chat_id === chatId && request.spec.sender_id === senderId);
+      const waiting = mine.filter((request) => request.state.status === 'clarification');
+      const parent = referencedId ? mine.find((request) => request.spec.id === referencedId) : waiting.length === 1 ? waiting[0] : null;
+      if (referencedId && (!parent || parent.state.status !== 'clarification')) throw new Conflict('that request is not awaiting a reply from this sender in this group');
+      if (!referencedId && waiting.length > 1) throw Object.assign(new Conflict('multiple requests await clarification; include the N-request ID in your reply'), { code: 'AMBIGUOUS_INBOX_REPLY' });
+      if (parent) return { id: parent.spec.id, event: { type: 'replied', content, message_key: key } };
+      const id = `N-${digest([this.agentId, key]).slice(0, 32).toUpperCase()}`;
+      return { id, spec: { schema_version: 1, id, repo: this.team.repo, target_agent: this.agentId, chat_id: chatId,
+        sender_id: senderId, content, message_key: key, admin_dispatch: !!admin }, event: { type: 'received' } };
+    }, { replay: (request) => {
+      const event = request.events.find((item) => item.idempotency_key === key);
+      const original = event.type === 'received' ? request.spec.content : event.content;
+      if (request.spec.chat_id !== chatId || request.spec.sender_id !== senderId || original !== content) throw new Conflict('group message ID already used with different content or sender');
+      const owner = this.team.agents[this.agentId]?.wecom_userid === senderId;
+      const admin = allowAdmin && Object.values(this.team.agents).some((agent) => agent.role === 'admin' && agent.wecom_userid === senderId);
+      if (!owner && !admin) throw new Denied('sender is not authorized for this bot');
+    } });
+  }
+  async resolveRequest(id, expectedSeq, resolution, { defaultWorkflow } = {}) {
+    const { action, response, task: input } = resolution || {};
+    if (!plainFields(resolution, ['action', 'response', 'task']) || response !== undefined && !validText(response, 2000)) throw new Conflict('invalid request resolution');
+    if (!inboxIdPattern.test(id || '') || !Number.isSafeInteger(expectedSeq) || expectedSeq < 1) throw new Conflict('provide request ID and latest expected_seq');
+    if (!['create_task', 'clarify', 'answer'].includes(action)) throw new Conflict('unsupported request resolution');
+    if (action === 'create_task') {
+      if (!plainFields(input, ['title', 'description', 'acceptance', 'workflow']) || !validText(input.title, 200) || input.description !== undefined && (typeof input.description !== 'string' || input.description.length > 4000) || !validList(input.acceptance, 32, 1000) || input.workflow !== undefined && !validList(input.workflow, 16, 64)) throw new Conflict('invalid structured task');
+    } else if (input !== undefined || !validText(response, 2000)) throw new Conflict('answer and clarification require a response without a task');
+    const key = `inbox-resolve:${id}:${expectedSeq}`;
+    const result = await this.store.transactInbox(key, (requests) => {
+      const request = requests.find((item) => item.spec.id === id);
+      if (!request || request.spec.target_agent !== this.agentId) throw new Denied('only the receiving bot identity may interpret this request');
+      if (request.state.status !== 'pending' || request.state.seq !== expectedSeq) throw new Conflict('request changed or is no longer pending');
+      if (action !== 'create_task') return { id, event: { type: action === 'clarify' ? 'clarified' : 'answered', response } };
+      if (!input) throw new Conflict('a structured task is required');
+      const taskSpec = { schema_version: 2, id: inboxTaskId(id), repo: this.team.repo, title: input.title,
+        description: input.description ?? '', base_branch: 'main', acceptance: input.acceptance,
+        workflow: input.workflow || defaultWorkflow || [this.team.default_route], execution_mode: 'desktop_poll', source: { channel: 'wecom', chat_id: request.spec.chat_id } };
+      return { id, taskSpec, event: { type: 'task_created', task_id: taskSpec.id, task_hash: digest(taskSpec), response: response || `已创建任务 ${taskSpec.id}：${taskSpec.title}。分工：${taskSpec.workflow.join(' → ')}；等待绑定对话认领。` } };
+    }, { replay: async (request) => {
+      const event = request.events.find((item) => item.idempotency_key === key);
+      const expectedType = { create_task: 'task_created', clarify: 'clarified', answer: 'answered' }[action];
+      if (event.type !== expectedType || response !== undefined && event.response !== response) throw new Conflict('request already resolved with different content');
+      if (action === 'create_task') {
+        const accepted = await this.store.readLocal(event.task_id);
+        const taskSpec = { schema_version: 2, id: inboxTaskId(id), repo: this.team.repo, title: input.title, description: input.description ?? '', base_branch: 'main', acceptance: input.acceptance, workflow: input.workflow || accepted.spec.workflow, execution_mode: 'desktop_poll', source: { channel: 'wecom', chat_id: request.spec.chat_id } };
+        if (digest(taskSpec) !== event.task_hash) throw new Conflict('request already resolved with a different task');
+      }
+    } });
+    if (result.state.task_id) await this.publish(await this.read(result.state.task_id), 'created');
+    else await this.publish(result, 'inbox_response');
+    return { request: result, ...(result.state.task_id ? { task: await this.read(result.state.task_id) } : {}) };
+  }
   async create(input, idempotencyKey = randomUUID()) {
     const id = input.id || `T-${digest(`${this.agentId}:${idempotencyKey}`).slice(0, 32).toUpperCase()}`;
     const result = await this.store.transact(id, idempotencyKey, (current) => {
       if (current) throw new Conflict('task already exists');
-      const spec = { schema_version: 2, id, repo: this.team.repo, title: input.title, description: input.description || '', base_branch: 'main', acceptance: input.acceptance,
+      const spec = { schema_version: 2, id, repo: this.team.repo, title: input.title, description: input.description ?? '', base_branch: 'main', acceptance: input.acceptance,
       workflow: input.workflow || [this.team.default_route], execution_mode: input.execution_mode || 'automatic', ...(input.chatId ? { source: { channel: 'wecom', chat_id: input.chatId } } : {}) };
       return { spec, event: { type: 'created' } };
     });

package/packages/peer/store.mjs

@@ -5,6 +5,7 @@ import { join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { digest, makeSigner, validateTeam } from './config.mjs';
 import { reducePeerTask, taskIdPattern } from './protocol.mjs';
+import { inboxIdPattern, reduceInbox } from './inbox.mjs';
 import { readRegistry, recordHash, registryPath } from './registry.mjs';
 const exec = promisify(execFile);
 const pause = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -113,6 +114,86 @@ export class PeerGitStore {
   }
   async list() { return this.locked(async () => { await this.sync(); return this.listLocal(); }); }
   async read(id) { return this.locked(async () => { await this.sync(); return this.readLocal(id); }); }
+  inboxRoot(id) {
+    if (!inboxIdPattern.test(id || '')) throw new Error('invalid inbox request ID');
+    return join(this.checkout, '.agent-collab', 'peer', 'inbox', id);
+  }
+  async readInboxLocal(id) {
+    const root = this.inboxRoot(id);
+    const spec = JSON.parse(await readFile(join(root, 'spec.json'), 'utf8'));
+    if (spec.id !== id) throw new Error('inbox directory/spec mismatch');
+    const files = (await readdir(join(root, 'events'))).sort();
+    if (files.some((file) => !/^\d{6}-[a-f0-9-]{36}\.json$/.test(file))) throw new Error('unexpected inbox event file');
+    const events = await Promise.all(files.map(async (file) => JSON.parse(await readFile(join(root, 'events', file), 'utf8'))));
+    const team = this.registry ? this.registry.teams.get(events[0]?.team_hash) : this.team;
+    if (!team) throw new Error('inbox references an untrusted team policy');
+    const state = reduceInbox(spec, events, team);
+    if (state.task_id) {
+      const task = await this.readLocal(state.task_id); const resolution = events.at(-1);
+      if (digest(task.spec) !== resolution.task_hash || task.events[0].actor_id !== spec.target_agent || task.spec.execution_mode !== 'desktop_poll' || task.spec.source?.chat_id !== spec.chat_id || task.events[0].idempotency_key !== `inbox-task:${id}`) throw new Error('inbox resolution does not match its signed task');
+    }
+    return { spec, events, state, team };
+  }
+  async listInboxLocal() {
+    let entries;
+    try { entries = await readdir(join(this.checkout, '.agent-collab', 'peer', 'inbox')); }
+    catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+    if (entries.some((id) => !inboxIdPattern.test(id))) throw new Error('unexpected inbox entry');
+    return Promise.all(entries.sort().map((id) => this.readInboxLocal(id)));
+  }
+  async listInbox() { return this.locked(async () => { await this.sync(); return this.listInboxLocal(); }); }
+  // One remote Git CAS publishes BOTH the interpreted task and its resolution.
+  // Retries cannot leave a task created with a still-pending request.
+  async transactInbox(idempotencyKey, build, { replay = () => {} } = {}) {
+    if (this.enrollmentOnly) throw new Error('enrollment client cannot write inbox requests');
+    if (typeof idempotencyKey !== 'string' || !idempotencyKey || idempotencyKey.length > 300) throw new Error('invalid inbox idempotency key');
+    return this.locked(async () => {
+      for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+        await this.sync();
+        const requests = await this.listInboxLocal();
+        const duplicate = requests.find((request) => request.events.some((event) => event.idempotency_key === idempotencyKey));
+        if (duplicate) {
+          if (duplicate.spec.target_agent !== this.agentId) throw new Error('inbox idempotency key belongs to another identity');
+          await replay(duplicate); return duplicate;
+        }
+        const built = await build(requests, this.clock());
+        const current = requests.find((request) => request.spec.id === built.id);
+        const spec = current?.spec || built.spec;
+        if (!spec || spec.id !== built.id || spec.target_agent !== this.agentId) throw new Error('inbox transaction identity mismatch');
+        const now = new Date(this.clock()).toISOString();
+        const team = current?.team || this.team;
+        const event = makeSigner(team, this.agentId, this.privateKey)({ schema_version: 1, request_id: spec.id,
+          seq: (current?.state.seq || 0) + 1, event_id: randomUUID(), actor_id: this.agentId, occurred_at: now,
+          idempotency_key: idempotencyKey, ...built.event, ...(current ? {} : { spec_hash: digest(spec) }) });
+        reduceInbox(spec, [...(current?.events || []), event], team);
+        if ((event.type === 'task_created') !== !!built.taskSpec) throw new Error('inbox task must be published with its resolution');
+        const paths = [this.inboxRoot(spec.id)];
+        if (built.taskSpec) {
+          const taskSpec = built.taskSpec;
+          const taskEvent = this.sign({ schema_version: 2, task_id: taskSpec.id, seq: 1, event_id: randomUUID(), actor_id: this.agentId,
+            occurred_at: now, idempotency_key: `inbox-task:${spec.id}`, type: 'created', spec_hash: digest(taskSpec) });
+          reducePeerTask(taskSpec, [taskEvent], this.team);
+          if (taskSpec.id !== event.task_id || digest(taskSpec) !== event.task_hash || taskSpec.execution_mode !== 'desktop_poll' || taskSpec.source?.chat_id !== spec.chat_id) throw new Error('inbox/task provenance mismatch');
+          const taskRoot = this.root(taskSpec.id); paths.push(taskRoot);
+          await mkdir(join(taskRoot, 'events'), { recursive: true });
+          await writeFile(join(taskRoot, 'spec.json'), JSON.stringify(taskSpec, null, 2) + '\n', { flag: 'wx' });
+          await writeFile(join(taskRoot, 'events', `000001-${taskEvent.event_id}.json`), JSON.stringify(taskEvent, null, 2) + '\n', { flag: 'wx' });
+        }
+        const root = this.inboxRoot(spec.id); await mkdir(join(root, 'events'), { recursive: true });
+        if (!current) await writeFile(join(root, 'spec.json'), JSON.stringify(spec, null, 2) + '\n', { flag: 'wx' });
+        await writeFile(join(root, 'events', `${String(event.seq).padStart(6, '0')}-${event.event_id}.json`), JSON.stringify(event, null, 2) + '\n', { flag: 'wx' });
+        await git(this.checkout, 'add', '--', ...paths); await git(this.checkout, 'commit', '-m', `collab(inbox): ${spec.id} ${event.type}`);
+        try { await git(this.checkout, 'push', 'origin', 'HEAD:refs/heads/agent-collab'); return this.readInboxLocal(spec.id); }
+        catch {
+          await this.sync();
+          const accepted = (await this.listInboxLocal()).find((request) => request.events.some((item) => item.idempotency_key === idempotencyKey));
+          if (accepted) { await replay(accepted); return accepted; }
+          await pause(20 * (attempt + 1));
+        }
+      }
+      throw new Error('inbox transaction not accepted; check Git access or retry');
+    });
+  }
   async registryTransaction(build) {
     return this.locked(async () => {
       for (let attempt = 0; attempt < this.maxRetries; attempt++) {

package/schemas/peer-inbox-event.schema.json

@@ -0,0 +1,284 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:codex-collab:peer-inbox-event:v1",
+  "title": "Codex Collab Signed Natural Language Inbox Event v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "request_id",
+    "seq",
+    "event_id",
+    "actor_id",
+    "occurred_at",
+    "idempotency_key",
+    "team_hash",
+    "signature",
+    "type"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "request_id": {
+      "type": "string",
+      "pattern": "^N-[A-F0-9]{32}$"
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "event_id": {
+      "type": "string",
+      "pattern": "^[a-f0-9-]{36}$"
+    },
+    "actor_id": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_-]{1,64}$"
+    },
+    "occurred_at": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "Z$"
+    },
+    "idempotency_key": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 300,
+      "pattern": "\\S"
+    },
+    "team_hash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "signature": {
+      "type": "string",
+      "minLength": 1
+    },
+    "type": {
+      "enum": [
+        "received",
+        "clarified",
+        "replied",
+        "task_created",
+        "answered"
+      ]
+    },
+    "spec_hash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "content": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000,
+      "pattern": "\\S"
+    },
+    "message_key": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 300,
+      "pattern": "\\S"
+    },
+    "response": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000,
+      "pattern": "\\S"
+    },
+    "task_id": {
+      "type": "string",
+      "pattern": "^T-[A-F0-9]{32}$"
+    },
+    "task_hash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    }
+  },
+  "oneOf": [
+    {
+      "properties": {
+        "type": {
+          "const": "received"
+        }
+      },
+      "required": [
+        "spec_hash"
+      ],
+      "not": {
+        "anyOf": [
+          {
+            "required": [
+              "content"
+            ]
+          },
+          {
+            "required": [
+              "message_key"
+            ]
+          },
+          {
+            "required": [
+              "response"
+            ]
+          },
+          {
+            "required": [
+              "task_hash"
+            ]
+          },
+          {
+            "required": [
+              "task_id"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "properties": {
+        "type": {
+          "const": "clarified"
+        }
+      },
+      "required": [
+        "response"
+      ],
+      "not": {
+        "anyOf": [
+          {
+            "required": [
+              "content"
+            ]
+          },
+          {
+            "required": [
+              "message_key"
+            ]
+          },
+          {
+            "required": [
+              "spec_hash"
+            ]
+          },
+          {
+            "required": [
+              "task_hash"
+            ]
+          },
+          {
+            "required": [
+              "task_id"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "properties": {
+        "type": {
+          "const": "replied"
+        }
+      },
+      "required": [
+        "content",
+        "message_key"
+      ],
+      "not": {
+        "anyOf": [
+          {
+            "required": [
+              "response"
+            ]
+          },
+          {
+            "required": [
+              "spec_hash"
+            ]
+          },
+          {
+            "required": [
+              "task_hash"
+            ]
+          },
+          {
+            "required": [
+              "task_id"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "properties": {
+        "type": {
+          "const": "task_created"
+        }
+      },
+      "required": [
+        "task_id",
+        "task_hash",
+        "response"
+      ],
+      "not": {
+        "anyOf": [
+          {
+            "required": [
+              "content"
+            ]
+          },
+          {
+            "required": [
+              "message_key"
+            ]
+          },
+          {
+            "required": [
+              "spec_hash"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "properties": {
+        "type": {
+          "const": "answered"
+        }
+      },
+      "required": [
+        "response"
+      ],
+      "not": {
+        "anyOf": [
+          {
+            "required": [
+              "content"
+            ]
+          },
+          {
+            "required": [
+              "message_key"
+            ]
+          },
+          {
+            "required": [
+              "spec_hash"
+            ]
+          },
+          {
+            "required": [
+              "task_hash"
+            ]
+          },
+          {
+            "required": [
+              "task_id"
+            ]
+          }
+        ]
+      }
+    }
+  ],
+  "$comment": "Runtime also verifies Ed25519 signatures and historical team hash, receiving-agent authorship, exact sequence, unique IDs and idempotency keys, nondecreasing UTC timestamps, signed spec digest and allowed transitions. received opens pending; clarified waits for a reply; replied returns to pending; task_created and answered resolve pending. A task_created event and its desktop_poll task commit atomically; runtime validates the exact task digest, deterministic task ID, original group, creator and creation key. Replies are scoped to the same bot, group and sender."
+}

package/schemas/peer-inbox.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:codex-collab:peer-inbox:v1",
+  "title": "Codex Collab Natural Language Inbox Request v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "id",
+    "repo",
+    "target_agent",
+    "chat_id",
+    "sender_id",
+    "content",
+    "message_key",
+    "admin_dispatch"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^N-[A-F0-9]{32}$"
+    },
+    "repo": {
+      "type": "string",
+      "minLength": 1
+    },
+    "target_agent": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_-]{1,64}$"
+    },
+    "chat_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "pattern": "\\S"
+    },
+    "sender_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "pattern": "\\S"
+    },
+    "content": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000,
+      "pattern": "\\S"
+    },
+    "message_key": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 300,
+      "pattern": "\\S"
+    },
+    "admin_dispatch": {
+      "type": "boolean"
+    }
+  },
+  "$comment": "Runtime also verifies the repo and target against the pinned team, a deterministic request ID derived from target_agent and message_key, and bot-owner or allowed administrator authorization. The original group request is shared in Git; private Codex transcripts, bindings and credentials stay local."
+}

package/scripts/peer/refresh-project.mjs

@@ -0,0 +1,76 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readPeerConfig } from '../../apps/peer/runtime.mjs';
+import { git } from '../../packages/peer/store.mjs';
+import { bindingPrompt } from './setup-desktop-project.mjs';
+const root = fileURLToPath(new URL('../../', import.meta.url));
+const legacyHashes = new Set(['6e4d1ea6a644fb3078c541e40bcc9e8bf5069462994152f3ec2fc3aa5fedd5fa', 'f98ad425e2ea3c8ab6fb86febef7d9cb288029ef55bea6937dda6de8b467fece']);
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const inside = (parent, child) => { const path = relative(parent, child); return !path || path !== '..' && !path.startsWith('../') && !isAbsolute(path); };
+async function plainPath(base, path) {
+  let current = base;
+  for (const part of relative(base, path).split('/').filter(Boolean)) {
+    current = join(current, part);
+    if ((await lstat(current)).isSymbolicLink()) throw new Error('协作配置或 Skill 是符号链接，请先手动检查；未覆盖文件。');
+  }
+}
+async function privateWrite(path, contents) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try { await writeFile(temporary, contents, { mode: 0o600, flag: 'wx' }); await rename(temporary, path); await chmod(path, 0o600); }
+  finally { await rm(temporary, { force: true }); }
+}
+// Only recognize our generated MCP entry. Never replace another identity's entry.
+export async function installedProjectConfig({ repoPath, agentId }) {
+  const repo = await realpath(repoPath);
+  const path = join(repo, '.codex/config.toml'); await plainPath(repo, path);
+  const before = await readFile(path, 'utf8');
+  const server = `team-collab-${agentId}`;
+  const headers = [...before.matchAll(/^\s*\[([^\]\n]+)\][^\n]*$/gm)];
+  if (headers.some((item) => item[1].startsWith(`mcp_servers.${server}.`))) throw new Error('协作 MCP 有自定义嵌套配置，请手动检查；未覆盖文件。');
+  const matching = headers.filter((item) => item[1] === `mcp_servers.${server}`);
+  if (matching.length !== 1) throw new Error('未找到唯一的已安装协作 MCP，请先完成项目接入。');
+  const header = matching[0]; const end = headers.find((item) => item.index > header.index)?.index ?? before.length;
+  const section = before.slice(header.index, end);
+  const argsLine = section.match(/^args\s*=\s*(\[[^\n]+\])\s*$/m);
+  const commandLine = section.match(/^command\s*=\s*("[^\n]+")\s*$/m);
+  let args, command;
+  try { args = JSON.parse(argsLine?.[1]); command = JSON.parse(commandLine?.[1]); } catch { /* reject below */ }
+  if (!Array.isArray(args) || args.length !== 2 || typeof args[0] !== 'string' || !args[0].endsWith('/apps/peer/mcp-main.mjs') || !isAbsolute(args[1] || '') || typeof command !== 'string' || !command) throw new Error('协作 MCP 不是可识别的安装配置，请手动检查；未覆盖文件。');
+  const keys = section.split(/\r?\n/).filter((line) => line.trim() && !/^\s*(?:#|\[)/.test(line));
+  if (keys.length !== 2) throw new Error('协作 MCP 有自定义设置，请手动检查；未覆盖文件。');
+  return { repo, path, before, section, config_path: args[1], command, args };
+}
+export async function refreshProject({ configPath }) {
+  if (!isAbsolute(configPath || '')) throw new Error('usage: codex-collab refresh-project /absolute/private-peer.json');
+  const { config } = await readPeerConfig(configPath);
+  if (config.execution_mode !== 'desktop_poll' || config.auto_execute !== false) throw new Error('refresh-project 需要 desktop_poll 配置且 SDK 已关闭。');
+  const installed = await installedProjectConfig({ repoPath: config.repo, agentId: config.agent_id });
+  const { repo, path: configFile, before, section } = installed;
+  if (await git(repo, 'rev-parse', '--show-toplevel') !== repo || await realpath(installed.config_path) !== await realpath(configPath)) throw new Error('项目 MCP 已绑定其他配置，请使用该 MCP 实际使用的个人配置路径；未更换身份。');
+  const skillFile = join(repo, '.agents/skills/team-collab-desktop/SKILL.md');
+  await plainPath(repo, skillFile);
+  if (await git(repo, 'ls-files', '--', '.codex/config.toml', '.agents/skills/team-collab-desktop')) throw new Error('协作配置或 Skill 已提交到项目 Git，请手动合并；未覆盖共享文件。');
+  const oldSkill = await readFile(skillFile, 'utf8');
+  const template = await readFile(join(root, 'packages/codex-kit/templates/.agents/skills/team-collab-desktop/SKILL.md'), 'utf8');
+  if (oldSkill !== template && !legacyHashes.has(hash(oldSkill))) throw new Error('协作 Skill 已自定义，请手动合并自然语言处理说明；未覆盖文件。');
+  const nextSection = section.replace(/^command\s*=.*$/m, `command = ${JSON.stringify(process.execPath)}`).replace(/^args\s*=.*$/m, `args = ${JSON.stringify([join(root, 'apps/peer/mcp-main.mjs'), installed.config_path])}`);
+  const next = before.replace(section, () => nextSection);
+  if (inside(repo, resolve(config.data_dir))) throw new Error('个人数据目录必须位于项目仓库之外。');
+  await mkdir(config.data_dir, { recursive: true, mode: 0o700 });
+  const dataDir = await realpath(config.data_dir);
+  if (inside(repo, dataDir)) throw new Error('个人数据目录必须位于项目仓库之外。');
+  const prompt = join(dataDir, 'desktop-binding-prompt.txt');
+  const changed = next !== before || oldSkill !== template;
+  let backup = null;
+  if (changed) {
+    backup = join(dataDir, `project-refresh-${randomUUID()}.json`);
+    await writeFile(backup, JSON.stringify({ repo, config_toml: before, skill: oldSkill, created_at: new Date().toISOString() }, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+    try { await privateWrite(configFile, next); await privateWrite(skillFile, template); }
+    catch (error) { await privateWrite(configFile, before); await privateWrite(skillFile, oldSkill); throw error; }
+  }
+  await privateWrite(prompt, bindingPrompt(config.agent_id, repo));
+  return { agent_id: config.agent_id, repo, changed, mcp_config: configFile, skill: skillFile, backup, binding_prompt: prompt,
+    next_step: '重新加载项目 MCP；把 binding_prompt 内容发送到原绑定对话，以更新原协作 heartbeat。', heartbeat_updated: false };
+}

package/scripts/peer/setup-desktop-project.mjs

@@ -8,7 +8,10 @@ const absent = async (path) => { try { await stat(path); return false; } catch (
 const readOptional = async (path) => { try { return await readFile(path, 'utf8'); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
 
 export function bindingPrompt(agentId, repo) {
-  return `请把当前已有 Codex 对话设为 ${agentId} 的企微协作执行对话，不要新建独立执行线程。\n项目：${repo}\n读取 ${join(repo, '.agents/skills/team-collab-desktop/SKILL.md')}。\n1. 用本项目 MCP 的 get_identity 确认身份是 ${agentId}，execution_mode 是 desktop_poll；若不匹配，停止并提示重新加载 MCP。\n2. 获取当前真实对话 ID：优先使用已提供的应用上下文，或当前终端 CODEX_THREAD_ID（如果存在）；不可猜 ID 或读取/修改应用数据库。没有可用 ID 时请让我复制当前对话 ID/链接。\n3. 调用 bind_desktop_thread 绑定当前真实对话，然后用应用 automation_update 工具在当前已有对话创建一个 heartbeat：每分钟检查（仅当工具接受该周期；否则说明限制），不要创建 cron、新对话或后台 SDK。先查现有 automation，避免重复；不要修改无关 automation 或 CC Switch。\n4. heartbeat 的保存提示词必须包含 ${agentId}、当前真实 thread_id 和该 skill 路径；每次 get_identity → poll_desktop_task。job=null 时保持安静；有任务就只在本对话和返回的隔离 worktree 执行本阶段，主动续租、测试、明确提交，然后 finish_desktop_task；失败时按 skill 处理。禁止启动 SDK/CLI 代替当前对话。仅新任务、结果、失败或需我操作时通知。\n5. 创建完成后立即调用一次 poll_desktop_task 验证，无任务应正常返回，不要创建测试任务。告诉我绑定身份、对话 ID 和 heartbeat 状态；若工具不可用明确说明未启用自动轮询。\n`;
+  return `使用 $team-collab-desktop，启用当前项目的团队协作，将 ${agentId} 机器人绑定到当前对话。项目：${repo}`;
+}
+export function detailedBindingPrompt(agentId, repo) {
+  return `请把当前已有 Codex 对话设为 ${agentId} 的企微协作执行对话，不要新建独立执行线程。\n项目：${repo}\n读取 ${join(repo, '.agents/skills/team-collab-desktop/SKILL.md')}。\n1. 用本项目 MCP 的 get_identity 确认身份是 ${agentId}，execution_mode 是 desktop_poll；若不匹配，停止并提示重新加载 MCP。\n2. 获取当前真实对话 ID：优先使用已提供的应用上下文，或当前终端 CODEX_THREAD_ID（如果存在）；不可猜 ID 或读取/修改应用数据库。没有可用 ID 时请让我复制当前对话 ID/链接。\n3. 调用 bind_desktop_thread 绑定当前真实对话，然后用应用 automation_update 工具在当前已有对话创建一个 heartbeat：每分钟检查（仅当工具接受该周期；否则说明限制），不要创建 cron、新对话或后台 SDK。先查现有 automation，避免重复；不要修改无关 automation 或 CC Switch。\n4. heartbeat 的保存提示词必须包含 ${agentId}、当前真实 thread_id 和该 skill 路径；每次 get_identity → poll_desktop_task。job=null 且 requests 为空 时保持安静；有任务就只在本对话和返回的隔离 worktree 执行本阶段，主动续租、测试、明确提交，然后 finish_desktop_task；失败时按 skill 处理。requests 非空时按 Skill 理解群消息，调用 resolve_desktop_request 创建任务、追问或回答；使用 team_context 的现有路由、能力与默认分工，不能猜测不存在的同事。解决后再次 poll 开始工作。自然语言“通过／完成”不能代替人工审核命令。复用或更新当前对话已有的协作 heartbeat，避免重复创建。禁止启动 SDK/CLI 代替当前对话。仅新任务、结果、失败或需我操作时通知。\n5. 创建完成后立即调用一次 poll_desktop_task 验证，无任务应正常返回，不要创建测试任务。告诉我绑定身份、对话 ID 和 heartbeat 状态；若工具不可用明确说明未启用自动轮询。\n`;
 }
 
 // An explicit project attachment: preserve unrelated TOML settings, keep a local