xuym-codex-collab 0.4.4 → 0.5.0

package/README.md

@@ -8,10 +8,10 @@
 
 ```sh
 npm install --global xuym-codex-collab
-codex-collab setup
+codex-collab
 ```
 
-`setup` 打开本机网页工作台，所有接入操作集中在一个页面。管理员选择“初始化团队”，成员选择“加入团队”；群身份验证、等待审批和本机配置会自动衔接，页面显示当前进度。已在使用旧配置的成员选择“导入已有配置”。终端保持运行即可继续使用工作台，关闭工作台后已启动的机器人连接仍运行。
+`setup` 打开本机网页工作台，所有接入操作集中在一个页面。管理员选择“连接我的机器人”，成员选择“接受同事邀请”；群身份验证、等待审批和本机配置会自动衔接，页面显示当前进度。已在使用旧配置的成员选择“导入已有配置”。命令启动后台工作台后退出，可以关闭终端和浏览器。macOS 默认设置登录自启；Linux 尝试配置 systemd 用户服务，失败时明确提示。工作台每 15 秒检查一次已开启的机器人进程，意外退出时恢复并在失败后退避重试；手动停止的连接保持停止。
 
 | 谁 | 在工作台做什么 | 接入后需要保留什么 |
 | --- | --- | --- |
@@ -36,6 +36,25 @@ Skill 完成身份核对、对话绑定和 heartbeat 配置，页面自动观察
 
 若管理员工作台显示接入包密码为空，通常是旧版本未保存原密码：无法从密文恢复，只能在管理员项目的“已分配的机器人”中重新生成包和密码。详情见[密码遗失恢复步骤](docs/onboarding.md#接入包密码遗失)。
 
+## 日常使用与升级
+
+在业务项目目录运行以下命令；只有一个接入时，也可以在任意目录运行。多个接入可通过 `codex-collab projects` 查看，再加 `--profile <项目ID>` 或唯一的 Agent ID 选择。原有显式 `peer.json` 路径参数继续支持。
+
+```sh
+codex-collab status
+codex-collab doctor
+codex-collab repair
+codex-collab stop
+codex-collab start
+codex-collab autostart status
+```
+
+`doctor` 检查项目 MCP/Skill、机器人进程与认证、对话绑定、真实轮询以及 Git 读取和推送权限，并给出下一步。页面也提供“检查整条连接”和“修复本机配置”。修复更新已识别的生成配置，并恢复缺失的 MCP 配置和 Skill；自定义、符号链接或已提交的共享配置需要手动合并。修复后请在 Codex 重新加载项目 MCP，在原对话执行启用指令。
+
+升级执行 `npm install -g xuym-codex-collab@latest`，然后重新打开工作台并修复项目配置。已经运行的 Node 进程需要重启才能加载新代码：停止并重新启动机器人；后台工作台可等下次登录，或终止 `codex-collab service-status` 显示的工作台 PID 后重新执行 `codex-collab`。0.5.0 迁移时只接管仍在运行的旧连接，已停止的旧连接需要你主动启动。
+
+`codex-collab autostart off` 关闭登录自启，`autostart on` 重新设置。`setup --no-startup` 仅跳过本次自启配置，`setup --foreground` 以前台模式运行，便于排查。Windows 支持独立后台工作台，暂未自动配置登录启动。电脑休眠、关机或退出系统期间不会执行群任务；Codex 对话的自动化仍需保持启用。
+
 ## 一次任务如何接力
 
 ```mermaid

package/apps/onboarding/commands.mjs

@@ -0,0 +1,46 @@
+import { isAbsolute, resolve } from 'node:path';
+import { SetupManager } from './manager.mjs';
+import { selectProfile, workspaceHome, profiles } from './workspace.mjs';
+import { configureStartup, startupStatus } from './startup.mjs';
+import { serviceState } from './main.mjs';
+
+// Preserve the original explicit peer.json interface for scripts and advanced users.
+export async function resolveCommand(args, { home = workspaceHome(), cwd = process.cwd() } = {}) {
+  const [command, ...input] = args;
+  let selector; const rest = [];
+  for (let i = 0; i < input.length; i++) {
+    if (input[i] === '--profile') { if (!input[i + 1]) throw new Error('--profile 需要项目 ID 或 Agent ID。'); selector = input[++i]; }
+    else rest.push(input[i]);
+  }
+  if (rest[0] && (isAbsolute(rest[0]) || rest[0].endsWith('.json'))) return { command, configPath: resolve(rest.shift()), args: rest };
+  const profile = await selectProfile({ home, cwd, selector });
+  return { command, configPath: profile.config_path, profile, args: rest };
+}
+export async function workspaceCommand(args, { home = workspaceHome() } = {}) {
+  if (args[0] === 'projects') {
+    console.log(JSON.stringify((await profiles(home)).map(({ id, agent_id, repo, phase }) => ({ id, agent_id, repo, phase })), null, 2)); return true;
+  }
+  if (args[0] === 'autostart') {
+    if (!['on', 'off', 'status'].includes(args[1])) throw new Error('usage: codex-collab autostart on|off|status');
+    console.log(JSON.stringify(args[1] === 'status' ? await startupStatus(home) : await configureStartup({ home, enabled: args[1] === 'on' }), null, 2)); return true;
+  }
+  if (args[0] === 'service-status') {
+    const state = await serviceState(home);
+    console.log(JSON.stringify({ online: !!state, pid: state?.pid || null, startup: await startupStatus(home) }, null, 2)); return true;
+  }
+  return false;
+}
+export async function guidedCommand(resolved, { home = workspaceHome() } = {}) {
+  if (resolved.command === 'repair' && !resolved.profile) {
+    const { refreshProject } = await import('../../scripts/peer/refresh-project.mjs');
+    console.log(JSON.stringify(await refreshProject({ configPath: resolved.configPath }), null, 2)); return true;
+  }
+  if (!['doctor', 'repair'].includes(resolved.command) || !resolved.profile) return false;
+  const manager = new SetupManager({ home });
+  try {
+    const value = resolved.command === 'repair' ? await manager.repair({ id: resolved.profile.id }) : await manager.diagnostics({ id: resolved.profile.id });
+    console.log(JSON.stringify(value, null, 2));
+    if (resolved.command === 'doctor' && value.checks.some((check) => !check.ok)) process.exitCode = 1;
+  } finally { manager.close(); }
+  return true;
+}

package/apps/onboarding/guided.mjs

@@ -55,6 +55,7 @@ export async function recommendTests(repo) {
   return commands.map((argv) => ({ argv, command: displayCommand(argv) }));
 }
 export function suggestedRepo(remote, agentId) {
+  if (typeof remote !== 'string' || !remote.trim()) throw new SetupError('请填写业务仓库地址。');
   const name = remote.split(/[/:]/).at(-1).replace(/\.git$/, '').replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 80) || 'project';
   return join(homedir(), 'codex-projects', `${name}-${agentId}`);
 }

package/apps/onboarding/main.mjs

@@ -1,32 +1,85 @@
 import { spawn } from 'node:child_process';
-import { mkdir, readFile, rm } from 'node:fs/promises';
+import { chmod, mkdir, open as openFile, readFile, rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { homedir } from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
 import { startSetupServer } from './server.mjs';
-import { SetupManager } from './manager.mjs';
+import { SetupManager, savePrivate } from './manager.mjs';
+import { RunnerSupervisor } from './supervisor.mjs';
+import { workspaceHome } from './workspace.mjs';
+import { configureStartup, startupStatus } from './startup.mjs';
 import { alive } from '../peer/process.mjs';
+const entry = fileURLToPath(import.meta.url);
 function openBrowser(url) {
   const command = process.platform === 'darwin' ? ['open', url] : process.platform === 'win32' ? ['cmd', '/c', 'start', '', url] : ['xdg-open', url];
   const child = spawn(command[0], command.slice(1), { stdio: 'ignore' }); child.on('error', () => {}); child.unref();
 }
-export async function runLocalSetup({ open = true, home = join(homedir(), '.config/codex-collab/workspace') } = {}) {
-  home = resolve(home); await mkdir(home, { recursive: true, mode: 0o700 });
+export async function serviceState(home) {
+  for (let attempt = 0; attempt < 30; attempt++) {
+    try { const state = JSON.parse(await readFile(join(home, 'wizard.json'), 'utf8')); return alive(state.pid) ? state : null; }
+    catch (error) { if (error.code === 'ENOENT') return null; if (!(error instanceof SyntaxError)) throw error; }
+    await delay(50);
+  }
+  throw new Error('本机工作台正在初始化，请稍后重试。');
+}
+export async function runService({ home = workspaceHome() } = {}) {
+  process.umask(0o077); home = resolve(home); await mkdir(home, { recursive: true, mode: 0o700 });
   const path = join(home, 'wizard.json'); let lock;
-  try { lock = await (await import('node:fs/promises')).open(path, 'wx', 0o600); }
-  catch (error) {
-    if (error.code !== 'EEXIST') throw error;
-    let previous; try { previous = JSON.parse(await readFile(path, 'utf8')); } catch { throw new Error('本机向导正在初始化，请稍后重试。'); }
-    if (alive(previous.pid)) { console.log(`本机向导已运行：${previous.url}`); if (open) openBrowser(previous.url); return; }
-    await rm(path, { force: true }); return runLocalSetup({ open, home });
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try { lock = await openFile(path, 'wx', 0o600); break; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if (await serviceState(home)) return null;
+      await rm(path, { force: true });
+    }
   }
-  let app;
+  if (!lock) throw new Error('无法取得本机工作台锁。');
+  let app, timer, stopping = false;
   try {
-    app = await startSetupServer({ manager: new SetupManager({ home }) });
-    await lock.writeFile(JSON.stringify({ pid: process.pid, url: app.url }) + '\n'); await lock.close();
-    console.log(`Codex Collab 本机接入向导：${app.url}\n保持此终端运行。Ctrl-C 关闭向导；已启动的机器人 Runner 会继续运行。`);
-    if (open) openBrowser(app.url);
-    const stop = async () => { await app.close(); await rm(path, { force: true }); process.exit(0); };
-    process.once('SIGINT', stop); process.once('SIGTERM', stop);
-    return app;
+    const manager = new SetupManager({ home });
+    app = await startSetupServer({ manager });
+    await lock.writeFile(JSON.stringify({ pid: process.pid, url: app.url, started_at: new Date().toISOString() }) + '\n'); await lock.close();
+    const supervisor = new RunnerSupervisor(manager);
+    const tick = async () => {
+      try { await manager.exclusive(() => supervisor.tick()); } catch { /* Local diagnostics show missing/invalid profiles without logging secrets. */ }
+      if (!stopping) timer = setTimeout(tick, 15000);
+    };
+    timer = setTimeout(tick, 1000);
+    const stop = async () => {
+      if (stopping) return; stopping = true; clearTimeout(timer);
+      await app.close(); const state = await serviceState(home); if (state?.pid === process.pid) await rm(path, { force: true });
+    };
+    process.once('SIGINT', () => void stop()); process.once('SIGTERM', () => void stop());
+    return { ...app, stop };
   } catch (error) { await lock.close().catch(() => {}); await rm(path, { force: true }); if (app) await app.close(); throw error; }
 }
+export async function runLocalSetup({ open = true, home = workspaceHome(), cwd = process.cwd(), foreground = false, startup = true } = {}) {
+  home = resolve(home); await savePrivate(join(home, 'context.json'), { cwd: resolve(cwd) });
+  let state = await serviceState(home);
+  if (foreground) {
+    if (state) { console.log(`本机工作台已运行：${state.url}`); if (open) openBrowser(state.url); return; }
+    const app = await runService({ home }); if (app) { console.log(`Codex Collab 工作台：${app.url}`); if (open) openBrowser(app.url); } return app;
+  }
+  const previous = await startupStatus(home);
+  let registered = startup ? previous : { enabled: false };
+  if (startup && (previous.enabled || previous.kind == null && previous.supported && !previous.error)) registered = await configureStartup({ home, start: !state });
+  if (!state) {
+    state = await serviceState(home);
+    if (!state && !registered.enabled) {
+      const log = await openFile(join(home, 'service.log'), 'a', 0o600); await chmod(join(home, 'service.log'), 0o600);
+      const child = spawn(process.execPath, [entry, '--home', home], { detached: true, stdio: ['ignore', log.fd, log.fd], env: process.env });
+      let error; child.on('error', () => { error = true; }); child.unref(); await log.close();
+      for (let i = 0; i < 100 && !state && !error; i++) { await delay(100); state = await serviceState(home); }
+    } else for (let i = 0; i < 100 && !state; i++) { await delay(100); state = await serviceState(home); }
+  }
+  if (!state) throw new Error(`本机后台工作台未启动，请检查 ${join(home, 'service.log')}，或运行 codex-collab setup --foreground。`);
+  console.log(`Codex Collab 工作台：${state.url}\n后台服务已运行，可以关闭终端和浏览器。${registered.enabled ? '登录时将自动恢复已开启的连接。' : '登录自启未启用。'}`);
+  if (registered.error) console.log(registered.error);
+  if (open) openBrowser(state.url);
+  return state;
+}
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  const args = process.argv.slice(2);
+  if (args.length !== 2 || args[0] !== '--home') throw new Error('Internal service requires --home.');
+  runService({ home: args[1] }).catch(() => { console.error('Codex Collab 后台服务启动失败，请运行 codex-collab setup --foreground 排查。'); process.exitCode = 1; });
+}

package/apps/onboarding/manager.mjs

@@ -2,9 +2,12 @@ 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';
@@ -111,12 +114,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; }
@@ -143,7 +147,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) {
@@ -178,7 +183,7 @@ 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;
+      ? 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);
     if (inside(selected.repo, this.home)) throw new SetupError('本机配置目录必须在业务仓库之外。');
     return { ...selected, tests: await recommendTests(selected.repo) };
@@ -282,11 +287,12 @@ export class SetupManager {
     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,6 +302,7 @@ 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') {
@@ -367,7 +374,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 });
@@ -618,7 +629,9 @@ 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 selected = await ensureRepo(repo);
     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; });
@@ -728,6 +741,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 +754,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 +766,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 登录，确认 origin/main 可读并具有推送权限。'); }
+    }
+    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 = { 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() })) });
+  }
+}

package/apps/onboarding/web/app.js

@@ -18,7 +18,13 @@ const values = (form) => Object.fromEntries(new FormData(form));
 function text(tag, value) { const node = document.createElement(tag); node.textContent = value; return node; }
 function button(label, fn) { const node = text('button', label); node.onclick = () => action(fn); return node; }
 async function overview() {
-  const value = await api('overview'); $('profiles').replaceChildren(); $('removed-profiles').replaceChildren();
+  const value = await api('overview');
+  if (value.defaults) {
+    if (!$('admin-form').elements.repo.value) $('admin-form').elements.repo.value = value.defaults.repo || '';
+    if (!$('admin-form').elements.display_name.value) $('admin-form').elements.display_name.value = value.defaults.display_name || '';
+  }
+  $('startup-status').textContent = value.startup?.enabled ? '后台服务已运行，登录时自动恢复已开启的连接。可关闭终端和浏览器。' : value.startup?.error || '后台工作台会保持连接；登录自启状态可用 codex-collab autostart status 查看。';
+  $('profiles').replaceChildren(); $('removed-profiles').replaceChildren();
   $('removed-projects').hidden = !(value.removed_profiles || []).length;
   for (const profile of value.removed_profiles || []) {
     const card = document.createElement('div'); card.className = 'card'; const info = document.createElement('div');
@@ -29,7 +35,7 @@ async function overview() {
     const card = document.createElement('div'); card.className = 'card';
     card.append(text('span', `${draft.display_name || draft.agent_id} · 待完成群验证`), button('继续创建团队', () => openDraft(draft.id))); $('profiles').append(card);
   }
-  if (!value.profiles.length && !(value.drafts || []).length) $('profiles').append(text('p', '还没有接入项目。管理员选择“初始化团队”，成员选择“加入团队”。'));
+  if (!value.profiles.length && !(value.drafts || []).length) $('profiles').append(text('p', '还没有接入项目。选择“连接我的机器人”，或导入同事提供的接入包。'));
   for (const profile of value.profiles) {
     const card = document.createElement('div'); card.className = 'card'; const info = document.createElement('div');
     info.append(text('strong', `${profile.display_name || profile.agent_id} · ${profile.role === 'admin' ? '管理员' : '成员'}`), text('p', profile.repo));
@@ -119,7 +125,7 @@ function renderProfile(value, automatic = false) {
   $('reset-conversation').hidden = value.phase !== 'ready'; $('reset-robot').hidden = value.phase !== 'ready';
   $('profile-title').textContent = `${value.display_name && value.display_name !== value.agent_id ? `${value.display_name}（${value.agent_id}）` : value.agent_id} · ${value.role === 'admin' ? '管理员' : '成员'}`; $('profile-repo').textContent = value.repo;
   $('profile-diagnostics').hidden = !value.config_path; $('config-path').textContent = value.config_path || '';
-  $('checks').replaceChildren(); $('progress').replaceChildren(); $('binding').hidden = value.phase !== 'ready'; $('runner-actions').hidden = value.phase !== 'ready'; $('admin-tools').hidden = value.role !== 'admin' || value.phase !== 'ready';
+  $('checks').replaceChildren(); $('progress').replaceChildren(); $('binding').hidden = value.phase !== 'ready'; $('runner-actions').hidden = value.phase !== 'ready'; $('diagnostic-actions').hidden = value.phase !== 'ready'; $('admin-tools').hidden = value.role !== 'admin' || value.phase !== 'ready';
   if (value.phase === 'ready') {
     $('binding-text').textContent = value.binding_prompt; $('binding-details').textContent = value.detailed_binding_prompt || value.binding_prompt;
     for (const [label, ok, wait] of [['项目 MCP', value.project_setup?.mcp_configured, '待配置'], ['项目 Skill', value.project_setup?.skill_installed, '待配置'], ['企业微信机器人', value.runner?.wecom === 'authenticated', value.runner?.online ? '连接中' : '已停止'], ['目标 Codex 对话', !!value.desktop?.binding, '待绑定'], ['对话实际轮询', value.poll_recent, value.poll_observed ? '最近未观察到轮询' : '待观察'], ['可接收任务', value.can_receive_tasks, '尚未满足条件']]) {
@@ -191,30 +197,46 @@ $('review-form').onsubmit = (event) => { event.preventDefault(); action(async ()
   await api('review-rules', { id: currentId, expected_version: reviewVersion, review_rules });
   await loadProfile(currentId); notice('审核规则已保存，新任务将使用此规则。');
 }); };
-for (const button of document.querySelectorAll('[data-view]')) button.onclick = () => action(async () => { clearInterval(timer); if (resetPlan) { await api('reset-cancel', { id: resetPlan.id, preview_token: resetPlan.preview_token }); resetPlan = null; resetDiscovery = null; $('reset-secret').value = ''; } remember(null); show(button.dataset.view); if (button.dataset.view === 'home') await overview(); });
+for (const button of document.querySelectorAll('[data-view]')) button.onclick = () => action(async () => { clearInterval(timer); if (resetPlan) { await api('reset-cancel', { id: resetPlan.id, preview_token: resetPlan.preview_token }); resetPlan = null; resetDiscovery = null; $('reset-secret').value = ''; } remember(null); show(button.dataset.view); if (button.dataset.view === 'home') await overview(); if (button.dataset.view === 'admin' && $('admin-form').elements.repo.value) await checkProject(); });
 function repoMode(prefix) {
   const clone = $(`${prefix}-repo-mode`).value === 'clone'; $(`${prefix}-existing-repo`).hidden = clone; $(`${prefix}-clone-repo`).hidden = !clone;
 }
-for (const prefix of ['admin', 'join']) $(`${prefix}-repo-mode`).onchange = () => repoMode(prefix);
-$('check-project').onclick = () => action(async () => {
-  const selected = await api('project-check', values($('admin-form')));
+for (const prefix of ['admin', 'join', 'own']) $(`${prefix}-repo-mode`).onchange = () => repoMode(prefix);
+async function checkProject() {
+  const snapshot = values($('admin-form'));
+  const selected = await api('project-check', snapshot);
+  const current = values($('admin-form'));
+  if (['repo_mode', 'repo', 'remote', 'destination'].some((key) => current[key] !== snapshot[key])) return;
   const form = $('admin-form'); form.elements.repo.value = selected.repo; $('admin-repo-mode').value = 'existing'; repoMode('admin');
   $('project-recommendation').textContent = `项目已检查：${selected.repo}。${selected.tests.length ? '推荐：' + selected.tests.map((test) => test.command).join(' / ') + '，请确认或修改。' : '未找到常见测试入口，请填写适合项目的验证命令。'}`;
   if (!$('test-command').value && selected.tests.length) $('test-command').value = selected.tests[0].command;
-});
+}
+$('check-project').onclick = () => action(checkProject);
+for (const id of ['admin-repo', 'admin-remote', 'admin-destination']) $(id).onchange = () => {
+  const form = $('admin-form');
+  if ($('admin-repo-mode').value === 'clone' ? form.elements.remote.value && form.elements.destination.value : form.elements.repo.value) action(checkProject);
+};
 $('admin-form').onsubmit = (event) => { event.preventDefault(); action(async () => {
   const input = values(event.target);
   const session = await api('admin-prepare', input); event.target.elements.secret.value = '';
   pending = { type: 'admin', draft_id: session.draft_id }; remember({ draft_id: session.draft_id }); await verifyView(session);
 }); };
 async function invitationInput(form) { const input = values(form); input.content = await input.file.text(); delete input.file; return input; }
-$('inspect-invite').onclick = () => action(async () => {
+async function inspectInvite() {
   $('invite-info').hidden = true; $('invite-summary').textContent = ''; $('invite-remote').textContent = '';
-  const value = await api('inspect-invite', await invitationInput($('join-form')));
+  const file = $('join-form').elements.file.files?.[0];
+  const input = await invitationInput($('join-form'));
+  const value = await api('inspect-invite', input);
+  if ($('join-form').elements.password.value !== input.password || $('join-form').elements.file.files?.[0] !== file) return;
   $('invite-info').hidden = false; $('invite-summary').textContent = `${value.display_name || value.agent_id}（${value.agent_id}）· 职责：${value.capabilities.join('、')}${value.team_name ? ' · ' + value.team_name : ''}`;
   $('invite-remote').textContent = value.remote;
   if (!$('join-form').elements.destination.value) $('join-form').elements.destination.value = value.suggested_repo;
-});
+}
+$('inspect-invite').onclick = () => action(inspectInvite);
+for (const id of ['invite-file', 'invite-password']) $(id).onchange = () => {
+  $('invite-info').hidden = true;
+  if ($('invite-file').files?.length && $('invite-password').value) action(inspectInvite);
+};
 $('join-form').onsubmit = (event) => { event.preventDefault(); action(async () => {
   const profile = await api('import', await invitationInput(event.target)); event.target.elements.password.value = ''; await connectMember(profile);
 }); };
@@ -242,6 +264,14 @@ $('retry-code').onclick = () => action(async () => {
 $('confirm-code').onclick = () => action(completeVerification);
 $('existing-form').onsubmit = (event) => { event.preventDefault(); action(async () => { const profile = await api('existing', values(event.target)); await loadProfile(profile.id); }); };
 $('issue-form').onsubmit = (event) => { event.preventDefault(); action(async () => { const input = values(event.target); input.id = currentId; input.prefer = event.target.elements.prefer.checked; input.commands_enabled = event.target.elements.commands_enabled.checked; const result = await api('issue', input); event.target.reset(); await loadProfile(currentId); await showDelivery(currentId, result.invite_id); notice('接入包已生成。下载文件交给指定成员，密码请单独发送。'); }); };
+$('run-diagnostics').onclick = () => action(async () => {
+  const value = await api('diagnostics', { id: currentId }); $('diagnostic-result').replaceChildren();
+  for (const check of value.checks) $('diagnostic-result').append(text('p', `${check.ok ? '✓' : '待处理'} ${check.label}${check.action ? '：' + check.action : ''}`));
+  $('diagnostic-result').append(text('p', value.note));
+});
+$('repair-project').onclick = () => action(async () => {
+  const value = await api('repair', { id: currentId }); await loadProfile(currentId); notice(value.next_step);
+});
 $('refresh').onclick = () => action(() => loadProfile(currentId));
 $('start').onclick = () => action(async () => { await api('runner', { id: currentId, command: 'start' }); await loadProfile(currentId); });
 $('stop').onclick = () => action(async () => { await api('runner', { id: currentId, command: 'stop' }); await loadProfile(currentId); });

package/apps/onboarding/web/index.html

@@ -1,32 +1,31 @@
 <!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Codex Collab · 团队接入</title><link rel="stylesheet" href="/style.css"></head><body>
 <header><span class="brand">Codex Collab</span><span>本机团队工作台</span></header>
-<main><h1>把群里的任务，交给你的 Codex 对话</h1><p class="intro">管理员分配机器人，成员导入接入包。项目配置与连接检查集中在这里。</p><div id="notice" role="status" hidden></div>
-<nav><button data-view="home">我的项目</button><button data-view="admin">初始化团队</button><button data-view="join">加入团队</button><button data-view="existing">导入已有配置</button></nav>
-<section id="home"><h2>我的项目</h2><div id="profiles"></div><details id="removed-projects" hidden><summary>已移除的接入</summary><p class="muted">本机身份与恢复记录保留。恢复前请确保原 clone 未绑定其他身份。</p><div id="removed-profiles"></div></details></section>
-<section id="admin" hidden><h2>管理员初始化</h2><p>先在企业微信创建智能机器人并加入协作群。这里会通过群验证码自动获取群和你的 userid。</p>
+<main><h1>把群里的任务，交给你的 Codex 对话</h1><p class="intro">选一种接入方式，按提示完成群验证，再把启用指令发给你的 Codex 对话。</p><div id="notice" role="status" hidden></div>
+<nav><button data-view="home">我的项目</button><button data-view="admin">连接我的机器人</button><button data-view="join">接受同事邀请</button><button data-view="existing">导入已有配置</button></nav>
+<section id="home"><div class="entry-options"><button data-view="admin">连接我的机器人<small>首次接入，或为团队建立协作项目</small></button><button data-view="join">接受同事邀请<small>已有接入包，自动带入机器人和项目信息</small></button></div><p id="startup-status" class="muted"></p><h2>我的项目</h2><div id="profiles"></div><details id="removed-projects" hidden><summary>已移除的接入</summary><p class="muted">本机身份与恢复记录保留。恢复前请确保原 clone 未绑定其他身份。</p><div id="removed-profiles"></div></details></section>
+<section id="admin" hidden><h2>连接我的机器人</h2><p>先在企业微信创建智能机器人并加入协作群。这里会通过群验证码自动获取群和你的 userid。</p>
 <form id="admin-form">
-<label>团队名称<input name="team_name" placeholder="例如：产品研发团队" maxlength="80"></label>
 <fieldset><legend>选择业务项目</legend><label>项目来源<select id="admin-repo-mode" name="repo_mode"><option value="existing">使用本机已有项目</option><option value="clone">从 Git 地址拉取新项目</option></select></label>
-<label id="admin-existing-repo">项目目录<input name="repo" placeholder="Git 仓库根目录的完整路径"></label>
-<div id="admin-clone-repo" hidden><label>Git 仓库地址<input name="remote" placeholder="HTTPS 或 SSH 地址，不含 Token"></label><label>保存到新目录<input name="destination" placeholder="新目录的完整路径"></label></div>
+<label id="admin-existing-repo">项目目录<input name="repo" id="admin-repo" placeholder="Git 仓库根目录的完整路径"></label>
+<div id="admin-clone-repo" hidden><label>Git 仓库地址<input name="remote" id="admin-remote" placeholder="HTTPS 或 SSH 地址，不含 Token"></label><label>保存到新目录（可选）<input name="destination" id="admin-destination" placeholder="留空按项目与名称生成独立目录"></label></div>
 <button id="check-project" type="button" class="secondary">检查项目并推荐验证命令</button><p id="project-recommendation" class="muted">自动拉取使用你本机已有的 Git 登录。仓库需要已有 main 分支。</p>
 <label>验证命令<input id="test-command" name="test_command" required placeholder="例如 npm test、go test ./...、sh test.sh"></label><p class="muted">请确认这个命令适合项目。工具使用固定程序和参数执行，不运行管道或拼接命令。</p></fieldset>
 <div class="row"><label>你的显示名称<input name="display_name" required placeholder="例如 Alice 或张三" maxlength="80"></label><label>主要职责<select name="responsibility"><option value="fullstack">全栈开发</option><option value="frontend">前端开发</option><option value="backend">后端开发</option><option value="testing">测试</option><option value="docs">文档</option><option value="general">通用开发</option></select></label></div>
-<details><summary>自定义内部身份与职责</summary><label>内部 Agent ID（可选）<input name="agent_id" pattern="[a-zA-Z0-9_-]{1,64}" placeholder="留空自动生成"></label><label>自定义职责标签（可选）<input name="capabilities" placeholder="英文标签，以逗号分隔"></label></details>
+<details><summary>更多设置：团队名称、内部身份与职责</summary><label>团队名称（可选）<input name="team_name" placeholder="留空使用项目名称" maxlength="80"></label><label>内部 Agent ID（可选）<input name="agent_id" pattern="[a-zA-Z0-9_-]{1,64}" placeholder="留空自动生成"></label><label>自定义职责标签（可选）<input name="capabilities" placeholder="英文标签，以逗号分隔"></label></details>
 <div class="row"><label>你的机器人 Bot ID<input name="bot_id" required autocomplete="off"></label><label>机器人 Secret<input name="secret" type="password" required autocomplete="off"></label></div>
-<button type="submit">创建团队并连接机器人</button></form></section>
+<button type="submit">连接并进入群验证</button></form></section>
 <section id="own" hidden><h2>给自己增加机器人</h2><p>同一个企业微信账号可以拥有多个 Agent。每个 Agent 使用独立机器人、独立 clone 和独立 Codex 对话。验证后自动完成本机接入，无需下载接入包。</p>
-<form id="own-form"><label>另一个 clone 的本机目录<input name="repo" required placeholder="同一业务仓库的另一个独立 clone"></label><div class="row"><label>新的 Agent 名称<input name="agent_id" required pattern="[a-zA-Z0-9_-]{1,64}" placeholder="bob"></label><label>职责标签<input name="capabilities" required placeholder="backend"></label></div><div class="row"><label>新机器人 Bot ID<input name="bot_id" required autocomplete="off"></label><label>新机器人 Secret<input name="secret" type="password" required autocomplete="off"></label></div><label class="checkbox"><input name="prefer" type="checkbox" checked>该 Agent 为这些职责的首选执行者</label><button type="submit">连接我的新机器人</button><button id="own-cancel" type="button" class="secondary">返回原项目</button></form></section>
-<section id="join" hidden><h2>加入团队</h2><p>导入管理员提供的加密接入包。机器人、职责和仓库信息会自动带入，密码请向管理员单独获取。</p>
-<form id="join-form"><label>接入包文件<input name="file" type="file" accept=".json" required></label><label>接入包密码<input name="password" type="password" required autocomplete="off"></label>
-<button id="inspect-invite" type="button" class="secondary">读取接入信息</button><div id="invite-info" hidden><p id="invite-summary"></p><p id="invite-remote" class="muted"></p></div>
+<form id="own-form"><label>准备项目<select id="own-repo-mode" name="repo_mode"><option value="clone">自动拉取独立项目</option><option value="existing">使用已有的独立 clone</option></select></label><label id="own-clone-repo">新项目目录（可选）<input name="destination" placeholder="留空按项目和 Agent 名称创建"></label><label id="own-existing-repo" hidden>另一个 clone 的本机目录<input name="repo" placeholder="同一业务仓库的另一个独立 clone"></label><div class="row"><label>新的 Agent 名称<input name="agent_id" required pattern="[a-zA-Z0-9_-]{1,64}" placeholder="bob"></label><label>职责标签<input name="capabilities" required placeholder="backend"></label></div><div class="row"><label>新机器人 Bot ID<input name="bot_id" required autocomplete="off"></label><label>新机器人 Secret<input name="secret" type="password" required autocomplete="off"></label></div><label class="checkbox"><input name="prefer" type="checkbox" checked>该 Agent 为这些职责的首选执行者</label><button type="submit">连接我的新机器人</button><button id="own-cancel" type="button" class="secondary">返回原项目</button></form></section>
+<section id="join" hidden><h2>接受同事邀请</h2><p>导入管理员提供的加密接入包。机器人、职责和仓库信息会自动带入，密码请向管理员单独获取。</p>
+<form id="join-form"><label>接入包文件<input name="file" id="invite-file" type="file" accept=".json" required></label><label>接入包密码<input name="password" id="invite-password" type="password" required autocomplete="off"></label>
+<button id="inspect-invite" type="button" class="secondary">重新读取接入信息</button><div id="invite-info" hidden><p id="invite-summary"></p><p id="invite-remote" class="muted"></p></div>
 <label>准备项目<select id="join-repo-mode" name="repo_mode"><option value="clone">帮我拉取到新目录</option><option value="existing">使用本机已有项目</option></select></label>
-<label id="join-clone-repo">新项目目录<input name="destination" placeholder="读取接入包后自动建议，亦可填写完整路径"></label>
+<label id="join-clone-repo">新项目目录<input name="destination" placeholder="留空使用推荐目录，亦可填写完整路径"></label>
 <label id="join-existing-repo" hidden>已有项目目录<input name="repo" placeholder="Git 仓库根目录的完整路径"></label>
 <button type="submit">接入我的机器人</button><p class="muted">工具使用本机 Git 登录拉取代码，不会改写已有目录。导入后请按提示在群里确认一次身份，审批和配置会自动继续。</p></form></section>
 <section id="existing" hidden><h2>导入已有协作项目</h2><p>先停止原 Runner。导入会保留原成员身份、任务和对话绑定，并重新启动机器人。旧团队由管理员先导入。</p><form id="existing-form"><label>已有私有 peer.json 路径<input name="config_path" required placeholder="完整路径"></label><button type="submit">导入已有项目</button></form></section>
 <section id="verification" hidden><h2>在群里确认身份</h2><p id="connection" role="status"></p><p class="muted">发送消息后页面会自动继续，无需回来确认。刷新页面可恢复当前接入进度。</p><p>请用自己的企业微信账号，<strong>@ 刚刚分配的机器人</strong>，发送下面这条消息：</p><pre id="code"></pre><button id="copy-code">复制消息</button><button id="confirm-code">立即检查</button><button id="retry-code" class="secondary" hidden>重新连接</button></section>
-<section id="profile" hidden><div class="row"><h2 id="profile-title"></h2><button id="refresh">刷新项目状态</button></div><p id="profile-repo"></p><details id="profile-diagnostics" hidden><summary>查看本机配置路径</summary><pre id="config-path"></pre><button id="copy-config-path">复制配置路径</button></details><p id="next-step" class="next-step" role="status"></p><ol id="setup-steps" class="setup-steps"></ol><details><summary>连接检查详情</summary><div id="checks"></div></details><div id="progress"></div><div id="binding" hidden><h3>最后一步：在你选定的 Codex 对话启用</h3><p>在 Codex 打开上面的项目，信任项目并加载 MCP，将下面的指令发到要绑定的对话。Skill 会完成身份检查、对话绑定和轮询启用。完成后本页自动更新实际连接状态。</p><pre id="binding-text"></pre><button id="copy-binding">复制启用指令</button><details><summary>无法识别 Skill 时使用详细指令</summary><pre id="binding-details"></pre><button id="copy-binding-details">复制详细指令</button></details></div><div id="runner-actions" hidden><button id="start">启动机器人连接</button><button id="stop" class="secondary">停止机器人连接</button><p class="muted">停止连接仅断开群机器人。对话中的轮询自动化需要在 Codex 中单独暂停。</p></div>
+<section id="profile" hidden><div class="row"><h2 id="profile-title"></h2><button id="refresh">刷新项目状态</button></div><p id="profile-repo"></p><details id="profile-diagnostics" hidden><summary>查看本机配置路径</summary><pre id="config-path"></pre><button id="copy-config-path">复制配置路径</button></details><p id="next-step" class="next-step" role="status"></p><ol id="setup-steps" class="setup-steps"></ol><details><summary>连接检查详情</summary><div id="checks"></div></details><div id="progress"></div><div id="binding" hidden><h3>最后一步：在你选定的 Codex 对话启用</h3><p>在 Codex 打开上面的项目，信任项目并加载 MCP（已打开的项目请重新加载 MCP），将下面的指令发到要绑定的对话。Skill 会完成身份检查、对话绑定和轮询启用。完成后本页自动更新实际连接状态。</p><pre id="binding-text"></pre><button id="copy-binding">复制启用指令</button><details><summary>无法识别 Skill 时使用详细指令</summary><pre id="binding-details"></pre><button id="copy-binding-details">复制详细指令</button></details></div><div id="diagnostic-actions" hidden><button id="run-diagnostics" class="secondary">检查整条连接</button><button id="repair-project" class="secondary">修复本机配置</button><div id="diagnostic-result" role="status"></div></div><div id="runner-actions" hidden><button id="start">启动机器人连接</button><button id="stop" class="secondary">停止机器人连接</button><p class="muted">停止连接仅断开群机器人。对话中的轮询自动化需要在 Codex 中单独暂停。</p></div>
 <details id="manage-project"><summary>管理与重置</summary><p>选择要调整的配置，先查看影响，再确认。每次只操作当前 Agent 和 clone。</p><div class="manage-actions"><button id="reset-conversation" class="secondary">重新绑定对话</button><button id="reset-robot" class="secondary">更新机器人凭据</button><button id="reset-project" class="danger">移除本机接入</button></div></details>
 <div id="admin-tools" hidden><details><summary>团队分工、审核与通知设置</summary><h3>团队 Agent 与分工</h3><div id="members"></div><div id="owners"></div><button id="add-own-agent" class="secondary">给自己增加机器人</button><div id="routes"></div><h3>真人审核与通知</h3><p>按职责设置：阶段结果提交后由谁审核、通知谁。关闭中间审核可直接接力；最终提交仍需真人审核，并由管理员完成任务。关闭审核的职责作为最后阶段时由管理员审核。</p><p id="review-policy-note" class="muted"></p><form id="review-form" hidden><div id="review-rules"></div><button type="submit">保存审核规则</button></form><p class="muted">规则保存后用于新任务。现有任务继续使用创建时的规则。审核通知附带分支、提交、测试和可复制的群命令；企业微信原生 @ 的显示效果需要在实际群中确认。</p></details><h3>批量分配机器人给同事</h3><p>每行分配一个独立机器人。同一个同事可以领取多行，分别绑定独立项目和对话。接入包密码自动生成。</p>
 <form id="batch-form"><div id="assignment-rows"></div><div class="row"><button id="add-assignment" type="button" class="secondary">增加一位成员／机器人</button><button type="submit">生成全部接入包</button></div></form>

package/apps/onboarding/web/style.css

@@ -5,3 +5,6 @@ form[hidden]{display:none}fieldset{border:1px solid #dbe6df;border-radius:9px;pa
 button[hidden],details[hidden],label[hidden]{display:none}details{margin:24px 0}summary{cursor:pointer;font-weight:600;line-height:1.7}.manage-actions{display:flex;gap:12px;flex-wrap:wrap}.danger{background:#fff;border:1px solid #d9aca4;color:#943c30}#reset-effects{line-height:1.9;padding-left:24px}#reset-target{overflow-wrap:anywhere}#reset-verification{padding:16px;background:#f0f5f2;border-radius:8px}
 
 #setup-steps{display:flex;flex-wrap:wrap;gap:10px;list-style:none;padding:0;margin:22px 0}#setup-steps li{font-size:13px;border:1px solid #e0e7e2;border-radius:7px;padding:9px 12px;color:#738379}#setup-steps .done{color:#176b4a;background:#eaf5ed;border-color:#cbe4d3}#setup-steps .active{color:#845d26;background:#fff5e2;border-color:#ebd29f}#next-step{padding:14px 16px;background:#edf6f0;border-radius:8px}#delivery-panel{padding:18px;background:#f6f9f7;border:1px solid #dbe6df;border-radius:9px;margin-top:20px}#delivery-panel h3{margin-top:0}#delivery-panel button{margin:6px 6px 6px 0}.assignment details{margin:0}.assignment>button{justify-self:start;background:#fff;color:#657970;border-color:#c9dacf}#assignment-rows{display:grid;gap:14px}#assignment-rows fieldset{margin:0}@media(max-width:640px){#setup-steps{gap:7px}#setup-steps li{flex:1 1 42%}.card>a{display:inline-block}.card{gap:14px}}
+
+.entry-options{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:16px;margin:12px 0 24px}.entry-options button{text-align:left;padding:24px;font-size:19px}.entry-options small{display:block;margin-top:10px;font-size:13px;font-weight:normal;line-height:1.6}#diagnostic-result p{line-height:1.7}#diagnostic-actions{margin:18px 0}
+form,label,fieldset,details,input,select{min-width:0}#invite-remote{overflow-wrap:anywhere}

package/apps/onboarding/workspace.mjs

@@ -0,0 +1,36 @@
+import { homedir, userInfo } from 'node:os';
+import { join, resolve } from 'node:path';
+import { readFile, readdir, realpath } from 'node:fs/promises';
+import { git } from '../../packages/peer/store.mjs';
+
+export const workspaceHome = () => resolve(process.env.CODEX_COLLAB_HOME || join(homedir(), '.config/codex-collab/workspace'));
+export async function localDefaults(cwd = process.cwd()) {
+  let repo = '';
+  try { repo = await git(cwd, 'rev-parse', '--show-toplevel'); } catch { /* Opening outside a project is supported. */ }
+  return { repo, display_name: userInfo().username };
+}
+export async function profiles(home = workspaceHome()) {
+  const root = join(home, 'profiles'); const result = [];
+  const entries = await readdir(root).catch((error) => { if (error.code === 'ENOENT') return []; throw error; });
+  for (const id of entries) {
+    if (!/^[a-f0-9-]{36}$/.test(id)) continue;
+    const state = JSON.parse(await readFile(join(root, id, 'setup.json'), 'utf8'));
+    if (state.phase !== 'removed') result.push({ ...state, config_path: state.existing_config || join(root, id, 'peer.json') });
+  }
+  return result;
+}
+export async function selectProfile({ home = workspaceHome(), selector, cwd = process.cwd() } = {}) {
+  let choices = (await profiles(home)).filter((state) => state.phase === 'ready');
+  if (selector) choices = choices.filter((state) => state.id === selector || state.agent_id === selector);
+  else {
+    const { repo } = await localDefaults(cwd);
+    if (repo) {
+      const matches = [];
+      for (const state of choices) if (await realpath(state.repo).catch(() => '') === repo) matches.push(state);
+      if (matches.length) choices = matches;
+    }
+  }
+  if (choices.length === 1) return choices[0];
+  if (!choices.length) throw new Error('未找到已接入项目。请先运行 codex-collab 完成接入。');
+  throw new Error(`找到多个接入，请使用 --profile <项目ID> 选择：\n${choices.map((state) => `${state.id}  ${state.agent_id}  ${state.repo}`).join('\n')}`);
+}

package/apps/peer/intent.mjs

@@ -0,0 +1,19 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+// Kept separately from setup.json: CLI stop must win over an open browser's stale state.
+export async function readRunnerIntent(dataDir) {
+  try {
+    const value = JSON.parse(await readFile(join(dataDir, 'runner-intent.json'), 'utf8'));
+    if (typeof value.enabled !== 'boolean') throw new Error('Invalid runner intent');
+    return value;
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+export async function writeRunnerIntent(dataDir, enabled) {
+  await mkdir(dataDir, { recursive: true, mode: 0o700 });
+  const path = join(dataDir, 'runner-intent.json'); const temporary = `${path}.${randomUUID()}.tmp`;
+  const value = { enabled, updated_at: new Date().toISOString() };
+  await writeFile(temporary, JSON.stringify(value) + '\n', { mode: 0o600, flag: 'wx' }); await rename(temporary, path);
+  return value;
+}

package/apps/peer/process.mjs

@@ -45,3 +45,16 @@ export async function acquireRunnerLock(dataDir, configPath) {
   }
   throw new Error('cannot acquire local Runner lock');
 }
+
+// Serialize CLI/supervisor start and stop across processes. The runner's own lock
+// still prevents duplicate bot connections; this control lock orders user intent.
+export async function acquireRunnerControl(dataDir, configPath) {
+  const deadline = Date.now() + 35000;
+  while (true) {
+    try { return await acquireRunnerLock(join(dataDir, 'runner-control'), configPath); }
+    catch (error) {
+      if (!error.message.startsWith('Runner already active') || Date.now() > deadline) throw error;
+      await delay(100);
+    }
+  }
+}

package/bin/codex-collab.mjs

@@ -12,15 +12,20 @@ function usage() {
   console.log(`Codex Collab
 
 Usage:
-  codex-collab setup [--no-open]
+  codex-collab setup [--no-open] [--foreground] [--no-startup]
   codex-collab setup --terminal [--role admin|member]
   codex-collab
   codex-collab identity create <agent-id> [--dir /absolute/private/directory]
   codex-collab wecom discover
-  codex-collab refresh-project /absolute/private-peer.json
-  codex-collab <doctor|start|stop|status|list|read|review|complete|reopen|...> /abs/private-peer.json [args]
+  codex-collab <status|start|stop|doctor|repair> [--profile <project-id|agent-id>]
+  codex-collab projects
+  codex-collab autostart on|off|status
+  codex-collab service-status
+  codex-collab refresh-project [--profile <project-id|agent-id>]
+  codex-collab <list|read|review|complete|reopen|...> [--profile <id>] [args]
+  Advanced: commands also accept /absolute/private-peer.json before args.
 
-setup opens the local web wizard. --terminal keeps the legacy terminal workflow. Never pass a bot Secret as a command argument.`);
+setup opens the local workspace and runs its service in the background. It restores enabled connections at login on macOS and Linux with a user service. --terminal keeps the legacy terminal workflow. Never pass a bot Secret as a command argument.`);
 }
 
 async function discoverWeCom() {
@@ -70,9 +75,10 @@ async function main() {
   }
 
   if (args[0] === 'refresh-project') {
-    if (args.length !== 2) throw new Error('usage: codex-collab refresh-project /absolute/private-peer.json');
+    const { resolveCommand } = await import('../apps/onboarding/commands.mjs');
+    const { configPath } = await resolveCommand(args);
     const { refreshProject } = await import('../scripts/peer/refresh-project.mjs');
-    console.log(JSON.stringify(await refreshProject({ configPath: args[1] }), null, 2));
+    console.log(JSON.stringify(await refreshProject({ configPath }), null, 2));
     return;
   }
 
@@ -84,19 +90,25 @@ async function main() {
 
   if (args[0] === 'setup' || args.length === 0) {
     const options = args[0] === 'setup' ? args.slice(1) : [];
-    let role, terminal = false, open = true;
+    let role, terminal = false, open = true, foreground = false, startup = true;
     for (let i = 0; i < options.length; i++) {
       if (options[i] === '--role' && ['admin', 'member'].includes(options[i + 1])) { role = options[++i]; terminal = true; }
       else if (options[i] === '--terminal') terminal = true;
       else if (options[i] === '--no-open') open = false;
+      else if (options[i] === '--foreground') foreground = true;
+      else if (options[i] === '--no-startup') startup = false;
       else throw new Error('usage: codex-collab setup [--no-open] or setup --terminal [--role admin|member]');
     }
     if (terminal) { const { runSetupWizard } = await import('../scripts/peer/onboarding.mjs'); await runSetupWizard({ role }); }
-    else { const { runLocalSetup } = await import('../apps/onboarding/main.mjs'); await runLocalSetup({ open }); }
+    else { const { runLocalSetup } = await import('../apps/onboarding/main.mjs'); await runLocalSetup({ open, foreground, startup }); }
     return;
   }
 
-  process.argv = [process.execPath, join(packageRoot, 'scripts/peer/cli.mjs'), ...args];
+  const { workspaceCommand, resolveCommand, guidedCommand } = await import('../apps/onboarding/commands.mjs');
+  if (await workspaceCommand(args)) return;
+  const resolved = await resolveCommand(args);
+  if (await guidedCommand(resolved)) return;
+  process.argv = [process.execPath, join(packageRoot, 'scripts/peer/cli.mjs'), resolved.command, resolved.configPath, ...resolved.args];
   await import('../scripts/peer/cli.mjs');
 }
 

package/docs/onboarding-audit.md

@@ -1,6 +1,6 @@
 # 网页向导功能检查与测试记录
 
-最近检查日期：2026-10-14。对象是工具仓库中的网页向导源码，初始记录对应 0.3.1 的发布前验证；后面的补充记录覆盖后续源码变更。
+最近检查日期：2026-10-22。对象是工具仓库中的网页向导源码，初始记录对应 0.3.1 的发布前验证；后面的补充记录覆盖后续源码变更。
 
 ## 测试范围
 
@@ -92,7 +92,7 @@ Skill 校验通过。`npm pack --dry-run` 确认发布包包含 `guided.mjs`、`
 | 更换 Bot ID、变更群 | 当前可在页面更新同一机器人的 Secret；更换 Bot ID 或群需移除接入，再使用管理员的新接入包 |
 | 撤销邀请、禁用/移除成员、轮换签名身份 | 当前没有产品化入口；需要补签名协议、权限与历史兼容，不能仅删本机文件 |
 | 修改既有成员职责、重排首选与候补 | 页面只展示已有分工；生成邀请时可以指定新成员优先级 |
-| 缺失 MCP/Skill 的一键修复 | 当前能识别缺失，但现有 Skill、受版本管理的配置等需要检查；不会自动覆盖 |
+| 自定义 MCP/Skill 的自动合并 | 0.5.0 可恢复缺失的生成配置；自定义、受版本管理或符号链接文件继续要求人工检查 |
 | 确认 heartbeat 持续启用 | 页面可解除旧绑定并观察最近轮询；暂停旧 heartbeat、启用新 heartbeat 仍需在对应 Codex 对话完成 |
 | 页面内展示日志与详细 Git 诊断 | 当前只有安全错误提示、私有配置路径；详细日志仍需本机查看 |
 | 多管理员配置冲突的页面引导 | 自动刷新保留未保存编辑，提示策略版本已变化；后端拒绝过时保存，仍需刷新重新确认 |
@@ -105,3 +105,13 @@ Skill 校验通过。`npm pack --dry-run` 确认发布包包含 `guided.mjs`、`
 - 应用退出、电脑休眠、heartbeat 暂停与网络恢复后，候补接管与旧执行者的租约隔离。
 
 页面的“项目 MCP / Skill 已就绪”表示本机文件已配置，并非读取了 Codex 的实际加载状态。近期成功轮询是额外证据，仍不能保证未来自动化持续运行。Git 启动检查与任务执行中的 Git 失败属于不同时间点，初始化通过不代表未来的 push 永远成功。
+
+## 2026-10-22 · 0.5.0 接入简化与后台运行
+
+完整自动测试通过 178 项，0 失败。新增覆盖后台工作台脱离终端、重复打开复用、会话鉴权与私有文件权限、已启用连接恢复与退避、主动停止后保持离线、升级迁移与并发停止、无需路径的项目选择，以及缺失 MCP/Skill 的安全修复。新增诊断和修复接口沿用本机会话与 Origin 校验。
+
+使用真实本机 Runner、临时业务 Git 仓库且不配置外部机器人，实际启动 Runner，强制结束进程，再通过后台监管恢复至不同 PID；执行停止命令后再次检查，连接保持离线。单独注册临时 macOS LaunchAgent，实际启动工作台并强制结束，确认 launchd 恢复至不同 PID，随后移除临时注册。测试没有接管个人现有机器人。
+
+使用本机 Chrome 实际检查：首页双入口、当前项目与本机名称默认值、验证命令推荐、连接诊断与修复、邀请文件上传和密码输入后自动读取、推荐 clone 目录。桌面与 390px 手机视口检查通过，邀请信息展开后没有横向溢出，页面没有脚本错误。机器人认证仍使用隔离测试连接，未连接真实企业微信群或创建 Codex 自动化。
+
+实际 npm tarball 在独立目录安装，命令入口、后台启动、页面资源、带会话鉴权的 API 与服务状态检查均通过。发布包包含 74 个文件，新增运行模块齐全，不包含本机凭据、运行日志或测试目录。Linux 仅验证 systemd 配置生成和失败处理；Windows 登录自启尚不支持。尚未实际退出登录或重启电脑，也未完成跨机器企业微信、真实 Codex 自动化与睡眠恢复的联合验收。

package/docs/onboarding.md

@@ -10,18 +10,18 @@
 
 ```sh
 npm install --global xuym-codex-collab
-codex-collab setup
+codex-collab
 ```
 
-网页自动打开；若未打开，执行 `codex-collab setup --no-open`，复制终端打印的本机链接。保留此终端以使用工作台。团队成员无需 clone 工具仓库。也可执行 `npx xuym-codex-collab@latest setup` 直接打开向导。
+网页自动打开；若未打开，执行 `codex-collab setup --no-open`，复制终端打印的本机链接。工作台已在后台运行，可以关闭终端和浏览器。macOS 默认设置登录自启，Linux 尝试设置 systemd 用户服务；未配置成功时页面和终端会明确提示。手动停止的连接不会在登录或后台检查时重新启动。团队成员无需 clone 工具仓库。也可执行 `npx xuym-codex-collab@latest setup` 临时打开向导；长期运行推荐全局安装，以便登录服务使用稳定安装路径。
 
 同一台电脑模拟两位成员时，使用同一业务仓库的两个独立 clone、两个机器人、两个 Codex 对话；同一个 clone 只能接入一个身份。同一个企业微信账号可以拥有多个 Agent，每个 Agent 的机器人、签名身份、clone 和对话独立。真正同事使用自己的企业微信账号和 Git 凭据。
 
 ## 管理员操作
 
 1. 在企业微信创建独立智能机器人，获取 Bot ID 和 Secret，拉进协作群。为每位成员分别创建机器人并加入同一个群；真人同事也加入群。
-2. 工作台选择“初始化团队”。填写团队名称，选择本机项目目录或 Git 地址与新目录。点击“检查项目并推荐验证命令”，确认或修改推荐命令，例如 `npm test`、`go test ./...` 或 `sh test.sh`。检查只读取常见测试入口，不执行项目脚本；实际任务使用确认后的固定程序与参数，不支持管道或命令拼接。
-3. 填写自己的显示名称、选择主要职责，输入自己的 Bot ID/Secret。名称可以是 `Alice` 或“张三”；内部 Agent ID 自动生成，自定义身份和标签可在折叠选项中调整。点击“创建团队并连接机器人”。
+2. 工作台选择“连接我的机器人”。当前目录属于 Git 项目时会自动带入项目根目录，并带入本机用户名。确认项目，或选择 Git 地址拉取新目录（目录可留空自动生成）。已有项目自动检查常见测试入口，也可点击“检查项目并推荐验证命令”；确认或修改推荐命令，例如 `npm test`、`go test ./...` 或 `sh test.sh`。检查只读取常见测试入口，不执行项目脚本；实际任务使用确认后的固定程序与参数，不支持管道或命令拼接。
+3. 填写自己的显示名称、选择主要职责，输入自己的 Bot ID/Secret。名称可以是 `Alice` 或“张三”；内部 Agent ID 自动生成，自定义身份和标签可在折叠选项中调整。点击“连接并进入群验证”。
 4. 用自己的企业微信账号 @ 此机器人，发送页面显示的 `协作 接入 六位数字`。页面自动发现群 `chatid` 与本人 `userid`，创建身份、签名账本，配置项目 MCP/Skill 并启动本机机器人 Runner；无需再点击继续。群验证中刷新页面可以恢复进度。
 5. 项目页面“批量分配机器人给同事”：每行填写显示名称、选择职责、填写独立机器人的 Bot ID/Secret，点击“增加一位成员／机器人”添加更多行。默认设为该职责的首选执行者并允许所有者群命令；候补与自定义 ID/职责在折叠选项中调整。一次最多 25 行。
 6. 点击“生成全部接入包”。密码自动生成；在“已分配的机器人”逐个下载加密 JSON 文件、查看并复制接入说明。把文件和说明交给指定成员，密码通过另一条可信渠道单独发送。说明不包含密码或 Secret。包默认 7 天有效，同一成员或机器人不会同时分发多个有效邀请；重复 ID/Bot 的批次会在发布前拒绝。
@@ -38,7 +38,7 @@ codex-collab setup
 2. 在管理员项目的“已分配的机器人”中，打开对应成员的“查看接入说明与密码”。如果显示密码缺失，点击“重新生成接入包与密码”。
 3. 页面会预填原 Bot ID；管理员在本机输入该机器人的 Secret。工具保留原 Agent 与职责，生成新加密文件和新密码，并在 Git 签名版本链中撤销旧邀请。Secret 不会发到聊天或写入 Git。
 4. 通过可信渠道分别交给成员新接入包和新密码。旧文件以及基于旧包创建、尚未批准的申请都不能再使用。
-5. 成员在“加入团队”选择 Bob 原来的本机 clone，上传新包并输入新密码，点击“读取接入信息”后再接入。工具会在确认签名替换关系后复用该 clone 的本地身份记录，清除旧申请并要求重新验证群身份；管理员随后确认新申请。
+5. 成员在“接受同事邀请”选择 Bob 原来的本机 clone，上传新包并输入新密码，选中文件并填完密码后，信息会自动读取；也可点击“重新读取接入信息”后再接入。工具会在确认签名替换关系后复用该 clone 的本地身份记录，清除旧申请并要求重新验证群身份；管理员随后确认新申请。
 
 该恢复入口仅用于未批准的普通成员邀请。已获批准的成员不能重签，应继续使用已有本机配置；管理员自己的机器人也不使用分发包恢复流程。若 Git 发布中断，半成品不会显示为可下载包；回到原邀请重试生成即可复用同一恢复记录。
 
@@ -50,8 +50,8 @@ codex-collab setup
 
 ## 成员操作
 
-1. 从管理员取得自己的加密接入包、接入说明和单独发送的密码，打开 `codex-collab setup` 或 `npx xuym-codex-collab@latest setup`，选择“加入团队”。
-2. 选择接入包文件、输入密码。可以点击“读取接入信息”查看团队、Agent、职责、仓库和建议目录。默认“帮我拉取到新目录”，可修改保存路径；也可切换“使用本机已有项目”。点击“接入我的机器人”。工具先验证接入包再 clone，使用本机 Git 登录；已有项目必须属于包内同一 remote，支持同一仓库的 SSH/HTTPS 表达。
+1. 从管理员取得自己的加密接入包、接入说明和单独发送的密码，打开 `codex-collab setup` 或 `npx xuym-codex-collab@latest setup`，选择“接受同事邀请”。
+2. 选择接入包文件、输入密码。填完后信息会自动读取；也可点击“重新读取接入信息”查看团队、Agent、职责、仓库和建议目录。默认“帮我拉取到新目录”，可修改保存路径；也可切换“使用本机已有项目”。点击“接入我的机器人”。工具先验证接入包再 clone，使用本机 Git 登录；已有项目必须属于包内同一 remote，支持同一仓库的 SSH/HTTPS 表达。
 3. 用**自己的企业微信账号** @ 分配给你的机器人，发送页面验证码。页面自动生成签名身份，把带公钥的入队申请写进协作分支，并进入等待批准；无需返回点击确认。刷新页面可以恢复当前验证或申请进度。
 4. 管理员明确批准后，页面自动检查 Git 权限、写入项目本地 MCP 和 Skill、启动机器人连接。正常流程无需点击“继续接入”；Git/配置异常时会停在可恢复的步骤，处理后再明确重试。
 5. 在 Codex 打开页面上的业务项目，信任项目并加载 MCP/Skill。点击“复制启用指令”，粘贴到要代表你的**已有对话**，例如：
@@ -171,3 +171,19 @@ Secret 若曾发到聊天或 Git，应在企业微信重新生成后更新本机
 重置预览有效期为十分钟。绑定、任务或文件变化后需重新预览；空闲轮询不会影响新 Secret 的群验证。当前 Agent 有有效任务租约时会拒绝重置，需先结束本阶段或在原对话报告失败；Git 无法访问时也不强行清理。自定义 Skill、自定义 MCP、Git 已跟踪或符号链接文件会阻止自动移除。
 
 操作前的私有备份位于向导配置目录的 `reset-backups/`，完成提示会显示完整路径。它可能包含私钥、旧 Secret 与本机任务信息，权限为 `0600`；目录权限为 `0700`，不要分享或提交。业务代码、共享任务分支、未提交改动和任务 worktree 保留。页面“移除”提供可恢复的解绑，并非清除所有私人数据；不再需要恢复时按本机配置路径自行清理备份与旧身份。
+
+## 0.5.0 后台连接与排查
+
+正常入口是 `codex-collab`；`setup` 保留为同一入口。首次在项目目录运行会带入项目路径与本机显示名称。团队名称、内部身份与职责标签收在更多设置中，仍需确认适合项目的验证命令。
+
+邀请文件和密码填好后自动展示成员、职责与项目。默认拉取到推荐目录；可以留空目录直接接入，也可以选择已有独立 clone。给自己增加机器人同样支持自动拉取独立目录。
+
+后台工作台与浏览器生命周期独立。macOS 使用 LaunchAgent；Linux 使用 systemd 用户服务。服务保留启动时的 Node 路径和 PATH，升级或更换 Node 安装位置后可运行 `codex-collab autostart on` 更新。自启注册失败会显示说明，当前会话仍尝试使用独立后台进程。Windows 暂时只支持独立后台进程。
+
+每 15 秒检查已开启的机器人进程。恢复失败按 15、30、60 秒等间隔退避，最长五分钟；机器人 SDK 本身处理连接重试。主动停止、移除、重置后的接入不会被恢复。0.4.x 的离线连接不会被迁移为自动启动。
+
+在业务项目目录执行 `codex-collab doctor`，或在页面点击“检查整条连接”，可以看到每个环节与处理办法。此检查读取真实状态并测试 Git 推送权限，不创建或执行业务测试任务；它不能证明未来的 Codex 自动化一定唤醒对话。`codex-collab repair` 更新受管理的项目 MCP 与 Skill，恢复缺失 MCP 配置和 Skill；自定义或共享文件会拒绝覆盖。之后仍需重新加载 MCP。
+
+`codex-collab status|start|stop|doctor|repair` 不再需要私有配置路径。多个接入时用 `codex-collab projects` 查看，再加 `--profile <项目ID>`；Agent ID 在本机唯一时也可使用。旧显式配置路径命令保留。`CODEX_COLLAB_HOME` 可指定独立私有工作台目录，用于隔离环境；不要放进业务仓库。
+
+`stop` 断开机器人并持久化停止意图；它不暂停 Codex 对话内的自动化。需要暂停整个协作时，还应在对应对话中暂停自动化。

package/docs/releases/0.5.0.md

@@ -0,0 +1,14 @@
+# 0.5.0 · 简化接入和后台运行
+
+日期：2026-10-22。
+
+- 首页提供“连接我的机器人”和“接受同事邀请”两个入口；带入当前 Git 项目和本机名称，自动推荐验证命令；团队名称与内部 ID 收进更多设置。
+- 输入邀请文件与密码后自动读取信息；成员默认自动拉取推荐目录，给自己增加机器人也支持自动创建独立 clone。
+- 普通启动命令退出后工作台留在后台。macOS 默认设置 LaunchAgent，Linux 尝试设置 systemd 用户服务；不支持或注册失败时给出明确状态。保留前台排查与跳过自启选项。
+- 后台只恢复已启用的机器人进程，失败后退避。持久化停止意图，串行处理跨进程启停，防止后台检查撤销用户的停止操作。迁移只接管仍运行的旧连接。
+- 增加无需配置路径的 status/start/stop/doctor/repair、项目选择、自启管理与后台服务状态命令；旧显式路径兼容。
+- 页面增加完整连接诊断与保守修复：真实进程、企微认证、绑定和轮询、Git 读写检查；恢复缺失的 MCP 配置和生成 Skill，自定义文件拒绝覆盖。
+
+企业微信机器人创建、管理员入队批准、选择真实 Codex 对话并启用自动化仍需要本人操作。此版本不引入云端中转、不自动创建业务任务作连接测试。
+
+验证详情见 `docs/onboarding-audit.md` 的 2026-10-22 条目。Windows 登录自启、真实重启登录、跨机器企业微信和 Codex 自动化联合验收仍需分别验证。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xuym-codex-collab",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Git-backed collaboration tools for Codex teams, with MCP, WeCom, and local runners.",
   "repository": {
     "type": "git",

package/scripts/peer/cli.mjs

@@ -6,9 +6,11 @@ import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
 import { loadRuntime, readPeerConfig } from '../../apps/peer/runtime.mjs';
-import { alive, readRunnerLock } from '../../apps/peer/process.mjs';
+import { alive, readRunnerLock, acquireRunnerControl } from '../../apps/peer/process.mjs';
 import { git } from '../../packages/peer/store.mjs';
 
+import { readRunnerIntent, writeRunnerIntent } from '../../apps/peer/intent.mjs';
+
 const root = fileURLToPath(new URL('../../', import.meta.url));
 const [command, configArg, ...args] = process.argv.slice(2);
 if (!command || !configArg) throw new Error('usage: node scripts/peer/cli.mjs install|doctor|probe|start|stop|status|list|read|review|complete|reopen|desktop-status|desktop-unbind /abs/peer.json [task-id] [decision/reason]');
@@ -20,6 +22,8 @@ async function running() {
   return state && alive(state.pid) ? state : null;
 }
 
+const releaseControl = ['start', 'recover', 'stop'].includes(command) ? await acquireRunnerControl(config.data_dir, configPath) : null;
+try {
 switch (command) {
   case 'probe': {
     try {
@@ -58,7 +62,9 @@ switch (command) {
     console.log(JSON.stringify({ identity: config.agent_id, auto_execute: config.auto_execute !== false, execution_session: config.execution_mode === 'desktop_poll' ? 'bound desktop heartbeat; adapter never launches SDK (check desktop-status and app heartbeat separately)' : 'new Runner-owned SDK thread; not an existing desktop conversation', config: 'valid; private key matches policy', git: 'shared origin and main readable', origin_configured: !!origin, wecom: config.wecom ? 'configured; live authentication not checked' : 'disabled', codex_provider: config.execution_mode === 'desktop_poll' ? 'uses the existing desktop conversation model; no SDK provider is launched by this adapter' : 'not tested; uses selected CODEX_HOME/provider configuration', test_argv: config.test_argv || ['sh', 'test.sh'] }, null, 2));
     break;
   }
-  case 'start': {
+  case 'start': case 'recover': {
+    if (command === 'recover') { if (!(await readRunnerIntent(config.data_dir))?.enabled) break; }
+    else await writeRunnerIntent(config.data_dir, true);
     const current = await running();
     if (current) { console.log(`Runner already online (PID ${current.pid})`); break; }
     await mkdir(config.data_dir, { recursive: true, mode: 0o700 });
@@ -81,10 +87,11 @@ switch (command) {
         if (health.pid === state.pid && new Date(health.updated_at).getTime() >= new Date(state.started_at).getTime() && ['connecting', 'authenticated', 'reconnecting', 'disconnected', 'failed'].includes(health.status)) wecom = health.status;
       } catch (error) { if (error.code !== 'ENOENT') throw error; }
     }
-    console.log(JSON.stringify({ identity: config.agent_id, execution_mode: config.execution_mode || 'legacy', auto_execute: config.auto_execute !== false, online: !!state, wecom, pid: state?.pid || null, log: join(config.data_dir, 'runner.log') }, null, 2));
+    console.log(JSON.stringify({ identity: config.agent_id, execution_mode: config.execution_mode || 'legacy', auto_execute: config.auto_execute !== false, online: !!state, connection_enabled: (await readRunnerIntent(config.data_dir))?.enabled ?? !!state, wecom, pid: state?.pid || null, log: join(config.data_dir, 'runner.log') }, null, 2));
     break;
   }
   case 'stop': {
+    await writeRunnerIntent(config.data_dir, false);
     const state = await running();
     if (!state) { console.log('Runner offline'); break; }
     if (state.config !== configPath) throw new Error('PID configuration mismatch; refusing to signal');
@@ -114,3 +121,5 @@ switch (command) {
   }
   default: throw new Error('unknown peer command');
 }
+
+} finally { await releaseControl?.(); }

package/scripts/peer/refresh-project.mjs

@@ -9,11 +9,12 @@ const root = fileURLToPath(new URL('../../', import.meta.url));
 const legacyHashes = new Set(['46543ca4fe00836f0ae0d7d7c12ea2756c9ab0220f01d29c391d608c5e405c53', '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) {
+async function plainPath(base, path, { allowMissing = false } = {}) {
   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 是符号链接，请先手动检查；未覆盖文件。');
+    let info; try { info = await lstat(current); } catch (error) { if (allowMissing && error.code === 'ENOENT') return; throw error; }
+    if (info.isSymbolicLink()) throw new Error('协作配置或 Skill 是符号链接，请先手动检查；未覆盖文件。');
   }
 }
 async function privateWrite(path, contents) {
@@ -22,14 +23,17 @@ async function privateWrite(path, contents) {
   finally { await rm(temporary, { force: true }); }
 }
 // Only recognize our generated MCP entry. Never replace another identity's entry.
-export async function installedProjectConfig({ repoPath, agentId }) {
+export async function installedProjectConfig({ repoPath, agentId, allowMissing = false }) {
   const repo = await realpath(repoPath);
-  const path = join(repo, '.codex/config.toml'); await plainPath(repo, path);
-  const before = await readFile(path, 'utf8');
+  const path = join(repo, '.codex/config.toml'); await plainPath(repo, path, { allowMissing });
+  const before = await readFile(path, 'utf8').catch((error) => { if (allowMissing && error.code === 'ENOENT') return null; throw error; });
   const server = `team-collab-${agentId}`;
-  const headers = [...before.matchAll(/^\s*\[([^\]\n]+)\][^\n]*$/gm)];
+  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}`);
+  // A missing block can be rebuilt from the private profile, but ambiguous or
+  // other identities' collaboration settings always require manual inspection.
+  if (!matching.length && allowMissing && !(before || '').includes('team-collab-')) return { repo, path, before, missing: true };
   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);
@@ -46,17 +50,19 @@ 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 installed = await installedProjectConfig({ repoPath: config.repo, agentId: config.agent_id, allowMissing: true });
   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 实际使用的个人配置路径；未更换身份。');
+  if (await git(repo, 'rev-parse', '--show-toplevel') !== repo || !installed.missing && 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);
+  await plainPath(repo, skillFile, { allowMissing: true });
   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 oldSkill = await readFile(skillFile, 'utf8').catch((error) => { if (error.code === 'ENOENT') return null; throw error; });
   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 (oldSkill !== null && oldSkill !== template && !legacyHashes.has(hash(oldSkill))) throw new Error('协作 Skill 已自定义，请手动合并自然语言处理说明；未覆盖文件。');
+  const command = `command = ${JSON.stringify(process.execPath)}`;
+  const args = `args = ${JSON.stringify([join(root, 'apps/peer/mcp-main.mjs'), installed.config_path || configPath])}`;
+  const nextSection = installed.missing ? `[mcp_servers.team-collab-${config.agent_id}]\n${command}\n${args}\n` : section.replace(/^command\s*=.*$/m, () => command).replace(/^args\s*=.*$/m, () => args);
+  const next = installed.missing ? `${before || ''}\n${nextSection}` : 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);
@@ -67,8 +73,10 @@ export async function refreshProject({ configPath }) {
   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' });
+    await mkdir(dirname(skillFile), { recursive: true, mode: 0o700 });
+    await mkdir(dirname(configFile), { recursive: true, mode: 0o700 });
     try { await privateWrite(configFile, next); await privateWrite(skillFile, template); }
-    catch (error) { await privateWrite(configFile, before); await privateWrite(skillFile, oldSkill); throw error; }
+    catch (error) { if (before === null) await rm(configFile, { force: true }); else await privateWrite(configFile, before); if (oldSkill === null) await rm(skillFile, { force: true }); else 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,