xuym-codex-collab 0.4.4 → 0.6.0

package/apps/onboarding/manager.mjs

@@ -1,10 +1,14 @@
+import { inspectRepository, RepositoryError, resolveRemote, teamBaseBranch } from '../../packages/peer/repository.mjs';
 import { defaultReviewRules } from '../../packages/peer/review.mjs';
 import { SetupError } from './errors.mjs';
 import { createPublicKey, randomBytes, randomUUID } from 'node:crypto';
 import { chmod, mkdir, readFile, readdir, realpath, rename, stat, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readRunnerIntent, writeRunnerIntent } from '../peer/intent.mjs';
+import { localDefaults, workspaceHome } from './workspace.mjs';
+import { startupStatus } from './startup.mjs';
 import { fileURLToPath } from 'node:url';
 import { canonical, digest, generateIdentity, readPrivateJson, validateTeam } from '../../packages/peer/config.mjs';
 import { PeerGitStore, git } from '../../packages/peer/store.mjs';
@@ -50,9 +54,8 @@ function gitFailure(error) {
   if (/could not resolve host|failed to connect|network is unreachable|connection refused|network failure/.test(detail)) {
     return new SetupError('无法连接远程仓库，请检查网络或代理后重试。');
   }
-  return new SetupError('Git 无法读取远程仓库，请检查 origin 地址、Git 权限和网络后重试。');
+  return new SetupError('Git 无法读取远程仓库，请检查所选远程地址、Git 权限和网络后重试。');
 }
-function shellQuote(value) { return `'${String(value).replaceAll("'", "'\\''")}'`; }
 function mcpSection(text, serverName) {
   let active = false; const lines = [];
   for (const line of String(text || '').split(/\r?\n/)) {
@@ -71,7 +74,7 @@ function projectMcpConfigured(projectConfig, configPath, config) {
   const section = mcpSection(projectConfig, `team-collab-${config.agent_id}`);
   return !/^\s*enabled\s*=\s*false\s*(?:#.*)?$/m.test(section) && paths.some((path) => section.includes(JSON.stringify(path)));
 }
-async function ensureRepo(path) {
+async function ensureRepo(path, options = {}) {
   if (typeof path !== 'string' || !isAbsolute(path)) throw new SetupError('请选择业务仓库的本机绝对路径。');
   let repo;
   try { repo = await realpath(path); } catch { throw new SetupError('请选择存在的业务仓库目录。'); }
@@ -81,25 +84,10 @@ async function ensureRepo(path) {
     if (error instanceof SetupError) throw error;
     throw new SetupError('请选择 Git 仓库根目录。');
   }
-  let remote;
-  try { remote = await git(repo, 'remote', 'get-url', 'origin'); }
-  catch (error) {
-    const detail = `${error?.stderr || ''}\n${error?.message || ''}`.toLowerCase();
-    if (/no such remote|does not appear to be a git repository/.test(detail)) throw new SetupError('该目录没有名为 origin 的远程仓库，请先配置 GitHub origin。');
-    throw gitFailure(error);
-  }
-  let main;
-  try { main = await git(repo, 'ls-remote', '--heads', 'origin', 'refs/heads/main'); }
-  catch (error) { throw gitFailure(error); }
-  if (!main) {
-    let heads;
-    try { heads = await git(repo, 'ls-remote', '--heads', 'origin'); }
-    catch (error) { throw gitFailure(error); }
-    if (!heads) throw new SetupError(`远程仓库为空，未找到 origin/main。请先在终端执行：\ngit -C ${shellQuote(repo)} push -u origin main`);
-    throw new SetupError(`远程仓库可访问，但没有 main 分支。请先将本地 main 推送到 origin：\ngit -C ${shellQuote(repo)} push -u origin main`);
-  }
-  return { repo, remote };
+  try { return { repo, ...await (options.remoteOnly ? resolveRemote(repo, options) : inspectRepository(repo, options)) }; }
+  catch (error) { if (error instanceof RepositoryError) throw new SetupError(error.message); throw gitFailure(error); }
 }
+
 function validateBundle(value) {
   if (!value || value.schema_version !== 1 || value.kind !== 'codex-collab-invite' || typeof value.remote !== 'string' || !value.remote || !value.history || !value.invitation || !value.wecom || typeof value.wecom.secret !== 'string' || !value.wecom.secret) throw new SetupError('接入包格式无效。');
   const history = validateHistory(value.history, value.root_hash);
@@ -111,12 +99,13 @@ function validateBundle(value) {
 }
 
 export class SetupManager {
-  constructor({ home = join(homedir(), '.config', 'codex-collab', 'workspace'), discovery = new BotDiscovery(), runCli } = {}) {
+  constructor({ home = workspaceHome(), discovery = new BotDiscovery(), runCli } = {}) {
     this.home = resolve(home); this.discovery = discovery; this.queue = Promise.resolve(); this.resets = new ResetActions(this);
-    this.runCli = runCli || ((command, config) => {
-      const result = spawnSync(process.execPath, [join(packageRoot, 'bin/codex-collab.mjs'), command, config], { encoding: 'utf8', timeout: 35000, maxBuffer: 200000 });
-      if (result.status !== 0) throw new Error(`本机 ${command} 操作未完成，请检查项目 Git 权限或 Runner 日志。`);
-      return result.stdout.trim();
+    this.runCli = runCli || (async (command, config) => {
+      try {
+        const result = await promisify(execFile)(process.execPath, [join(packageRoot, 'scripts/peer/cli.mjs'), command, config], { timeout: 35000, maxBuffer: 200000 });
+        return result.stdout.trim();
+      } catch { throw new Error(`本机 ${command} 操作未完成，请检查项目 Git 权限或 Runner 日志。`); }
     });
   }
   async exclusive(fn) { const action = this.queue.then(fn); this.queue = action.catch(() => {}); return action; }
@@ -126,7 +115,7 @@ export class SetupManager {
   async profileStore(state, { enrollmentOnly = false } = {}) {
     const identity = await readPrivateJson(state.identity_path);
     const initial = state.bootstrap_team;
-    return new PeerGitStore({ repo: state.repo, dataDir: state.data_dir || join(this.path(state.id), 'data'), team: initial,
+    return new PeerGitStore({ remoteName: state.remote_name, remoteUrl: state.remote, repo: state.repo, dataDir: state.data_dir || join(this.path(state.id), 'data'), team: initial,
       agentId: state.agent_id, privateKey: identity.private_key, registryRoot: state.root_hash, enrollmentOnly }).init();
   }
   async overview() {
@@ -143,7 +132,8 @@ export class SetupManager {
       const draft = await readPrivateJson(join(this.home, 'drafts', file));
       if (!draft.profile_id) drafts.push({ id: draft.id, agent_id: draft.input.agent_id, display_name: draft.input.display_name, repo: draft.input.repo });
     }
-    return { profiles, removed_profiles, drafts };
+    let context = {}; try { context = await readPrivateJson(join(this.home, 'context.json')); } catch {}
+    return { profiles, removed_profiles, drafts, defaults: await localDefaults(context.cwd || this.home), startup: await startupStatus(this.home) };
   }
   async checkBotAvailable(botId) {
     for (const profile of (await this.overview()).profiles) {
@@ -162,7 +152,7 @@ export class SetupManager {
     }
     await this.checkBotAvailable(credentials.bot_id);
     if (input.repo) {
-      const { repo } = await ensureRepo(input.repo);
+      const { repo } = await ensureRepo(input.repo, { remoteName: input.remote_name, expectedRemote: input.remote_url, remoteOnly: true });
       const toml = await readFile(join(repo, '.codex/config.toml'), 'utf8').catch(() => '');
       for (const match of toml.matchAll(/"((?:[^"\\]|\\.)*\.json)"/g)) {
         try {
@@ -178,8 +168,8 @@ export class SetupManager {
   }
   async prepareProject(input) {
     const path = input.repo_mode === 'clone'
-      ? await cloneRepository({ remote: input.remote, destination: input.destination, privateHome: this.home }) : input.repo;
-    const selected = await ensureRepo(path);
+      ? await cloneRepository({ remote: input.remote, destination: input.destination || suggestedRepo(input.remote, memberFields({ ...input, display_name: input.display_name || input.agent_id || 'owner' }).agent_id), privateHome: this.home }) : input.repo;
+    const selected = await ensureRepo(path, { remoteName: input.remote_name, baseBranch: input.base_branch, allowSelection: true });
     if (inside(selected.repo, this.home)) throw new SetupError('本机配置目录必须在业务仓库之外。');
     return { ...selected, tests: await recommendTests(selected.repo) };
   }
@@ -191,7 +181,8 @@ export class SetupManager {
     const argv = input.test_command ? commandArgv(input.test_command) : testArgv(input.test_argv);
     const selected = await this.prepareProject(input);
     for (const profile of (await this.overview()).profiles) if (profile.repo === selected.repo) throw new SetupError('这个 clone 已接入其他身份，请选择独立 clone。');
-    const draft = { id: randomUUID(), input: { ...fields, repo: selected.repo, test_argv: argv, team_name: input.team_name?.trim() || null,
+    if (selected.selection_required) throw new SetupError('请先检查项目并选择协作远程和业务基准分支。');
+    const draft = { id: randomUUID(), input: { ...fields, repo: selected.repo, remote_name: selected.remote_name, remote_url: selected.remote, base_branch: selected.base_branch, test_argv: argv, team_name: input.team_name?.trim() || null,
       bot_id: input.bot_id, secret: input.secret } };
     await savePrivate(this.draftPath(draft.id), draft);
     return this.adminDraft({ id: draft.id });
@@ -202,7 +193,7 @@ export class SetupManager {
     let session;
     if (draft.discovery_id && !reconnect) { try { session = this.discovery.view(draft.discovery_id); if (['failed', 'expired', 'disconnected'].includes(session.status)) session = null; } catch {} }
     if (!session) {
-      session = await this.beginDiscovery({ bot_id: draft.input.bot_id, secret: draft.input.secret, repo: draft.input.repo });
+      session = await this.beginDiscovery({ bot_id: draft.input.bot_id, secret: draft.input.secret, repo: draft.input.repo, remote_name: draft.input.remote_name, remote_url: draft.input.remote_url });
       draft.discovery_id = session.id; await savePrivate(this.draftPath(id), draft);
     }
     return { ...session, draft_id: id, agent_id: draft.input.agent_id, repo: draft.input.repo };
@@ -223,18 +214,18 @@ export class SetupManager {
   async createAdmin(input, { onSaved } = {}) {
     const fields = memberFields(input), agentId = fields.agent_id;
     const caps = fields.capabilities; const argv = input.test_command ? commandArgv(input.test_command) : testArgv(input.test_argv || ['sh', 'test.sh']);
-    const { repo, remote } = await ensureRepo(input.repo);
+    const { repo, remote, remote_name, base_branch } = await ensureRepo(input.repo, { remoteName: input.remote_name, expectedRemote: input.remote_url, baseBranch: input.base_branch });
     if (inside(repo, this.home)) throw new SetupError('本机配置目录必须在业务仓库之外。');
     for (const profile of (await this.overview()).profiles) if (profile.repo === repo) throw new SetupError('这个 clone 已接入其他身份，请选择独立 clone。');
     const proof = this.discovery.consume(input.discovery_id);
     const id = randomUUID(); const directory = this.path(id);
     const identity = await getOrCreateIdentityFiles(agentId, join(this.home, 'identities'));
-    const team = buildTeamPolicy({ repo: input.repo_id?.trim() || remote, reviewer: agentId, defaultRoute: caps[0],
+    const team = buildTeamPolicy({ baseBranch: base_branch, repo: input.repo_id?.trim() || remote, reviewer: agentId, defaultRoute: caps[0],
       agents: [{ id: agentId, role: 'admin', capabilities: caps, publicKey: await readFile(identity.public_key_file, 'utf8'), wecomUserid: proof.userid }],
       routes: Object.fromEntries(caps.map((cap) => [cap, [agentId]])) });
     team.schema_version = 3; team.review_rules = defaultReviewRules(team.routes);
     const record = policyVersion(team, null, agentId, (await readPrivateJson(identity.private_key_file)).private_key);
-    const state = { id, role: 'admin', agent_id: agentId, display_name: fields.display_name, team_name: input.team_name || null, repo, remote, identity_path: identity.private_key_file, bootstrap_team: team,
+    const state = { id, role: 'admin', agent_id: agentId, display_name: fields.display_name, team_name: input.team_name || null, repo, remote, remote_name, identity_path: identity.private_key_file, bootstrap_team: team,
       root_hash: recordHash(record), genesis: record, test_argv: argv,
       wecom: { bot_id: proof.bot_id, secret: proof.secret, chat_ids: [proof.chatid], commands_enabled: true, allow_admin_commands: true }, phase: 'initializing' };
     await this.save(state);
@@ -256,7 +247,7 @@ export class SetupManager {
     const id = randomUUID(); const identityPath = join(this.path(id), 'identity.json');
     await savePrivate(identityPath, identity);
     let genesis, rootHash = config.team_registry_root;
-    const store = await new PeerGitStore({ repo: config.repo, dataDir: config.data_dir, team, agentId: config.agent_id, privateKey: config.private_key, registryRoot: rootHash }).init();
+    const store = await new PeerGitStore({ remoteName: config.remote_name, remoteUrl: config.remote_url, repo: config.repo, dataDir: config.data_dir, team, agentId: config.agent_id, privateKey: config.private_key, registryRoot: rootHash }).init();
     if (!rootHash) {
       const firstPath = join(store.checkout, '.agent-collab/team/versions/000001.json');
       if (await exists(firstPath)) {
@@ -277,16 +268,17 @@ export class SetupManager {
       }
     }
     const state = { id, role: team.agents[config.agent_id].role, agent_id: config.agent_id, repo: config.repo,
-      remote: await git(config.repo, 'remote', 'get-url', 'origin'), identity_path: identityPath, bootstrap_team: team, root_hash: rootHash,
+      remote: store.remoteUrl, remote_name: store.remoteName, identity_path: identityPath, bootstrap_team: team, root_hash: rootHash,
       test_argv: config.test_argv || ['sh', 'test.sh'], wecom: config.wecom, phase: 'ready', existing_config: resolve(config_path), data_dir: config.data_dir, attached: true };
     await savePrivate(join(this.path(id), 'peer.json'), { ...config, team_registry_root: rootHash });
     // Existing MCP processes keep using this path and the same private desktop state.
     await savePrivate(resolve(config_path), { ...config, team_registry_root: rootHash });
-    await this.save(state); this.runCli('start', resolve(config_path)); return this.detail(id, { localOnly: true });
+    await this.save(state); await this.runCli('start', resolve(config_path)); return this.detail(id, { localOnly: true });
   }
   async refreshAttachment(state, configPath) {
     try {
-      const installed = await installedProjectConfig({ repoPath: state.repo, agentId: state.agent_id });
+      const installed = await installedProjectConfig({ repoPath: state.repo, agentId: state.agent_id, allowMissing: true });
+      if (installed.missing) { await refreshProject({ configPath }); return; }
       const source = (await readPeerConfig(configPath)).config;
       const bound = (await readPeerConfig(installed.config_path)).config;
       if (bound.agent_id !== source.agent_id || bound.private_key !== source.private_key ||
@@ -296,10 +288,11 @@ export class SetupManager {
   }
   async resume(id) {
     const state = await this.state(id);
+    const wasReady = state.phase === 'ready';
     if (state.phase === 'removed') throw new SetupError('该项目已移除，请从首页恢复接入。');
     try {
       if (state.role === 'admin' && state.phase === 'initializing') {
-        const bootstrap = new PeerGitStore({ repo: state.repo, dataDir: join(this.path(id), 'data'), team: state.bootstrap_team, agentId: state.agent_id,
+        const bootstrap = new PeerGitStore({ remoteName: state.remote_name, remoteUrl: state.remote, repo: state.repo, dataDir: join(this.path(id), 'data'), team: state.bootstrap_team, agentId: state.agent_id,
           privateKey: (await readPrivateJson(state.identity_path)).private_key });
         await bootstrap.init();
         await bootstrap.registryTransaction(async () => {
@@ -351,7 +344,7 @@ export class SetupManager {
         const teamPath = join(this.path(id), 'team.json'); await savePrivate(teamPath, store.team);
         const configPath = join(this.path(id), 'peer.json');
         if (!await exists(configPath)) await createMemberConfig({ teamPath, identityPath: state.identity_path, repoPath: state.repo,
-          dataDir: join(this.path(id), 'data'), configPath, testArgv: state.test_argv });
+          dataDir: join(this.path(id), 'data'), configPath, testArgv: state.test_argv, remoteName: state.remote_name, remoteUrl: state.remote });
         const config = await readPrivateJson(configPath);
         await savePrivate(configPath, { ...config, team_registry_root: state.root_hash, wecom: state.wecom });
         await diagnosePeer(configPath, { testPush: true });
@@ -367,7 +360,11 @@ export class SetupManager {
       if (state.phase === 'ready') {
         await this.refreshAttachment(state, state.existing_config || join(this.path(id), 'peer.json'));
         await savePrivate(join(this.path(id), 'binding.json'), { prompt: bindingPrompt(state.agent_id, state.repo) });
-        this.runCli('start', state.existing_config || join(this.path(id), 'peer.json'));
+        const configPath = state.existing_config || join(this.path(id), 'peer.json');
+        const { config } = await readPeerConfig(configPath);
+        const intent = await readRunnerIntent(config.data_dir);
+        if (intent?.enabled) await this.runCli('recover', configPath);
+        else if (!intent && !wasReady) { await writeRunnerIntent(config.data_dir, true); await this.runCli('start', configPath); }
       }
       state.last_error = null; await this.save(state);
       return this.detail(id, { localOnly: true });
@@ -386,7 +383,7 @@ export class SetupManager {
   async inspectBundle(input) {
     const bundle = this.readBundle(input), invite = bundle.invitation;
     return { agent_id: invite.agent_id, display_name: bundle.display_name || invite.agent_id, team_name: bundle.team_name || null,
-      remote: bundle.remote, capabilities: invite.capabilities, bot_id: invite.bot_id, suggested_repo: suggestedRepo(bundle.remote, invite.agent_id) };
+      remote: bundle.remote, base_branch: teamBaseBranch(validateHistory(bundle.history, bundle.root_hash).latest.team), capabilities: invite.capabilities, bot_id: invite.bot_id, suggested_repo: suggestedRepo(bundle.remote, invite.agent_id) };
   }
   async importBundle(input) {
     const bundle = this.readBundle(input);
@@ -401,9 +398,9 @@ export class SetupManager {
   }
   async importAssignment(value, repo, ownAdminId) {
     const { bundle, history } = validateBundle(value);
-    const selected = await ensureRepo(repo);
+    const selected = await ensureRepo(repo, { expectedRemote: bundle.remote, remoteOnly: true });
     if (inside(selected.repo, this.home)) throw new SetupError('本机配置目录必须在业务仓库之外。');
-    if (remoteIdentity(selected.remote) !== remoteIdentity(bundle.remote)) throw new SetupError('该目录的 origin 与邀请仓库不一致，请选择正确仓库；工具不会改写 origin。');
+    if (remoteIdentity(selected.remote) !== remoteIdentity(bundle.remote)) throw new SetupError('该目录的远程与邀请仓库不一致，请选择正确仓库；工具不会改写远程配置。');
     let recovered;
     for (const profile of (await this.overview()).profiles) {
       const current = await this.state(profile.id);
@@ -422,7 +419,7 @@ export class SetupManager {
       recovered = current;
     }
     const id = recovered?.id || randomUUID(); const identity = await getOrCreateIdentityFiles(bundle.invitation.agent_id, join(this.home, 'identities'));
-    const state = { id, role: 'member', agent_id: bundle.invitation.agent_id, display_name: bundle.display_name || bundle.invitation.agent_id, team_name: bundle.team_name || null, repo: selected.repo, remote: selected.remote, identity_path: identity.private_key_file,
+    const state = { id, role: 'member', agent_id: bundle.invitation.agent_id, display_name: bundle.display_name || bundle.invitation.agent_id, team_name: bundle.team_name || null, repo: selected.repo, remote: selected.remote, remote_name: selected.remote_name, identity_path: identity.private_key_file,
       bootstrap_team: history.latest.team, root_hash: bundle.root_hash, bundle, test_argv: bundle.test_argv, phase: 'imported',
       ...(ownAdminId ? { own_admin_id: ownAdminId } : {}) };
     await this.save(state); return this.detail(id, { localOnly: true });
@@ -618,7 +615,10 @@ export class SetupManager {
   async createOwnAgent(input) {
     const state = await this.state(input.id);
     if (state.role !== 'admin' || state.phase !== 'ready') throw new SetupError('请从已接入的管理员项目添加自己的机器人。');
-    const selected = await ensureRepo(input.repo);
+    if (!idPattern.test(input.agent_id?.trim() || '')) throw new SetupError('请填写新 Agent 名称。');
+    const repo = input.repo_mode === 'clone' ? await cloneRepository({ remote: state.remote, destination: input.destination || suggestedRepo(state.remote, input.agent_id.trim()), privateHome: this.home }) : input.repo;
+    const team = (await this.profileStore(state)).team;
+    const selected = await ensureRepo(repo, { expectedRemote: state.remote, baseBranch: teamBaseBranch(team) });
     if (inside(selected.repo, this.home)) throw new SetupError('本机配置目录必须在业务仓库之外。');
     if (remoteIdentity(selected.remote) !== remoteIdentity(state.remote)) throw new SetupError('新 Agent 必须选择同一业务仓库的另一个 clone。');
     const files = await readdir(join(this.path(input.id), 'exports')).catch((error) => { if (error.code === 'ENOENT') return []; throw error; });
@@ -661,6 +661,32 @@ export class SetupManager {
     await savePrivate(config.team_file, store.team);
     return this.detail(id);
   }
+  async repositorySettings({ id }) {
+    const state = await this.state(id);
+    if (state.role !== 'admin' || state.phase !== 'ready') throw new SetupError('只有已接入的管理员可设置基准分支。');
+    const store = await this.profileStore(state);
+    const selected = await ensureRepo(state.repo, { remoteName: store.remoteName, expectedRemote: state.remote, allowSelection: true });
+    return { branches: selected.branches, base_branch: teamBaseBranch(store.team), default_branch: selected.base_branch, version: store.registry.latest.version };
+  }
+  async setRepositoryPolicy({ id, expected_version, base_branch }) {
+    const state = await this.state(id);
+    if (state.role !== 'admin' || state.phase !== 'ready') throw new SetupError('只有已接入的管理员可设置基准分支。');
+    if (!Number.isSafeInteger(expected_version) || expected_version < 1 || typeof base_branch !== 'string' || !base_branch) throw new SetupError('请重新读取团队基准分支后再保存。');
+    const store = await this.profileStore(state); const identity = await readPrivateJson(state.identity_path);
+    await ensureRepo(state.repo, { remoteName: store.remoteName, expectedRemote: state.remote, baseBranch: base_branch });
+    await store.registryTransaction(async (history) => {
+      if (history.latest.team.agents[state.agent_id]?.role !== 'admin') throw new SetupError('需要管理员权限。');
+      if (history.latest.version !== expected_version) throw new SetupError('团队规则已更新，请重新读取基准分支后再保存。');
+      const team = { ...structuredClone(history.latest.team), base_branch };
+      validateTeam(team);
+      if (canonical(team) === canonical(history.latest.team)) return { value: history.latest.version };
+      const version = policyVersion(team, history.latest, state.agent_id, identity.private_key);
+      return { files: [[versionFile(version), version]], value: version.version };
+    });
+    const { config } = await readPeerConfig(state.existing_config || join(this.path(id), 'peer.json'));
+    await savePrivate(config.team_file, store.team);
+    return this.detail(id);
+  }
   async setReviewRules({ id, expected_version, review_rules }) {
     const state = await this.state(id);
     if (state.role !== 'admin' || state.phase !== 'ready') throw new SetupError('只有已接入的管理员可设置审核规则。');
@@ -684,8 +710,12 @@ export class SetupManager {
     const state = await this.state(id); const result = { id, agent_id: state.agent_id, display_name: state.display_name || state.agent_id, team_name: state.team_name || null, role: state.role, repo: state.repo, phase: state.phase, own_agent: !!state.own_admin_id, error: state.last_error || null };
     if (state.phase === 'imported') result.assignment = { capabilities: state.bundle.invitation.capabilities, bot_id: state.bundle.invitation.bot_id,
       expires_at: state.bundle.invitation.expires_at };
-    if (state.role === 'admin' && state.phase === 'ready' && !localOnly) {
-      const store = await this.profileStore(state); const owners = new Map();
+    let synchronized;
+    if (state.phase === 'ready' && !localOnly) {
+      synchronized = await this.profileStore(state); result.base_branch = teamBaseBranch(synchronized.team); result.remote_name = synchronized.remoteName;
+    }
+    if (state.role === 'admin' && synchronized) {
+      const store = synchronized; const owners = new Map();
       result.members = Object.entries(store.team.agents).map(([id, agent]) => {
         if (agent.wecom_userid) {
           const group = owners.get(agent.wecom_userid) || []; group.push(id); owners.set(agent.wecom_userid, group);
@@ -693,7 +723,7 @@ export class SetupManager {
         return { id, capabilities: agent.capabilities, role: agent.role, verified_owner: !!agent.wecom_userid };
       });
       result.owners = [...owners].map(([userid, agent_ids]) => ({ agent_ids, is_you: userid === store.team.agents[state.agent_id]?.wecom_userid }));
-      result.routes = store.team.routes; result.review_rules = store.team.review_rules || null; result.policy_schema_version = store.team.schema_version; result.version = store.registry.latest.version; result.requests = [];
+      result.base_branch = teamBaseBranch(store.team); result.remote_name = store.remoteName; result.routes = store.team.routes; result.review_rules = store.team.review_rules || null; result.policy_schema_version = store.team.schema_version; result.version = store.registry.latest.version; result.requests = [];
       const files = await readdir(join(store.checkout, registryPath, 'requests')).catch((error) => { if (error.code === 'ENOENT') return []; throw error; });
       for (const file of files) {
         try {
@@ -716,7 +746,8 @@ export class SetupManager {
     }
     if (state.phase === 'ready') {
       result.config_path = state.existing_config || join(this.path(id), 'peer.json'); result.binding_prompt = bindingPrompt(state.agent_id, state.repo); result.detailed_binding_prompt = detailedBindingPrompt(state.agent_id, state.repo);
-      const config = (await readPeerConfig(result.config_path)).config;
+      const { config, team: cachedTeam } = await readPeerConfig(result.config_path);
+      result.base_branch ??= teamBaseBranch(cachedTeam); result.remote_name ??= config.remote_name || state.remote_name;
       const skillName = config.execution_mode === 'desktop_poll' ? 'team-collab-desktop' : 'team-collab';
       const projectConfig = await readFile(join(state.repo, '.codex', 'config.toml'), 'utf8').catch((error) => error.code === 'ENOENT' ? '' : Promise.reject(error));
       const installedSkill = await readFile(join(state.repo, '.agents', 'skills', skillName, 'SKILL.md'), 'utf8').catch((error) => error.code === 'ENOENT' ? '' : Promise.reject(error));
@@ -728,6 +759,7 @@ export class SetupManager {
       }
       const desktop = new DesktopExecutor({ agentId: config.agent_id, store: { clock: Date.now } }, config);
       result.desktop = await desktop.status();
+      result.connection_enabled = (await readRunnerIntent(config.data_dir))?.enabled ?? result.runner.online;
       result.last_poll_at = result.desktop.last_poll_at || null;
       result.poll_observed = !!result.last_poll_at;
       result.poll_recent = !!result.last_poll_at && Date.now() - Date.parse(result.last_poll_at) < 180000;
@@ -740,7 +772,10 @@ export class SetupManager {
     const state = await this.state(id); if (state.phase !== 'ready' || !['start', 'stop'].includes(command)) throw new SetupError('无效连接操作。');
     try {
       if (command === 'start' && [...this.discovery.sessions.values()].some((session) => session.bot_id === state.wecom?.bot_id && ['connecting', 'authenticated'].includes(session.status))) throw new SetupError('机器人正在验证，请先取消验证，再启动连接。');
-      this.runCli(command, state.existing_config || join(this.path(id), 'peer.json'));
+      const configPath = state.existing_config || join(this.path(id), 'peer.json');
+      const { config } = await readPeerConfig(configPath);
+      await writeRunnerIntent(config.data_dir, command === 'start');
+      await this.runCli(command, configPath);
       state.last_error = null; await this.save(state);
     } catch (error) {
       if (error instanceof SetupError) throw error;
@@ -749,6 +784,32 @@ export class SetupManager {
     }
     return this.detail(id, { localOnly: true });
   }
+  async diagnostics({ id }) {
+    const value = await this.detail(id, { localOnly: true });
+    const checks = [];
+    const add = (key, label, ok, action) => checks.push({ key, label, ok: !!ok, action: ok ? null : action });
+    add('setup', '本机接入', value.phase === 'ready', '先继续完成群身份验证和管理员确认。');
+    if (value.phase === 'ready') {
+      add('mcp', '项目 MCP', value.project_setup.mcp_configured, '点击修复本机配置，然后在 Codex 中重新加载项目 MCP。');
+      add('skill', '接入 Skill', value.project_setup.skill_installed, '点击修复本机配置，恢复工具生成的 Skill。');
+      add('runner', '后台机器人进程', value.runner.online, value.connection_enabled ? '连接已启用，后台将尝试恢复；也可以点击启动机器人连接。' : '连接已停止。需要接任务时点击启动机器人连接。');
+      add('wecom', '企业微信认证', value.runner.wecom === 'authenticated', '等待认证；若持续失败，请检查网络或通过更新机器人凭据重新验证。');
+      add('binding', '目标 Codex 对话', !!value.desktop.binding, '复制启用指令，发送到你选定的 Codex 对话。');
+      add('poll', '对话实际轮询', value.poll_recent, '在绑定对话中执行启用指令，并确认该对话的协作自动化已启用。');
+      try { await diagnosePeer(value.config_path, { testPush: true }); add('git', 'Git 读取与推送权限', true); }
+      catch { add('git', 'Git 读取与推送权限', false, '请完成本机 Git 登录，确认所选远程和团队基准分支可读，并具有协作分支推送权限。'); }
+    }
+    const startup = await startupStatus(this.home);
+    return { id, checks, ready: value.can_receive_tasks === true, startup, heartbeat_confirmed: false,
+      note: '检查使用真实进程、认证和轮询记录，不创建测试任务。未来能否自动唤醒仍需在 Codex 中确认自动化。' };
+  }
+  async repair({ id }) {
+    const state = await this.state(id);
+    if (state.phase !== 'ready') throw new SetupError('请先完成本机接入。');
+    const configPath = state.existing_config || join(this.path(id), 'peer.json');
+    await this.refreshAttachment(state, configPath);
+    return { id, repaired: true, next_step: '本机生成配置已更新。请在 Codex 重新加载项目 MCP，并在原绑定对话中执行启用指令。' };
+  }
   resetPreview(input) { return this.resets.preview(input); }
   resetDiscovery(input) { return this.resets.discover(input); }
   resetCancel(input) { return this.resets.cancel(input); }

package/apps/onboarding/reset.mjs

@@ -6,6 +6,7 @@ import { SetupError } from './errors.mjs';
 import { readPeerConfig, loadRuntime } from '../peer/runtime.mjs';
 import { PrivateDesktopState } from '../peer/private-state.mjs';
 import { alive, readRunnerLock } from '../peer/process.mjs';
+import { writeRunnerIntent } from '../peer/intent.mjs';
 import { installedProjectConfig } from '../../scripts/peer/refresh-project.mjs';
 import { bindingPrompt } from '../../scripts/peer/setup-desktop-project.mjs';
 import { digest, readPrivateJson } from '../../packages/peer/config.mjs';
@@ -152,8 +153,9 @@ export class ResetActions {
     if (!value || value.id !== input.id || value.kind !== input.kind || value.expires < Date.now() || value.fingerprint !== fingerprint) throw new SetupError('项目配置或绑定已改变，或预览已过期，请重新预览。');
   }
   async stop(context, plan) {
+    await writeRunnerIntent(context.dataDir, false);
     if (!plan.lock || !alive(plan.lock.pid)) return;
-    try { this.manager.runCli('stop', plan.lock.config); }
+    try { await this.manager.runCli('stop', plan.lock.config); }
     catch { throw new SetupError('机器人停止失败，未修改配置；请检查 Runner 后重试。'); }
     const lock = await readRunnerLock(join(context.dataDir, 'runner.pid.json'));
     if (lock && alive(lock.pid)) throw new SetupError('机器人仍在停止，请稍后重试；未修改配置。');

package/apps/onboarding/server.mjs

@@ -41,7 +41,7 @@ export async function startSetupServer({ manager = new SetupManager(), port = 0
         const value = await manager.exclusive(() => manager.exportedBundle(url.searchParams.get('id'), url.searchParams.get('invite')));
         res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Disposition': `attachment; filename="${value.filename}"` }); res.end(value.content); return;
       }
-      const actions = { 'project-check': () => manager.prepareProject(body), 'admin-prepare': () => manager.prepareAdmin(body), 'admin-complete': () => manager.completeAdmin(body), 'admin-retry': () => manager.adminDraft({ id: body.id, reconnect: true }), 'inspect-invite': () => manager.inspectBundle(body), progress: () => manager.progress(body), 'issue-batch': () => manager.issueBatch(body), 'reissue-invite': () => manager.reissueBundle(body), delivery: () => manager.delivery(body), 'reset-cancel': () => manager.resetCancel(body), 'reset-preview': () => manager.resetPreview(body), 'reset-discovery': () => manager.resetDiscovery(body), reset: () => manager.reset(body), 'own-agent': () => manager.createOwnAgent(body), 'own-agent-resume': () => manager.resumeOwnAgent(body), discovery: () => manager.beginDiscovery(body), admin: () => manager.createAdmin(body), import: () => manager.importBundle(body), existing: () => manager.importExisting(body), verify: () => manager.verifyMember(body), resume: () => manager.resume(body.id), issue: () => manager.issueBundle(body), approve: () => manager.approve(body), runner: () => manager.runner(body), 'review-rules': () => manager.setReviewRules(body) };
+      const actions = { 'repository-settings': () => manager.repositorySettings(body), 'repository-policy': () => manager.setRepositoryPolicy(body), diagnostics: () => manager.diagnostics(body), repair: () => manager.repair(body), 'project-check': () => manager.prepareProject(body), 'admin-prepare': () => manager.prepareAdmin(body), 'admin-complete': () => manager.completeAdmin(body), 'admin-retry': () => manager.adminDraft({ id: body.id, reconnect: true }), 'inspect-invite': () => manager.inspectBundle(body), progress: () => manager.progress(body), 'issue-batch': () => manager.issueBatch(body), 'reissue-invite': () => manager.reissueBundle(body), delivery: () => manager.delivery(body), 'reset-cancel': () => manager.resetCancel(body), 'reset-preview': () => manager.resetPreview(body), 'reset-discovery': () => manager.resetDiscovery(body), reset: () => manager.reset(body), 'own-agent': () => manager.createOwnAgent(body), 'own-agent-resume': () => manager.resumeOwnAgent(body), discovery: () => manager.beginDiscovery(body), admin: () => manager.createAdmin(body), import: () => manager.importBundle(body), existing: () => manager.importExisting(body), verify: () => manager.verifyMember(body), resume: () => manager.resume(body.id), issue: () => manager.issueBundle(body), approve: () => manager.approve(body), runner: () => manager.runner(body), 'review-rules': () => manager.setReviewRules(body) };
       const key = url.pathname.replace('/api/', ''); const action = Object.hasOwn(actions, key) ? actions[key] : null;
       if (req.method === 'POST' && url.pathname.startsWith('/api/') && action) return json(200, await manager.exclusive(action));
       return json(404, { error: '操作不存在。' });

package/apps/onboarding/startup.mjs

@@ -0,0 +1,61 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, open, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+const exec = promisify(execFile);
+const entry = fileURLToPath(new URL('./main.mjs', import.meta.url));
+const xml = (value) => String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+const unitArg = (value, expand = true) => {
+  let text = String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%');
+  if (expand) text = text.replaceAll('$', () => '$$');
+  return `"${text}"`;
+};
+export function startupDefinition({ home, platform = process.platform, userHome = homedir(), node = process.execPath, path = process.env.PATH || '/usr/bin:/bin' }) {
+  if ([home, userHome, node, path].some((value) => typeof value !== 'string' || /[\x00\r\n]/.test(value))) throw new Error('自启路径不能包含换行或空字符。');
+  const suffix = createHash('sha256').update(home).digest('hex').slice(0, 12);
+  const label = `com.codex-collab.${suffix}`;
+  const log = join(home, 'service.log');
+  if (platform === 'darwin') return { kind: 'launchd', label, path: join(userHome, 'Library/LaunchAgents', `${label}.plist`), content: `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>${label}</string><key>ProgramArguments</key><array>${[node, entry, '--home', home].map((arg) => `<string>${xml(arg)}</string>`).join('')}</array><key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict><key>ThrottleInterval</key><integer>15</integer><key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(path)}</string></dict><key>Umask</key><integer>63</integer><key>StandardOutPath</key><string>${xml(log)}</string><key>StandardErrorPath</key><string>${xml(log)}</string></dict></plist>\n` };
+  if (platform === 'linux') return { kind: 'systemd', label: `${label}.service`, path: join(userHome, '.config/systemd/user', `${label}.service`), content: `[Unit]\nDescription=Codex Collab local workspace\n[Service]\nType=simple\nExecStart=${[node, entry, '--home', home].map((arg) => unitArg(arg)).join(' ')}\nEnvironment=${unitArg(`PATH=${path}`, false)}\nRestart=on-failure\nRestartSec=15\nUMask=0077\n[Install]\nWantedBy=default.target\n` };
+  return null;
+}
+export async function configureStartup({ home, enabled = true, start = false, platform = process.platform, userHome = homedir(), execute = exec } = {}) {
+  const definition = startupDefinition({ home, platform, userHome });
+  const status = { enabled: false, supported: !!definition, kind: definition?.kind || null };
+  await mkdir(home, { recursive: true, mode: 0o700 });
+  const run = (command, args) => execute(command, args, { timeout: 10000, maxBuffer: 10000 });
+  if (definition) {
+    try {
+      if (enabled) {
+        const logPath = join(home, 'service.log');
+        const log = await open(logPath, 'a', 0o600); await log.close(); await chmod(logPath, 0o600);
+        await mkdir(dirname(definition.path), { recursive: true, mode: 0o700 });
+        await writeFile(definition.path, definition.content, { mode: 0o600 });
+        if (definition.kind === 'launchd') {
+          const domain = `gui/${process.getuid()}`;
+          if (start) {
+            try { await run('launchctl', ['bootstrap', domain, definition.path]); }
+            catch { await run('launchctl', ['kickstart', `${domain}/${definition.label}`]); }
+          }
+        } else {
+          await run('systemctl', ['--user', 'daemon-reload']);
+          await run('systemctl', ['--user', 'enable', ...(start ? ['--now'] : []), definition.label]);
+        }
+        status.enabled = true;
+      } else {
+        if (definition.kind === 'launchd') await run('launchctl', ['bootout', `gui/${process.getuid()}/${definition.label}`]).catch(() => {});
+        else await run('systemctl', ['--user', 'disable', definition.label]);
+        await rm(definition.path, { force: true });
+      }
+    } catch { status.error = '登录自启未完成。后台连接仍可使用，可运行 codex-collab autostart on 重试。'; }
+  } else if (enabled) status.error = '此系统暂不支持自动配置登录自启；本次后台服务已独立运行。';
+  await writeFile(join(home, 'startup.json'), JSON.stringify(status) + '\n', { mode: 0o600 });
+  return status;
+}
+export async function startupStatus(home) {
+  try { return JSON.parse(await readFile(join(home, 'startup.json'), 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return { enabled: false, supported: ['darwin', 'linux'].includes(process.platform) }; throw error; }
+}

package/apps/onboarding/supervisor.mjs

@@ -0,0 +1,41 @@
+import { join } from 'node:path';
+import { profiles } from './workspace.mjs';
+import { readPeerConfig } from '../peer/runtime.mjs';
+import { alive, readRunnerLock, acquireRunnerControl } from '../peer/process.mjs';
+import { readRunnerIntent, writeRunnerIntent } from '../peer/intent.mjs';
+import { savePrivate } from './manager.mjs';
+
+export class RunnerSupervisor {
+  constructor(manager, { clock = Date.now } = {}) { this.manager = manager; this.clock = clock; this.failures = new Map(); }
+  async tick() {
+    for (const profile of await profiles(this.manager.home)) {
+      if (profile.phase !== 'ready') continue;
+      const retry = this.failures.get(profile.id);
+      if (retry?.after > this.clock()) continue;
+      try {
+        const { config } = await readPeerConfig(profile.config_path);
+        const lock = await readRunnerLock(join(config.data_dir, 'runner.pid.json'));
+        let intent = await readRunnerIntent(config.data_dir);
+        // Upgrade only adopts a live connection. Previously stopped installations stay stopped.
+        if (!intent) {
+          const release = await acquireRunnerControl(config.data_dir, profile.config_path);
+          try {
+            intent = await readRunnerIntent(config.data_dir);
+            if (!intent) {
+              const current = await readRunnerLock(join(config.data_dir, 'runner.pid.json'));
+              intent = await writeRunnerIntent(config.data_dir, !!current && alive(current.pid));
+            }
+          } finally { await release(); }
+        }
+        if (!intent.enabled || lock && alive(lock.pid)) { this.failures.delete(profile.id); continue; }
+        if ([...this.manager.discovery.sessions.values()].some((session) => session.bot_id === config.wecom?.bot_id && ['connecting', 'authenticated'].includes(session.status))) continue;
+        await this.manager.runCli('recover', profile.config_path);
+        this.failures.delete(profile.id);
+      } catch {
+        const attempts = (retry?.attempts || 0) + 1;
+        this.failures.set(profile.id, { attempts, after: this.clock() + Math.min(300000, 15000 * 2 ** Math.min(attempts - 1, 5)) });
+      }
+    }
+    await savePrivate(join(this.manager.home, 'supervisor.json'), { checked_at: new Date(this.clock()).toISOString(), retrying: [...this.failures].map(([id, retry]) => ({ id, next_retry_at: new Date(retry.after).toISOString() })) });
+  }
+}