xuym-codex-collab 0.1.0 → 0.3.0

package/packages/peer/registry.mjs

@@ -0,0 +1,130 @@
+import { createPublicKey, sign, verify } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { defaultReviewRules } from './review.mjs';
+import { canonical, digest, validateTeam } from './config.mjs';
+
+export const registryPath = '.agent-collab/team';
+const idPattern = /^[a-zA-Z0-9_-]{1,64}$/;
+const uuidPattern = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const hashPattern = /^[a-f0-9]{64}$/;
+const fail = () => { throw new Error('Team registry signature, history or enrollment is invalid.'); };
+function fields(value, allowed) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some((key) => !allowed.includes(key))) fail();
+}
+export function signRecord(value, privateKey) {
+  return { ...value, signature: sign(null, Buffer.from(canonical(value)), privateKey).toString('base64') };
+}
+export function verifyRecord(record, publicKey) {
+  const { signature, ...body } = record || {};
+  try { if (typeof signature !== 'string' || !verify(null, Buffer.from(canonical(body)), publicKey, Buffer.from(signature, 'base64'))) fail(); }
+  catch { fail(); }
+  return body;
+}
+export function recordHash(record) { const { signature, ...body } = record; return digest(body); }
+export function policyVersion(team, previous, actorId, privateKey, enrollment) {
+  validateTeam(team);
+  const value = { schema_version: 1, version: previous ? previous.version + 1 : 1,
+    parent_hash: previous ? recordHash(previous) : null, team_hash: digest(team), team, actor_id: actorId,
+    ...(enrollment ? { enrollment } : {}) };
+  return signRecord(value, privateKey);
+}
+export function validateHistory(records, rootHash) {
+  if (!Array.isArray(records) || !records.length || !hashPattern.test(rootHash || '') || recordHash(records[0]) !== rootHash) fail();
+  const teams = new Map();
+  let previous;
+  for (const record of records) {
+    fields(record, ['schema_version', 'version', 'parent_hash', 'team_hash', 'team', 'actor_id', 'enrollment', 'signature']);
+    if (record.schema_version !== 1 || record.version !== (previous?.version || 0) + 1 || record.parent_hash !== (previous ? recordHash(previous) : null)) fail();
+    const team = validateTeam(record.team);
+    const authority = previous?.team || team;
+    if (authority.agents[record.actor_id]?.role !== 'admin' || digest(team) !== record.team_hash || previous && team.repo !== authority.repo) fail();
+    verifyRecord(record, authority.agents[record.actor_id].public_key);
+    // Existing keys/roles remain stable; old tasks continue to use old routes.
+    if (previous && team.schema_version < authority.schema_version) fail();
+    if (previous) for (const [id, agent] of Object.entries(authority.agents)) {
+      if (!team.agents[id] || team.agents[id].public_key !== agent.public_key || team.agents[id].role !== agent.role || team.agents[id].wecom_userid !== agent.wecom_userid) fail();
+    }
+    if (record.enrollment) {
+      fields(record.enrollment, ['invite_id', 'request_id']);
+      if (!uuidPattern.test(record.enrollment.invite_id || '') || !uuidPattern.test(record.enrollment.request_id || '')) fail();
+    }
+    teams.set(record.team_hash, team); previous = record;
+  }
+  return { records, teams, latest: previous, root_hash: rootHash };
+}
+export async function readRegistry(checkout, rootHash) {
+  const dir = join(checkout, registryPath, 'versions');
+  let files;
+  try { files = (await readdir(dir)).sort(); }
+  catch (error) { if (error.code === 'ENOENT' && !rootHash) return null; throw error; }
+  if (!files.length || files.some((file, index) => file !== `${String(index + 1).padStart(6, '0')}.json`)) fail();
+  const records = await Promise.all(files.map(async (file) => JSON.parse(await readFile(join(dir, file), 'utf8'))));
+  // Legacy peers must explicitly import/adopt a registry before trusting changes.
+  if (!rootHash) return null;
+  return validateHistory(records, rootHash);
+}
+export function invitationRecord(input, record, actorId, privateKey) {
+  const invite = { schema_version: 1, invite_id: input.invite_id, agent_id: input.agent_id,
+    capabilities: input.capabilities, bot_id: input.bot_id, chat_ids: input.chat_ids,
+    commands_enabled: input.commands_enabled, prefer: input.prefer,
+    claim_public_key: input.claim_public_key, expires_at: input.expires_at,
+    team_hash: record.team_hash, actor_id: actorId };
+  const signed = signRecord(invite, privateKey);
+  validateInvitation(signed, { teams: new Map([[record.team_hash, record.team]]) });
+  return signed;
+}
+export function validateInvitation(invite, history) {
+  fields(invite, ['schema_version', 'invite_id', 'agent_id', 'capabilities', 'bot_id', 'chat_ids', 'commands_enabled', 'prefer', 'claim_public_key', 'expires_at', 'team_hash', 'actor_id', 'signature']);
+  const team = history.teams.get(invite.team_hash);
+  if (invite.schema_version !== 1 || !uuidPattern.test(invite.invite_id || '') || !idPattern.test(invite.agent_id || '') || !team || team.agents[invite.actor_id]?.role !== 'admin' ||
+    !Array.isArray(invite.capabilities) || !invite.capabilities.length || invite.capabilities.length > 16 || invite.capabilities.some((cap) => !idPattern.test(cap)) || new Set(invite.capabilities).size !== invite.capabilities.length ||
+    typeof invite.bot_id !== 'string' || !invite.bot_id || invite.bot_id.length > 200 ||
+    !Array.isArray(invite.chat_ids) || !invite.chat_ids.length || invite.chat_ids.some((id) => typeof id !== 'string' || !id || id.length > 200) ||
+    typeof invite.commands_enabled !== 'boolean' || typeof invite.prefer !== 'boolean' || !Number.isFinite(Date.parse(invite.expires_at))) fail();
+  try { if (createPublicKey(invite.claim_public_key).asymmetricKeyType !== 'ed25519') fail(); } catch { fail(); }
+  verifyRecord(invite, team.agents[invite.actor_id].public_key);
+  return invite;
+}
+export function enrollmentRequest({ invite, publicKey, userid, chatid, requestId, privateKey, claimPrivateKey }) {
+  const body = { schema_version: 1, request_id: requestId, invite_id: invite.invite_id, agent_id: invite.agent_id,
+    public_key: publicKey, wecom_userid: invite.commands_enabled ? userid : null, chat_id: chatid };
+  const member = signRecord(body, privateKey);
+  return { ...member, invitation_signature: sign(null, Buffer.from(canonical(body)), claimPrivateKey).toString('base64') };
+}
+export function validateEnrollment(request, invite, history, { now = Date.now(), allowExpired = false } = {}) {
+  validateInvitation(invite, history);
+  fields(request, ['schema_version', 'request_id', 'invite_id', 'agent_id', 'public_key', 'wecom_userid', 'chat_id', 'signature', 'invitation_signature']);
+  if (request.schema_version !== 1 || !uuidPattern.test(request.request_id || '') || request.invite_id !== invite.invite_id || request.agent_id !== invite.agent_id ||
+    !invite.chat_ids.includes(request.chat_id) || (invite.commands_enabled ? typeof request.wecom_userid !== 'string' || !request.wecom_userid || request.wecom_userid.length > 200 : request.wecom_userid !== null) ||
+    !allowExpired && now > Date.parse(invite.expires_at)) fail();
+  const { invitation_signature, ...member } = request;
+  try { if (createPublicKey(request.public_key).asymmetricKeyType !== 'ed25519') fail(); } catch { fail(); }
+  const body = verifyRecord(member, request.public_key);
+  try { if (typeof invitation_signature !== 'string' || !verify(null, Buffer.from(canonical(body)), invite.claim_public_key, Buffer.from(invitation_signature, 'base64'))) fail(); }
+  catch { fail(); }
+  return request;
+}
+export function approveEnrollment(request, invite, history, actorId, privateKey) {
+  const consumed = history.records.find((version) => version.enrollment?.invite_id === invite.invite_id);
+  validateEnrollment(request, invite, history, { allowExpired: !!consumed });
+  const previous = history.latest;
+  if (previous.team.agents[actorId]?.role !== 'admin') fail();
+  if (history.records.some((version) => version.enrollment?.invite_id === invite.invite_id)) {
+    if (!history.records.some((version) => version.enrollment?.invite_id === invite.invite_id && version.enrollment.request_id === request.request_id) || previous.team.agents[request.agent_id]?.public_key !== request.public_key) fail();
+    return null;
+  }
+  if (previous.team.agents[request.agent_id]) fail();
+  const team = structuredClone(previous.team);
+  team.agents[request.agent_id] = { role: 'member', capabilities: invite.capabilities, max_concurrent_tasks: 1, public_key: request.public_key,
+    ...(request.wecom_userid ? { wecom_userid: request.wecom_userid } : {}) };
+  for (const capability of invite.capabilities) {
+    const candidates = team.routes[capability] || [];
+    team.routes[capability] = invite.prefer ? [request.agent_id, ...candidates] : [...candidates, request.agent_id];
+    if (team.schema_version === 3 && !team.review_rules[capability]) team.review_rules[capability] = defaultReviewRules({ [capability]: [] })[capability];
+  }
+  return policyVersion(team, previous, actorId, privateKey, { invite_id: invite.invite_id, request_id: request.request_id });
+}
+export const versionFile = (record) => `${registryPath}/versions/${String(record.version).padStart(6, '0')}.json`;
+export const invitationFile = (id) => { if (!uuidPattern.test(id || '')) fail(); return `${registryPath}/invitations/${id}.json`; };
+export const requestFile = (id) => { if (!uuidPattern.test(id || '')) fail(); return `${registryPath}/requests/${id}.json`; };

package/packages/peer/review.mjs

@@ -0,0 +1,51 @@
+const memberSelector = /^member:([a-zA-Z0-9_-]{1,64})$/;
+
+export function validateReviewRules(team) {
+  if (team.review_rules === undefined) return;
+  if (!team.review_rules || typeof team.review_rules !== 'object' || Array.isArray(team.review_rules)) throw new Error('invalid human review rules');
+  if (Object.keys(team.routes).some((route) => !Object.hasOwn(team.review_rules, route))) throw new Error('human review rules must cover every route');
+  for (const [route, rule] of Object.entries(team.review_rules)) {
+    if (!team.routes[route] || !rule || typeof rule !== 'object' || Array.isArray(rule) || Object.keys(rule).some((key) => !['required', 'reviewer', 'notify'].includes(key)) || typeof rule.required !== 'boolean') throw new Error('invalid human review rule');
+    for (const field of ['reviewer', 'notify']) {
+      const value = rule[field];
+      const reserved = field === 'reviewer' ? ['owner', 'admin'] : ['owner', 'reviewer', 'none'];
+      if (reserved.includes(value)) continue;
+      const member = typeof value === 'string' && memberSelector.exec(value)?.[1];
+      if (!member || !team.agents[member]?.wecom_userid) throw new Error('review/notification member needs a verified WeCom account');
+    }
+  }
+}
+
+export function stageReviewRule(team, route) {
+  return team.review_rules?.[route] || { required: false, reviewer: 'admin', notify: 'owner' };
+}
+
+export function resolveHuman(selector, executorId, team, reviewerId = team.reviewer) {
+  if (selector === 'none') return null;
+  if (selector === 'reviewer') return reviewerId;
+  if (selector === 'admin') return team.reviewer;
+  // Notification-only identities cannot send approval commands. Route their review
+  // to the administrator, including the one-human/two-bot local simulation.
+  if (selector === 'owner') return team.agents[executorId]?.wecom_userid ? executorId : team.reviewer;
+  return memberSelector.exec(selector || '')?.[1] || null;
+}
+
+export function stageReviewer(team, route, executorId) {
+  const rule = stageReviewRule(team, route);
+  return rule.required ? resolveHuman(rule.reviewer, executorId, team) : team.reviewer;
+}
+
+export function reviewNotificationMembers(task, team) {
+  const event = task.events.at(-1);
+  const waiting = ['stage_review', 'review'].includes(task.state.status);
+  if (!['handoff', 'stage_review_requested', 'review_requested'].includes(event?.type)) return [];
+  const completedStage = event.type === 'handoff' ? task.state.stage - 1 : task.state.stage;
+  const rule = stageReviewRule(team, task.spec.workflow[completedStage]);
+  const reviewer = waiting ? task.state.assignee : stageReviewer(team, task.spec.workflow[completedStage], event.actor_id);
+  const notified = resolveHuman(rule.notify, event.actor_id, team, reviewer);
+  return [...new Set([notified, ...(waiting ? [reviewer] : [])].filter((id) => id && team.agents[id]?.wecom_userid))];
+}
+
+export function defaultReviewRules(routes) {
+  return Object.fromEntries(Object.keys(routes).map((route) => [route, { required: true, reviewer: 'owner', notify: 'owner' }]));
+}

package/packages/peer/service.mjs

@@ -1,27 +1,32 @@
+import { stageReviewRule } from './review.mjs';
 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';
 export class PeerService {
-  constructor(store, { notify = async () => {} } = {}) { this.store = store; this.team = store.team; this.agentId = store.agentId; this.notify = notify; }
+  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; }
   async create(input, idempotencyKey = randomUUID()) {
     const id = input.id || `T-${digest(`${this.agentId}:${idempotencyKey}`).slice(0, 32).toUpperCase()}`;
-    const spec = { schema_version: 2, id, repo: this.team.repo, title: input.title, description: input.description || '', base_branch: 'main', acceptance: input.acceptance,
+    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,
       workflow: input.workflow || [this.team.default_route], execution_mode: input.execution_mode || 'automatic', ...(input.chatId ? { source: { channel: 'wecom', chat_id: input.chatId } } : {}) };
-    const result = await this.store.transact(id, idempotencyKey, (current) => { if (current) throw new Conflict('task already exists'); return { spec, event: { type: 'created' } }; });
+      return { spec, event: { type: 'created' } };
+    });
     return this.publish(result, 'created');
   }
   async nextJob({ executionMode = 'runner' } = {}) {
     const tasks = await this.list(); const now = this.store.clock();
-    return tasks.find((task) => (executionMode === 'runner' ? task.spec.execution_mode !== 'desktop_poll' : task.spec.execution_mode === executionMode) && eligible(task, this.agentId, tasks, this.team, now)) || null;
+    return tasks.find((task) => (executionMode === 'runner' ? task.spec.execution_mode !== 'desktop_poll' : task.spec.execution_mode === executionMode) && eligible(task, this.agentId, tasks, task.team || this.team, now)) || null;
   }
   async claim(id, idempotencyKey = randomUUID(), { executionMode = 'runner' } = {}) {
     const result = await this.store.transact(id, idempotencyKey, (current, tasks, now) => {
-      if (!current || (executionMode === 'runner' ? current.spec.execution_mode === 'desktop_poll' : current.spec.execution_mode !== executionMode) || !eligible(current, this.agentId, tasks, this.team, now)) throw new Conflict('task not eligible or capacity exhausted');
-      return { event: { type: 'claimed', epoch: current.state.epoch + 1, lease_id: randomUUID(), expires_at: new Date(now + this.team.policy.lease_ms).toISOString() } };
+      if (!current || (executionMode === 'runner' ? current.spec.execution_mode === 'desktop_poll' : current.spec.execution_mode !== executionMode) || !eligible(current, this.agentId, tasks, current.team || this.team, now)) throw new Conflict('task not eligible or capacity exhausted');
+      return { event: { type: 'claimed', epoch: current.state.epoch + 1, lease_id: randomUUID(), expires_at: new Date(now + (current.team || this.team).policy.lease_ms).toISOString() } };
     });
     return this.publish(result, result.state.epoch > 1 ? 'taken_over' : 'claimed');
   }
@@ -29,7 +34,7 @@ export class PeerService {
     if (!Number.isSafeInteger(expectedSeq) || expectedSeq < 1) throw new Conflict('latest expected_seq required');
     const result = await this.store.transact(id, idempotencyKey, (task, tasks, now) => {
       if (!task || task.state.seq !== expectedSeq) throw new Conflict('stale task revision');
-      if (!canClaimDesktop(task, this.agentId, tasks, this.team, now)) throw new Conflict('desktop handoff not eligible or capacity exhausted');
+      if (!canClaimDesktop(task, this.agentId, tasks, task.team || this.team, now)) throw new Conflict('desktop handoff not eligible or capacity exhausted');
       return { event: { type: 'desktop_claimed' } };
     });
     return this.publish(result, 'desktop_claimed');
@@ -41,7 +46,7 @@ export class PeerService {
   renew(id, token) {
     return this.store.transact(id, randomUUID(), (task, _tasks, now) => {
       this.checkLease(task, token, now);
-      return { event: { type: 'renewed', ...token, expires_at: new Date(now + this.team.policy.lease_ms).toISOString() } };
+      return { event: { type: 'renewed', ...token, expires_at: new Date(now + (task.team || this.team).policy.lease_ms).toISOString() } };
     });
   }
   async verifyRefs(refs) {
@@ -53,29 +58,32 @@ export class PeerService {
     if (tip !== refs.commit.toLowerCase()) throw new Conflict('code commit must be the shared branch tip');
   }
   async report(id, payload, token = {}, idempotencyKey = randomUUID(), expectedSeq) {
-    const allowed = ['progress', 'checkpoint', 'handoff', 'review_requested', 'run_failed', 'blocked', 'reviewed', 'completed', 'cancelled', 'reopened'];
+    const allowed = ['progress', 'checkpoint', 'handoff', 'stage_review_requested', 'review_requested', 'run_failed', 'blocked', 'reviewed', 'completed', 'cancelled', 'reopened'];
     if (!allowed.includes(payload.type)) throw new Error('unsupported peer report');
     const result = await this.store.transact(id, idempotencyKey, async (task, _tasks, now) => {
       if (!task) throw new Error('unknown task');
-      if (expectedSeq !== undefined && expectedSeq !== task.state.seq) throw new Conflict('stale task revision');
-      const desktop = ['handoff', 'checkpoint', 'review_requested'].includes(payload.type) && task.state.status === 'desktop' && task.state.assignee === this.agentId;
+      if (expectedSeq !== undefined && (!Number.isSafeInteger(expectedSeq) || expectedSeq !== task.state.seq)) throw new Conflict('stale task revision');
+      const desktop = ['handoff', 'checkpoint', 'stage_review_requested', 'review_requested'].includes(payload.type) && task.state.status === 'desktop' && task.state.assignee === this.agentId;
       const human = ['reviewed', 'completed', 'cancelled', 'reopened'].includes(payload.type);
       if (!human && !desktop) this.checkLease(task, token, now);
-      if (['reviewed', 'completed', 'cancelled', 'reopened'].includes(payload.type) && this.team.agents[this.agentId].role !== 'admin') throw new Denied('human administrator approval required');
-      if (['checkpoint', 'handoff', 'review_requested'].includes(payload.type)) {
+      if (payload.type === 'reviewed' && this.agentId !== task.state.assignee) throw new Denied('only the pinned human reviewer may decide; human administrator approval required for legacy tasks');
+      if (payload.type === 'reviewed' && (task.team || this.team).review_rules && expectedSeq === undefined) throw new Conflict('review requires the R-sequence from the current notification');
+      if (['completed', 'cancelled', 'reopened'].includes(payload.type) && (task.team || this.team).agents[this.agentId]?.role !== 'admin') throw new Denied('human administrator approval required');
+      if (['checkpoint', 'handoff', 'stage_review_requested', 'review_requested'].includes(payload.type)) {
         await this.verifyRefs(payload.refs);
         if (task.state.checkpoint) {
           try { await git(this.store.checkout, 'merge-base', '--is-ancestor', task.state.checkpoint.commit, payload.refs.commit); }
           catch { throw new Conflict('code must descend from the pinned handoff commit'); }
         }
       }
-      const event = { type: payload.type, ...(!desktop && !human ? token : {}) };
+      const type = payload.type === 'handoff' && stageReviewRule(task.team || this.team, task.spec.workflow[task.state.stage]).required ? 'stage_review_requested' : payload.type;
+      const event = { type, ...(!desktop && !human ? token : {}) };
       for (const field of ['summary', 'decision', 'refs']) if (payload[field] !== undefined) event[field] = payload[field];
-      if (payload.type === 'handoff') event.next_stage = task.state.stage + 1;
+      if (['handoff', 'stage_review_requested'].includes(type)) event.next_stage = task.state.stage + 1;
       if (payload.type === 'completed') event.refs = task.state.checkpoint;
       return { event };
     });
-    return this.publish(result, payload.type);
+    return this.publish(result, result.events.at(-1).type);
   }
   async handoff(id, payload, expectedSeq, key) { const task = await this.read(id); if (task.spec.execution_mode === 'desktop_poll') throw new Denied('use the bound desktop finish tool'); return this.report(id, { type: 'handoff', ...payload }, leaseToken(task), key, expectedSeq); }
   async requestReview(id, payload, expectedSeq, key) { const task = await this.read(id); if (task.spec.execution_mode === 'desktop_poll') throw new Denied('use the bound desktop finish tool'); return this.report(id, { type: 'review_requested', ...payload }, leaseToken(task), key, expectedSeq); }

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 { readRegistry, recordHash, registryPath } from './registry.mjs';
 const exec = promisify(execFile);
 const pause = (ms) => new Promise((r) => setTimeout(r, ms));
 export async function git(cwd, ...args) {
@@ -14,9 +15,10 @@ export async function git(cwd, ...args) {
 
 /** Disposable ledger clone, cross-process local lock, remote fast-forward CAS and signed replay. */
 export class PeerGitStore {
-  constructor({ repo, dataDir, team, agentId, privateKey, clock = Date.now, maxRetries = 8 }) {
+  constructor({ repo, dataDir, team, agentId, privateKey, clock = Date.now, maxRetries = 8, registryRoot, enrollmentOnly = false }) {
     this.repo = resolve(repo); this.dataDir = resolve(dataDir); this.checkout = join(this.dataDir, 'peer-ledger');
-    this.team = validateTeam(team); this.agentId = agentId; this.sign = makeSigner(team, agentId, privateKey);
+    this.team = validateTeam(team); this.agentId = agentId; this.enrollmentOnly = enrollmentOnly; this.sign = enrollmentOnly ? null : makeSigner(team, agentId, privateKey);
+    this.privateKey = privateKey; this.registryRoot = registryRoot; this.registry = null;
     this.clock = clock; this.maxRetries = maxRetries; this.push = true;
   }
   async locked(fn) {
@@ -63,6 +65,23 @@ export class PeerGitStore {
     await git(this.checkout, 'checkout', '-B', 'agent-collab', 'refs/remotes/origin/agent-collab');
     await git(this.checkout, 'reset', '--hard', 'refs/remotes/origin/agent-collab');
     await git(this.checkout, 'clean', '-fd');
+    if (this.registryRoot) {
+      const registry = await readRegistry(this.checkout, this.registryRoot);
+      const checkpointPath = join(this.dataDir, 'team-checkpoint.json');
+      let checkpoint;
+      try { checkpoint = JSON.parse(await readFile(checkpointPath, 'utf8')); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+      if (checkpoint && (registry.records.length < checkpoint.version || recordHash(registry.records[checkpoint.version - 1]) !== checkpoint.hash)) throw new Error('team registry rolled back or forked; refusing to trust it');
+      if (!this.enrollmentOnly) {
+        if (!registry.latest.team.agents[this.agentId]) throw new Error('member is not yet approved in the team registry');
+        this.sign = makeSigner(registry.latest.team, this.agentId, this.privateKey);
+      }
+      this.team = registry.latest.team; this.registry = registry;
+      const temporary = `${checkpointPath}.${process.pid}.tmp`;
+      await writeFile(temporary, JSON.stringify({ version: registry.latest.version, hash: recordHash(registry.latest) }) + '\n', { mode: 0o600 });
+      const { rename } = await import('node:fs/promises');
+      await rename(temporary, checkpointPath);
+    }
   }
   root(id) {
     if (!taskIdPattern.test(id ?? '')) throw new Error('invalid peer task ID');
@@ -74,7 +93,9 @@ export class PeerGitStore {
     const files = (await readdir(join(root, 'events'))).sort();
     if (files.some((f) => !/^\d{6}-[a-f0-9-]{36}\.json$/.test(f))) throw new Error('unexpected peer event file');
     const events = await Promise.all(files.map(async (file) => JSON.parse(await readFile(join(root, 'events', file), 'utf8'))));
-    return { spec, events, state: reducePeerTask(spec, events, this.team) };
+    const team = this.registry ? this.registry.teams.get(events[0]?.team_hash) : this.team;
+    if (!team) throw new Error('task references an untrusted team policy');
+    return { spec, events, state: reducePeerTask(spec, events, team), ...(this.registry ? { team } : {}) };
   }
   async listLocal() {
     let entries;
@@ -85,7 +106,29 @@ 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); }); }
+  async registryTransaction(build) {
+    return this.locked(async () => {
+      for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+        await this.sync();
+        const result = await build(this.registry);
+        if (!result.files?.length) return result.value;
+        for (const [path, value] of result.files) {
+          if (!new RegExp(`^${registryPath.replace('.', '\\.')}/(?:versions/\\d{6}|(?:invitations|requests)/[a-f0-9-]{36})\\.json$`).test(path)) throw new Error('unsupported team registry file');
+          const target = join(this.checkout, path);
+          await mkdir(join(target, '..'), { recursive: true });
+          await writeFile(target, JSON.stringify(value, null, 2) + '\n', { flag: 'wx' });
+          await git(this.checkout, 'add', '--', path);
+        }
+        await git(this.checkout, 'commit', '-m', 'collab: update signed team enrollment');
+        try { await git(this.checkout, 'push', 'origin', 'HEAD:refs/heads/agent-collab'); }
+        catch { await pause(20 * (attempt + 1)); continue; }
+        await this.sync(); return result.value;
+      }
+      throw new Error('team enrollment not accepted; check Git access and retry');
+    });
+  }
   async transact(id, idempotencyKey, build) {
+    if (this.enrollmentOnly) throw new Error('enrollment client cannot write tasks');
     if (typeof idempotencyKey !== 'string' || !idempotencyKey || idempotencyKey.length > 300) throw new Error('invalid idempotency key');
     return this.locked(async () => {
       for (let attempt = 0; attempt < this.maxRetries; attempt++) {
@@ -102,10 +145,12 @@ export class PeerGitStore {
         if (!built) return null;
         const spec = current?.spec || built.spec;
         if (!spec || spec.id !== id) throw new Error('transaction task mismatch');
-        const event = this.sign({ schema_version: 2, task_id: id, seq: (current?.state.seq || 0) + 1,
+        const taskTeam = current?.team || this.team;
+        const sign = makeSigner(taskTeam, this.agentId, this.privateKey);
+        const event = sign({ schema_version: 2, task_id: id, seq: (current?.state.seq || 0) + 1,
           event_id: randomUUID(), actor_id: this.agentId, occurred_at: new Date(now).toISOString(), idempotency_key: idempotencyKey,
           ...built.event, ...(current ? {} : { spec_hash: digest(spec) }) });
-        reducePeerTask(spec, [...(current?.events || []), event], this.team);
+        reducePeerTask(spec, [...(current?.events || []), event], taskTeam);
         const root = this.root(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' });

package/schemas/encrypted-invite.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:codex-collab:encrypted-invite:v1",
+  "title": "Codex Collab Encrypted Private Onboarding Package v1",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "kind",
+    "salt",
+    "iv",
+    "tag",
+    "ciphertext"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "kind": {
+      "const": "codex-collab-encrypted-invite"
+    },
+    "salt": {
+      "type": "string",
+      "contentEncoding": "base64"
+    },
+    "iv": {
+      "type": "string",
+      "contentEncoding": "base64"
+    },
+    "tag": {
+      "type": "string",
+      "contentEncoding": "base64"
+    },
+    "ciphertext": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500000,
+      "contentEncoding": "base64"
+    }
+  },
+  "$comment": "This file is private, not a Git ledger record. Runtime validates decoded salt=16 bytes, IV=12 bytes and tag=16 bytes; scrypt derives AES-256-GCM key from a separate password, then verifies signed history and invitation in the decrypted payload."
+}

package/schemas/event.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:codex-collab:event:v1",
+  "title": "Codex Collab Event v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "event_id", "task_id", "seq", "type", "actor_id", "occurred_at", "idempotency_key"],
+  "allOf": [{
+    "if": { "properties": { "type": { "const": "handoff" } }, "required": ["type"] },
+    "then": {
+      "required": ["summary", "refs"],
+      "properties": {
+        "summary": { "type": "string", "minLength": 1, "maxLength": 4000 },
+        "refs": {
+          "type": "object", "required": ["branch", "commit", "tests"],
+          "properties": {
+            "branch": { "type": "string", "pattern": "^codex/[A-Za-z0-9][A-Za-z0-9._/-]{0,150}$" },
+            "commit": { "type": "string", "pattern": "^[a-fA-F0-9]{40}([a-fA-F0-9]{24})?$" },
+            "tests": { "type": "string", "minLength": 1, "maxLength": 1000 }
+          }
+        }
+      }
+    }
+  }],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "event_id": { "type": "string", "minLength": 1 },
+    "task_id": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]{1,63}$" },
+    "seq": { "type": "integer", "minimum": 1 },
+    "type": { "enum": ["created", "assigned", "run_started", "progress", "blocked", "run_failed", "handoff", "review_requested", "review_started", "review_note", "reviewed", "completed", "cancelled"] },
+    "actor_id": { "type": "string", "minLength": 1 },
+    "occurred_at": { "type": "string", "format": "date-time" },
+    "idempotency_key": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string", "maxLength": 4000 },
+    "assignee": { "type": "string", "minLength": 1 },
+    "chat_id": { "type": "string", "minLength": 1 },
+    "channel": { "enum": ["feishu", "wecom"] },
+    "run_id": { "type": "string", "minLength": 1 },
+    "decision": { "enum": ["approved", "changes_requested"] },
+    "refs": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "branch": { "type": "string" },
+        "commit": { "type": "string" },
+        "pr": { "type": "string" },
+        "tests": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/peer-event.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:codex-collab:peer-event:v2",
+  "title": "Codex Collab Signed Peer Event v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "event_id", "task_id", "seq", "type", "actor_id", "occurred_at", "idempotency_key", "team_hash", "signature"],
+  "properties": {
+    "schema_version": { "const": 2 },
+    "event_id": { "type": "string", "minLength": 1 },
+    "task_id": { "type": "string", "pattern": "^T-[A-Z0-9-]{1,62}$" },
+    "seq": { "type": "integer", "minimum": 1 },
+    "type": { "enum": ["created", "desktop_claimed", "claimed", "renewed", "progress", "checkpoint", "handoff", "stage_review_requested", "review_requested", "run_failed", "blocked", "reopened", "reviewed", "completed", "cancelled"] },
+    "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 },
+    "team_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "signature": { "type": "string", "minLength": 1 },
+    "spec_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "epoch": { "type": "integer", "minimum": 1 },
+    "lease_id": { "type": "string", "minLength": 1 },
+    "expires_at": { "type": "string", "format": "date-time" },
+    "summary": { "type": "string", "maxLength": 4000 },
+    "next_stage": { "type": "integer", "minimum": 1 },
+    "decision": { "enum": ["approved", "changes_requested"] },
+    "refs": {
+      "type": "object", "additionalProperties": false, "required": ["branch", "commit", "tests"],
+      "properties": {
+        "branch": { "type": "string", "pattern": "^codex/[A-Za-z0-9][A-Za-z0-9._/-]{0,150}$" },
+        "commit": { "type": "string", "pattern": "^[a-fA-F0-9]{40}([a-fA-F0-9]{24})?$" },
+        "tests": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" }
+      }
+    }
+  },
+  "allOf": [
+    { "if": { "properties": { "type": { "const": "created" } }, "required": ["type"] }, "then": { "required": ["spec_hash"] } },
+    { "if": { "properties": { "type": { "enum": ["claimed", "renewed"] } }, "required": ["type"] }, "then": { "required": ["epoch", "lease_id", "expires_at"] } },
+    { "if": { "properties": { "type": { "enum": ["checkpoint", "handoff", "stage_review_requested", "review_requested", "completed"] } }, "required": ["type"] }, "then": { "required": ["refs"] } },
+    { "if": { "properties": { "type": { "enum": ["handoff", "stage_review_requested"] } }, "required": ["type"] }, "then": { "required": ["summary", "next_stage"], "properties": { "summary": { "minLength": 1, "pattern": "\\S" } } } },
+    { "if": { "properties": { "type": { "const": "reviewed" } }, "required": ["type"] }, "then": { "required": ["decision"] } },
+    { "if": { "properties": { "type": { "const": "reopened" } }, "required": ["type"] }, "then": { "required": ["summary"], "properties": { "summary": { "minLength": 1, "pattern": "\\S" } } } }
+  ],
+  "$comment": "Runtime additionally verifies Ed25519 signatures, pinned team hash, event sequence, role/route/capacity, exact shared branch-tip SHA and state transitions. Manual desktop reservations have no lease and require manual continuation or cancellation. desktop_poll tasks use the claimed/renewed lease events and existing fencing; bound conversation IDs stay private, never in event fields or idempotency keys. Team policy v3 requires nonempty rejection feedback and a current expected_seq on human review writes; runtime checks these policy-dependent requirements."
+}

package/schemas/peer-task.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:codex-collab:peer-task:v2",
+  "title": "Codex Collab Peer Task v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "id", "repo", "title", "base_branch", "acceptance", "workflow"],
+  "properties": {
+    "schema_version": { "const": 2 },
+    "id": { "type": "string", "pattern": "^T-[A-Z0-9-]{1,62}$" },
+    "repo": { "type": "string", "minLength": 1 },
+    "title": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" },
+    "description": { "type": "string", "maxLength": 4000 },
+    "base_branch": { "const": "main" },
+    "execution_mode": { "enum": ["desktop", "automatic", "desktop_poll"] },
+    "acceptance": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" } },
+    "workflow": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" } },
+    "source": { "type": "object", "additionalProperties": false, "required": ["channel", "chat_id"], "properties": { "channel": { "const": "wecom" }, "chat_id": { "type": "string", "minLength": 1 } } }
+  },
+  "$comment": "Runtime additionally verifies repo identity and every workflow route against the pinned team policy. desktop_poll starts open and uses signed execution leases for existing-thread heartbeat workers; automatic SDK dispatch excludes that mode."
+}

package/schemas/task.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:codex-collab:task:v1",
+  "title": "Codex Collab Task v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "id", "repo", "title", "base_branch", "acceptance"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "id": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]{1,63}$" },
+    "repo": { "type": "string", "minLength": 1 },
+    "title": { "type": "string", "minLength": 1, "maxLength": 200 },
+    "description": { "type": "string" },
+    "base_branch": { "type": "string", "minLength": 1 },
+    "acceptance": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "source": { "type": "object", "additionalProperties": { "type": "string" } }
+  }
+}