ai_co_discuss 0.2.13 → 0.2.15

package/runner/discussion_launch.mjs

@@ -1,664 +1,728 @@
-/** Shared launch configuration for an existing AI conversation and the local website. */
-import { spawn } from 'node:child_process';
-import { createHash, randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { setTimeout as sleep } from 'node:timers/promises';
-import { pathToFileURL } from 'node:url';
-import { parseArgs } from 'node:util';
-
-import { atomic_json } from './discussion_adapters.mjs';
-import { software_models } from './discussion_models.mjs';
-import { acquire_lock, api, CODEX_ADAPTERS, DiscussionStore, service_drafts, task_files, validate_config } from './discussion_runner.mjs';
-import { assert_shared_home, CONNECTION_FIELDS, configuration_snapshot, read_registry, registered_identity, register_room, service_home, service_pid, start_service } from './discussion_service.mjs';
-
-const CLIENTS = { Codex: ['codex_cli', 'codex'], Claude: ['claude'], Gemini: ['antigravity_cli', 'antigravity'] };
-// A platform is a type; `Claude-评审` is another Claude instance with its own session, model and effort.
-const INSTANCE_PATTERN = /^(Codex|Claude|Gemini|DeepSeek|Qwen)(?:-[0-9A-Za-z_一-鿿]{1,16})?$/;
-
-/** The platform of an AI instance name, or null. */
-export function platform_of(name) { return typeof name === 'string' ? INSTANCE_PATTERN.exec(name)?.[1] ?? null : null; }
-
-/** The first unused instance name of a platform: the platform itself, then platform-2, platform-3, …. */
-export function next_instance(platform, taken) {
-  if (!taken.has(platform)) return platform;
-  for (let number = 2; ; number++) if (!taken.has(`${platform}-${number}`)) return `${platform}-${number}`;
-}
-
-/** Supported local clients of an instance's platform. */
-function clients_of(name) { return CLIENTS[platform_of(name)]; }
-// Reasoning effort is a separate CLI argument only for Codex and Claude; agy encodes it in the model name.
-const EFFORT_LEVELS = { codex_cli: ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'], claude: ['low', 'medium', 'high', 'xhigh', 'max'] };
-const PROFILE_FIELDS = ['adapter', 'executable', 'model', 'effort', 'source_thread_id', 'ipc_directory', 'allowed_tools', 'cwd', 'project_name', 'project_id'];
-const MAX_MINUTES = 1440;
-const CONFIG_APPLY_TIMEOUT_MS = 6000;
-const CONFIG_APPLY_POLL_MS = 100;
-const HELP = `用法：codiscuss launch settings [--file FILE]
-      codiscuss launch start --file FILE [--dry-run]
-      codiscuss launch room-config --file FILE
-      codiscuss launch room-models --file FILE
-      codiscuss launch models --file FILE
-      codiscuss launch room-member --file FILE
-      codiscuss launch pick-directory
-
-settings 读取本机软件默认配置；指定文件时保存，不启动 AI。
-start 使用启动 JSON 创建或接入房间并启动；--dry-run 只校验和预览。
-room-config 修正已暂停房间的软件路径或切换 Codex App / CLI，不启动讨论；须提供 site、room_id、token。
-room-models 只读指定 site、room_id 的本机登记模型与思考强度，不启动讨论。
-models 按 adapter、executable 读取本机 CLI 的模型目录，不启动讨论或生成回答。
-pick-directory 在本机弹出系统目录选择窗口，返回所选路径；取消时不返回路径。
-room-member 为运行中的自由房间邀请或请回一位成员；须提供 site、room_id、token、action（add/rejoin）、name。
-JSON 指定 site、entry（conversation/web）、room（建房内容，含 submission_id）
-或 room_id（已有房间）、participants（本次软件覆盖配置）。
-conversation 还须 current_session_id，当前会话接手首个主持任务。
-已有受保护房间使用 access_file。路径、凭据只保存在本机。
-详见 docs/runner.md 的“两种讨论入口与启动配置”。
-`;
-
-// Windows PowerShell 5.1 ships WinForms. A background process cannot take the foreground, so the owner must be
-// shown (off-screen) as a topmost window; the dialog it owns then stays above the browser that asked for it.
-const WINDOWS_PICKER = [
-  'Add-Type -AssemblyName System.Windows.Forms',
-  '[Console]::OutputEncoding = [Text.Encoding]::UTF8',
-  '$owner = New-Object System.Windows.Forms.Form -Property @{ TopMost = $true; ShowInTaskbar = $false; FormBorderStyle = "None"; StartPosition = "Manual"; Location = New-Object System.Drawing.Point(-32000, -32000); Size = New-Object System.Drawing.Size(1, 1) }',
-  '$owner.Show(); $owner.Activate()',
-  '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog -Property @{ Description = "选择项目目录"; ShowNewFolderButton = $true }',
-  'if ($dialog.ShowDialog($owner) -eq "OK") { $dialog.SelectedPath }',
-  '$owner.Close()',
-].join('; ');
-const PICKERS = {
-  win32: ['powershell.exe', ['-NoProfile', '-STA', '-Command', WINDOWS_PICKER]],
-  darwin: ['osascript', ['-e', 'POSIX path of (choose folder with prompt "选择项目目录")']],
-  linux: ['zenity', ['--file-selection', '--directory', '--title=选择项目目录']],
-};
-
-/** Show the platform's own folder dialog on this computer; cancelling resolves without a path. */
-export function pick_directory({ platform = process.platform, spawn_process = spawn } = {}) {
-  const picker = PICKERS[platform];
-  if (!picker) return Promise.reject(new Error('此系统不支持目录选择窗口，请直接输入完整路径'));
-  return new Promise((resolve_result, reject) => {
-    const child = spawn_process(picker[0], picker[1], { shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
-    let output = '';
-    child.stdout.setEncoding('utf8');
-    child.stdout.on('data', chunk => { output += chunk; });
-    child.once('error', () => reject(new Error('无法打开目录选择窗口，请直接输入完整路径')));
-    child.once('close', code => {
-      const path = output.trim();
-      resolve_result(code === 0 && isAbsolute(path) ? { path } : { cancelled: true });
-    });
-  });
-}
-
-/** Some CLIs take seconds to list models; reuse a good list for a day unless the executable changes or the user retries. */
-const MODEL_CACHE_MS = 24 * 60 * 60 * 1000;
-
-/** Return the software catalog, served from the private service home when still valid. */
-export async function cached_software_models(home, profile, { refresh = false, query = software_models } = {}) {
-  const path = join(home, 'model-catalogs.json');
-  let stamp = '';
-  try { const file = statSync(profile.executable); stamp = `${file.size}:${file.mtimeMs}`; } catch {}
-  const key = JSON.stringify([profile.adapter, profile.executable || '', stamp]);
-  let cache = {};
-  try { cache = JSON.parse(readFileSync(path, 'utf8')); } catch {}
-  const hit = cache[key];
-  if (!refresh && hit && Date.now() - hit.at < MODEL_CACHE_MS) return hit.result;
-  const result = await query(profile);
-  if (!result.error && result.models.length) {
-    const prefix = JSON.stringify([profile.adapter, profile.executable || '']).slice(0, -1);
-    for (const old of Object.keys(cache)) if (old.startsWith(prefix)) delete cache[old];
-    atomic_json(path, { ...cache, [key]: { at: Date.now(), result } });
-  }
-  return result;
-}
-
-/** Read private defaults without selecting a global room or identity. */
-export function launch_settings(home) {
-  const path = join(home, 'launch-settings.json');
-  return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : { participants: {} };
-}
-
-/** Read only the registered room's model choices, never machine defaults or connection secrets. */
-export function room_models(home, raw) {
-  const input = launch_input({ ...raw, entry: 'web' });
-  if (!input.room_id) throw new Error('读取本场模型须提供 room_id');
-  const paths = read_registry(home).filter(path => {
-    const identity = registered_identity(path);
-    return identity?.site === input.site && identity.room === input.room_id;
-  });
-  if (paths.length > 1) throw new Error('本场存在多份登记配置，无法确定模型设置');
-  const profiles = paths.length ? configuration_snapshot(paths[0]).config.participants : {};
-  const participants = Object.fromEntries(Object.entries(profiles).map(([name, profile]) => {
-    const cli = ['codex_cli', 'claude', 'antigravity_cli'].includes(profile.adapter);
-    return [name, { adapter: profile.adapter, model: cli ? profile.model || '' : '',
-      effort: EFFORT_LEVELS[profile.adapter] ? profile.effort || '' : '' }];
-  }));
-  return { room_id: input.room_id, participants };
-}
-
-/** Save only reusable client settings; room credentials and session bindings are never defaults. */
-export function save_launch_settings(home, input) {
-  const participants = {};
-  for (const [name, profile] of Object.entries(input.participants || {})) {
-    if (platform_of(name) !== name) throw new Error(`本机默认配置按平台保存；${name} 的模型与强度只用于本场讨论`);
-    validate_profile(name, profile);
-    participants[name] = profile;
-  }
-  const settings = { participants };
-  mkdirSync(home, { recursive: true, mode: 0o700 });
-  atomic_json(join(home, 'launch-settings.json'), settings);
-  return settings;
-}
-
-/** Reject malformed client fields before saving defaults or creating any discussion. */
-function validate_profile(name, profile, binding = false) {
-  if (!clients_of(name) || !profile || typeof profile !== 'object' || Array.isArray(profile)) throw new Error(`不支持的软件配置：${name}`);
-  if (profile.adapter && !clients_of(name).includes(profile.adapter)) throw new Error(`${name} 的客户端不匹配`);
-  // Session bindings and project write access apply to one launch only, never to machine defaults.
-  const fields = binding ? [...PROFILE_FIELDS, 'session_id', 'project_access'] : PROFILE_FIELDS;
-  if (Object.keys(profile).some(key => !fields.includes(key))) throw new Error('软件配置包含不支持的字段；默认配置不能保存房间或会话绑定');
-  for (const [key, value] of Object.entries(profile)) {
-    if (key === 'allowed_tools') {
-      if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) throw new Error(`${name}.allowed_tools 必须为工具名称数组`);
-    } else if (typeof value !== 'string') throw new Error(`${name}.${key} 必须为文本`);
-    if (['executable', 'cwd', 'ipc_directory'].includes(key) && value && !isAbsolute(value)) throw new Error(`${name}.${key} 必须为完整绝对路径`);
-    // The model is passed as one CLI argument, so it must not look like a flag or contain spaces.
-    if (key === 'model' && value && !/^[A-Za-z0-9][A-Za-z0-9._:/@[\]-]*$/.test(value)) throw new Error(`${name}.model 只能是模型名称，例如 gpt-6-astra、opus 或 gemini-4-argon-high`);
-  }
-  if (profile.effort && !EFFORT_LEVELS[profile.adapter]?.includes(profile.effort)) {
-    throw new Error(EFFORT_LEVELS[profile.adapter] ? `${name}.effort 只能是 ${EFFORT_LEVELS[profile.adapter].join(' / ')}`
-      : `${name} 的思考档位不能单独设置；agy 请选择带档位的模型名，App 在软件内选择`);
-  }
-}
-
-/** Send one request without following redirects that could disclose the room credential. */
-async function site_request(site, path, token, body) {
-  const response = await fetch(`${site}${path}`, { method: body === undefined ? 'GET' : 'POST',
-    headers: { 'Content-Type': 'application/json', 'X-Discussion-Token': token },
-    body: body === undefined ? undefined : JSON.stringify(body), redirect: 'error', signal: AbortSignal.timeout(10000) });
-  const result = await response.json();
-  if (!response.ok) throw new Error(`HTTP ${response.status}: ${result.error || '请求失败'}`);
-  return result;
-}
-
-/** Require an explicit website, launch entry and stable creation identity. */
-function launch_input(input) {
-  const value = structuredClone(input);
-  const url = new URL(value.site);
-  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw new Error('site 必须为 HTTP(S) 根地址');
-  value.site = url.origin;
-  if (!['conversation', 'web'].includes(value.entry)) throw new Error('entry 必须为 conversation 或 web');
-  if (value.entry === 'conversation' && (typeof value.current_session_id !== 'string' || !value.current_session_id.trim())) throw new Error('对话入口须提供当前实际会话的 current_session_id');
-  if (value.cwd && (typeof value.cwd !== 'string' || !isAbsolute(value.cwd))) throw new Error('cwd 必须为完整绝对路径');
-  if (value.project_access && !['read', 'write'].includes(value.project_access)) throw new Error('project_access 只能为 read 或 write');
-  if (value.room_id && !/^[A-Za-z0-9_-]+$/.test(value.room_id)) throw new Error('房间编号无效');
-  if (!value.room_id && !value.room?.submission_id) throw new Error('新房间须提供 room.submission_id；重试沿用原编号');
-  if (value.room?.mode === 'free') {
-    // P1: a free room is launched once, at creation, from the web page.
-    if (value.entry !== 'web' || value.room_id) throw new Error('自由协作房间目前只能在网页创建时启动');
-    const members = value.room.members;
-    const names = members?.map(member => typeof member === 'string' ? member : member.name);
-    if (!Array.isArray(members) || !members.length || new Set(names).size !== names.length || names.some(name => !clients_of(name))) {
-      throw new Error('自由协作房间须选择至少 1 位支持自动接入的 AI 成员，且不能重复');
-    }
-  }
-  if (value.access_file) {
-    const access = JSON.parse(readFileSync(resolve(value.access_file), 'utf8'));
-    if (access.site?.replace(/\/$/, '') !== value.site || access.room !== value.room_id) throw new Error('access_file 与本次站点或房间不符');
-    value.token = access.token;
-  }
-  return value;
-}
-
-/** Merge machine defaults and explicit room overrides, preserving the selected participants. */
-function launch_config(home, input, room, directory, options) {
-  if (room.mode === 'free') return free_launch_config(home, input, room, directory, options);
-  if (!clients_of(room.host)) throw new Error('请选择支持全自动讨论的 AI 主持人');
-  if (!room.experts || room.experts[room.host] !== 'cli') throw new Error('请将 AI 主持人的参与方式设为本地读写');
-  const online = Object.entries(room.experts).filter(([, mode]) => mode !== 'cli').map(([name]) => name);
-  if (online.length) throw new Error(`全自动无法接入在线专家：${online.join('、')}。请调整参与方式或改用手动推进`);
-  const defaults = options.defaults || launch_settings(home).participants;
-  const participants = {};
-  for (const name of new Set([room.host, ...Object.keys(room.experts)])) {
-    participants[name] = participant_profile(name, defaults, input, name === room.host);
-  }
-  const members = launch_members(input, Object.keys(participants), options);
-  return validate_config({ site: input.site, room: room.id || 'preview', token: options.token, participants, members,
-    cwd: input.cwd, discussion_project: input.discussion_project, project_access: input.project_access || undefined,
-    data_directory: join(directory, 'runtime'), draft_directory: service_drafts(home, join(directory, 'runtime')) }, directory);
-}
-
-/** Free rooms add one private credential per member, kept with the room configuration for retries. */
-function free_launch_config(home, input, room, directory, options) {
-  const defaults = options.defaults || launch_settings(home).participants;
-  const names = room.members.map(member => typeof member === 'string' ? member : member.name);
-  const participants = Object.fromEntries(names.map(name => [name, participant_profile(name, defaults, input, false)]));
-  const members = launch_members(input, names, options);
-  return validate_config({ site: input.site, room: room.id || 'preview', token: options.token, mode: 'free', participants, members,
-    cwd: input.cwd, project_access: input.project_access || undefined,
-    data_directory: join(directory, 'runtime'), draft_directory: service_drafts(home, join(directory, 'runtime')) }, directory);
-}
-
-/** Preserve caller-generated member credentials; journal newly generated ones before creation. */
-function launch_members(input, names, options) {
-  return Object.fromEntries(names.map(name => {
-    const supplied = input.room?.members?.find(member => member?.name === name);
-    return [name, { token: supplied?.token || options.members?.[name]?.token || `${randomUUID()}${randomUUID()}` }];
-  }));
-}
-
-/** Merge one participant's machine defaults with this launch's overrides and check its software. */
-function participant_profile(name, defaults, input, current_host) {
-  const platform = platform_of(name);
-  // An extra instance starts from its platform's settings but never from another instance's bound session.
-  const { session_id: ignored_session, ...inherited } = name === platform ? {} : input.participants?.[platform] || {};
-  const profile = { ...defaults[platform], ...(name === platform ? {} : defaults[name]), ...inherited, ...input.participants?.[name] };
-  for (const field of ['cwd', 'model', 'effort', 'project_name', 'project_id', 'project_access']) if (profile[field] === '') delete profile[field];
-  validate_profile(name, profile, true);
-  if (!clients_of(name)?.includes(profile.adapter)) throw new Error(`请配置 ${name} 的 CLI / App 客户端`);
-  if (profile.adapter !== 'antigravity' && (!existsSync(profile.executable || '') || !statSync(profile.executable).isFile()
-    || (process.platform === 'win32' && !/\.exe$/i.test(profile.executable)))) throw new Error(`${name}：请指定实际原生可执行文件，Windows 使用 .exe`);
-  const cwd = profile.cwd || input.cwd;
-  if (cwd && (!existsSync(cwd) || !statSync(cwd).isDirectory())) throw new Error(`${name}：工作目录不存在或不是文件夹，请核对本次目录配置`);
-  if (input.entry === 'conversation' && current_host) profile.session_id = input.current_session_id;
-  // agy runs only in sessions this tool creates, so its native discussion project always applies.
-  if (profile.adapter === 'antigravity_cli' && profile.session_id) throw new Error(`${name}：agy 不能绑定已有会话或从当前 agy 对话主持全自动讨论；请从网页或其他软件发起，agy 会由讨论服务新建会话`);
-  return profile;
-}
-
-/** Find the one registered configuration of a free room after proving the owner's credential. */
-async function free_room_context(home, raw) {
-  const input = launch_input({ ...raw, entry: 'web' });
-  if (!input.room_id || typeof input.token !== 'string' || !input.token.trim()) throw new Error('管理成员须提供房间编号和房间控制凭据');
-  await site_request(input.site, `/api/rooms/${input.room_id}/inbox`, input.token);
-  const paths = read_registry(home).filter(path => {
-    const identity = registered_identity(path);
-    return identity?.site === input.site && identity.room === input.room_id;
-  });
-  if (paths.length !== 1) throw new Error('未找到本房间唯一的已登记配置，请核对本机接入服务');
-  const config = configuration_snapshot(paths[0]).config;
-  if (config.mode !== 'free') throw new Error('只有自由协作房间可以在运行中增减成员');
-  return { input, path: paths[0], config };
-}
-
-/** Write a manual member's private credential next to the room configuration, never into a receipt. */
-function manual_access(path, input, name, token) {
-  const access_path = join(dirname(path), `manual-${name}.access.json`);
-  atomic_json(access_path, { site: input.site, room: input.room_id, token });
-  return access_path;
-}
-
-/**
- * Invite (add) or bring back (rejoin) one member of a running free room.
- * The local configuration is written before the website call, so a retry reuses the same credential.
- */
-export async function room_member(home, raw, locked = false) {
-  const { input, path } = await free_room_context(home, raw);
-  const { action, name } = input;
-  const access = input.access || 'runner';
-  if (!['add', 'rejoin'].includes(action) || !platform_of(name) || (access !== 'manual' && !clients_of(name)) || !['runner', 'manual'].includes(access)) {
-    throw new Error('action 须为 add/rejoin，成员须为支持的 AI，接入方式须为 runner/manual');
-  }
-  const release = locked ? () => {} : acquire_lock(join(dirname(path), 'configuration-edit'));
-  try {
-    const config = configuration_snapshot(path).config;
-    const room = await site_request(input.site, `/api/rooms/${input.room_id}`, input.token);
-    if (action === 'add' && input.new_instance) {
-      // A name once bound keeps its session locally, so a new instance never reuses a removed member's name.
-      const taken = new Set([...room.free.members.map(member => member.name), ...Object.keys(config.participants), ...Object.keys(config.members || {})]);
-      return room_member(home, { ...raw, name: next_instance(platform_of(name), taken), new_instance: false }, true);
-    }
-    const current = room.free.members.find(member => member.name === name);
-    if (input.member_token !== undefined && (typeof input.member_token !== 'string' || input.member_token.length < 32 || input.member_token.length > 256)) throw new Error('member_token 须为 32–256 字符');
-    if (current?.status === 'active' && input.member_token && config.members?.[name]?.token === input.member_token) {
-      const view = await site_request(input.site, `/api/rooms/${input.room_id}/members/${current.id}`, input.token, { action: 'active', token: input.member_token });
-      return { room_id: input.room_id, member: name, access: current.access, free: view, access_file: null };
-    }
-    if (action === 'add' && !current && config.participants[name] && !locked) throw new Error(`${name} 曾在本房间使用过并绑定了会话；请换一个名称`);
-    if (action === 'rejoin' && current?.status !== 'away') throw new Error(`${name} 不是离开状态，无需请回`);
-    if (action === 'add' && current) throw new Error(`${name} 已是本房间成员；离开的成员请用请回`);
-    const manual = action === 'rejoin' ? current.access === 'manual' : access === 'manual';
-    const pending = input.retry_token && config.members?.[name]?.pending === input.retry_token;
-    const token = input.member_token || (pending ? config.members[name].token : `${randomUUID()}${randomUUID()}`);
-    let profile = config.participants[name];
-    if (!manual) {
-      if (action === 'add') profile = participant_profile(name, launch_settings(home).participants, { ...input, cwd: input.cwd || config.cwd }, false);
-      if (!profile) throw new Error(`${name} 没有本机接入配置；请移除后重新邀请`);
-      const next = { ...config, participants: { ...config.participants, [name]: profile },
-        members: { ...config.members, [name]: { token, pending: input.retry_token || '' } } };
-      validate_config(next, dirname(path));
-      atomic_json(path, next);
-    }
-    const access_file = manual ? manual_access(path, input, name, token) : null;
-    const body = action === 'add'
-      ? { name, adapter: manual ? '' : profile.adapter, token, access, session_mode: profile?.session_id ? 'borrowed' : 'new' }
-      : { action: 'active', token };
-    const view = await site_request(input.site, action === 'add' ? `/api/rooms/${input.room_id}/members` : `/api/rooms/${input.room_id}/members/${current.id}`,
-      input.token, body);
-    return { room_id: input.room_id, member: name, access: manual ? 'manual' : 'runner', free: view, access_file };
-  } finally { release(); }
-}
-
-/** Stable signatures make changed retry requests explicit without putting credentials in receipts. */
-function signature(value) {
-  if (Array.isArray(value)) return `[${value.map(signature).join(',')}]`;
-  if (value && typeof value === 'object') return `{${Object.keys(value).sort().filter(key => value[key] !== undefined).map(key => `${JSON.stringify(key)}:${signature(value[key])}`).join(',')}}`;
-  return JSON.stringify(value);
-}
-
-/** Inherit the topic duration unless overridden; zero leaves the run without a time limit. */
-function launch_minutes(input, room) {
-  const minutes = Number(input.minutes ?? room.limits?.max_minutes ?? 0);
-  if (!Number.isFinite(minutes) || minutes < 0 || minutes > MAX_MINUTES) throw new Error('讨论总时长或 minutes 须在 [0,1440]，0 表示不限时长');
-  return minutes;
-}
-
-/** Refuse a second registry owner before changing the website runtime. */
-function check_registration(home, config, path) {
-  for (const registered of read_registry(home)) {
-    if (resolve(registered) === path || !existsSync(registered)) continue;
-    const other = registered_identity(registered);
-    if (other?.site === config.site && other.room === config.room) throw new Error('房间已使用另一份接入配置登记；请沿用原配置，不重复接入');
-  }
-}
-
-/** Start once; a lost start response is reconciled from the persisted expected generation. */
-async function enable_run(config, record, persist, minutes) {
-  let runtime = await api(config, '/runtime');
-  if (!record.generation && record.expected_generation === runtime.generation && runtime.revision === record.start_revision && runtime.status === 'running') {
-    record.generation = runtime.generation;
-    persist();
-  }
-  if (record.generation) {
-    if (runtime.generation !== record.generation || runtime.status !== 'running' || runtime.expired) throw new Error('这次启动已暂停、停止或过期；请在原房间核对并明确继续');
-    return runtime;
-  }
-  if (runtime.status !== 'ready' || runtime.expired) throw new Error('房间已运行、暂停、停止或过期；请在原房间核对，不会重新启动');
-  if (!record.start_revision) { record.start_revision = runtime.revision + 1; persist(); }
-  if (runtime.revision + 1 !== record.start_revision) throw new Error('启动期间房间状态已变化，请核对原房间');
-  record.expected_generation = runtime.generation + 1;
-  persist();
-  try {
-    runtime = await api(config, '/runtime', { action: 'start', mode: 'automatic', revision: runtime.revision,
-      deadline: minutes ? Math.floor(Date.now() / 1000 + minutes * 60) : 0 });
-  } catch (error) {
-    const latest = await api(config, '/runtime');
-    if (latest.generation !== record.expected_generation || latest.status !== 'running') throw error;
-    runtime = latest;
-  }
-  record.generation = runtime.generation;
-  persist();
-  return runtime;
-}
-
-/** Reserve the first host task for the calling conversation without sending it a duplicate prompt. */
-async function current_host_task(config, record, persist, room) {
-  const page = await api(config, '/events?after=0');
-  const event = record.event_id ? page.events.find(item => item.id === record.event_id)
-    : page.events.filter(item => item.generation === record.generation && item.role === 'host' && item.participant === room.host && item.status === 'pending').at(-1);
-  if (!event) throw new Error('没有可由当前会话接手的主持任务；请核对原房间');
-  record.event_id = event.id;
-  record.execution_token ||= randomUUID();
-  persist();
-  if (event.status === 'pending') await api(config, `/events/${event.id}`, { action: 'reserve', execution_token: record.execution_token });
-  else await api(config, `/events/${event.id}`, { action: 'view' }, record.execution_token);
-  const store = new DiscussionStore(config.directory);
-  try {
-    store.context(config);
-    const runtime = await api(config, '/runtime');
-    store.scope(config, runtime.run_id);
-    store.receive(page);
-    const session_id = config.participants[room.host].session_id;
-    store.bind(room.host, session_id);
-    const task = task_files(config, event, record.execution_token, { session_id });
-    store.record(event.id, { status: 'accepted', token: record.execution_token, sent_at: Date.now() });
-    return { event_id: event.id, access_file: task.access_path, task_file: join(config.directory, `${task.id}.task.json`) };
-  } finally { store.close(); }
-}
-
-/** Return launch evidence and paths, never raw control or execution tokens. */
-async function launch_receipt(config, record, config_path) {
-  const room = await api(config, '');
-  return { entry: record.entry, room, url: `${config.site}/?room=${config.room}`, config_path,
-    status: room.mode === 'free' ? 'free' : room.runtime.status, current_task: record.current_task || null };
-}
-
-/** Read a saved launch without creating state during validation or preview. */
-function read_launch(directory) {
-  const path = join(directory, 'launch.json');
-  return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
-}
-
-/** Find the registered room only after proving the caller's original control credential. */
-async function room_config_context(home, raw) {
-  const input = launch_input({ ...raw, entry: 'web' });
-  if (!input.room_id || typeof input.token !== 'string' || !input.token.trim()) throw new Error('读取本场配置须提供房间编号和原控制凭据');
-  const room = await site_request(input.site, `/api/rooms/${input.room_id}`, input.token);
-  if (!room.runtime?.protected) throw new Error('本场配置修正仅支持具有原控制凭据的受保护房间');
-  await verify_control({ site: input.site, room: input.room_id, token: input.token }, room);
-  if (room.archived || room.runtime.mode !== 'automatic' || room.runtime.status !== 'paused' || room.phase === 'concluded') throw new Error('请先暂停本场讨论，再修正软件路径');
-  const paths = read_registry(home).filter(path => {
-    const identity = registered_identity(path);
-    return identity?.site === input.site && identity.room === input.room_id;
-  });
-  if (paths.length !== 1) throw new Error('未找到本场唯一的已登记配置，请核对原接入服务');
-  const path = paths[0];
-  const journal = read_launch(dirname(path));
-  if (journal && !journal.finished) throw new Error('本次启动尚未完成，请先核对原启动待办');
-  return { input, room, path, ...configuration_snapshot(path) };
-}
-
-/** Expose only editable connection paths, never credentials or unrelated room settings. */
-function connection_view(context) {
-  return { room_id: context.room.id, runtime_revision: context.room.runtime.revision, version: context.version,
-    participants: Object.fromEntries(Object.entries(context.config.participants).map(([name, profile]) =>
-      [name, Object.fromEntries(['adapter', ...CONNECTION_FIELDS].filter(field => profile[field] !== undefined).map(field => [field, profile[field]]))])) };
-}
-
-/** Switch only Codex's execution entrypoint, keeping its actual original conversation. */
-function switch_codex_adapter(context, name, profile, adapter) {
-  if (!CODEX_ADAPTERS.includes(profile.adapter) || !CODEX_ADAPTERS.includes(adapter)) throw new Error('本场仅支持 Codex App / CLI 切换');
-  const current = validate_config(context.config, dirname(context.path));
-  let session = profile.session_id;
-  if (existsSync(join(current.directory, 'runtime.sqlite3'))) {
-    const store = new DiscussionStore(current.directory);
-    try {
-      const binding = store.binding(name).session_id;
-      if (session && binding && session !== binding) throw new Error('原会话绑定不一致，请先核对原会话');
-      session = binding || session;
-    } finally { store.close(); }
-  }
-  if (!session) throw new Error('尚无实际 Codex 会话，不能切换；请先完成首次接入');
-  profile.adapter = adapter;
-  profile.session_id = session;
-}
-
-/** Validate paused-room paths and Codex entrypoints without replacing the discussion or session. */
-function corrected_configuration(context) {
-  const config = structuredClone(context.config);
-  for (const [name, patch] of Object.entries(context.input.participants)) {
-    const profile = config.participants[name];
-    const field = profile?.adapter === 'antigravity' ? 'ipc_directory' : 'executable';
-    const fields = CODEX_ADAPTERS.includes(profile?.adapter) ? [field, 'adapter'] : [field];
-    if (!profile || !patch || typeof patch !== 'object' || Array.isArray(patch) || Object.keys(patch).some(key => !fields.includes(key))) throw new Error('本场修正仅支持软件路径、Sidecar 目录及 Codex App / CLI；参与者、项目及会话保持不变');
-    validate_profile(name, patch);
-    if (patch.adapter && patch.adapter !== profile.adapter) switch_codex_adapter(context, name, profile, patch.adapter);
-    const path = patch[field] ?? profile[field];
-    if (typeof path !== 'string' || !path || !existsSync(path)
-      || (field === 'executable' ? !statSync(path).isFile() || (process.platform === 'win32' && !/\.exe$/i.test(path)) : !statSync(path).isDirectory())) throw new Error(`${name}：请提供有效的软件文件或连接目录`);
-    profile[field] = path;
-  }
-  validate_config(config, dirname(context.path));
-  return config;
-}
-
-/** Wait for the resident worker to read this version before suggesting a manual restart. */
-async function configuration_applied(home, path, version) {
-  for (let waited = 0; waited < CONFIG_APPLY_TIMEOUT_MS; waited += CONFIG_APPLY_POLL_MS) {
-    const pid = service_pid(home);
-    if (!pid) return false;
-    const status_path = join(home, 'status.json');
-    const status = existsSync(status_path) ? JSON.parse(readFileSync(status_path, 'utf8')) : {};
-    const worker = status.rooms?.find(item => resolve(item.config) === resolve(path));
-    if (status.pid === pid && worker?.config_version === version && worker.status === 'paused') return true;
-    await sleep(CONFIG_APPLY_POLL_MS);
-  }
-  return false;
-}
-
-/** Read or save a paused room's connection paths without changing its runtime or global defaults. */
-export async function room_configuration(home, raw, options = {}) {
-  if (raw.participants !== undefined && !options.local_guard) return save_room_connection(raw);
-  let context = await room_config_context(home, raw);
-  if (raw.participants === undefined) return connection_view(context);
-  if (!raw.participants || typeof raw.participants !== 'object' || Array.isArray(raw.participants)) throw new Error('participants 须为本场软件路径对象');
-  const release = acquire_lock(join(dirname(context.path), 'configuration-edit'));
-  try {
-    context = await room_config_context(home, raw);
-    const config = corrected_configuration(context);
-    if (raw.version !== context.version || raw.runtime_revision !== context.room.runtime.revision) throw new Error('房间状态或配置已变化，请重新读取本场配置后核对');
-    atomic_json(context.path, config);
-    const saved = { ...context, ...configuration_snapshot(context.path) };
-    return { ...connection_view(saved), applied: await configuration_applied(home, context.path, saved.version) };
-  } finally { release(); }
-}
-
-/** Serialize file replacement with runtime changes through the local website's database guard. */
-async function save_room_connection(raw) {
-  const input = launch_input({ ...raw, entry: 'web' });
-  const url = new URL(input.site);
-  if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost'].includes(url.hostname)) throw new Error('本场路径修正须通过已启用本机启动的回环网站');
-  const response = await fetch(`${input.site}/api/local/room-config`, { method: 'POST',
-    headers: { 'Content-Type': 'application/json', 'X-CoDiscuss-Local': '1' },
-    body: JSON.stringify(input), redirect: 'error', signal: AbortSignal.timeout(15000) });
-  const result = await response.json();
-  if (!response.ok) throw new Error(`HTTP ${response.status}: ${result.error || '本场配置保存失败'}`);
-  return result;
-}
-
-/** Prove dispatcher access before a protected room is started or a corrected credential is saved. */
-async function verify_control(config, room) {
-  if (room.runtime?.protected) await api({ ...config, room: room.id }, '/events?after=0');
-}
-
-/** Pin resolved defaults, while comparing retries against only the caller's explicit request. */
-async function prepare_launch(home, input, directory, options = {}) {
-  const previous = read_launch(directory);
-  if (options.browser_request && (typeof input.token !== 'string' || !input.token.trim())) throw new Error('网页启动须携带本次原始控制凭据，不能认领其他启动记录');
-  const { token: ignored_token, access_file: ignored_access, ...request } = input;
-  const request_signature = signature(request);
-  if (previous?.request_signature && previous.request_signature !== request_signature) throw new Error('启动配置与原请求不同；同一次重试须沿用原配置，新讨论请使用新提交编号');
-  const legacy = previous && !previous.request_signature ? JSON.parse(previous.signature) : null;
-  const config_path = join(directory, 'config.json');
-  const saved = previous?.config || (previous && existsSync(config_path) ? JSON.parse(readFileSync(config_path, 'utf8')) : null);
-  const token = input.token || previous?.token || randomUUID();
-  const room_id = input.room_id || previous?.room_id || (saved?.room !== 'preview' ? saved?.room : null);
-  if (options.browser_request && previous && token !== previous.token && !room_id) throw new Error('尚未确认原房间，不能替换本次控制凭据');
-  const room = room_id ? await site_request(input.site, `/api/rooms/${room_id}`, token) : input.room;
-  if (room.runtime?.protected && !input.token && !previous) throw new Error('已有房间需要原接入配置的 access_file');
-  if (!previous && room.runtime && room.runtime.status !== 'ready') throw new Error('房间已启动过；请沿用原配置核对或从原进度看板明确继续');
-  const config = previous?.request_signature ? { ...structuredClone(saved), token }
-    : launch_config(home, input, room, directory, { token, defaults: saved?.participants || legacy?.participants, members: saved?.members });
-  config.draft_directory = service_drafts(home, config.directory);
-  if (previous?.request_signature && !previous.finished) validate_config(config, directory);
-  const minutes = previous?.minutes ?? legacy?.minutes ?? launch_minutes(input, room);
-  const draft = signature({ entry: input.entry, room_id: input.room_id, room: input.room, participants: config.participants, cwd: input.cwd, discussion_project: input.discussion_project, minutes });
-  if (legacy && previous.signature !== draft) throw new Error('启动配置与原请求不同；同一次重试须沿用原配置，新讨论请使用新提交编号');
-  await verify_control(config, room);
-  return { input, config, room, minutes, draft, request_signature, directory, previous };
-}
-
-/** Launch a room through either entry, using a durable journal for safe retries. */
-export async function launch_discussion(home, raw, options = {}) {
-  assert_shared_home(home);
-  const input = launch_input(raw);
-  const key = createHash('sha256').update(`${input.site}/${input.room_id || input.room.submission_id}`).digest('hex');
-  const directory = join(home, 'launches', key);
-  let release;
-  try {
-    const preview = await prepare_launch(home, input, directory, options);
-    if (options.dry_run) return { dry_run: true, entry: input.entry, site: input.site, room_id: input.room_id || null,
-      host: preview.room.host, participants: preview.config.participants, cwd: preview.config.cwd || null,
-      discussion_project: preview.config.discussion_project || null, minutes: preview.minutes };
-    release = acquire_lock(directory);
-    return await perform_launch(home, await prepare_launch(home, input, directory, options), options);
-  } catch (error) {
-    error.launch ||= { stage: existsSync(join(directory, 'launch.json')) ? 'unconfirmed' : 'not_started' };
-    throw error;
-  } finally { release?.(); }
-}
-
-/** Persist preparation before writes, hand off the current host when needed, then register once. */
-async function perform_launch(home, context, options) {
-  const { input, config, minutes, draft, request_signature, directory, previous } = context;
-  const record = previous || { token: config.token, signature: draft, request_signature, config, minutes, entry: input.entry };
-  const persist = () => atomic_json(join(directory, 'launch.json'), record);
-  if (!previous) persist();
-  const progress = { stage: 'unconfirmed' };
-  try {
-    let room = context.room;
-    const free = config.mode === 'free';
-    if (!input.room_id) room = await site_request(input.site, '/api/rooms', config.token, {
-      ...input.room, ...(free ? {} : { runtime_mode: 'automatic' }),
-      members: Object.keys(config.participants).map(name => ({ name, adapter: config.participants[name].adapter,
-        token: config.members[name].token, access: 'runner', session_mode: config.participants[name].session_id ? 'borrowed' : 'new' })),
-    });
-    config.room = room.id;
-    await verify_control(config, room);
-    Object.assign(progress, { stage: 'created', room_id: room.id });
-    Object.assign(record, { token: config.token, request_signature, config, minutes, room_id: room.id });
-    if (!record.start_revision && room.runtime.status === 'ready') record.start_revision = room.runtime.revision + 1;
-    persist();
-    const config_path = join(directory, 'config.json');
-    check_registration(home, config, config_path);
-    if (record.finished) {
-      const saved = existsSync(config_path) ? JSON.parse(readFileSync(config_path, 'utf8')) : config;
-      if (saved.token !== config.token || !existsSync(config_path)) atomic_json(config_path, { ...saved, token: config.token });
-      return launch_receipt(config, record, config_path);
-    }
-    atomic_json(config_path, config);
-    const service = await (options.start_service || start_service)(home);
-    if (!service?.running) throw new Error('讨论服务未就绪，未开始本次讨论');
-    // Free rooms have no discussion run: registering the room is what lets the service deliver requests.
-    if (!free) await enable_run(config, record, persist, minutes);
-    progress.stage = 'started';
-    if (input.entry === 'conversation') record.current_task = await current_host_task(config, record, persist, room);
-    register_room(home, config_path);
-    record.finished = true;
-    persist();
-    return launch_receipt(config, record, config_path);
-  } catch (error) { error.launch = progress; throw error; }
-}
-
-/** CLI and local HTTP bridge use the same commands and configuration validation. */
-export async function launch_main(args = process.argv.slice(2), input_text) {
-  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
-    file: { type: 'string' }, 'dry-run': { type: 'boolean' }, browser: { type: 'boolean' },
-    'configuration-locked': { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
-  } });
-  if (values.help || !positionals.length) return process.stdout.write(HELP);
-  const input = input_text === undefined ? (values.file ? JSON.parse(readFileSync(values.file, 'utf8').replace(/^\uFEFF/, '')) : null) : JSON.parse(input_text);
-  const home = service_home();
-  assert_shared_home(home);
-  let result;
-  if (positionals[0] === 'settings') result = input ? save_launch_settings(home, input) : launch_settings(home);
-  else if (positionals[0] === 'room-models' && input) result = room_models(home, input);
-  else if (positionals[0] === 'models' && input) {
-    const saved = Object.values(launch_settings(home).participants).find(profile => profile.adapter === input.adapter);
-    result = await cached_software_models(home, { adapter: input.adapter, executable: input.executable || saved?.executable }, { refresh: input.refresh === true });
-  }
-  else if (positionals[0] === 'room-member' && input) result = await room_member(home, input);
-  else if (positionals[0] === 'pick-directory') result = await pick_directory();
-  else if (positionals[0] === 'start' && input) result = await launch_discussion(home, input, { dry_run: values['dry-run'], browser_request: values.browser });
-  else if (positionals[0] === 'room-config' && input) result = await room_configuration(home, input, { local_guard: values['configuration-locked'] });
-  else throw new Error(HELP);
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-}
-
-if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
-  const args = process.argv.slice(2);
-  const stdin = args.includes('--stdin') ? readFileSync(0, 'utf8') : undefined;
-  launch_main(args.filter(arg => arg !== '--stdin'), stdin).catch(error => {
-    const failure = args.includes('--browser') ? JSON.stringify({ error: error.message, launch: error.launch || { stage: 'not_started' } }) : error.message;
-    process.stderr.write(`${failure}\n`); process.exitCode = 1;
-  });
-}
+/** Shared launch configuration for an existing AI conversation and the local website. */
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+
+import { atomic_json } from './discussion_adapters.mjs';
+import { software_models } from './discussion_models.mjs';
+import { API_PROVIDERS, api_models, save_api_key, validate_api_profile } from './discussion_api.mjs';
+import { acquire_lock, api, CODEX_ADAPTERS, DiscussionStore, service_drafts, task_files, validate_config } from './discussion_runner.mjs';
+import { assert_shared_home, CONNECTION_FIELDS, configuration_snapshot, read_registry, registered_identity, register_room, service_home, service_pid, start_service } from './discussion_service.mjs';
+
+const CLIENTS = { Codex: ['codex_cli', 'codex', 'api'], Claude: ['claude', 'api'], Gemini: ['antigravity_cli', 'antigravity', 'api'], DeepSeek: ['api'], Qwen: ['api'], Grok: ['api'] };
+// A platform is a type; `Claude-评审` is another Claude instance with its own session, model and effort.
+const INSTANCE_PATTERN = /^(Codex|Claude|Gemini|DeepSeek|Qwen|Grok)(?:-[0-9A-Za-z_一-鿿]{1,16})?$/;
+
+/** The platform of an AI instance name, or null. */
+export function platform_of(name) { return typeof name === 'string' ? INSTANCE_PATTERN.exec(name)?.[1] ?? null : null; }
+
+/** The first unused instance name of a platform: the platform itself, then platform-2, platform-3, …. */
+export function next_instance(platform, taken) {
+  if (!taken.has(platform)) return platform;
+  for (let number = 2; ; number++) if (!taken.has(`${platform}-${number}`)) return `${platform}-${number}`;
+}
+
+/** Supported local clients of an instance's platform. */
+function clients_of(name) { return CLIENTS[platform_of(name)]; }
+// Reasoning effort is a separate CLI argument only for Codex and Claude; agy encodes it in the model name.
+const EFFORT_LEVELS = { codex_cli: ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'], claude: ['low', 'medium', 'high', 'xhigh', 'max'] };
+const PROFILE_FIELDS = ['adapter', 'executable', 'model', 'effort', 'source_thread_id', 'ipc_directory', 'allowed_tools', 'cwd', 'project_name', 'project_id', 'base_url', 'api_protocol', 'api_key_ref'];
+const MAX_MINUTES = 1440;
+const SESSION_ID_PATTERN = /^[0-9A-Za-z_-]{8,128}$/;
+// Reading events after this id proves the owner credential without transferring any.
+const MAX_EVENT_ID = 2147483647;
+const CONFIG_APPLY_TIMEOUT_MS = 6000;
+const CONFIG_APPLY_POLL_MS = 100;
+const HELP = `用法：codiscuss launch settings [--file FILE]
+      codiscuss launch start --file FILE [--dry-run]
+      codiscuss launch room-config --file FILE
+      codiscuss launch room-models --file FILE
+      codiscuss launch models --file FILE
+      codiscuss launch api-key --file FILE
+      codiscuss launch room-member --file FILE
+      codiscuss launch pick-directory
+
+settings 读取本机软件默认配置；指定文件时保存，不启动 AI。
+start 使用启动 JSON 创建或接入房间并启动；--dry-run 只校验和预览。
+room-config 修正已暂停房间的软件路径或切换 Codex App / CLI，不启动讨论；须提供 site、room_id、token。
+room-models 只读指定 site、room_id 的本机登记模型与思考强度，不启动讨论。
+models 按 adapter、executable 或 API profile 读取模型目录，不启动讨论或生成回答。
+api-key 将 base_url、api_key 保存于本机私有目录，只返回 api_key_ref。
+pick-directory 在本机弹出系统目录选择窗口，返回所选路径；取消时不返回路径。
+room-member 为运行中的自由房间或讨论邀请、请回一位成员（讨论只接受本机唤醒的成员）；须提供 site、room_id、token、action（add/rejoin）、name。
+JSON 指定 site、entry（conversation/web）、room（建房内容，含 submission_id）
+或 room_id（已有房间）、participants（本次软件覆盖配置）。
+conversation 还须 current_session_id，当前会话接手首个主持任务。
+已有受保护房间使用 access_file。路径、凭据只保存在本机。
+详见 docs/runner.md 的“两种讨论入口与启动配置”。
+`;
+
+// Windows PowerShell 5.1 ships WinForms. A background process cannot take the foreground, so the owner must be
+// shown (off-screen) as a topmost window; the dialog it owns then stays above the browser that asked for it.
+const WINDOWS_PICKER = [
+  'Add-Type -AssemblyName System.Windows.Forms',
+  '[Console]::OutputEncoding = [Text.Encoding]::UTF8',
+  '$owner = New-Object System.Windows.Forms.Form -Property @{ TopMost = $true; ShowInTaskbar = $false; FormBorderStyle = "None"; StartPosition = "Manual"; Location = New-Object System.Drawing.Point(-32000, -32000); Size = New-Object System.Drawing.Size(1, 1) }',
+  '$owner.Show(); $owner.Activate()',
+  '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog -Property @{ Description = "选择项目目录"; ShowNewFolderButton = $true }',
+  'if ($dialog.ShowDialog($owner) -eq "OK") { $dialog.SelectedPath }',
+  '$owner.Close()',
+].join('; ');
+const PICKERS = {
+  win32: ['powershell.exe', ['-NoProfile', '-STA', '-Command', WINDOWS_PICKER]],
+  darwin: ['osascript', ['-e', 'POSIX path of (choose folder with prompt "选择项目目录")']],
+  linux: ['zenity', ['--file-selection', '--directory', '--title=选择项目目录']],
+};
+
+/** Show the platform's own folder dialog on this computer; cancelling resolves without a path. */
+export function pick_directory({ platform = process.platform, spawn_process = spawn } = {}) {
+  const picker = PICKERS[platform];
+  if (!picker) return Promise.reject(new Error('此系统不支持目录选择窗口，请直接输入完整路径'));
+  return new Promise((resolve_result, reject) => {
+    const child = spawn_process(picker[0], picker[1], { shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+    let output = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', chunk => { output += chunk; });
+    child.once('error', () => reject(new Error('无法打开目录选择窗口，请直接输入完整路径')));
+    child.once('close', code => {
+      const path = output.trim();
+      resolve_result(code === 0 && isAbsolute(path) ? { path } : { cancelled: true });
+    });
+  });
+}
+
+/** Some CLIs take seconds to list models; reuse a good list for a day unless the executable changes or the user retries. */
+const MODEL_CACHE_MS = 24 * 60 * 60 * 1000;
+
+/** Return the software catalog, served from the private service home when still valid. */
+export async function cached_software_models(home, profile, { refresh = false, query = software_models } = {}) {
+  const path = join(home, 'model-catalogs.json');
+  let stamp = '';
+  try { const file = statSync(profile.executable); stamp = `${file.size}:${file.mtimeMs}`; } catch {}
+  const key = JSON.stringify([profile.adapter, profile.executable || '', stamp]);
+  let cache = {};
+  try { cache = JSON.parse(readFileSync(path, 'utf8')); } catch {}
+  const hit = cache[key];
+  if (!refresh && hit && Date.now() - hit.at < MODEL_CACHE_MS) return hit.result;
+  const result = await query(profile);
+  if (!result.error && result.models.length) {
+    const prefix = JSON.stringify([profile.adapter, profile.executable || '']).slice(0, -1);
+    for (const old of Object.keys(cache)) if (old.startsWith(prefix)) delete cache[old];
+    atomic_json(path, { ...cache, [key]: { at: Date.now(), result } });
+  }
+  return result;
+}
+
+/** Read private defaults without selecting a global room or identity. */
+export function launch_settings(home) {
+  const path = join(home, 'launch-settings.json');
+  return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : { participants: {} };
+}
+
+/** Read only the registered room's model choices, never machine defaults or connection secrets. */
+export function room_models(home, raw) {
+  const input = launch_input({ ...raw, entry: 'web' });
+  if (!input.room_id) throw new Error('读取本场模型须提供 room_id');
+  const paths = read_registry(home).filter(path => {
+    const identity = registered_identity(path);
+    return identity?.site === input.site && identity.room === input.room_id;
+  });
+  if (paths.length > 1) throw new Error('本场存在多份登记配置，无法确定模型设置');
+  const profiles = paths.length ? configuration_snapshot(paths[0]).config.participants : {};
+  const participants = Object.fromEntries(Object.entries(profiles).map(([name, profile]) => {
+    const cli = ['codex_cli', 'claude', 'antigravity_cli', 'api'].includes(profile.adapter);
+    return [name, { adapter: profile.adapter, model: cli ? profile.model || '' : '',
+      effort: EFFORT_LEVELS[profile.adapter] ? profile.effort || '' : '' }];
+  }));
+  return { room_id: input.room_id, participants };
+}
+
+/** Save only reusable client settings; room credentials and session bindings are never defaults. */
+export function save_launch_settings(home, input) {
+  const participants = {};
+  for (const [name, profile] of Object.entries(input.participants || {})) {
+    if (platform_of(name) !== name) throw new Error(`本机默认配置按平台保存；${name} 的模型与强度只用于本场讨论`);
+    validate_profile(name, profile);
+    participants[name] = profile;
+  }
+  const settings = { participants };
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  atomic_json(join(home, 'launch-settings.json'), settings);
+  return settings;
+}
+
+/** Reject malformed client fields before saving defaults or creating any discussion. */
+function validate_profile(name, profile, binding = false) {
+  if (!clients_of(name) || !profile || typeof profile !== 'object' || Array.isArray(profile)) throw new Error(`不支持的软件配置：${name}`);
+  if (profile.adapter && !clients_of(name).includes(profile.adapter)) throw new Error(`${name} 的客户端不匹配`);
+  // Session bindings and project write access apply to one launch only, never to machine defaults.
+  const fields = binding ? [...PROFILE_FIELDS, 'session_id', 'project_access'] : PROFILE_FIELDS;
+  if (Object.keys(profile).some(key => !fields.includes(key))) throw new Error('软件配置包含不支持的字段；默认配置不能保存房间或会话绑定');
+  for (const [key, value] of Object.entries(profile)) {
+    if (key === 'allowed_tools') {
+      if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) throw new Error(`${name}.allowed_tools 必须为工具名称数组`);
+    } else if (typeof value !== 'string') throw new Error(`${name}.${key} 必须为文本`);
+    if (['executable', 'cwd', 'ipc_directory'].includes(key) && value && !isAbsolute(value)) throw new Error(`${name}.${key} 必须为完整绝对路径`);
+    // The model is passed as one CLI argument, so it must not look like a flag or contain spaces.
+    if (key === 'model' && value && !/^[A-Za-z0-9][A-Za-z0-9._:/@[\]-]*$/.test(value)) throw new Error(`${name}.model 只能是模型名称，例如 gpt-6-astra、opus 或 gemini-4-argon-high`);
+  }
+  if (profile.adapter === 'api') validate_api_profile(profile);
+  if (profile.effort && profile.adapter !== 'api' && !EFFORT_LEVELS[profile.adapter]?.includes(profile.effort)) {
+    throw new Error(EFFORT_LEVELS[profile.adapter] ? `${name}.effort 只能是 ${EFFORT_LEVELS[profile.adapter].join(' / ')}`
+      : `${name} 的思考档位不能单独设置；agy 请选择带档位的模型名，App 在软件内选择`);
+  }
+}
+
+/** Send one request without following redirects that could disclose the room credential. */
+async function site_request(site, path, token, body) {
+  const response = await fetch(`${site}${path}`, { method: body === undefined ? 'GET' : 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Discussion-Token': token },
+    body: body === undefined ? undefined : JSON.stringify(body), redirect: 'error', signal: AbortSignal.timeout(10000) });
+  const result = await response.json();
+  if (!response.ok) throw new Error(`HTTP ${response.status}: ${result.error || '请求失败'}`);
+  return result;
+}
+
+/** Require an explicit website, launch entry and stable creation identity. */
+function launch_input(input) {
+  const value = structuredClone(input);
+  const url = new URL(value.site);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw new Error('site 必须为 HTTP(S) 根地址');
+  value.site = url.origin;
+  if (!['conversation', 'web'].includes(value.entry)) throw new Error('entry 必须为 conversation 或 web');
+  if (value.entry === 'conversation' && (typeof value.current_session_id !== 'string' || !value.current_session_id.trim())) throw new Error('对话入口须提供当前实际会话的 current_session_id');
+  if (value.cwd && (typeof value.cwd !== 'string' || !isAbsolute(value.cwd))) throw new Error('cwd 必须为完整绝对路径');
+  if (value.project_access && !['read', 'write'].includes(value.project_access)) throw new Error('project_access 只能为 read 或 write');
+  if (value.room_id && !/^[A-Za-z0-9_-]+$/.test(value.room_id)) throw new Error('房间编号无效');
+  if (!value.room_id && !value.room?.submission_id) throw new Error('新房间须提供 room.submission_id；重试沿用原编号');
+  if (value.room?.mode === 'free') {
+    // P1: a free room is launched once, at creation, from the web page.
+    if (value.entry !== 'web' || value.room_id) throw new Error('自由协作房间目前只能在网页创建时启动');
+    const members = value.room.members;
+    const names = members?.map(member => typeof member === 'string' ? member : member.name);
+    const woken = Array.isArray(members) ? members.filter(woken_member).map(member => typeof member === 'string' ? member : member.name) : [];
+    if (!woken.length || new Set(names).size !== names.length || woken.some(name => !clients_of(name))) {
+      throw new Error('自由协作房间须选择至少 1 位支持自动接入的 AI 成员，且不能重复');
+    }
+  }
+  if (value.access_file) {
+    const access = JSON.parse(readFileSync(resolve(value.access_file), 'utf8'));
+    if (access.site?.replace(/\/$/, '') !== value.site || access.room !== value.room_id) throw new Error('access_file 与本次站点或房间不符');
+    value.token = access.token;
+  }
+  return value;
+}
+
+/** Merge machine defaults and explicit room overrides, preserving the selected participants. */
+function launch_config(home, input, room, directory, options) {
+  if (room.mode === 'free') return free_launch_config(home, input, room, directory, options);
+  if (!clients_of(room.host)) throw new Error('请选择支持全自动讨论的 AI 主持人');
+  if (!room.experts || room.experts[room.host] !== 'cli') throw new Error('请将 AI 主持人的参与方式设为本地读写');
+  const online = Object.entries(room.experts).filter(([, mode]) => mode !== 'cli').map(([name]) => name);
+  if (online.length) throw new Error(`全自动无法接入在线专家：${online.join('、')}。请调整参与方式或改用手动推进`);
+  const defaults = options.defaults || launch_settings(home).participants;
+  const participants = {};
+  for (const name of new Set([room.host, ...Object.keys(room.experts)])) {
+    participants[name] = participant_profile(name, defaults, input, name === room.host);
+  }
+  const members = launch_members(input, Object.keys(participants), options);
+  return validate_config({ site: input.site, room: room.id || 'preview', token: options.token, participants, members, api_home: home,
+    cwd: input.cwd, discussion_project: input.discussion_project, project_access: input.project_access || undefined,
+    data_directory: join(directory, 'runtime'), draft_directory: service_drafts(home, join(directory, 'runtime')) }, directory);
+}
+
+/** A free-room member the local service wakes; manual and online members join without local configuration. */
+function woken_member(member) { return typeof member === 'string' || !member.access || member.access === 'runner'; }
+
+/** Free rooms add one private credential per woken member, kept with the room configuration for retries. */
+function free_launch_config(home, input, room, directory, options) {
+  const defaults = options.defaults || launch_settings(home).participants;
+  const names = room.members.filter(woken_member).map(member => typeof member === 'string' ? member : member.name);
+  const participants = Object.fromEntries(names.map(name => [name, participant_profile(name, defaults, input, false)]));
+  const members = launch_members(input, names, options);
+  return validate_config({ site: input.site, room: room.id || 'preview', token: options.token, mode: 'free', participants, members, api_home: home,
+    cwd: input.cwd, project_access: input.project_access || undefined,
+    data_directory: join(directory, 'runtime'), draft_directory: service_drafts(home, join(directory, 'runtime')) }, directory);
+}
+
+/** Preserve caller-generated member credentials; journal newly generated ones before creation. */
+function launch_members(input, names, options) {
+  return Object.fromEntries(names.map(name => {
+    const supplied = input.room?.members?.find(member => member?.name === name);
+    return [name, { token: supplied?.token || options.members?.[name]?.token || `${randomUUID()}${randomUUID()}` }];
+  }));
+}
+
+/** Merge one participant's machine defaults with this launch's overrides and check its software. */
+function participant_profile(name, defaults, input, current_host) {
+  const platform = platform_of(name);
+  // An extra instance starts from its platform's settings but never from another instance's bound session.
+  const { session_id: ignored_session, ...inherited } = name === platform ? {} : input.participants?.[platform] || {};
+  const profile = { ...defaults[platform], ...(name === platform ? {} : defaults[name]), ...inherited, ...input.participants?.[name] };
+  for (const field of ['cwd', 'model', 'effort', 'project_name', 'project_id', 'project_access']) if (profile[field] === '') delete profile[field];
+  validate_profile(name, profile, true);
+  if (!clients_of(name)?.includes(profile.adapter)) throw new Error(`请配置 ${name} 的 CLI / App 客户端`);
+  if (profile.adapter === 'api') {
+    if (input.entry === 'conversation' && current_host) throw new Error('API 主持人请从网页启动；当前软件会话主持须选择对应 CLI / App');
+    return profile;
+  }
+  if (profile.adapter !== 'antigravity' && (!existsSync(profile.executable || '') || !statSync(profile.executable).isFile()
+    || (process.platform === 'win32' && !/\.exe$/i.test(profile.executable)))) throw new Error(`${name}：请指定实际原生可执行文件，Windows 使用 .exe`);
+  const cwd = profile.cwd || input.cwd;
+  if (cwd && (!existsSync(cwd) || !statSync(cwd).isDirectory())) throw new Error(`${name}：工作目录不存在或不是文件夹，请核对本次目录配置`);
+  if (input.entry === 'conversation' && current_host) profile.session_id = input.current_session_id;
+  // agy runs only in sessions this tool creates, so its native discussion project always applies.
+  if (profile.adapter === 'antigravity_cli' && profile.session_id) throw new Error(`${name}：agy 不能绑定已有会话或从当前 agy 对话主持全自动讨论；请从网页或其他软件发起，agy 会由讨论服务新建会话`);
+  return profile;
+}
+
+/** List every file below a directory, or nothing when the software has never stored a session there. */
+function session_files(directory) {
+  return existsSync(directory) ? readdirSync(directory, { recursive: true }).map(path => join(directory, String(path))) : [];
+}
+
+/** Compare directories as the operating system resolves them (Windows short names and case). */
+function same_directory(left, right) {
+  const real = path => { try { return realpathSync.native(path); } catch { return resolve(path); } };
+  const [a, b] = [real(left), real(right)];
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+/**
+ * Prove an invited existing conversation is on this machine before it can hold a turn, so a mistyped ID
+ * fails here instead of pausing the discussion later. Claude stores sessions per directory and resumes only
+ * from the original one, so its cwd follows the session; a different room project is refused.
+ */
+export function borrowed_session(name, profile, room_cwd, env = process.env) {
+  const id = profile.session_id;
+  if (!SESSION_ID_PATTERN.test(id)) throw new Error(`${name}：会话 ID 格式不正确`);
+  if (CODEX_ADAPTERS.includes(profile.adapter)) {
+    const sessions = join(env.CODEX_HOME || join(homedir(), '.codex'), 'sessions');
+    if (!session_files(sessions).some(path => path.endsWith(`-${id}.jsonl`))) throw new Error(`${name}：本机找不到 Codex 会话 ${id}，请核对会话 ID`);
+    return profile;
+  }
+  if (profile.adapter !== 'claude') throw new Error(`${name}：只有 Codex 与 Claude 可以接入已有会话`);
+  const projects = join(env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects');
+  const file = session_files(projects).find(path => path.endsWith(`${id}.jsonl`) && dirname(dirname(path)) === projects);
+  if (!file) throw new Error(`${name}：本机找不到 Claude 会话 ${id}，请核对会话 ID`);
+  const cwd = readFileSync(file, 'utf8').split('\n').map(line => { try { return JSON.parse(line).cwd; } catch { return undefined; } }).find(Boolean);
+  if (!cwd) throw new Error(`${name}：Claude 会话 ${id} 没有记录原工作目录，无法续接`);
+  const wanted = profile.cwd || room_cwd;
+  if (wanted && !same_directory(wanted, cwd)) throw new Error(`${name}：这个 Claude 会话属于 ${cwd}，只能在原目录续接；请让项目目录与它一致，或留空会话 ID 新建会话`);
+  return { ...profile, cwd: wanted || cwd };
+}
+
+/** Find the one registered configuration of a room after proving the owner's credential. */
+async function member_room_context(home, raw) {
+  const input = launch_input({ ...raw, entry: 'web' });
+  if (!input.room_id || typeof input.token !== 'string' || !input.token.trim()) throw new Error('管理成员须提供房间编号和房间控制凭据');
+  const paths = read_registry(home).filter(path => {
+    const identity = registered_identity(path);
+    return identity?.site === input.site && identity.room === input.room_id;
+  });
+  if (paths.length !== 1) throw new Error('未找到本房间唯一的已登记配置，请核对本机接入服务');
+  const config = configuration_snapshot(paths[0]).config;
+  // Both reads need the owner credential; a discussion reads past its last event so nothing is transferred.
+  await site_request(input.site, `/api/rooms/${input.room_id}/${config.mode === 'free' ? 'inbox' : `events?after=${MAX_EVENT_ID}`}`, input.token);
+  return { input, path: paths[0], config };
+}
+
+/** Write a manual member's private credential next to the room configuration, never into a receipt. */
+function manual_access(path, input, name, token) {
+  const access_path = join(dirname(path), `manual-${name}.access.json`);
+  atomic_json(access_path, { site: input.site, room: input.room_id, token });
+  return access_path;
+}
+
+/**
+ * Invite (add) or bring back (rejoin) one member of a running free room or discussion.
+ * The local configuration is written before the website call, so a retry reuses the same credential.
+ * Discussions only admit members the local service wakes.
+ */
+export async function room_member(home, raw, locked = false) {
+  const { input, path, config: registered } = await member_room_context(home, raw);
+  const { action, name } = input;
+  const access = input.access || 'runner';
+  const free = registered.mode === 'free';
+  if (!['add', 'rejoin'].includes(action) || !platform_of(name) || (access !== 'manual' && !clients_of(name)) || !(free ? ['runner', 'manual'] : ['runner']).includes(access)) {
+    throw new Error(free ? 'action 须为 add/rejoin，成员须为支持的 AI，接入方式须为 runner/manual' : '讨论房间只接受本机唤醒的成员；action 须为 add/rejoin');
+  }
+  const release = locked ? () => {} : acquire_lock(join(dirname(path), 'configuration-edit'));
+  try {
+    const config = configuration_snapshot(path).config;
+    config.api_home = home;
+    const room = await site_request(input.site, `/api/rooms/${input.room_id}`, input.token);
+    const roster = free ? room.free.members : room.members;
+    if (action === 'add' && input.new_instance) {
+      // A name once bound keeps its session locally, so a new instance never reuses a removed member's name.
+      const taken = new Set([...roster.map(member => member.name), ...Object.keys(config.participants), ...Object.keys(config.members || {})]);
+      return room_member(home, { ...raw, name: next_instance(platform_of(name), taken), new_instance: false }, true);
+    }
+    const current = roster.find(member => member.name === name);
+    if (input.member_token !== undefined && (typeof input.member_token !== 'string' || input.member_token.length < 32 || input.member_token.length > 256)) throw new Error('member_token 须为 32–256 字符');
+    if (current?.status === 'active' && input.member_token && config.members?.[name]?.token === input.member_token) {
+      const view = await site_request(input.site, `/api/rooms/${input.room_id}/members/${current.id}`, input.token, { action: 'active', token: input.member_token });
+      return { room_id: input.room_id, member: name, access: current.access, [free ? 'free' : 'room']: view, access_file: null };
+    }
+    if (action === 'add' && !current && config.participants[name] && !locked) throw new Error(`${name} 曾在本房间使用过并绑定了会话；请换一个名称`);
+    if (action === 'rejoin' && current?.status !== 'away') throw new Error(`${name} 不是离开状态，无需请回`);
+    if (action === 'add' && current) throw new Error(`${name} 已是本房间成员；离开的成员请用请回`);
+    const manual = action === 'rejoin' ? current.access === 'manual' : access === 'manual';
+    const pending = input.retry_token && config.members?.[name]?.pending === input.retry_token;
+    const token = input.member_token || (pending ? config.members[name].token : `${randomUUID()}${randomUUID()}`);
+    let profile = config.participants[name];
+    if (!manual) {
+      if (action === 'add') {
+        profile = participant_profile(name, launch_settings(home).participants, { ...input, cwd: input.cwd || config.cwd }, false);
+        if (profile.session_id) profile = borrowed_session(name, profile, input.cwd || config.cwd);
+      }
+      if (!profile) throw new Error(`${name} 没有本机接入配置；请移除后重新邀请`);
+      const next = { ...config, participants: { ...config.participants, [name]: profile },
+        members: { ...config.members, [name]: { token, pending: input.retry_token || '' } } };
+      validate_config(next, dirname(path));
+      atomic_json(path, next);
+    }
+    const access_file = manual ? manual_access(path, input, name, token) : null;
+    const body = action === 'add'
+      ? { name, adapter: manual ? '' : profile.adapter, token, access, session_mode: profile?.session_id ? 'borrowed' : 'new' }
+      : { action: 'active', token };
+    const view = await site_request(input.site, action === 'add' ? `/api/rooms/${input.room_id}/members` : `/api/rooms/${input.room_id}/members/${current.id}`,
+      input.token, body);
+    return { room_id: input.room_id, member: name, access: manual ? 'manual' : 'runner', [free ? 'free' : 'room']: view, access_file };
+  } finally { release(); }
+}
+
+/** Stable signatures make changed retry requests explicit without putting credentials in receipts. */
+function signature(value) {
+  if (Array.isArray(value)) return `[${value.map(signature).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().filter(key => value[key] !== undefined).map(key => `${JSON.stringify(key)}:${signature(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+
+/** Inherit the topic duration unless overridden; zero leaves the run without a time limit. */
+function launch_minutes(input, room) {
+  const minutes = Number(input.minutes ?? room.limits?.max_minutes ?? 0);
+  if (!Number.isFinite(minutes) || minutes < 0 || minutes > MAX_MINUTES) throw new Error('讨论总时长或 minutes 须在 [0,1440]，0 表示不限时长');
+  return minutes;
+}
+
+/** Refuse a second registry owner before changing the website runtime. */
+function check_registration(home, config, path) {
+  for (const registered of read_registry(home)) {
+    if (resolve(registered) === path || !existsSync(registered)) continue;
+    const other = registered_identity(registered);
+    if (other?.site === config.site && other.room === config.room) throw new Error('房间已使用另一份接入配置登记；请沿用原配置，不重复接入');
+  }
+}
+
+/** Start once; a lost start response is reconciled from the persisted expected generation. */
+async function enable_run(config, record, persist, minutes) {
+  let runtime = await api(config, '/runtime');
+  if (!record.generation && record.expected_generation === runtime.generation && runtime.revision === record.start_revision && runtime.status === 'running') {
+    record.generation = runtime.generation;
+    persist();
+  }
+  if (record.generation) {
+    if (runtime.generation !== record.generation || runtime.status !== 'running' || runtime.expired) throw new Error('这次启动已暂停、停止或过期；请在原房间核对并明确继续');
+    return runtime;
+  }
+  if (runtime.status !== 'ready' || runtime.expired) throw new Error('房间已运行、暂停、停止或过期；请在原房间核对，不会重新启动');
+  if (!record.start_revision) { record.start_revision = runtime.revision + 1; persist(); }
+  if (runtime.revision + 1 !== record.start_revision) throw new Error('启动期间房间状态已变化，请核对原房间');
+  record.expected_generation = runtime.generation + 1;
+  persist();
+  try {
+    runtime = await api(config, '/runtime', { action: 'start', mode: 'automatic', revision: runtime.revision,
+      deadline: minutes ? Math.floor(Date.now() / 1000 + minutes * 60) : 0 });
+  } catch (error) {
+    const latest = await api(config, '/runtime');
+    if (latest.generation !== record.expected_generation || latest.status !== 'running') throw error;
+    runtime = latest;
+  }
+  record.generation = runtime.generation;
+  persist();
+  return runtime;
+}
+
+/** Reserve the first host task for the calling conversation without sending it a duplicate prompt. */
+async function current_host_task(config, record, persist, room) {
+  const page = await api(config, '/events?after=0');
+  const event = record.event_id ? page.events.find(item => item.id === record.event_id)
+    : page.events.filter(item => item.generation === record.generation && item.role === 'host' && item.participant === room.host && item.status === 'pending').at(-1);
+  if (!event) throw new Error('没有可由当前会话接手的主持任务；请核对原房间');
+  record.event_id = event.id;
+  record.execution_token ||= randomUUID();
+  persist();
+  if (event.status === 'pending') await api(config, `/events/${event.id}`, { action: 'reserve', execution_token: record.execution_token });
+  else await api(config, `/events/${event.id}`, { action: 'view' }, record.execution_token);
+  const store = new DiscussionStore(config.directory);
+  try {
+    store.context(config);
+    const runtime = await api(config, '/runtime');
+    store.scope(config, runtime.run_id);
+    store.receive(page);
+    const session_id = config.participants[room.host].session_id;
+    store.bind(room.host, session_id);
+    const task = task_files(config, event, record.execution_token, { session_id });
+    store.record(event.id, { status: 'accepted', token: record.execution_token, sent_at: Date.now() });
+    return { event_id: event.id, access_file: task.access_path, task_file: join(config.directory, `${task.id}.task.json`) };
+  } finally { store.close(); }
+}
+
+/** Return launch evidence and paths, never raw control or execution tokens. */
+async function launch_receipt(config, record, config_path) {
+  const room = await api(config, '');
+  return { entry: record.entry, room, url: `${config.site}/?room=${config.room}`, config_path,
+    status: room.mode === 'free' ? 'free' : room.runtime.status, current_task: record.current_task || null };
+}
+
+/** Read a saved launch without creating state during validation or preview. */
+function read_launch(directory) {
+  const path = join(directory, 'launch.json');
+  return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+}
+
+/** Find the registered room only after proving the caller's original control credential. */
+async function room_config_context(home, raw) {
+  const input = launch_input({ ...raw, entry: 'web' });
+  if (!input.room_id || typeof input.token !== 'string' || !input.token.trim()) throw new Error('读取本场配置须提供房间编号和原控制凭据');
+  const room = await site_request(input.site, `/api/rooms/${input.room_id}`, input.token);
+  if (!room.runtime?.protected) throw new Error('本场配置修正仅支持具有原控制凭据的受保护房间');
+  await verify_control({ site: input.site, room: input.room_id, token: input.token }, room);
+  if (room.archived || room.runtime.mode !== 'automatic' || room.runtime.status !== 'paused' || room.phase === 'concluded') throw new Error('请先暂停本场讨论，再修正软件路径');
+  const paths = read_registry(home).filter(path => {
+    const identity = registered_identity(path);
+    return identity?.site === input.site && identity.room === input.room_id;
+  });
+  if (paths.length !== 1) throw new Error('未找到本场唯一的已登记配置，请核对原接入服务');
+  const path = paths[0];
+  const journal = read_launch(dirname(path));
+  if (journal && !journal.finished) throw new Error('本次启动尚未完成，请先核对原启动待办');
+  return { input, room, path, ...configuration_snapshot(path) };
+}
+
+/** Expose only editable connection paths, never credentials or unrelated room settings. */
+function connection_view(context) {
+  return { room_id: context.room.id, runtime_revision: context.room.runtime.revision, version: context.version,
+    participants: Object.fromEntries(Object.entries(context.config.participants).map(([name, profile]) =>
+      [name, Object.fromEntries(['adapter', ...CONNECTION_FIELDS].filter(field => profile[field] !== undefined).map(field => [field, profile[field]]))])) };
+}
+
+/** Switch only Codex's execution entrypoint, keeping its actual original conversation. */
+function switch_codex_adapter(context, name, profile, adapter) {
+  if (!CODEX_ADAPTERS.includes(profile.adapter) || !CODEX_ADAPTERS.includes(adapter)) throw new Error('本场仅支持 Codex App / CLI 切换');
+  const current = validate_config(context.config, dirname(context.path));
+  let session = profile.session_id;
+  if (existsSync(join(current.directory, 'runtime.sqlite3'))) {
+    const store = new DiscussionStore(current.directory);
+    try {
+      const binding = store.binding(name).session_id;
+      if (session && binding && session !== binding) throw new Error('原会话绑定不一致，请先核对原会话');
+      session = binding || session;
+    } finally { store.close(); }
+  }
+  if (!session) throw new Error('尚无实际 Codex 会话，不能切换；请先完成首次接入');
+  profile.adapter = adapter;
+  profile.session_id = session;
+}
+
+/** Validate paused-room paths and Codex entrypoints without replacing the discussion or session. */
+function corrected_configuration(context) {
+  const config = structuredClone(context.config);
+  for (const [name, patch] of Object.entries(context.input.participants)) {
+    const profile = config.participants[name];
+    const field = profile?.adapter === 'antigravity' ? 'ipc_directory' : 'executable';
+    const fields = CODEX_ADAPTERS.includes(profile?.adapter) ? [field, 'adapter'] : [field];
+    if (!profile || !patch || typeof patch !== 'object' || Array.isArray(patch) || Object.keys(patch).some(key => !fields.includes(key))) throw new Error('本场修正仅支持软件路径、Sidecar 目录及 Codex App / CLI；参与者、项目及会话保持不变');
+    validate_profile(name, patch);
+    if (patch.adapter && patch.adapter !== profile.adapter) switch_codex_adapter(context, name, profile, patch.adapter);
+    const path = patch[field] ?? profile[field];
+    if (typeof path !== 'string' || !path || !existsSync(path)
+      || (field === 'executable' ? !statSync(path).isFile() || (process.platform === 'win32' && !/\.exe$/i.test(path)) : !statSync(path).isDirectory())) throw new Error(`${name}：请提供有效的软件文件或连接目录`);
+    profile[field] = path;
+  }
+  validate_config(config, dirname(context.path));
+  return config;
+}
+
+/** Wait for the resident worker to read this version before suggesting a manual restart. */
+async function configuration_applied(home, path, version) {
+  for (let waited = 0; waited < CONFIG_APPLY_TIMEOUT_MS; waited += CONFIG_APPLY_POLL_MS) {
+    const pid = service_pid(home);
+    if (!pid) return false;
+    const status_path = join(home, 'status.json');
+    const status = existsSync(status_path) ? JSON.parse(readFileSync(status_path, 'utf8')) : {};
+    const worker = status.rooms?.find(item => resolve(item.config) === resolve(path));
+    if (status.pid === pid && worker?.config_version === version && worker.status === 'paused') return true;
+    await sleep(CONFIG_APPLY_POLL_MS);
+  }
+  return false;
+}
+
+/** Read or save a paused room's connection paths without changing its runtime or global defaults. */
+export async function room_configuration(home, raw, options = {}) {
+  if (raw.participants !== undefined && !options.local_guard) return save_room_connection(raw);
+  let context = await room_config_context(home, raw);
+  if (raw.participants === undefined) return connection_view(context);
+  if (!raw.participants || typeof raw.participants !== 'object' || Array.isArray(raw.participants)) throw new Error('participants 须为本场软件路径对象');
+  const release = acquire_lock(join(dirname(context.path), 'configuration-edit'));
+  try {
+    context = await room_config_context(home, raw);
+    const config = corrected_configuration(context);
+    if (raw.version !== context.version || raw.runtime_revision !== context.room.runtime.revision) throw new Error('房间状态或配置已变化，请重新读取本场配置后核对');
+    atomic_json(context.path, config);
+    const saved = { ...context, ...configuration_snapshot(context.path) };
+    return { ...connection_view(saved), applied: await configuration_applied(home, context.path, saved.version) };
+  } finally { release(); }
+}
+
+/** Serialize file replacement with runtime changes through the local website's database guard. */
+async function save_room_connection(raw) {
+  const input = launch_input({ ...raw, entry: 'web' });
+  const url = new URL(input.site);
+  if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost'].includes(url.hostname)) throw new Error('本场路径修正须通过已启用本机启动的回环网站');
+  const response = await fetch(`${input.site}/api/local/room-config`, { method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-CoDiscuss-Local': '1' },
+    body: JSON.stringify(input), redirect: 'error', signal: AbortSignal.timeout(15000) });
+  const result = await response.json();
+  if (!response.ok) throw new Error(`HTTP ${response.status}: ${result.error || '本场配置保存失败'}`);
+  return result;
+}
+
+/** Prove dispatcher access before a protected room is started or a corrected credential is saved. */
+async function verify_control(config, room) {
+  if (room.runtime?.protected) await api({ ...config, room: room.id }, '/events?after=0');
+}
+
+/** Pin resolved defaults, while comparing retries against only the caller's explicit request. */
+async function prepare_launch(home, input, directory, options = {}) {
+  const previous = read_launch(directory);
+  if (options.browser_request && (typeof input.token !== 'string' || !input.token.trim())) throw new Error('网页启动须携带本次原始控制凭据，不能认领其他启动记录');
+  const { token: ignored_token, access_file: ignored_access, ...request } = input;
+  const request_signature = signature(request);
+  if (previous?.request_signature && previous.request_signature !== request_signature) throw new Error('启动配置与原请求不同；同一次重试须沿用原配置，新讨论请使用新提交编号');
+  const legacy = previous && !previous.request_signature ? JSON.parse(previous.signature) : null;
+  const config_path = join(directory, 'config.json');
+  const saved = previous?.config || (previous && existsSync(config_path) ? JSON.parse(readFileSync(config_path, 'utf8')) : null);
+  const token = input.token || previous?.token || randomUUID();
+  const room_id = input.room_id || previous?.room_id || (saved?.room !== 'preview' ? saved?.room : null);
+  if (options.browser_request && previous && token !== previous.token && !room_id) throw new Error('尚未确认原房间，不能替换本次控制凭据');
+  const room = room_id ? await site_request(input.site, `/api/rooms/${room_id}`, token) : input.room;
+  if (room.runtime?.protected && !input.token && !previous) throw new Error('已有房间需要原接入配置的 access_file');
+  if (!previous && room.runtime && room.runtime.status !== 'ready') throw new Error('房间已启动过；请沿用原配置核对或从原进度看板明确继续');
+  const config = previous?.request_signature ? { ...structuredClone(saved), token }
+    : launch_config(home, input, room, directory, { token, defaults: saved?.participants || legacy?.participants, members: saved?.members });
+  config.draft_directory = service_drafts(home, config.directory);
+  if (previous?.request_signature && !previous.finished) validate_config(config, directory);
+  const minutes = previous?.minutes ?? legacy?.minutes ?? launch_minutes(input, room);
+  const draft = signature({ entry: input.entry, room_id: input.room_id, room: input.room, participants: config.participants, cwd: input.cwd, discussion_project: input.discussion_project, minutes });
+  if (legacy && previous.signature !== draft) throw new Error('启动配置与原请求不同；同一次重试须沿用原配置，新讨论请使用新提交编号');
+  await verify_control(config, room);
+  return { input, config, room, minutes, draft, request_signature, directory, previous };
+}
+
+/** Launch a room through either entry, using a durable journal for safe retries. */
+export async function launch_discussion(home, raw, options = {}) {
+  assert_shared_home(home);
+  const input = launch_input(raw);
+  const key = createHash('sha256').update(`${input.site}/${input.room_id || input.room.submission_id}`).digest('hex');
+  const directory = join(home, 'launches', key);
+  let release;
+  try {
+    const preview = await prepare_launch(home, input, directory, options);
+    if (options.dry_run) return { dry_run: true, entry: input.entry, site: input.site, room_id: input.room_id || null,
+      host: preview.room.host, participants: preview.config.participants, cwd: preview.config.cwd || null,
+      discussion_project: preview.config.discussion_project || null, minutes: preview.minutes };
+    release = acquire_lock(directory);
+    return await perform_launch(home, await prepare_launch(home, input, directory, options), options);
+  } catch (error) {
+    error.launch ||= { stage: existsSync(join(directory, 'launch.json')) ? 'unconfirmed' : 'not_started' };
+    throw error;
+  } finally { release?.(); }
+}
+
+/** Persist preparation before writes, hand off the current host when needed, then register once. */
+async function perform_launch(home, context, options) {
+  const { input, config, minutes, draft, request_signature, directory, previous } = context;
+  const record = previous || { token: config.token, signature: draft, request_signature, config, minutes, entry: input.entry };
+  const persist = () => atomic_json(join(directory, 'launch.json'), record);
+  if (!previous) persist();
+  const progress = { stage: 'unconfirmed' };
+  try {
+    let room = context.room;
+    const free = config.mode === 'free';
+    if (!input.room_id) room = await site_request(input.site, '/api/rooms', config.token, {
+      ...input.room, ...(free ? {} : { runtime_mode: 'automatic' }),
+      members: [...Object.keys(config.participants).map(name => ({ name, adapter: config.participants[name].adapter,
+        token: config.members[name].token, access: 'runner', session_mode: config.participants[name].session_id ? 'borrowed' : 'new' })),
+      // Manual and online members keep the credentials the browser generated; nothing local is configured for them.
+      ...(free ? input.room.members.filter(member => !woken_member(member))
+        .map(({ name, token, access }) => ({ name, token, access, adapter: '', session_mode: 'new' })) : [])],
+    });
+    config.room = room.id;
+    await verify_control(config, room);
+    Object.assign(progress, { stage: 'created', room_id: room.id });
+    Object.assign(record, { token: config.token, request_signature, config, minutes, room_id: room.id });
+    if (!record.start_revision && room.runtime.status === 'ready') record.start_revision = room.runtime.revision + 1;
+    persist();
+    const config_path = join(directory, 'config.json');
+    check_registration(home, config, config_path);
+    if (record.finished) {
+      const saved = existsSync(config_path) ? JSON.parse(readFileSync(config_path, 'utf8')) : config;
+      if (saved.token !== config.token || !existsSync(config_path)) atomic_json(config_path, { ...saved, token: config.token });
+      return launch_receipt(config, record, config_path);
+    }
+    atomic_json(config_path, config);
+    const service = await (options.start_service || start_service)(home);
+    if (!service?.running) throw new Error('讨论服务未就绪，未开始本次讨论');
+    // Free rooms have no discussion run: registering the room is what lets the service deliver requests.
+    if (!free) await enable_run(config, record, persist, minutes);
+    progress.stage = 'started';
+    if (input.entry === 'conversation') record.current_task = await current_host_task(config, record, persist, room);
+    register_room(home, config_path);
+    record.finished = true;
+    persist();
+    return launch_receipt(config, record, config_path);
+  } catch (error) { error.launch = progress; throw error; }
+}
+
+/** CLI and local HTTP bridge use the same commands and configuration validation. */
+export async function launch_main(args = process.argv.slice(2), input_text) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+    file: { type: 'string' }, 'dry-run': { type: 'boolean' }, browser: { type: 'boolean' },
+    'configuration-locked': { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+  } });
+  if (values.help || !positionals.length) return process.stdout.write(HELP);
+  const input = input_text === undefined ? (values.file ? JSON.parse(readFileSync(values.file, 'utf8').replace(/^\uFEFF/, '')) : null) : JSON.parse(input_text);
+  const home = service_home();
+  assert_shared_home(home);
+  let result;
+  if (positionals[0] === 'settings') result = { ...(input ? save_launch_settings(home, input) : launch_settings(home)), api_providers: API_PROVIDERS };
+  else if (positionals[0] === 'api-key' && input) result = save_api_key(home, input);
+  else if (positionals[0] === 'room-models' && input) result = room_models(home, input);
+  else if (positionals[0] === 'models' && input?.adapter === 'api') result = await api_models(home, input);
+  else if (positionals[0] === 'models' && input) {
+    const saved = Object.values(launch_settings(home).participants).find(profile => profile.adapter === input.adapter);
+    result = await cached_software_models(home, { adapter: input.adapter, executable: input.executable || saved?.executable }, { refresh: input.refresh === true });
+  }
+  else if (positionals[0] === 'room-member' && input) result = await room_member(home, input);
+  else if (positionals[0] === 'pick-directory') result = await pick_directory();
+  else if (positionals[0] === 'start' && input) result = await launch_discussion(home, input, { dry_run: values['dry-run'], browser_request: values.browser });
+  else if (positionals[0] === 'room-config' && input) result = await room_configuration(home, input, { local_guard: values['configuration-locked'] });
+  else throw new Error(HELP);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  const args = process.argv.slice(2);
+  const stdin = args.includes('--stdin') ? readFileSync(0, 'utf8') : undefined;
+  launch_main(args.filter(arg => arg !== '--stdin'), stdin).catch(error => {
+    const failure = args.includes('--browser') ? JSON.stringify({ error: error.message, launch: error.launch || { stage: 'not_started' } }) : error.message;
+    process.stderr.write(`${failure}\n`); process.exitCode = 1;
+  });
+}