@larktask/aamp-feishu-task-agent 0.1.0-dev.173 → 0.1.1-dev.2

package/bin/feishu-task-agent-controller.mjs

@@ -8,8 +8,24 @@ import { ReadStream, WriteStream } from 'node:tty';
 import { emitKeypressEvents } from 'node:readline';
 import { spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
+import { fileURLToPath } from 'node:url';
+import {
+  TASK_AGENT_TYPES,
+  resolveTaskAgentMetadata,
+} from './agent-metadata.mjs';
+import {
+  createKeyedSerialExecutor,
+  createSerializedRunner,
+  runLayeredStarts,
+} from './runtime-concurrency.mjs';
+import {
+  createPackageExecutableLauncher,
+  npmExecutableResolverArgs,
+  parseResolvedPackageExecutable,
+} from './runtime-package-executable.mjs';
 import {
   agentStartRetryError,
+  agentStartFailureMessage,
   bridgeAuthenticationRetryError,
   classifyNetworkError,
   createSerializedLineWriter,
@@ -18,6 +34,7 @@ import {
   launchDetachedDiagnostic,
   networkEnvironmentSummary,
   probeEndpoint,
+  preserveAgentStartFailure,
   safeDiagnosticUrl,
   withNetworkRetry,
 } from './runtime-network.mjs';
@@ -43,8 +60,8 @@ const NPM_BIN = process.env.AAMP_TASK_NPM_BIN || 'npm';
 const NPM_REGISTRY = process.env.AAMP_TASK_NPM_REGISTRY || 'https://registry.npmjs.org/';
 const FEISHU_API_PROBE_URL = 'https://open.feishu.cn/';
 const NPM_CACHE_DIR = process.env.AAMP_TASK_NPM_CACHE_DIR || path.join(os.tmpdir(), 'aamp-one-click-npm-cache');
-const ACP_PACKAGE = process.env.AAMP_TASK_ACP_BRIDGE_PKG || '@zengxingyuan/aamp-acp-bridge@0.1.28-dev.20';
-const FEISHU_PACKAGE = process.env.AAMP_TASK_FEISHU_BRIDGE_PKG || '@zengxingyuan/aamp-feishu-bridge@0.1.51';
+const ACP_PACKAGE = process.env.AAMP_TASK_ACP_BRIDGE_PKG || '@luckyterry/aamp-acp-bridge@0.1.29-dev.0';
+const FEISHU_PACKAGE = process.env.AAMP_TASK_FEISHU_BRIDGE_PKG || '@iluolyx/aamp-feishu-bridge@0.1.52-dev.5';
 const INSTALL_COMMAND = process.env.AAMP_TASK_INSTALL_COMMAND
   || 'npx -y --package @larktask/aamp-feishu-task-agent@dev feishu-task-agent install';
 const DEFAULT_AGENT = process.env.AAMP_TASK_DEFAULT_AGENT || '';
@@ -54,24 +71,67 @@ const READY_TIMEOUT_MS = Number(process.env.AAMP_TASK_READY_TIMEOUT_MS || 90_000
 const NETWORK_MAX_ATTEMPTS = Math.max(1, Number(process.env.AAMP_TASK_NETWORK_MAX_ATTEMPTS || 3));
 const NETWORK_RETRY_BASE_DELAY_MS = Math.max(0, Number(process.env.AAMP_TASK_NETWORK_RETRY_BASE_DELAY_MS || 500));
 const NETWORK_PROBE_TIMEOUT_MS = Math.max(1_000, Number(process.env.AAMP_TASK_NETWORK_PROBE_TIMEOUT_MS || 10_000));
+const FEISHU_START_CONCURRENCY = 4;
 const CONFIG_SCHEMA = 'aamp.feishu-task-agent.bindings';
 const CONFIG_VERSION = 1;
-const AGENT_TYPES = ['codex', 'cursor'];
-const PROFILE_DOMAINS = [
-  'base', 'calendar', 'contact', 'docs', 'im', 'mail', 'mindnotes', 'minutes',
-  'note', 'sheets', 'slides', 'task', 'vc', 'wiki',
-];
+const PROFILE_DOMAINS = ['task'];
 
 const secrets = new Set();
 const managedProcesses = new Set();
 const transientProcesses = new Set();
 const heldLeases = new Set();
 const bindingStatuses = new Map();
+const runPairingSerially = createKeyedSerialExecutor();
+const errorLogWriter = createSerializedLineWriter((content) => appendPrivate(ERRORS_LOG, content));
+const manifestWriter = createSerializedRunner(async () => {
+  const statuses = [...bindingStatuses.entries()].map(([bindingId, status]) => ({
+    binding_id: bindingId,
+    ...status,
+  }));
+  await writeJsonAtomic(MANIFEST_FILE, {
+    schema: 'aamp.local_logs.run.v2',
+    run_id: RUN_ID,
+    task_agent_version: process.env.AAMP_TASK_AGENT_VERSION || '',
+    command: COMMAND,
+    started_at: process.env.AAMP_TASK_RUN_STARTED_AT || RUN_STARTED_AT,
+    config_file: CONFIG_FILE,
+    runtime_home: RUNTIME_HOME,
+    bindings: statuses,
+    errors_log: ERRORS_LOG,
+    log_dir: RUN_LOG_DIR,
+  });
+});
 let stopRequested = false;
 let stopSignal = '';
-let cleanupPromise;
 let terminal;
 
+function createResourceCleanup(drain) {
+  const runner = createSerializedRunner(drain);
+  return () => runner.run();
+}
+
+function createPromptInterrupter() {
+  let activeCancel;
+  return {
+    activate(cancel) {
+      if (activeCancel) throw new Error('已有交互提示正在等待输入');
+      activeCancel = cancel;
+      return () => {
+        if (activeCancel === cancel) activeCancel = undefined;
+      };
+    },
+    interrupt(error) {
+      const cancel = activeCancel;
+      if (!cancel) return false;
+      activeCancel = undefined;
+      cancel(error);
+      return true;
+    },
+  };
+}
+
+const promptInterrupter = createPromptInterrupter();
+
 function nowIso() {
   return new Date().toISOString();
 }
@@ -116,13 +176,258 @@ function addSecret(value) {
 function redact(value) {
   let output = String(value ?? '');
   for (const secret of secrets) output = output.split(secret).join('[REDACTED]');
+  output = output.replace(/\b(Bearer|Basic)\s+[^\s,}]+/gi, '$1 [REDACTED]');
   output = output
     .replace(/([?&]pair_code=)[^&\s"']+/gi, '$1[REDACTED]')
-    .replace(/("?(?:app_secret|appSecret|smtpPassword|mailboxToken|access_token|device_code|pairCode)"?\s*[:=]\s*"?)[^",\s}]+/gi, '$1[REDACTED]')
+    .replace(/("?(?:app_secret|appSecret|smtpPassword|mailboxToken|access_token|accessToken|refresh_token|refreshToken|id_token|idToken|session_token|sessionToken|device_code|pairCode|api_key|apiKey|api-key|private_key|privateKey|private-key|auth_token|auth-token|password|authorization|cookie|credential|secret|token|session)"?\s*[:=]\s*"?)(?:(?:Bearer|Basic)\s+)?[^",\s}]+/gi, '$1[REDACTED]')
     .replace(/(--app-secret\s+)[^\s]+/gi, '$1[REDACTED]');
   return output;
 }
 
+const REMOTE_EVENT_PATH_PREFIX = 'aamp-runtime:';
+const REMOTE_AGENT_FAILED = 'REMOTE_AGENT_FAILED: Remote Agent execution failed.';
+const REMOTE_AGENT_PREPARATION_FAILED = 'REMOTE_AGENT_PREPARATION_FAILED: Remote Agent preparation failed.';
+const REMOTE_FAILURE_CODES = new Set([
+  'AIME_ACCESS_DENIED',
+  'AIME_EMPTY_RESPONSE',
+  'AIME_MODEL_NOT_FOUND',
+  'AIME_NETWORK_UNREACHABLE',
+  'AIME_PROTOCOL_DRIFT',
+  'AIME_SDK_INCOMPATIBLE',
+  'AIME_SEND_FAILED',
+  'AIME_SESSION_NOT_FOUND',
+  'AIME_STREAM_INTERRUPTED',
+  'AIME_UNSUPPORTED_CONTENT',
+  'AUTH_CONFIGURATION_UNSUPPORTED',
+  'AUTH_IDENTITY_CHANGED',
+  'AUTH_IDENTITY_UNAVAILABLE',
+  'AUTH_REQUIRED',
+  'AUTH_SOURCE_UNSUPPORTED',
+  'REMOTE_AGENT_FAILED',
+  'REMOTE_ARTIFACT_UNSUPPORTED',
+]);
+
+function isRemoteExecution(options) {
+  return options?.executionLocation === 'remote';
+}
+
+function encodeRemoteEventPath(value, options = {}) {
+  const eventPathRoot = options.eventPathRoot;
+  const eventPathHandles = options.eventPathHandles;
+  if (!eventPathRoot || !(eventPathHandles instanceof Map)
+    || typeof value !== 'string' || !path.isAbsolute(value)) return '';
+  const root = path.resolve(eventPathRoot);
+  const resolved = path.resolve(value);
+  if (!isPathInside(root, resolved)) return '';
+  let handle;
+  do {
+    handle = `${REMOTE_EVENT_PATH_PREFIX}${crypto.randomBytes(24).toString('base64url')}`;
+  } while (eventPathHandles.has(handle));
+  eventPathHandles.set(handle, { root, resolved });
+  return handle;
+}
+
+function safeRemoteFailure(value) {
+  const message = redact(value);
+  const candidate = /\b(?:AIME|AUTH|REMOTE)_[A-Z0-9_]+\b/.exec(message)?.[0];
+  const code = candidate && REMOTE_FAILURE_CODES.has(candidate) ? candidate : 'REMOTE_AGENT_FAILED';
+  if (message.trim()) return { code, message };
+  return { code, message: code === 'REMOTE_AGENT_FAILED' ? REMOTE_AGENT_FAILED : `${code}: Remote Agent execution failed.` };
+}
+
+function trustedAgentExecutionLocations(entries = []) {
+  const locations = new Map();
+  const ambiguous = new Set();
+  const values = entries instanceof Map ? entries.entries() : entries;
+  for (const entry of values || []) {
+    if (!Array.isArray(entry) || entry.length < 2) continue;
+    const [name, executionLocation] = entry;
+    if (typeof name !== 'string' || !['local', 'remote'].includes(executionLocation)) continue;
+    if (locations.has(name) || ambiguous.has(name)) {
+      locations.delete(name);
+      ambiguous.add(name);
+      continue;
+    }
+    locations.set(name, executionLocation);
+  }
+  return locations;
+}
+
+function trustedAgentIdentity(value, options, executionLocation) {
+  if (typeof value !== 'string') return '';
+  const actual = options.agentExecutionLocations?.get(value);
+  return actual && (!executionLocation || actual === executionLocation) ? value : '';
+}
+
+function allowedStructuralIdentity(value, allowedValues) {
+  return typeof value === 'string' && new Set(allowedValues || []).has(value) ? value : '';
+}
+
+function safeRemoteDuration(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function projectTrustedLocalAgentEvent(document, options = {}) {
+  if (!document || typeof document !== 'object' || Array.isArray(document)) return undefined;
+  const type = typeof document.type === 'string' ? document.type : '';
+  const agent = trustedAgentIdentity(document.agent, options, 'local');
+  if (!agent || !['agent.starting', 'agent.started', 'agent.identity', 'agent.failed'].includes(type)) {
+    return undefined;
+  }
+  const event = {
+    type,
+    ...(document.bridge === 'acp-bridge' ? { bridge: 'acp-bridge' } : {}),
+    agent,
+  };
+  if (type === 'agent.starting') return event;
+  const durationMs = safeRemoteDuration(document.durationMs);
+  if (type === 'agent.started') {
+    return {
+      ...event,
+      ...(typeof document.email === 'string' ? { email: redact(document.email) } : {}),
+      connected: document.connected === true,
+      pollingFallback: document.pollingFallback === true,
+      ...(durationMs === undefined ? {} : { durationMs }),
+    };
+  }
+  if (type === 'agent.identity') {
+    return {
+      ...event,
+      ...(typeof document.email === 'string' ? { email: redact(document.email) } : {}),
+      ...(typeof document.acpCommand === 'string' ? { acpCommand: redact(document.acpCommand) } : {}),
+    };
+  }
+  return {
+    ...event,
+    message: redact(document.message || `${agent} Agent Bridge 启动失败`),
+    ...(typeof document.code === 'string'
+      ? { code: redact(document.code) }
+      : typeof document.code === 'number' ? { code: document.code } : {}),
+    ...(durationMs === undefined ? {} : { durationMs }),
+  };
+}
+
+function projectRemoteOperationalEvent(document, options = {}) {
+  if (!document || typeof document !== 'object' || Array.isArray(document)) return undefined;
+  const type = typeof document.type === 'string' ? document.type : '';
+  if (type === 'bridge.process') {
+    if (!['started', 'exited'].includes(document.status)) return undefined;
+    const event = { type, status: document.status };
+    const durationMs = safeRemoteDuration(document.durationMs);
+    if (durationMs !== undefined) event.durationMs = durationMs;
+    if (document.status === 'exited') {
+      event.code = Number.isInteger(document.code) ? document.code : null;
+      event.signal = typeof document.signal === 'string' && /^SIG[A-Z0-9]+$/.test(document.signal)
+        ? document.signal
+        : null;
+      event.expectedStop = document.expectedStop === true;
+      if (document.error) event.error = REMOTE_AGENT_FAILED;
+    }
+    return event;
+  }
+  if (type === 'bridge.running') {
+    const agents = Array.isArray(document.agents)
+      ? document.agents.flatMap((agent) => {
+          const name = trustedAgentIdentity(agent?.name, options);
+          return name ? [{ name }] : [];
+        })
+      : [];
+    return { type, agentCount: agents.length, agents };
+  }
+  if (type === 'bridge.task_runtime.starting') {
+    const appId = allowedStructuralIdentity(document.appId, options.allowedAppIds);
+    const imConfigDir = encodeRemoteEventPath(document.imConfigDir, options);
+    const taskConfigDir = encodeRemoteEventPath(document.taskConfigDir, options);
+    if (!appId || !imConfigDir || !taskConfigDir) return undefined;
+    return { type, appId, imConfigDir, taskConfigDir };
+  }
+  if (type === 'bridge.task_runtime.running') {
+    return { type };
+  }
+  if (type === 'agent.starting') {
+    const agent = trustedAgentIdentity(document.agent, options, 'remote');
+    return agent ? { type, agent } : undefined;
+  }
+  if (type === 'agent.started') {
+    const agent = trustedAgentIdentity(document.agent, options, 'remote');
+    if (!agent) return undefined;
+    const durationMs = safeRemoteDuration(document.durationMs);
+    return {
+      type,
+      agent,
+      connected: document.connected === true,
+      pollingFallback: document.pollingFallback === true,
+      ...(durationMs === undefined ? {} : { durationMs }),
+    };
+  }
+  if (type === 'agent.identity') {
+    const agent = trustedAgentIdentity(document.agent, options, 'remote');
+    if (!agent) return undefined;
+    return {
+      type,
+      agent,
+      executionLocation: 'remote',
+      acpCommandConfigured: document.acpCommandConfigured === true,
+    };
+  }
+  if (type === 'agent.failed') {
+    const agent = trustedAgentIdentity(document.agent, options, 'remote');
+    if (!agent) return undefined;
+    const failure = safeRemoteFailure(document.message);
+    const durationMs = safeRemoteDuration(document.durationMs);
+    return {
+      type,
+      agent,
+      ...failure,
+      ...(durationMs === undefined ? {} : { durationMs }),
+    };
+  }
+  return undefined;
+}
+
+function safeOperationalLine(line, options = {}) {
+  if (!String(line || '').trim()) return '';
+  const text = String(line).trim();
+  if (!isRemoteExecution(options)) return redact(text);
+  try {
+    const document = JSON.parse(text);
+    const localEvent = projectTrustedLocalAgentEvent(document, options);
+    if (localEvent) return JSON.stringify(localEvent);
+    const projected = projectRemoteOperationalEvent(document, options);
+    return projected ? JSON.stringify(projected) : redact(text);
+  } catch {
+    return redact(text);
+  }
+}
+
+function safeOperationalOutput(value, options = {}) {
+  return String(value ?? '')
+    .split(/\r?\n/)
+    .map((line) => safeOperationalLine(line, options))
+    .join('\n');
+}
+
+function safeCapturedLog(stdout, stderr, options = {}) {
+  const chunks = [stdout, stderr]
+    .map((value) => safeOperationalOutput(value, options).replace(/\n+$/g, ''))
+    .filter(Boolean);
+  return chunks.length ? `${chunks.join('\n')}\n` : '';
+}
+
+function resolveRemoteEventPath(value, record, eventPathRoot) {
+  const isHandle = typeof value === 'string' && value.startsWith(REMOTE_EVENT_PATH_PREFIX);
+  if (!isHandle) {
+    if (record?.eventPathHandles instanceof Map) throw new Error('Feishu Bridge 返回了无效的安全路径');
+    return value;
+  }
+  const entry = record?.eventPathHandles?.get(value);
+  const root = path.resolve(eventPathRoot);
+  if (!entry || entry.root !== root || !isPathInside(root, entry.resolved)) {
+    throw new Error('Feishu Bridge 返回了无效的安全路径');
+  }
+  return entry.resolved;
+}
+
 async function ensurePrivateDir(dir) {
   await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
   await fsp.chmod(dir, 0o700).catch(() => {});
@@ -380,6 +685,10 @@ async function acquireRuntimeSessionLease(action) {
   }
   const lease = { lockDir: RUNTIME_SESSION_LOCK, release };
   heldLeases.add(lease);
+  if (stopRequested) {
+    await releaseLease(lease);
+    throwIfStopping();
+  }
   return lease;
 }
 
@@ -428,18 +737,55 @@ async function assertNoSymlinkPath(root, candidate) {
   }
 }
 
+async function resolveConfiguredPendingPairingFile(group, agentType) {
+  const configuredAgents = (group?.agents || []).filter((agent) => agent?.name === agentType);
+  if (configuredAgents.length !== 1 || typeof configuredAgents[0].pairingFile !== 'string'
+    || !configuredAgents[0].pairingFile.trim()) {
+    throw new Error('ACP Bridge 私有配对文件配置缺失或 Agent 不唯一');
+  }
+  if (typeof group?.home !== 'string' || !path.isAbsolute(group.home)
+    || !isPathInside(RUNTIME_HOME, group.home)) {
+    throw new Error('ACP Bridge runtime 不属于 Task Agent 私有目录');
+  }
+  if (!path.isAbsolute(configuredAgents[0].pairingFile)
+    || !isPathInside(group.home, configuredAgents[0].pairingFile)) {
+    throw new Error('ACP Bridge 私有配对文件不属于当前 Agent Bridge runtime');
+  }
+  const configuredPairingFile = path.resolve(configuredAgents[0].pairingFile);
+  await assertNoSymlinkPath(RUNTIME_HOME, configuredPairingFile);
+  return configuredPairingFile;
+}
+
+async function resolvePendingPairingFile(group, agentType, pairing) {
+  const configuredPairingFile = await resolveConfiguredPendingPairingFile(group, agentType);
+  const executionLocation = resolveTaskAgentMetadata(agentType).executionLocation;
+  if (executionLocation === 'remote' && pairing?.pairingFileConfigured !== true) {
+    throw new Error('ACP Bridge 未确认远程 Agent 的私有配对文件配置');
+  }
+  if (executionLocation !== 'remote' && (typeof pairing?.pairingFile !== 'string'
+    || path.resolve(pairing.pairingFile) !== configuredPairingFile)) {
+    throw new Error('ACP Bridge 返回的本地配对文件与私有配置不一致');
+  }
+  return configuredPairingFile;
+}
+
 function validateBinding(binding, index) {
   if (!binding || typeof binding !== 'object') throw new Error(`bindings[${index}] 无效`);
   assertString(binding.binding_id, `bindings[${index}].binding_id`);
   if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(binding.binding_id)) {
     throw new Error(`bindings[${index}].binding_id 必须是 UUID`);
   }
-  if (!AGENT_TYPES.includes(binding.agent_type)) throw new Error(`bindings[${index}].agent_type 仅支持 codex/cursor`);
+  if (!TASK_AGENT_TYPES.includes(binding.agent_type)) {
+    throw new Error(`bindings[${index}].agent_type 仅支持 codex/cursor/coco/traex/traecli/workbuddy/workbuddy_ai/aime`);
+  }
   assertString(binding.aamp_host, `bindings[${index}].aamp_host`);
   assertString(binding.environment?.name, `bindings[${index}].environment.name`);
   assertString(binding.bot?.app_id, `bindings[${index}].bot.app_id`);
   assertString(binding.bot?.app_secret, `bindings[${index}].bot.app_secret`);
-  assertString(binding.bot?.lark_cli_profile, `bindings[${index}].bot.lark_cli_profile`);
+  const metadata = resolveTaskAgentMetadata(binding.agent_type);
+  if (metadata.executionLocation === 'local') {
+    assertString(binding.bot?.lark_cli_profile, `bindings[${index}].bot.lark_cli_profile`);
+  }
   assertString(binding.feishu_config_dir, `bindings[${index}].feishu_config_dir`);
   const expectedConfigDir = expectedFeishuConfigDir(binding.binding_id);
   if (path.resolve(binding.feishu_config_dir) !== path.resolve(expectedConfigDir)) {
@@ -488,20 +834,57 @@ async function loadStore() {
   }
 }
 
-async function replaceBindings(bindings) {
-  await withConfigLock(async () => {
-    await writeJsonAtomic(CONFIG_FILE, { ...emptyStore(), bindings });
-  });
+function bindingExpectation(binding) {
+  return {
+    binding_id: binding.binding_id,
+    updated_at: binding.updated_at,
+  };
 }
 
-async function appendBinding(binding) {
-  await withConfigLock(async () => {
+function sameBindingRelationship(existing, candidate) {
+  return Boolean(existing && candidate
+    && existing.agent_type === candidate.agent_type
+    && existing.aamp_host === candidate.aamp_host
+    && existing.environment?.name === candidate.environment?.name
+    && existing.bot?.app_id === candidate.bot?.app_id);
+}
+
+async function upsertBindings(intents) {
+  return withConfigLock(async () => {
     const store = await loadStore();
-    if (store.bindings.some((item) => item.bot.app_id === binding.bot.app_id)) {
-      throw new Error(`Bot ${binding.bot.app_id} 已绑定，不能重复选择`);
+    const intentByAppId = new Map();
+    for (const intent of intents) {
+      const appId = intent.binding.bot.app_id;
+      if (intentByAppId.has(appId)) throw new Error(`Bot ${appId} 在本次操作中重复选择`);
+      intentByAppId.set(appId, intent);
+    }
+
+    let replacedCount = 0;
+    const consumed = new Set();
+    const bindings = store.bindings.map((current) => {
+      const appId = current.bot.app_id;
+      const intent = intentByAppId.get(appId);
+      if (!intent) return current;
+      const expected = intent.expected;
+      if (!expected
+        || current.binding_id !== expected.binding_id
+        || current.updated_at !== expected.updated_at) {
+        throw new Error(`Bot ${appId} 的绑定已发生变化，请重新执行`);
+      }
+      consumed.add(appId);
+      replacedCount += 1;
+      return intent.binding;
+    });
+
+    for (const [appId, intent] of intentByAppId) {
+      if (consumed.has(appId)) continue;
+      if (intent.expected) throw new Error(`Bot ${appId} 的绑定已发生变化，请重新执行`);
+      bindings.push(intent.binding);
     }
-    validateBinding(binding, store.bindings.length);
-    await writeJsonAtomic(CONFIG_FILE, { ...emptyStore(), bindings: [...store.bindings, binding] });
+
+    const next = validateStore({ ...emptyStore(), bindings });
+    await writeJsonAtomic(CONFIG_FILE, next);
+    return { bindings: intents.map(({ binding }) => binding), replacedCount };
   });
 }
 
@@ -520,50 +903,207 @@ async function updateBinding(binding) {
   });
 }
 
-function bindingLabel(binding) {
+function agentSelectionDisplayName(agent) {
+  return agent;
+}
+
+function agentBindingDisplayName(agent) {
+  return agent;
+}
+
+function bindingLabel(binding, resolvedAgentType = binding.agent_type) {
   const botName = binding.bot?.display_name || binding.bot?.app_id || 'unknown Bot';
-  return `${binding.agent_type} ↔ ${botName} (${binding.bot?.app_id || 'unknown'})`;
+  return `${agentBindingDisplayName(resolvedAgentType)} ↔ ${botName} (${binding.bot?.app_id || 'unknown'})`;
+}
+
+function pairingQueueKey(prepared) {
+  return `${prepared.group.host}\u0000${prepared.binding.agent_type}`;
 }
 
-function printBindingStarted(binding) {
-  console.log(`[aamp-one-click] 启动成功：${bindingLabel(binding)}`);
+function orderStartupItems(bindings, items) {
+  const order = new Map(bindings.map((binding, index) => [binding.binding_id, index]));
+  return [...items].sort((left, right) => (
+    (order.get(left.binding.binding_id) ?? Number.MAX_SAFE_INTEGER)
+      - (order.get(right.binding.binding_id) ?? Number.MAX_SAFE_INTEGER)
+  ));
+}
+
+function startupSummaryLines({ title, plannedCount, running = [], failed = [], cancelled = [] }) {
+  const lines = [`${title} ${running.length}/${plannedCount} 个配置。`];
+  if (running.length) {
+    lines.push('启动成功：');
+    for (const item of running) {
+      lines.push(`- ${bindingLabel(item.binding, item.runtimeAgentType)}`);
+    }
+  }
+  if (failed.length) {
+    lines.push('启动失败：');
+    for (const item of failed) {
+      lines.push(`- ${bindingLabel(item.binding, item.runtimeAgentType)}`);
+      lines.push(`  原因：${safeBindingFailureReason(item.binding, item.reason)}`);
+    }
+  }
+  if (cancelled.length) {
+    lines.push('已取消：');
+    for (const item of cancelled) {
+      lines.push(`- ${bindingLabel(item.binding, item.runtimeAgentType)}`);
+      lines.push(`  原因：${redact(item.reason)}`);
+    }
+  }
+  return lines;
+}
+
+function printStartupSummary(options) {
+  console.log(`\n${startupSummaryLines(options).join('\n')}`);
+}
+
+function installHasOnlyCancellations({ cancelled = [], failures = [], selectionFailures = [] }) {
+  return cancelled.length > 0 && failures.length === 0 && selectionFailures.length === 0;
+}
+
+function agentFailureMessage(agentType, message) {
+  const text = safeAgentFailureReason(agentType, message || 'Agent Bridge 启动失败');
+  if (agentType === 'traecli') {
+    return `${text}\n请执行 'traecli doctor --json' 检查 TraeCode CLI，修复后重试。`;
+  }
+  const productName = agentType === 'workbuddy'
+    ? 'WorkBuddy'
+    : agentType === 'workbuddy_ai'
+      ? 'WorkBuddy AI'
+      : '';
+  if (!productName) return text;
+  if (text.startsWith(`${productName} is not logged in.`)
+    || text.startsWith(`${productName} login expired.`)) return text;
+  return `${text}\n如果尚未登录，请打开 ${productName} 完成登录后重试。`;
+}
+
+function safeAgentFailureReason(agentType, message) {
+  try {
+    if (typeof resolveTaskAgentMetadata === 'function'
+      && resolveTaskAgentMetadata(agentType).executionLocation === 'remote') {
+      return safeRemoteFailure(message).message;
+    }
+  } catch {
+    // Unknown Agent validation remains authoritative at its existing call sites.
+  }
+  return String(message ?? '');
+}
+
+function safeBindingFailureReason(binding, message) {
+  try {
+    if (resolveTaskAgentMetadata(binding?.agent_type).executionLocation === 'remote') {
+      return safeRemoteFailure(message).message;
+    }
+  } catch {
+    // Binding validation remains authoritative at its existing call sites.
+  }
+  return redact(message);
+}
+
+function resolvePreparedAgentBindings(bindings, host, requestedAgentType, preparedAgentType) {
+  const runtimeAgentType = preparedAgentType || requestedAgentType;
+  if (!TASK_AGENT_TYPES.includes(runtimeAgentType)) {
+    throw new Error(`unexpected prepared Agent type: ${runtimeAgentType}`);
+  }
+  if (runtimeAgentType === requestedAgentType) {
+    return {
+      requestedAgentType,
+      runtimeAgentType,
+      stableAgentType: requestedAgentType,
+      stableAgentTypes: [requestedAgentType],
+      bindingsToNormalize: [],
+    };
+  }
+  if (requestedAgentType !== 'coco' || !['traex', 'traecli'].includes(runtimeAgentType)) {
+    throw new Error(`unexpected prepared Agent type: ${requestedAgentType} -> ${runtimeAgentType}`);
+  }
+  const matching = bindings.filter((binding) => (
+    binding.aamp_host === host && binding.agent_type === requestedAgentType
+  ));
+  const bindingsToNormalize = matching.filter((binding) => (
+    binding.state === 'pending' && !binding.agent_target_email
+  ));
+  const keepHistoricalIdentity = matching.some((binding) => !bindingsToNormalize.includes(binding));
+  const stableAgentTypes = [
+    ...(keepHistoricalIdentity || !bindingsToNormalize.length ? [requestedAgentType] : []),
+    ...(bindingsToNormalize.length ? [runtimeAgentType] : []),
+  ];
+  return {
+    requestedAgentType,
+    runtimeAgentType,
+    stableAgentType: stableAgentTypes[0],
+    stableAgentTypes,
+    bindingsToNormalize,
+  };
+}
+
+function commitPreparedAgentBindings(plan) {
+  for (const binding of plan.bindingsToNormalize) binding.agent_type = plan.runtimeAgentType;
+  return plan.stableAgentType;
+}
+
+async function prepareAndCommitAgentBindings(plan, prepare) {
+  const results = [];
+  for (const stableAgentType of plan.stableAgentTypes) {
+    results.push(await prepare(stableAgentType));
+  }
+  commitPreparedAgentBindings(plan);
+  return results;
+}
+
+function recordPreparationFailure(group, requestedAgentType, runtimeAgentType, error) {
+  const reason = agentFailureMessage(runtimeAgentType || requestedAgentType, error?.message || error);
+  group.failures.set(requestedAgentType, reason);
+  return reason;
+}
+
+function recordStableAgentFailure(group, stableAgentType, message) {
+  const runtimeAgentType = group.runtimeAgentTypes.get(stableAgentType) || stableAgentType;
+  const reason = agentFailureMessage(runtimeAgentType, message);
+  group.failures.set(stableAgentType, reason);
+  return reason;
+}
+
+function printBindingStarted(binding, runtimeAgentType = binding.agent_type) {
+  console.log(`[aamp-one-click] 启动成功：${bindingLabel(binding, runtimeAgentType)}`);
+}
+
+function bindingCancellationReason(groups, binding) {
+  return groups.get(binding.aamp_host)?.cancellations?.get(binding.agent_type) || '';
+}
+
+function printBindingCancelled(binding, reason) {
+  console.log(`\n🟡 已取消：${bindingLabel(binding)}`);
+  console.log(`   原因：${reason}`);
 }
 
 async function recordError(component, message, binding) {
-  await appendPrivate(ERRORS_LOG, `${JSON.stringify({
+  const safeMessage = binding ? safeBindingFailureReason(binding, message) : redact(message);
+  await errorLogWriter.write(`${JSON.stringify({
     timestamp: nowIso(),
     level: 'error',
     component,
     binding_id: binding?.binding_id,
     app_id: binding?.bot?.app_id,
-    message: redact(message),
+    message: safeMessage,
   })}\n`);
 }
 
 async function writeManifest() {
-  const statuses = [...bindingStatuses.entries()].map(([bindingId, status]) => ({ binding_id: bindingId, ...status }));
-  await writeJsonAtomic(MANIFEST_FILE, {
-    schema: 'aamp.local_logs.run.v2',
-    run_id: RUN_ID,
-    task_agent_version: process.env.AAMP_TASK_AGENT_VERSION || '',
-    command: COMMAND,
-    started_at: process.env.AAMP_TASK_RUN_STARTED_AT || RUN_STARTED_AT,
-    config_file: CONFIG_FILE,
-    runtime_home: RUNTIME_HOME,
-    bindings: statuses,
-    errors_log: ERRORS_LOG,
-    log_dir: RUN_LOG_DIR,
-  });
+  await manifestWriter.run();
 }
 
 async function setBindingStatus(binding, phase, status, reason = '') {
+  const safeReason = status === 'failed'
+    ? safeBindingFailureReason(binding, reason)
+    : redact(reason);
   bindingStatuses.set(binding.binding_id, {
     agent_type: binding.agent_type,
     app_id: binding.bot.app_id,
     bot_name: binding.bot.display_name || binding.bot.app_id,
     phase,
     status,
-    ...(reason ? { reason: redact(reason) } : {}),
+    ...(reason ? { reason: safeReason } : {}),
     updated_at: nowIso(),
   });
   await writeManifest();
@@ -592,7 +1132,12 @@ async function chooseOne(title, items, render, initialIndex = 0) {
 
   draw();
   return new Promise((resolve, reject) => {
+    let finished = false;
+    let releasePrompt = () => {};
     const finish = (error) => {
+      if (finished) return;
+      finished = true;
+      releasePrompt();
       input.off('keypress', onKeypress);
       input.setRawMode(wasRaw);
       input.pause();
@@ -618,6 +1163,7 @@ async function chooseOne(title, items, render, initialIndex = 0) {
       }
       draw(true);
     };
+    releasePrompt = promptInterrupter.activate(finish);
     input.on('keypress', onKeypress);
   });
 }
@@ -642,12 +1188,17 @@ async function chooseMany(title, items, render) {
       const mark = checked.has(index) ? 'x' : ' ';
       output.write(`\x1b[2K\r  ${pointer} [${mark}] ${option.label}\n`);
     });
-    output.write('\x1b[2K\r使用 ↑/↓ 移动，空格多选，回车确认；选择“全部”会忽略其他选项。\n');
+    output.write('\x1b[2K\r使用 ↑/↓ 移动，按空格键选择（支持多选），按回车键确认；选择“全部”会取消其他选项的选中状态。\n');
   };
 
   draw();
   return new Promise((resolve, reject) => {
+    let finished = false;
+    let releasePrompt = () => {};
     const finish = (error) => {
+      if (finished) return;
+      finished = true;
+      releasePrompt();
       input.off('keypress', onKeypress);
       input.setRawMode(wasRaw);
       input.pause();
@@ -683,6 +1234,7 @@ async function chooseMany(title, items, render) {
       }
       draw(true);
     };
+    releasePrompt = promptInterrupter.activate(finish);
     input.on('keypress', onKeypress);
   });
 }
@@ -709,10 +1261,28 @@ function helperArgs(action, bindingOrAgent) {
 async function runBootstrapHelper(action, bindingOrAgent, extraEnv = {}) {
   if (!BOOTSTRAP) throw new Error('Bootstrap path is unavailable');
   throwIfStopping();
-  const { input } = terminalStreams();
+  const helperAgent = typeof bindingOrAgent === 'object'
+    ? bindingOrAgent?.agent_type
+    : bindingOrAgent;
+  let executionLocation = 'local';
+  if (helperAgent) executionLocation = resolveTaskAgentMetadata(helperAgent).executionLocation;
+  const input = executionLocation === 'remote' && !process.stdin.isTTY
+    ? process.stdin
+    : terminalStreams().input;
   const helperEnv = { ...extraEnv };
   const inputPayload = helperEnv.AAMP_TASK_INTERNAL_BINDING_JSON || '';
   delete helperEnv.AAMP_TASK_INTERNAL_BINDING_JSON;
+  const remoteHelper = executionLocation === 'remote';
+  const helperProcessGroup = remoteHelper && process.platform !== 'win32';
+  // node (v25) aborts at startup when spawned detached with a /dev/tty stdin.
+  // Remote helpers never read stdin (interactive prompts use /dev/tty directly).
+  const helperStdin = remoteHelper ? 'ignore' : input;
+  const helperOutputOptions = {
+    executionLocation,
+    agentExecutionLocations: trustedAgentExecutionLocations(
+      helperAgent ? [[helperAgent, executionLocation]] : [],
+    ),
+  };
   const child = spawn('bash', helperArgs(action, bindingOrAgent), {
     env: {
       ...process.env,
@@ -720,21 +1290,52 @@ async function runBootstrapHelper(action, bindingOrAgent, extraEnv = {}) {
       AAMP_TASK_INTERNAL: 'true',
       AAMP_TASK_INTERNAL_RESULT_FD: '3',
       AAMP_TASK_INTERNAL_INPUT_FD: '4',
+      ...(remoteHelper ? {
+        AAMP_TASK_INTERNAL_EXECUTION_LOCATION: 'remote',
+        ONE_CLICK_LOG: '/dev/null',
+        ERRORS_LOG: '/dev/null',
+      } : {}),
     },
-    stdio: [input, 'inherit', 'inherit', 'pipe', 'pipe'],
+    stdio: [helperStdin, remoteHelper ? 'pipe' : 'inherit', remoteHelper ? 'pipe' : 'inherit', 'pipe', 'pipe'],
+    ...(helperProcessGroup ? { detached: true } : {}),
   });
-  const processRecord = trackTransientProcess(child, `Bootstrap helper ${action}`, false);
+  const processRecord = trackTransientProcess(child, `Bootstrap helper ${action}`, helperProcessGroup);
   let result = '';
+  const relayWrites = [];
+  const remoteDiagnostics = [];
+  const relayRemoteLine = (streamName, line) => {
+    if (!String(line || '').trim()) return;
+    const safeLine = safeOperationalLine(line, helperOutputOptions);
+    remoteDiagnostics.push(safeLine);
+    const target = streamName === 'stderr' ? process.stderr : process.stdout;
+    target.write(`${safeLine}\n`);
+    if (process.env.ONE_CLICK_LOG && process.env.ONE_CLICK_LOG !== '/dev/null') {
+      relayWrites.push(appendPrivate(process.env.ONE_CLICK_LOG, `${safeLine}\n`));
+    }
+  };
+  if (remoteHelper) {
+    createLineReader(child.stdout, (line) => relayRemoteLine('stdout', line));
+    createLineReader(child.stderr, (line) => relayRemoteLine('stderr', line));
+  }
   child.stdio[3].setEncoding('utf8');
   child.stdio[3].on('data', (chunk) => { result += chunk; });
   child.stdio[4].end(inputPayload ? `${inputPayload}\n` : '');
   if (stopRequested) await stopManagedProcess(processRecord);
   const exit = await processRecord.exitPromise;
+  await Promise.allSettled(relayWrites);
   throwIfStopping();
-  if (exit.code !== 0) throw exit.error || new Error(`Bootstrap helper ${action} failed${exit.signal ? ` (${exit.signal})` : ''}`);
+  if (exit.code !== 0) {
+    if (remoteHelper) {
+      throw new Error(remoteDiagnostics.at(-1) || REMOTE_AGENT_PREPARATION_FAILED);
+    }
+    throw exit.error || new Error(`Bootstrap helper ${action} failed${exit.signal ? ` (${exit.signal})` : ''}`);
+  }
   try {
     return JSON.parse(result.trim() || '{}');
   } catch {
+    if (remoteHelper) {
+      throw new Error(remoteDiagnostics.at(-1) || REMOTE_AGENT_PREPARATION_FAILED);
+    }
     throw new Error(`Bootstrap helper ${action} returned invalid result`);
   }
 }
@@ -746,7 +1347,7 @@ function npmExecArgs(packageSpec, executable, args) {
   ];
 }
 
-async function runCapture(packageSpec, executable, args, options = {}) {
+async function runNpmExecCapture(packageSpec, executable, args, options = {}) {
   throwIfStopping();
   const child = spawn(NPM_BIN, npmExecArgs(packageSpec, executable, args), {
     env: options.env || process.env,
@@ -766,10 +1367,67 @@ async function runCapture(packageSpec, executable, args, options = {}) {
   const exit = await processRecord.exitPromise;
   throwIfStopping();
   if (options.logFile) {
-    await appendPrivate(options.logFile, `${stdout}${stderr ? `\n${stderr}` : ''}`);
+    await appendPrivate(options.logFile, safeCapturedLog(stdout, stderr, options));
   }
   if (exit.code !== 0) {
-    const detail = redact(stderr.trim() || stdout.trim() || exit.error?.message || `exit ${exit.code}`);
+    const detail = safeOperationalOutput(
+      stderr.trim() || stdout.trim() || exit.error?.message || `exit ${exit.code}`,
+      options,
+    );
+    throw new Error(`${executable} failed: ${detail.split('\n').slice(-8).join('\n')}`);
+  }
+  return { stdout, stderr };
+}
+
+const packageExecutableLauncher = createPackageExecutableLauncher({
+  materialize: async (packageSpec, executable, options = {}) => {
+    const result = await runNpmExecCapture(
+      packageSpec,
+      process.execPath,
+      npmExecutableResolverArgs(executable),
+      options,
+    );
+    return parseResolvedPackageExecutable(result.stdout, executable);
+  },
+});
+
+async function runCapture(packageSpec, executable, args, options = {}) {
+  throwIfStopping();
+  const preparedExecutable = await packageExecutableLauncher.resolve(
+    packageSpec,
+    executable,
+    options,
+  );
+  throwIfStopping();
+  const child = packageExecutableLauncher.launchPrepared({
+    preparedExecutable,
+    args,
+    spawnOptions: {
+      env: options.env || process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    },
+  });
+  const processRecord = trackTransientProcess(child, executable, process.platform !== 'win32');
+  let stdout = '';
+  let stderr = '';
+  child.stdout.setEncoding('utf8');
+  child.stderr.setEncoding('utf8');
+  child.stdout.on('data', (chunk) => { stdout += chunk; });
+  child.stderr.on('data', (chunk) => { stderr += chunk; });
+  if (options.input !== undefined) child.stdin.end(options.input);
+  else child.stdin.end();
+  if (stopRequested) await stopManagedProcess(processRecord);
+  const exit = await processRecord.exitPromise;
+  throwIfStopping();
+  if (options.logFile) {
+    await appendPrivate(options.logFile, safeCapturedLog(stdout, stderr, options));
+  }
+  if (exit.code !== 0) {
+    const detail = safeOperationalOutput(
+      stderr.trim() || stdout.trim() || exit.error?.message || `exit ${exit.code}`,
+      options,
+    );
     throw new Error(`${executable} failed: ${detail.split('\n').slice(-8).join('\n')}`);
   }
   return { stdout, stderr };
@@ -829,15 +1487,42 @@ function createLineReader(stream, onLine) {
   });
 }
 
-async function startManagedProcess({ label, packageSpec, executable, args, env, logFile }) {
+async function startManagedProcess({
+  label,
+  packageSpec,
+  executable,
+  args,
+  env,
+  logFile,
+  preparedExecutable,
+  executionLocation = 'local',
+  eventPathRoot,
+  agentExecutionLocations = [],
+  allowedAppIds = [],
+}) {
   await ensurePrivateDir(path.dirname(logFile));
   throwIfStopping();
   await fsp.writeFile(logFile, '', { mode: 0o600, flag: 'a' });
   throwIfStopping();
-  const child = spawn(NPM_BIN, npmExecArgs(packageSpec, executable, args), {
-    env: env || process.env,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    detached: process.platform !== 'win32',
+  const executableDescriptor = preparedExecutable || await packageExecutableLauncher.resolve(
+    packageSpec,
+    executable,
+    {
+      env: env || process.env,
+      executionLocation,
+      eventPathRoot,
+      ...(executionLocation === 'remote' ? { logFile } : {}),
+    },
+  );
+  throwIfStopping();
+  const child = packageExecutableLauncher.launchPrepared({
+    preparedExecutable: executableDescriptor,
+    args,
+    spawnOptions: {
+      env: env || process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    },
   });
   const processStartedAt = Date.now();
   const logWriter = createSerializedLineWriter((content) => appendPrivate(logFile, content));
@@ -852,11 +1537,19 @@ async function startManagedProcess({ label, packageSpec, executable, args, env,
     expectedStop: false,
     processGroup: process.platform !== 'win32',
     outputTail: [],
+    eventPathHandles: executionLocation === 'remote' && eventPathRoot ? new Map() : undefined,
     logWriter,
     logWriteError: undefined,
   };
   managedProcesses.add(record);
-  void logWriter.write(`${JSON.stringify({
+  const outputOptions = {
+    executionLocation,
+    eventPathRoot,
+    eventPathHandles: record.eventPathHandles,
+    agentExecutionLocations: trustedAgentExecutionLocations(agentExecutionLocations),
+    allowedAppIds,
+  };
+  void logWriter.write(`${safeOperationalLine(JSON.stringify({
     timestamp: nowIso(),
     type: 'bridge.process',
     status: 'started',
@@ -865,17 +1558,21 @@ async function startManagedProcess({ label, packageSpec, executable, args, env,
     package: packageSpec,
     pid: child.pid || null,
     node: process.version,
-  })}\n`).catch((error) => {
+  }), outputOptions)}\n`).catch((error) => {
     record.logWriteError ??= error;
   });
   const handleLine = (streamName, line) => {
-    const safeLine = redact(line);
+    const safeLine = safeOperationalLine(line, outputOptions);
     record.outputTail.push(`[${streamName}] ${safeLine}`);
     if (record.outputTail.length > 30) record.outputTail.shift();
     record.emitter.emit('output', safeLine);
-    if (streamName === 'stdout' && line.trim()) {
+    if (streamName === 'stdout' && safeLine.trim()) {
       try {
-        const event = JSON.parse(line.trim());
+        const rawEvent = JSON.parse(String(line).trim());
+        const event = executionLocation === 'remote'
+          ? (projectTrustedLocalAgentEvent(rawEvent, outputOptions)
+            || projectRemoteOperationalEvent(rawEvent, outputOptions))
+          : JSON.parse(safeLine.trim());
         if (event && typeof event.type === 'string') {
           record.events.push(event);
           record.emitter.emit('event', event);
@@ -884,7 +1581,7 @@ async function startManagedProcess({ label, packageSpec, executable, args, env,
         // Feishu task mode can mix human-readable lines with JSON events.
       }
     }
-    void logWriter.write(`${line}\n`).catch((error) => {
+    void logWriter.write(`${safeLine}\n`).catch((error) => {
       record.logWriteError ??= error;
     });
   };
@@ -895,7 +1592,7 @@ async function startManagedProcess({ label, packageSpec, executable, args, env,
     const finish = async (exit) => {
       if (settled) return;
       settled = true;
-      await logWriter.write(`${JSON.stringify({
+      await logWriter.write(`${safeOperationalLine(JSON.stringify({
         timestamp: nowIso(),
         type: 'bridge.process',
         status: 'exited',
@@ -908,12 +1605,13 @@ async function startManagedProcess({ label, packageSpec, executable, args, env,
         signal: exit.signal || null,
         expectedStop: record.expectedStop,
         ...(exit.error ? { error: describeNetworkError(exit.error) } : {}),
-      })}\n`).catch((error) => {
+      }), outputOptions)}\n`).catch((error) => {
         record.logWriteError ??= error;
       });
       await logWriter.flush().catch((error) => {
         record.logWriteError ??= error;
       });
+      record.eventPathHandles?.clear();
       record.exited = true;
       record.exit = {
         ...exit,
@@ -1047,7 +1745,29 @@ async function releaseLease(lease) {
   await lease.release();
 }
 
-async function setupAgentGroups(bindings) {
+function acpBridgeAgentPolicy(stableAgentType) {
+  const metadata = resolveTaskAgentMetadata(stableAgentType);
+  return {
+    executionLocation: metadata.executionLocation,
+    ...(metadata.attachmentPolicy ? { attachmentPolicy: metadata.attachmentPolicy } : {}),
+    ...(metadata.taskDispatchConcurrency
+      ? { taskDispatchConcurrency: metadata.taskDispatchConcurrency }
+      : {}),
+  };
+}
+
+function agentExecutionLocations(agents) {
+  return new Set((agents || []).map((agent) => (
+    resolveTaskAgentMetadata(agent.name).executionLocation
+  )));
+}
+
+function groupProcessExecutionLocation(agents) {
+  return agentExecutionLocations(agents).has('remote') ? 'remote' : 'local';
+}
+
+async function initializeAgentGroups(bindings, operations = {}) {
+  const prepareAgent = operations.runBootstrapHelper || runBootstrapHelper;
   const byHost = new Map();
   for (const binding of bindings) {
     if (!byHost.has(binding.aamp_host)) byHost.set(binding.aamp_host, new Map());
@@ -1074,45 +1794,88 @@ async function setupAgentGroups(bindings) {
       identities: new Map(),
       availableAgents: new Set(),
       failures: new Map(),
+      cancellations: new Map(),
+      runtimeAgentTypes: new Map(),
       leases: new Map(),
+      agents: [],
+      bridgeEnv,
       process: undefined,
     };
     groups.set(host, group);
     const agents = [];
     for (const [agentType, sampleBinding] of agentBindings) {
       throwIfStopping();
+      let runtimeAgentType;
+      let stableAgentTypes = [agentType];
       try {
         const lease = await acquireAgentLease(host, agentType);
         throwIfStopping();
         group.leases.set(agentType, lease);
-        console.log(`[aamp-one-click] 正在检查 ${agentType} 本地智能体...`);
-        const prepared = await runBootstrapHelper('__prepare-agent', sampleBinding);
+        const metadata = resolveTaskAgentMetadata(agentType);
+        console.log(`[aamp-one-click] 正在检查 ${agentSelectionDisplayName(agentType)} ${metadata.executionLocation === 'remote' ? '远程智能体' : '本地智能体'}...`);
+        const prepared = await prepareAgent('__prepare-agent', sampleBinding);
         throwIfStopping();
-        if (path.resolve(prepared.lark_cli_config_dir || '') !== path.resolve(bridgeEnv.LARKSUITE_CLI_CONFIG_DIR)) {
-          throw new Error(`Agent 使用的 lark-cli 配置目录与 Online 配置不一致：${prepared.lark_cli_config_dir || 'unknown'}`);
+        runtimeAgentType = prepared.agent_type || agentType;
+        if (prepared.cancelled === true) {
+          const reason = redact(prepared.reason || '用户取消了 Agent 准备流程');
+          group.cancellations.set(agentType, reason);
+          await releaseLease(group.leases.get(agentType));
+          group.leases.delete(agentType);
+          continue;
         }
-        const agentHome = path.join(home, 'agents', agentType);
-        await assertNoSymlinkPath(RUNTIME_HOME, agentHome);
-        throwIfStopping();
-        await ensurePrivateDir(agentHome);
-        throwIfStopping();
-        agents.push({
-          name: agentType,
-          acpCommand: prepared.acp_command,
-          credentialsFile: path.join(agentHome, 'credentials.json'),
-          pairingFile: path.join(agentHome, 'pairing.json'),
-          senderPoliciesFile: path.join(agentHome, 'sender-policies.json'),
-          createPairing: false,
+        if (prepared.agent_type && prepared.agent_type !== agentType && agentBindings.has(prepared.agent_type)) {
+          throw new Error(`Agent 类型归一化后发生重复：${agentType} -> ${prepared.agent_type}`);
+        }
+        const bindingPlan = resolvePreparedAgentBindings(
+          bindings,
+          host,
+          agentType,
+          runtimeAgentType,
+        );
+        stableAgentTypes = bindingPlan.stableAgentTypes;
+        const preparedAgents = await prepareAndCommitAgentBindings(bindingPlan, async (stableAgentType) => {
+          if (!group.leases.has(stableAgentType)) {
+            group.leases.set(stableAgentType, await acquireAgentLease(host, stableAgentType));
+          }
+          const stableMetadata = resolveTaskAgentMetadata(stableAgentType);
+          if (stableMetadata.executionLocation === 'local'
+            && path.resolve(prepared.lark_cli_config_dir || '') !== path.resolve(bridgeEnv.LARKSUITE_CLI_CONFIG_DIR)) {
+            throw new Error(`Agent 使用的 lark-cli 配置目录与 Online 配置不一致：${prepared.lark_cli_config_dir || 'unknown'}`);
+          }
+          const agentHome = path.join(home, 'agents', stableAgentType);
+          await assertNoSymlinkPath(RUNTIME_HOME, agentHome);
+          throwIfStopping();
+          await ensurePrivateDir(agentHome);
+          throwIfStopping();
+          return {
+            name: stableAgentType,
+            acpCommand: prepared.acp_command,
+            credentialsFile: path.join(agentHome, 'credentials.json'),
+            pairingFile: path.join(agentHome, 'pairing.json'),
+            senderPoliciesFile: path.join(agentHome, 'sender-policies.json'),
+            createPairing: false,
+            ...acpBridgeAgentPolicy(stableAgentType),
+          };
         });
+        if (!stableAgentTypes.includes(agentType)) {
+          await releaseLease(group.leases.get(agentType));
+          group.leases.delete(agentType);
+        }
+        agents.push(...preparedAgents);
+        for (const stableAgentType of stableAgentTypes) {
+          group.runtimeAgentTypes.set(stableAgentType, runtimeAgentType);
+        }
       } catch (error) {
-        const reason = redact(error.message || error);
-        group.failures.set(agentType, reason);
-        await releaseLease(group.leases.get(agentType));
-        group.leases.delete(agentType);
+        recordPreparationFailure(group, agentType, runtimeAgentType, redact(error.message || error));
+        for (const stableAgentType of new Set([...stableAgentTypes, agentType])) {
+          await releaseLease(group.leases.get(stableAgentType));
+          group.leases.delete(stableAgentType);
+        }
         if (stopRequested) throw error;
       }
     }
     if (!agents.length) continue;
+    group.executionLocation = groupProcessExecutionLocation(agents);
     try {
       throwIfStopping();
       const initResult = await runNetworkStage(async () => {
@@ -1120,7 +1883,16 @@ async function setupAgentGroups(bindings) {
           ACP_PACKAGE,
           'aamp-acp-bridge',
           ['init', '--json', '--config', group.configFile, '--input', '-'],
-          { input: JSON.stringify({ aampHost: host, agents }), env: bridgeEnv, logFile },
+          { input: JSON.stringify({ aampHost: host, agents }),
+            env: bridgeEnv,
+            logFile,
+            executionLocation: group.executionLocation,
+            eventPathRoot: group.home,
+            agentExecutionLocations: trustedAgentExecutionLocations(agents.map((agent) => [
+              agent.name,
+              resolveTaskAgentMetadata(agent.name).executionLocation,
+            ])),
+          },
         );
       }, {
         stage: 'acp-init',
@@ -1132,15 +1904,58 @@ async function setupAgentGroups(bindings) {
       throwIfStopping();
       const initialized = parseJsonDocument(initResult.stdout, 'ACP init');
       for (const agent of initialized.agents || []) group.identities.set(agent.name, agent.email);
-      console.log(`[aamp-one-click] 正在启动本地 Agent Bridge (${agents.map((agent) => agent.name).join(', ')})...`);
+      group.agents = agents;
+    } catch (error) {
+      for (const agent of agents) {
+        const message = agentStartFailureMessage(
+          error?.agentStartEvents || group.process?.events,
+          agent.name,
+          redact(error.message || error),
+        );
+        recordStableAgentFailure(group, agent.name, message);
+      }
+      if (group.process) await stopManagedProcess(group.process);
+      for (const lease of group.leases.values()) await releaseLease(lease);
+      group.leases.clear();
+      if (stopRequested) throw error;
+    }
+  }
+  return groups;
+}
+
+async function startAgentGroups(groups) {
+  for (const group of groups.values()) {
+    const agents = group.agents || [];
+    if (!agents.length) continue;
+    const bridgeEnv = group.bridgeEnv;
+    try {
+      throwIfStopping();
+      const runtimeAgentNames = agents
+        .map((agent) => group.runtimeAgentTypes.get(agent.name) || agent.name)
+        .map(agentSelectionDisplayName);
+      const executionLocations = agentExecutionLocations(agents);
+      if (executionLocations.size === 1 && executionLocations.has('remote')) {
+        console.log(`[aamp-one-click] 正在启动远程 Agent Bridge (${runtimeAgentNames.join(', ')})...`);
+      } else if (executionLocations.size === 1 && executionLocations.has('local')) {
+        console.log(`[aamp-one-click] 正在启动本地 Agent Bridge (${runtimeAgentNames.join(', ')})...`);
+      } else {
+        console.log(`[aamp-one-click] 正在启动 Agent Bridge (${runtimeAgentNames.join(', ')})...`);
+      }
+      const executionLocation = executionLocations.has('remote') ? 'remote' : 'local';
       const started = await runNetworkStage(async ({ attempt, maxAttempts }) => {
         const process = await startManagedProcess({
-          label: `ACP Bridge ${host}`,
+          label: `ACP Bridge ${group.host}`,
           packageSpec: ACP_PACKAGE,
           executable: 'aamp-acp-bridge',
           args: ['start', '--config', group.configFile, '--json', ...(DEBUG_MODE ? ['--debug'] : [])],
           env: bridgeEnv,
-          logFile,
+          logFile: group.logFile,
+          executionLocation,
+          eventPathRoot: group.home,
+          agentExecutionLocations: agents.map((agent) => [
+            agent.name,
+            resolveTaskAgentMetadata(agent.name).executionLocation,
+          ]),
         });
         group.process = process;
         try {
@@ -1154,16 +1969,17 @@ async function setupAgentGroups(bindings) {
           if (retryError) throw retryError;
           return { process, running };
         } catch (error) {
+          const failure = preserveAgentStartFailure(error, process.events);
           await stopManagedProcess(process);
           managedProcesses.delete(process);
           if (group.process === process) group.process = undefined;
-          throw error;
+          throw failure;
         }
       }, {
         stage: 'acp-start',
         label: 'Agent Bridge 启动',
-        host,
-        logFile,
+        host: group.host,
+        logFile: group.logFile,
         environment: bridgeEnv,
       });
       group.process = started.process;
@@ -1174,13 +1990,24 @@ async function setupAgentGroups(bindings) {
       for (const agent of agents) {
         if (!group.availableAgents.has(agent.name)) {
           const failed = group.process.events.find((event) => event.type === 'agent.failed' && event.agent === agent.name);
-          group.failures.set(agent.name, failed?.message || `${agent.name} Agent Bridge 启动失败`);
+          recordStableAgentFailure(
+            group,
+            agent.name,
+            failed?.message || `${agent.name} Agent Bridge 启动失败`,
+          );
           await releaseLease(group.leases.get(agent.name));
           group.leases.delete(agent.name);
         }
       }
     } catch (error) {
-      for (const agent of agents) group.failures.set(agent.name, redact(error.message || error));
+      for (const agent of agents) {
+        const message = agentStartFailureMessage(
+          error?.agentStartEvents || group.process?.events,
+          agent.name,
+          redact(error.message || error),
+        );
+        recordStableAgentFailure(group, agent.name, message);
+      }
       if (group.process) await stopManagedProcess(group.process);
       for (const lease of group.leases.values()) await releaseLease(lease);
       group.leases.clear();
@@ -1190,11 +2017,31 @@ async function setupAgentGroups(bindings) {
   return groups;
 }
 
-function resolveGroup(groups, binding) {
+async function setupAgentGroups(bindings) {
+  const groups = await initializeAgentGroups(bindings);
+  await startAgentGroups(groups);
+  return groups;
+}
+
+function resolveInitializedGroup(groups, binding) {
   const group = groups.get(binding.aamp_host);
   if (!group) throw new Error(`Agent Bridge group is unavailable for ${binding.aamp_host}`);
+  const agentCancellation = group.cancellations.get(binding.agent_type);
+  if (agentCancellation) throw new Error(agentCancellation);
   const agentFailure = group.failures.get(binding.agent_type);
-  if ((!group.process || group.process.exited) && agentFailure) throw new Error(agentFailure);
+  if (agentFailure) throw new Error(agentFailure);
+  const email = group.identities.get(binding.agent_type);
+  if (!email) throw new Error(`${binding.agent_type} Agent mailbox is unavailable`);
+  if (binding.agent_target_email && binding.agent_target_email !== email) {
+    throw new Error(`Agent mailbox 已变化（配置=${binding.agent_target_email}，当前=${email}），请使用 add 或 install 重新绑定`);
+  }
+  const runtimeAgentType = group.runtimeAgentTypes.get(binding.agent_type) || binding.agent_type;
+  return { group, email, runtimeAgentType };
+}
+
+function resolveGroup(groups, binding) {
+  const resolved = resolveInitializedGroup(groups, binding);
+  const { group } = resolved;
   if (!group.process || group.process.exited) {
     const tail = group.process?.outputTail?.slice(-10).join('\n');
     throw new Error(`Agent Bridge 已退出${tail ? `：\n${tail}` : ''}`);
@@ -1202,12 +2049,7 @@ function resolveGroup(groups, binding) {
   if (!group.availableAgents.has(binding.agent_type)) {
     throw new Error(group.failures.get(binding.agent_type) || `${binding.agent_type} Agent Bridge 未启动`);
   }
-  const email = group.identities.get(binding.agent_type);
-  if (!email) throw new Error(`${binding.agent_type} Agent mailbox is unavailable`);
-  if (binding.agent_target_email && binding.agent_target_email !== email) {
-    throw new Error(`Agent mailbox 已变化（配置=${binding.agent_target_email}，当前=${email}），请使用 add 或 install 重新绑定`);
-  }
-  return { group, email };
+  return resolved;
 }
 
 async function writeFeishuRuntimeProfile(binding) {
@@ -1215,14 +2057,15 @@ async function writeFeishuRuntimeProfile(binding) {
   const instancesDir = path.join(binding.feishu_config_dir, 'task-runtime', 'instances');
   await assertNoSymlinkPath(RUNTIME_HOME, profileFile);
   await assertNoSymlinkPath(RUNTIME_HOME, instancesDir);
+  const metadata = resolveTaskAgentMetadata(binding.agent_type);
   await writeJsonAtomic(profileFile, {
     version: 1,
     profiles: [{
       app_id: binding.bot.app_id,
       app_secret: binding.bot.app_secret,
-      profile: binding.bot.lark_cli_profile,
       display_name: binding.bot.display_name,
-      auth_mode: 'lark-cli',
+      auth_mode: metadata.executionLocation === 'remote' ? 'app-secret' : 'lark-cli',
+      ...(metadata.executionLocation === 'local' ? { profile: binding.bot.lark_cli_profile } : {}),
       capabilities: ['im', 'task'],
       domains: PROFILE_DOMAINS,
       updated_at: nowIso(),
@@ -1236,7 +2079,55 @@ async function ensureBindingProfile(binding) {
   });
 }
 
+async function probeBindingProfile(binding) {
+  return runBootstrapHelper('__probe-profile', binding, {
+    AAMP_TASK_INTERNAL_BINDING_JSON: JSON.stringify({
+      agent_type: binding.agent_type,
+      aamp_host: binding.aamp_host,
+      bot: {
+        app_id: binding.bot.app_id,
+        lark_cli_profile: binding.bot.lark_cli_profile,
+      },
+    }),
+  });
+}
+
+const readyProfileProbeOperations = Object.freeze({
+  probeBindingProfile,
+  throwIfStopping,
+});
+
+async function probeReadyBindingProfiles(
+  bindings,
+  operations = readyProfileProbeOperations,
+) {
+  const probes = new Map();
+  for (const binding of bindings) {
+    if (bindingNeedsInitialStart(binding)
+      || resolveTaskAgentMetadata(binding.agent_type).executionLocation === 'remote') continue;
+    operations.throwIfStopping();
+    try {
+      const profile = await operations.probeBindingProfile(binding);
+      operations.throwIfStopping();
+      if (profile?.ready === true && profile.lark_cli_bin) probes.set(binding, profile);
+    } catch {
+      operations.throwIfStopping();
+      // The normal binding preparation remains authoritative for misses and failures.
+    }
+  }
+  return probes;
+}
+
+function prewarmFeishuExecutable(binding) {
+  return packageExecutableLauncher.resolve(
+    FEISHU_PACKAGE,
+    'aamp-feishu-bridge',
+    { env: onlineEnvironment(binding) },
+  );
+}
+
 function feishuArgs(binding, larkCliBin, target) {
+  const metadata = resolveTaskAgentMetadata(binding.agent_type);
   const targetArgs = target.pairingUrl
     ? ['--pairing-url', target.pairingUrl]
     : ['--target-agent', target.agentTargetEmail];
@@ -1245,48 +2136,104 @@ function feishuArgs(binding, larkCliBin, target) {
     '--config-dir', binding.feishu_config_dir,
     '--aamp-host', binding.aamp_host,
     '--agent', binding.agent_type,
+    '--agent-execution-location', metadata.executionLocation,
     ...targetArgs,
     '--app-id', binding.bot.app_id,
     '--bot-name', binding.bot.display_name || binding.bot.app_id,
-    '--use-feishu-cli',
-    '--feishu-cli-profile', binding.bot.lark_cli_profile,
-    '--feishu-cli-bin', larkCliBin,
+    ...(metadata.executionLocation === 'local' ? [
+      '--use-feishu-cli',
+      '--feishu-cli-profile', binding.bot.lark_cli_profile,
+      '--feishu-cli-bin', larkCliBin,
+    ] : []),
     '--json',
     ...(DEBUG_MODE ? ['--debug'] : []),
   ];
 }
 
-async function prepareFeishuProcess(binding, phase) {
-  throwIfStopping();
-  await writeFeishuRuntimeProfile(binding);
-  throwIfStopping();
-  const profile = await ensureBindingProfile(binding);
-  throwIfStopping();
-  if (!profile.lark_cli_bin) throw new Error(`lark-cli profile ${binding.bot.lark_cli_profile} is unavailable`);
+const feishuPreparationOperations = Object.freeze({
+  ensureBindingProfile,
+  onlineEnvironment,
+  throwIfStopping,
+  writeFeishuRuntimeProfile,
+});
+
+async function prepareFeishuProcess(
+  binding,
+  phase,
+  runtimeAgentType = binding.agent_type,
+  profileProbes,
+  operations = feishuPreparationOperations,
+) {
+  operations.throwIfStopping();
+  await operations.writeFeishuRuntimeProfile(binding);
+  operations.throwIfStopping();
+  const environment = operations.onlineEnvironment(binding);
+  const metadata = resolveTaskAgentMetadata(binding.agent_type);
+  const probedProfile = profileProbes?.get(binding);
+  const profile = metadata.executionLocation === 'remote'
+    ? {}
+    : (probedProfile?.ready === true
+      && probedProfile.lark_cli_bin
+      && path.resolve(probedProfile.lark_cli_config_dir || '')
+        === path.resolve(environment.LARKSUITE_CLI_CONFIG_DIR || '')
+      ? probedProfile
+      : await operations.ensureBindingProfile(binding));
+  operations.throwIfStopping();
+  if (metadata.executionLocation === 'local' && !profile.lark_cli_bin) throw new Error(`lark-cli profile ${binding.bot.lark_cli_profile} is unavailable`);
+  const logFile = path.join(RUN_LOG_DIR, `feishu-bridge-${safeId(binding.binding_id)}-${phase}.jsonl`);
+  const preparedExecutable = operations.resolveFeishuExecutable
+    ? await operations.resolveFeishuExecutable(environment)
+    : await packageExecutableLauncher.resolve(
+        FEISHU_PACKAGE,
+        'aamp-feishu-bridge',
+        {
+          env: environment,
+          executionLocation: metadata.executionLocation,
+          ...(metadata.executionLocation === 'remote' ? { logFile } : {}),
+        },
+      );
+  operations.throwIfStopping();
   return {
     binding,
     phase,
+    runtimeAgentType,
     larkCliBin: profile.lark_cli_bin,
-    logFile: path.join(RUN_LOG_DIR, `feishu-bridge-${safeId(binding.binding_id)}-${phase}.jsonl`),
+    logFile,
+    preparedExecutable,
   };
 }
 
 async function startPreparedFeishuProcess(prepared, target, environment = onlineEnvironment(prepared.binding)) {
   throwIfStopping();
-  const { binding, phase, larkCliBin, logFile } = prepared;
+  const {
+    binding,
+    phase,
+    runtimeAgentType,
+    larkCliBin,
+    logFile,
+    preparedExecutable,
+  } = prepared;
   const phaseMessage = phase === 'install'
     ? '正在建立绑定并启动飞书任务 Bridge'
     : phase === 'add'
       ? '正在验证飞书任务绑定'
       : '正在启动飞书任务 Bridge';
-  console.log(`[aamp-one-click] ${phaseMessage}：${bindingLabel(binding)}...`);
+  console.log(`[aamp-one-click] ${phaseMessage}：${bindingLabel(binding, runtimeAgentType)}...`);
   return startManagedProcess({
-    label: `Feishu Bridge ${bindingLabel(binding)}`,
+    label: `Feishu Bridge ${bindingLabel(binding, runtimeAgentType)}`,
     packageSpec: FEISHU_PACKAGE,
     executable: 'aamp-feishu-bridge',
     args: feishuArgs(binding, larkCliBin, target),
     env: environment,
     logFile,
+    preparedExecutable,
+    executionLocation: resolveTaskAgentMetadata(binding.agent_type).executionLocation,
+    eventPathRoot: binding.feishu_config_dir,
+    agentExecutionLocations: [[
+      binding.agent_type,
+      resolveTaskAgentMetadata(binding.agent_type).executionLocation,
+    ]],
+    allowedAppIds: [binding.bot.app_id],
   });
 }
 
@@ -1366,9 +2313,11 @@ async function waitForInitialBinding(record, pairingFile) {
 async function readInitialRuntimeMetadata(binding, record, expectedAgentEmail) {
   const starting = record.events.find((event) => event.type === 'bridge.task_runtime.starting' && event.appId === binding.bot.app_id);
   if (!starting?.imConfigDir || !starting?.taskConfigDir) throw new Error('Feishu Bridge 未返回实例配置目录');
-  const imFile = path.join(starting.imConfigDir, 'config.json');
-  const taskFile = path.join(starting.taskConfigDir, 'config.json');
-  if (!isPathInside(binding.feishu_config_dir, starting.imConfigDir) || !isPathInside(binding.feishu_config_dir, starting.taskConfigDir)) {
+  const imConfigDir = resolveRemoteEventPath(starting.imConfigDir, record, binding.feishu_config_dir);
+  const taskConfigDir = resolveRemoteEventPath(starting.taskConfigDir, record, binding.feishu_config_dir);
+  const imFile = path.join(imConfigDir, 'config.json');
+  const taskFile = path.join(taskConfigDir, 'config.json');
+  if (!isPathInside(binding.feishu_config_dir, imConfigDir) || !isPathInside(binding.feishu_config_dir, taskConfigDir)) {
     throw new Error('Feishu Bridge 返回了新流程 runtime-v1 之外的配置目录');
   }
   await assertNoSymlinkPath(RUNTIME_HOME, imFile);
@@ -1381,8 +2330,8 @@ async function readInitialRuntimeMetadata(binding, record, expectedAgentEmail) {
     throw new Error('Feishu Bridge 实例的 Bot App ID 与本次配对不一致');
   }
   return {
-    im_config_dir: starting.imConfigDir,
-    task_config_dir: starting.taskConfigDir,
+    im_config_dir: imConfigDir,
+    task_config_dir: taskConfigDir,
     feishu_bridge_email: imConfig.mailbox?.email || '',
   };
 }
@@ -1417,130 +2366,601 @@ async function validateSavedRuntime(binding) {
   }
 }
 
-async function bindOneDraft(draft, groups, mode) {
-  await setBindingStatus(draft, 'bind', 'starting');
-  throwIfStopping();
-  const { group, email } = resolveGroup(groups, draft);
-  const binding = { ...draft, state: 'ready', agent_target_email: email, updated_at: nowIso() };
-  const preparedFeishu = await prepareFeishuProcess(binding, mode);
-  throwIfStopping();
-  const pairResult = await runCapture(
-    ACP_PACKAGE,
-    'aamp-acp-bridge',
-    ['pair', '--agent', draft.agent_type, '--config', group.configFile, '--json', '--no-start'],
-    { logFile: group.logFile },
+const bindingStartOperations = Object.freeze({
+  // User-visible success output is deferred until layered results are back in selection order.
+  printBindingStarted: () => {},
+  readInitialRuntimeMetadata,
+  runCapture,
+  parseJsonDocument,
+  resolveConfiguredPendingPairingFile,
+  resolvePendingPairingFile,
+  setBindingStatus,
+  startPreparedFeishuUntilReady,
+  stopManagedProcess,
+  throwIfStopping,
+  updateBinding,
+  validateSavedRuntime,
+});
+
+const bindingPreparationOperations = Object.freeze({
+  nowIso,
+  prepareFeishuProcess,
+  resolveGroup,
+  resolveInitializedGroup,
+  setBindingStatus,
+  throwIfStopping,
+  validateSavedRuntime,
+});
+
+async function prepareBindingStart(
+  binding,
+  groups,
+  mode,
+  operations = bindingPreparationOperations,
+  options = {},
+) {
+  operations.throwIfStopping();
+  const pending = bindingNeedsInitialStart(binding);
+  await operations.setBindingStatus(binding, pending ? 'bind' : 'start', 'starting');
+  operations.throwIfStopping();
+  const resolve = options.allowAgentStarting && !pending
+    ? operations.resolveInitializedGroup
+    : operations.resolveGroup;
+  const { group, email, runtimeAgentType } = resolve(groups, binding);
+  const activeBinding = pending
+    ? { ...binding, state: 'ready', agent_target_email: email, updated_at: operations.nowIso() }
+    : binding;
+  if (!pending) {
+    if (email !== binding.agent_target_email) {
+      throw new Error('当前 Agent mailbox 与绑定记录不一致，请重新绑定');
+    }
+    await operations.validateSavedRuntime(binding);
+  }
+  operations.throwIfStopping();
+  const preparedFeishu = await operations.prepareFeishuProcess(
+    activeBinding,
+    mode,
+    runtimeAgentType,
+    options.profileProbes,
   );
-  throwIfStopping();
-  const pairing = parseJsonDocument(pairResult.stdout, 'ACP pairing');
-  if (!pairing.connectUrl || !pairing.pairingFile || pairing.mailbox !== email) {
-    throw new Error('ACP Bridge 返回的配对信息不完整或 mailbox 不一致');
+  return {
+    originalBinding: binding,
+    binding: activeBinding,
+    group,
+    mode,
+    pending,
+    email,
+    runtimeAgentType,
+    preparedFeishu,
+    deferReadyCommit: Boolean(options.deferReadyCommit && !pending),
+  };
+}
+
+async function executePreparedReadyBindingStart(prepared, operations = bindingStartOperations) {
+  const { binding, group, runtimeAgentType, preparedFeishu } = prepared;
+  let feishu;
+  try {
+    feishu = await operations.startPreparedFeishuUntilReady(
+      preparedFeishu,
+      { agentTargetEmail: binding.agent_target_email },
+      { stage: 'feishu-start' },
+    );
+    operations.throwIfStopping();
+    if (!prepared.deferReadyCommit) {
+      await operations.setBindingStatus(binding, 'start', 'running');
+      operations.throwIfStopping();
+      operations.printBindingStarted(binding, runtimeAgentType);
+    }
+    return { binding, process: feishu, group, runtimeAgentType };
+  } catch (error) {
+    if (feishu) await operations.stopManagedProcess(feishu);
+    throw error;
   }
+}
+
+async function executePreparedPendingBindingStart(prepared, operations = bindingStartOperations) {
+  const {
+    originalBinding,
+    binding,
+    group,
+    mode,
+    email,
+    runtimeAgentType,
+    preparedFeishu,
+  } = prepared;
   let feishu;
-  let keepRunning = false;
   try {
-    feishu = await startPreparedFeishuUntilReady(
+    const configuredPairingFile = await operations.resolveConfiguredPendingPairingFile(
+      group,
+      originalBinding.agent_type,
+    );
+    operations.throwIfStopping();
+    const pairResult = await operations.runCapture(
+      ACP_PACKAGE,
+      'aamp-acp-bridge',
+      ['pair', '--agent', originalBinding.agent_type, '--config', group.configFile, '--json', '--no-start'],
+      {
+        logFile: group.logFile,
+        executionLocation: resolveTaskAgentMetadata(originalBinding.agent_type).executionLocation,
+      },
+    );
+    operations.throwIfStopping();
+    const pairing = operations.parseJsonDocument(pairResult.stdout, 'ACP pairing');
+    if (!pairing.connectUrl || pairing.mailbox !== email) {
+      throw new Error('ACP Bridge 返回的配对信息不完整或 mailbox 不一致');
+    }
+    const pairingFile = await operations.resolvePendingPairingFile(
+      group,
+      originalBinding.agent_type,
+      pairing,
+    );
+    if (pairingFile !== configuredPairingFile) {
+      throw new Error('ACP Bridge 私有配对文件在配对过程中发生变化');
+    }
+    feishu = await operations.startPreparedFeishuUntilReady(
       preparedFeishu,
       { pairingUrl: pairing.connectUrl },
-      { stage: mode === 'install' ? 'feishu-install-bind' : 'feishu-add-bind', pairingFile: pairing.pairingFile },
+      { stage: mode === 'install' ? 'feishu-install-bind' : 'feishu-add-bind', pairingFile },
     );
-    throwIfStopping();
-    binding.runtime = await readInitialRuntimeMetadata(binding, feishu, email);
-    throwIfStopping();
-    await validateSavedRuntime(binding);
-    throwIfStopping();
-    const startsBridge = mode === 'install' || mode === 'start';
-    await setBindingStatus(binding, startsBridge ? 'start' : 'bind', startsBridge ? 'running' : 'succeeded');
-    throwIfStopping();
-    keepRunning = startsBridge;
-    return { binding, process: keepRunning ? feishu : undefined, group };
-  } finally {
-    if (!keepRunning) await stopManagedProcess(feishu);
+    operations.throwIfStopping();
+    binding.runtime = await operations.readInitialRuntimeMetadata(binding, feishu, email);
+    operations.throwIfStopping();
+    await operations.validateSavedRuntime(binding);
+    operations.throwIfStopping();
+    await operations.updateBinding(binding);
+    operations.throwIfStopping();
+    await operations.setBindingStatus(binding, 'start', 'running');
+    operations.throwIfStopping();
+    return { binding, process: feishu, group, runtimeAgentType };
+  } catch (error) {
+    if (feishu) await operations.stopManagedProcess(feishu);
+    throw error;
   }
 }
 
-async function startOneBinding(binding, groups) {
-  await setBindingStatus(binding, 'start', 'starting');
-  throwIfStopping();
-  const { email } = resolveGroup(groups, binding);
-  if (email !== binding.agent_target_email) throw new Error('当前 Agent mailbox 与绑定记录不一致，请重新绑定');
-  await validateSavedRuntime(binding);
-  throwIfStopping();
-  const preparedFeishu = await prepareFeishuProcess(binding, 'start');
-  const feishu = await startPreparedFeishuUntilReady(
-    preparedFeishu,
-    { agentTargetEmail: binding.agent_target_email },
-    { stage: 'feishu-start' },
-  );
-  throwIfStopping();
-  await setBindingStatus(binding, 'start', 'running');
-  throwIfStopping();
-  printBindingStarted(binding);
-  return feishu;
+async function executePreparedBindingStart(prepared, operations = bindingStartOperations) {
+  if (!prepared.pending) return executePreparedReadyBindingStart(prepared, operations);
+  return runPairingSerially(pairingQueueKey(prepared), async () => {
+    return executePreparedPendingBindingStart(prepared, operations);
+  });
 }
 
-async function startSelectedBindings(bindings, existingGroups) {
+async function runPreparedBindingStarts(preparedItems, start = executePreparedBindingStart) {
+  const lanes = [];
+  const pendingLanes = new Map();
+  for (const item of preparedItems) {
+    if (!item.prepared.pending) {
+      lanes.push([item]);
+      continue;
+    }
+    const key = pairingQueueKey(item.prepared);
+    let lane = pendingLanes.get(key);
+    if (!lane) {
+      lane = [];
+      pendingLanes.set(key, lane);
+      lanes.push(lane);
+    }
+    lane.push(item);
+  }
+
+  const laneOutcomes = await runLayeredStarts(lanes, {
+    concurrency: FEISHU_START_CONCURRENCY,
+    prepare: async (lane) => lane,
+    start: async (lane) => {
+      const outcomes = [];
+      for (const item of lane) {
+        try {
+          outcomes.push({
+            status: 'fulfilled',
+            phase: 'start',
+            value: await start(item.prepared),
+            item: item.prepared.originalBinding || item.prepared.binding,
+            index: item.index,
+          });
+        } catch (reason) {
+          if (stopRequested) throw reason;
+          outcomes.push({
+            status: 'rejected',
+            phase: 'start',
+            reason,
+            item: item.prepared.originalBinding || item.prepared.binding,
+            index: item.index,
+          });
+        }
+      }
+      return outcomes;
+    },
+  });
+  const rejectedLane = laneOutcomes.find((outcome) => outcome.status === 'rejected');
+  if (rejectedLane && stopRequested) throw rejectedLane.reason;
+  const byIndex = new Map(laneOutcomes.flatMap((outcome) => (
+    outcome.status === 'fulfilled' ? outcome.value : []
+  )).map((outcome) => [outcome.index, outcome]));
+  return preparedItems.map(({ index }) => byIndex.get(index));
+}
+
+function reportBindingFailure(binding, runtimeAgentType, reason, mode) {
+  const safeReason = safeBindingFailureReason(binding, reason);
+  console.error(`🔴 启动失败：${bindingLabel(binding, runtimeAgentType)}\n   原因：${safeReason}`);
+  if (mode === 'install') {
+    console.error('   绑定配置已保存，可稍后运行 feishu-task-agent start 重试。');
+  } else {
+    console.error('   已跳过该项，继续启动下一项。');
+  }
+}
+
+const bindingLauncherOperations = Object.freeze({
+  bindingCancellationReason,
+  executePreparedBindingStart,
+  prepareBindingStart: (binding, groups, mode, options) => (
+    prepareBindingStart(binding, groups, mode, bindingPreparationOperations, options)
+  ),
+  printBindingCancelled,
+  printBindingStarted,
+  recordError,
+  reportBindingFailure,
+  setBindingStatus,
+  throwIfStopping,
+});
+
+async function finalizeDeferredLaunchResults(launched, mode, operations = bindingLauncherOperations) {
+  for (const item of launched.cancelled) {
+    await operations.setBindingStatus(
+      item.binding,
+      mode === 'install' ? 'bind' : 'start',
+      'cancelled',
+      item.reason,
+    );
+    operations.printBindingCancelled(item.binding, item.reason);
+  }
+  for (const item of launched.failed) {
+    await operations.setBindingStatus(item.binding, 'start', 'failed', item.reason);
+    await operations.recordError('startup', item.reason, item.binding);
+    operations.reportBindingFailure(
+      item.binding,
+      item.runtimeAgentType,
+      item.reason,
+      mode,
+    );
+  }
+}
+
+async function startBindingsWithGroups(
+  bindings,
+  groups,
+  mode,
+  operations = bindingLauncherOperations,
+  options = {},
+) {
+  const cancelled = [];
+  const candidates = [];
+  for (const binding of bindings) {
+    operations.throwIfStopping();
+    const reason = operations.bindingCancellationReason(groups, binding);
+    if (reason) {
+      const runtimeAgentType = groups.get(binding.aamp_host)?.runtimeAgentTypes?.get(binding.agent_type)
+        || binding.agent_type;
+      cancelled.push({ binding, reason, runtimeAgentType });
+    } else {
+      candidates.push(binding);
+    }
+  }
+
+  const outcomes = new Array(candidates.length);
+  const preparedItems = [];
+  for (let index = 0; index < candidates.length; index += 1) {
+    const binding = candidates[index];
+    try {
+      preparedItems.push({
+        index,
+        prepared: await operations.prepareBindingStart(binding, groups, mode, options),
+      });
+    } catch (reason) {
+      if (stopRequested) throw reason;
+      outcomes[index] = { status: 'rejected', phase: 'prepare', reason, item: binding, index };
+    }
+  }
+  const started = await runPreparedBindingStarts(preparedItems, (prepared) => {
+    operations.throwIfStopping();
+    return operations.executePreparedBindingStart(prepared);
+  });
+  started.forEach((outcome, preparedIndex) => {
+    outcomes[preparedItems[preparedIndex].index] = outcome;
+  });
+  operations.throwIfStopping();
+
   const running = [];
   const failed = [];
+  for (const outcome of outcomes) {
+    if (outcome.status === 'fulfilled') {
+      running.push(outcome.value);
+      if (mode === 'start' && !options.deferReadyCommit) {
+        operations.printBindingStarted(outcome.value.binding, outcome.value.runtimeAgentType);
+      }
+      continue;
+    }
+    const binding = outcome.item;
+    const reason = safeBindingFailureReason(binding, outcome.reason?.message || outcome.reason);
+    const runtimeAgentType = groups.get(binding.aamp_host)?.runtimeAgentTypes?.get(binding.agent_type)
+      || binding.agent_type;
+    failed.push({ binding, reason, runtimeAgentType });
+  }
+  const launched = {
+    running: orderStartupItems(bindings, running),
+    failed: orderStartupItems(bindings, failed),
+    cancelled: orderStartupItems(bindings, cancelled),
+  };
+  if (!options.deferReadyCommit) {
+    await finalizeDeferredLaunchResults(launched, mode, operations);
+  }
+  return launched;
+}
+
+async function stopRunningBindings(running) {
+  for (const item of [...running].reverse()) {
+    if (item.process && !item.process.exited) await stopManagedProcess(item.process);
+  }
+}
+
+const overlappedReadyReconcileOperations = Object.freeze({
+  printBindingCancelled,
+  printBindingStarted,
+  recordError,
+  reportBindingFailure,
+  setBindingStatus,
+  stopManagedProcess,
+  throwIfStopping,
+});
+
+async function reconcileOverlappedReadyBindings(
+  bindings,
+  launched,
+  groups,
+  operations = overlappedReadyReconcileOperations,
+) {
+  const alive = [];
+  const failed = [];
+  const cancelled = [];
+  const outcomes = orderStartupItems(bindings, [
+    ...launched.running.map((item) => ({ ...item, launchStatus: 'running' })),
+    ...launched.failed.map((item) => ({ ...item, launchStatus: 'failed' })),
+    ...launched.cancelled.map((item) => ({ ...item, launchStatus: 'cancelled' })),
+  ]);
+  for (const item of outcomes) {
+    operations.throwIfStopping();
+    const { binding, process: feishu } = item;
+    const group = item.group || groups.get(binding.aamp_host);
+    const runtimeAgentType = item.runtimeAgentType
+      || group?.runtimeAgentTypes?.get(binding.agent_type)
+      || binding.agent_type;
+    const cancellation = group?.cancellations?.get(binding.agent_type) || '';
+    if (cancellation) {
+      if (feishu && !feishu.exited) await operations.stopManagedProcess(feishu);
+      await operations.setBindingStatus(binding, 'start', 'cancelled', cancellation);
+      operations.printBindingCancelled(binding, cancellation);
+      cancelled.push({ binding, reason: cancellation, runtimeAgentType });
+      continue;
+    }
+
+    let reason = group?.failures?.get(binding.agent_type) || '';
+    if (!reason && (!group?.process || group.process.exited)) {
+      reason = `${bindingLabel(binding, runtimeAgentType)} 的 Agent Bridge 在启动期间已退出：${group?.host || binding.aamp_host}`;
+    }
+    if (!reason && !group.availableAgents?.has(binding.agent_type)) {
+      reason = `${binding.agent_type} Agent Bridge 未启动`;
+    }
+    if (!reason && item.launchStatus === 'failed') {
+      reason = item.reason;
+    }
+    if (!reason && item.launchStatus === 'running' && (!feishu || feishu.exited)) {
+      reason = `${bindingLabel(binding, runtimeAgentType)} 的 Feishu Bridge 在进入监督前已退出 (${feishu?.exit?.signal || feishu?.exit?.code || 'unknown'})`;
+    }
+    if (reason) {
+      const redactedReason = safeBindingFailureReason(binding, reason);
+      if (feishu && !feishu.exited) await operations.stopManagedProcess(feishu);
+      await operations.setBindingStatus(binding, 'start', 'failed', redactedReason);
+      await operations.recordError('startup', redactedReason, binding);
+      operations.reportBindingFailure(binding, runtimeAgentType, redactedReason, 'start');
+      failed.push({ binding, reason: redactedReason, runtimeAgentType });
+      continue;
+    }
+    if (item.launchStatus === 'cancelled') {
+      const launchCancellation = redact(item.reason);
+      await operations.setBindingStatus(binding, 'start', 'cancelled', launchCancellation);
+      operations.printBindingCancelled(binding, launchCancellation);
+      cancelled.push({ binding, reason: launchCancellation, runtimeAgentType });
+      continue;
+    }
+
+    await operations.setBindingStatus(binding, 'start', 'running');
+    operations.throwIfStopping();
+    operations.printBindingStarted(binding, runtimeAgentType);
+    alive.push(item);
+  }
+  return { alive, failed, cancelled };
+}
+
+async function runOverlappedStartup(bindings, groups, operations, profileProbes) {
+  const readyBindings = bindings.filter((binding) => !bindingNeedsInitialStart(binding));
+  const pendingBindings = bindings.filter((binding) => bindingNeedsInitialStart(binding));
+  const emptyLaunch = { running: [], failed: [], cancelled: [] };
+  const agentBranch = Promise.resolve().then(() => operations.startAgentGroups(groups));
+  const readyBranch = readyBindings.length
+    ? Promise.resolve().then(() => operations.startBindingsWithGroups(
+        readyBindings,
+        groups,
+        'start',
+        { allowAgentStarting: true, deferReadyCommit: true, profileProbes },
+      ))
+    : Promise.resolve(emptyLaunch);
+
+  const [agentOutcome, readyOutcome] = await Promise.allSettled([agentBranch, readyBranch]);
+  const earlyRunning = readyOutcome.status === 'fulfilled' ? readyOutcome.value.running : [];
+  if (agentOutcome.status === 'rejected' || readyOutcome.status === 'rejected') {
+    await operations.stopRunningBindings(earlyRunning);
+    operations.throwIfStopping();
+    throw (agentOutcome.status === 'rejected' ? agentOutcome.reason : readyOutcome.reason);
+  }
+  operations.throwIfStopping();
+
+  const reconciledReady = await operations.reconcileOverlappedReadyBindings(
+    readyBindings,
+    readyOutcome.value,
+    groups,
+  );
+  operations.throwIfStopping();
+  const pendingLaunch = pendingBindings.length
+    ? await operations.startBindingsWithGroups(pendingBindings, groups, 'start')
+    : emptyLaunch;
+  operations.throwIfStopping();
+
+  return {
+    running: orderStartupItems(bindings, [
+      ...reconciledReady.alive,
+      ...pendingLaunch.running,
+    ]),
+    failed: orderStartupItems(bindings, [
+      ...reconciledReady.failed,
+      ...pendingLaunch.failed,
+    ]),
+    cancelled: orderStartupItems(bindings, [
+      ...reconciledReady.cancelled,
+      ...pendingLaunch.cancelled,
+    ]),
+  };
+}
+
+function startupDisposition({ running = [], failed = [], cancelled = [] }, extraFailureCount = 0) {
+  if (running.length) return 'supervise';
+  if (cancelled.length && !failed.length && extraFailureCount === 0) return 'only-cancel';
+  return 'all-failed';
+}
+
+async function reconcileStartupResults(
+  bindings,
+  launched,
+  validationFailures = [],
+  reconcile = reconcileRetainedBindings,
+) {
+  const reconciled = await reconcile(launched.running);
+  const result = {
+    running: orderStartupItems(bindings, reconciled.alive),
+    failed: orderStartupItems(bindings, [
+      ...validationFailures,
+      ...launched.failed,
+      ...reconciled.failed,
+    ]),
+    cancelled: orderStartupItems(bindings, launched.cancelled),
+  };
+  return { ...result, disposition: startupDisposition(result) };
+}
+
+async function recordOnlineValidationFailure(binding, error) {
+  const reason = safeBindingFailureReason(binding, error.message || error);
+  await setBindingStatus(binding, 'start', 'failed', reason);
+  await recordError('startup', reason, binding);
+  console.error(`\n🔴 启动失败：${bindingLabel(binding)}\n   原因：${reason}`);
+  console.error('   已跳过该项，继续启动下一项。');
+  return { binding, reason };
+}
+
+function startBindingsForOverlap(bindings, groups, mode, options) {
+  return startBindingsWithGroups(bindings, groups, mode, bindingLauncherOperations, options);
+}
+
+const startupOrchestrationOperations = Object.freeze({
+  finalizeDeferredLaunchResults: (launched) => finalizeDeferredLaunchResults(launched, 'start'),
+  initializeAgentGroups,
+  prewarmFeishuExecutable,
+  probeReadyBindingProfiles,
+  reconcileRetainedBindings,
+  reconcileOverlappedReadyBindings,
+  recordValidationFailure: recordOnlineValidationFailure,
+  startAgentGroups,
+  startBindingsWithGroups: startBindingsForOverlap,
+  stopRunningBindings,
+  throwIfStopping,
+  validateBinding: assertOnlineBinding,
+});
+
+async function orchestrateStartupBindings(
+  bindings,
+  existingGroups,
+  operations = startupOrchestrationOperations,
+) {
+  const validationFailures = [];
   const onlineBindings = [];
   for (const binding of bindings) {
     try {
-      assertOnlineBinding(binding);
+      operations.validateBinding(binding);
       onlineBindings.push(binding);
     } catch (error) {
-      const reason = redact(error.message || error);
-      failed.push({ binding, reason });
-      await setBindingStatus(binding, 'start', 'failed', reason);
-      await recordError('startup', reason, binding);
-      console.error(`\n🔴 启动失败：${bindingLabel(binding)}\n   原因：${reason}`);
-      console.error('   已跳过该项，继续启动下一项。');
+      validationFailures.push(await operations.recordValidationFailure(binding, error));
     }
   }
-  const groups = existingGroups || await setupAgentGroups(onlineBindings);
-  for (const binding of onlineBindings) {
-    throwIfStopping();
+  if (onlineBindings.length && operations.prewarmFeishuExecutable) {
     try {
-      let activeBinding = binding;
-      let group = groups.get(binding.aamp_host);
-      let processRecord;
-      if (bindingNeedsInitialStart(binding)) {
-        const paired = await bindOneDraft(binding, groups, 'start');
-        if (!paired.process) throw new Error('首次启动完成配对后未获得可监督的 Feishu Bridge 进程');
-        try {
-          await updateBinding(paired.binding);
-        } catch (error) {
-          await stopManagedProcess(paired.process);
-          throw error;
-        }
-        activeBinding = paired.binding;
-        group = paired.group;
-        processRecord = paired.process;
-        printBindingStarted(activeBinding);
-      } else {
-        processRecord = await startOneBinding(binding, groups);
-      }
-      throwIfStopping();
-      running.push({ binding: activeBinding, process: processRecord, group });
-    } catch (error) {
-      if (stopRequested) throw error;
-      const reason = redact(error.message || error);
-      failed.push({ binding, reason });
-      await setBindingStatus(binding, 'start', 'failed', reason);
-      await recordError('startup', reason, binding);
-      console.error(`\n🔴 启动失败：${bindingLabel(binding)}\n   原因：${reason}`);
-      console.error('   已跳过该项，继续启动下一项。');
+      void Promise.resolve(operations.prewarmFeishuExecutable(onlineBindings[0])).catch(() => {});
+    } catch {
+      // This is speculative only. Binding preparation performs the authoritative resolve.
     }
   }
-  const reconciled = await reconcileRetainedBindings(running);
-  running.splice(0, running.length, ...reconciled.alive);
-  failed.push(...reconciled.failed);
-  if (!running.length) {
-    await shutdownGroups(groups);
-    throw new Error('全部配置启动失败');
+  let groups = existingGroups;
+  let profileProbes;
+  if (!groups) {
+    const initialization = Promise.resolve().then(() => operations.initializeAgentGroups(onlineBindings));
+    const probing = operations.probeReadyBindingProfiles
+      ? Promise.resolve().then(() => operations.probeReadyBindingProfiles(onlineBindings))
+      : Promise.resolve(new Map());
+    const [initializationOutcome, probingOutcome] = await Promise.allSettled([
+      initialization,
+      probing,
+    ]);
+    operations.throwIfStopping();
+    if (initializationOutcome.status === 'rejected') throw initializationOutcome.reason;
+    groups = initializationOutcome.value;
+    profileProbes = probingOutcome.status === 'fulfilled' ? probingOutcome.value : new Map();
+  }
+  const launched = existingGroups
+    ? await operations.startBindingsWithGroups(onlineBindings, groups, 'start')
+    : await runOverlappedStartup(onlineBindings, groups, operations, profileProbes);
+  const result = await reconcileStartupResults(
+    bindings,
+    launched,
+    validationFailures,
+    operations.reconcileRetainedBindings,
+  );
+  return { groups, ...result };
+}
+
+async function dispatchStartupResult(result, operations) {
+  const disposition = startupDisposition(result, operations.extraFailureCount || 0);
+  if (disposition === 'supervise') {
+    return operations.supervise(result.running, result.groups);
   }
-  console.log(`\n已成功启动 ${running.length}/${bindings.length} 个配置。`);
-  console.log('🟢 保持终端打开，你可以给 agent 派发飞书任务');
-  if (failed.length) console.log(`另有 ${failed.length} 个配置启动失败，详情见上方信息和本地日志。`);
-  await supervise(running, groups);
+  await operations.shutdown(result.groups);
+  if (disposition === 'only-cancel') return operations.onlyCancelled();
+  return operations.allFailed();
+}
+
+async function startSelectedBindings(bindings, existingGroups) {
+  const result = await orchestrateStartupBindings(bindings, existingGroups);
+  printStartupSummary({
+    title: '已成功启动',
+    plannedCount: bindings.length,
+    running: result.running,
+    failed: result.failed,
+    cancelled: result.cancelled,
+  });
+  await dispatchStartupResult(result, {
+    supervise: async (running, groups) => {
+      console.log('🟢 保持终端打开，你可以给 agent 派发飞书任务');
+      await supervise(running, groups);
+    },
+    shutdown: shutdownGroups,
+    onlyCancelled: async () => {},
+    allFailed: async () => { throw new Error('全部配置启动失败'); },
+  });
 }
 
 async function markRuntimeFailed(binding, reason, component) {
@@ -1560,12 +2980,12 @@ async function reconcileRetainedBindings(running) {
       continue;
     }
     const reason = !feishuAlive
-      ? `${bindingLabel(item.binding)} 的 Feishu Bridge 在进入监督前已退出 (${item.process?.exit?.signal || item.process?.exit?.code || 'unknown'})`
-      : `${bindingLabel(item.binding)} 的 Agent Bridge 在进入监督前已退出：${item.group?.host || item.binding.aamp_host}`;
+      ? `${bindingLabel(item.binding, item.runtimeAgentType)} 的 Feishu Bridge 在进入监督前已退出 (${item.process?.exit?.signal || item.process?.exit?.code || 'unknown'})`
+      : `${bindingLabel(item.binding, item.runtimeAgentType)} 的 Agent Bridge 在进入监督前已退出：${item.group?.host || item.binding.aamp_host}`;
     if (feishuAlive) await stopManagedProcess(item.process);
     await markRuntimeFailed(item.binding, reason, 'startup');
-    failed.push({ binding: item.binding, reason });
-    console.error(`\n🔴 启动失败：${bindingLabel(item.binding)}\n   原因：${reason}`);
+    failed.push({ binding: item.binding, reason, runtimeAgentType: item.runtimeAgentType });
+    console.error(`\n🔴 启动失败：${bindingLabel(item.binding, item.runtimeAgentType)}\n   原因：${reason}`);
   }
   return { alive, failed };
 }
@@ -1609,23 +3029,27 @@ async function shutdownGroups(groups) {
   }
 }
 
-async function cleanupAll() {
-  if (cleanupPromise) return cleanupPromise;
-  cleanupPromise = (async () => {
-    while (managedProcesses.size || transientProcesses.size || heldLeases.size) {
-      const records = [...managedProcesses].reverse();
-      for (const record of records) {
-        managedProcesses.delete(record);
-        await stopManagedProcess(record).catch(() => {});
-      }
-      for (const record of [...transientProcesses].reverse()) {
-        transientProcesses.delete(record);
-        await stopManagedProcess(record).catch(() => {});
-      }
-      for (const lease of [...heldLeases]) await releaseLease(lease).catch(() => {});
+const cleanupRuntimeResources = createResourceCleanup(async () => {
+  while (managedProcesses.size || transientProcesses.size || heldLeases.size) {
+    const records = [...managedProcesses].reverse();
+    for (const record of records) {
+      managedProcesses.delete(record);
+      await stopManagedProcess(record).catch(() => {});
     }
-  })();
-  return cleanupPromise;
+    for (const record of [...transientProcesses].reverse()) {
+      transientProcesses.delete(record);
+      await stopManagedProcess(record).catch(() => {});
+    }
+    for (const lease of [...heldLeases]) await releaseLease(lease).catch(() => {});
+  }
+});
+
+async function cleanupAll() {
+  await cleanupRuntimeResources();
+  await Promise.allSettled([
+    (async () => await manifestWriter.flush())(),
+    (async () => await errorLogWriter.flush())(),
+  ]);
 }
 
 function printLogHints(detailed = false) {
@@ -1644,7 +3068,7 @@ function displayBindings(bindings) {
   }
   const rows = bindings.map((binding, index) => ({
     index: String(index + 1),
-    agent: binding.agent_type,
+    agent: agentBindingDisplayName(binding.agent_type),
     bot: binding.bot.display_name || binding.bot.app_id,
     appId: binding.bot.app_id,
     environment: binding.environment.name,
@@ -1662,22 +3086,26 @@ function displayBindings(bindings) {
 
 async function discoverAgents() {
   const result = await runBootstrapHelper('__discover-agents', '');
-  const agents = (result.agents || []).filter((agent) => AGENT_TYPES.includes(agent));
-  if (!agents.length) throw new Error('暂未检测到本地智能体。请先安装并登录 Codex 或 Cursor CLI 后重试。');
+  const agents = (result.agents || []).filter((agent) => TASK_AGENT_TYPES.includes(agent));
+  if (!agents.length) {
+    throw new Error('暂未检测到智能体。请先安装 Codex、Cursor、Trae CLI、TraeCode CLI、WorkBuddy 或 WorkBuddy AI，或连接公司内网使用 AIME。');
+  }
   return agents;
 }
 
-async function createDraft(agents, unavailableAppIds) {
-  const agent = DEFAULT_AGENT || await chooseOne('请选择要绑定的本地智能体：', agents, (item) => item);
+async function createDraft(agents, selectedAppIds) {
+  const agent = DEFAULT_AGENT || await chooseOne('请选择要绑定的智能体：', agents, agentSelectionDisplayName);
   const registered = await runBootstrapHelper('__register-binding', agent);
   addSecret(registered.app_secret);
-  if (!registered.app_id || !registered.app_secret || !registered.lark_cli_profile) {
+  const metadata = resolveTaskAgentMetadata(agent);
+  if (!registered.app_id || !registered.app_secret
+    || (metadata.executionLocation === 'local' && !registered.lark_cli_profile)) {
     throw new Error('飞书应用授权结果不完整');
   }
-  if (unavailableAppIds.has(registered.app_id)) {
+  if (selectedAppIds.has(registered.app_id)) {
     throw new Error(`Bot ${registered.app_id} 已经选择过，不能重复绑定`);
   }
-  unavailableAppIds.add(registered.app_id);
+  selectedAppIds.add(registered.app_id);
   const bindingId = randomId();
   const timestamp = nowIso();
   return {
@@ -1687,7 +3115,7 @@ async function createDraft(agents, unavailableAppIds) {
       app_id: registered.app_id,
       app_secret: registered.app_secret,
       display_name: registered.display_name || registered.app_id,
-      lark_cli_profile: registered.lark_cli_profile,
+      ...(metadata.executionLocation === 'local' ? { lark_cli_profile: registered.lark_cli_profile } : {}),
     },
     environment: { name: 'online' },
     state: 'pending',
@@ -1701,24 +3129,55 @@ async function createDraft(agents, unavailableAppIds) {
 async function runBindingSession(mode) {
   const store = await loadStore();
   throwIfStopping();
-  const unavailableAppIds = new Set(mode === 'add' ? store.bindings.map((binding) => binding.bot.app_id) : []);
+  const existingByAppId = new Map(store.bindings.map((binding) => [binding.bot.app_id, binding]));
+  const selectedAppIds = new Set();
   const agents = DEFAULT_AGENT ? [DEFAULT_AGENT] : await discoverAgents();
   throwIfStopping();
-  const sessionDrafts = [];
+  const bindingIntents = [];
+  const acceptedBindings = [];
+  const selectedBindings = [];
   const succeeded = [];
   const failed = [];
+  const cancelled = [];
   const selectionFailures = [];
   const running = [];
+  let selectedCount = 0;
 
   console.log('\n=== 选择绑定配置 ===');
   let keepGoing = true;
   while (keepGoing) {
     throwIfStopping();
     try {
-      const draft = await createDraft(agents, unavailableAppIds);
+      const draft = await createDraft(agents, selectedAppIds);
       throwIfStopping();
-      sessionDrafts.push(draft);
-      console.log(`已选择：${bindingLabel(draft)}`);
+      selectedCount += 1;
+      const existing = existingByAppId.get(draft.bot.app_id);
+      let accepted = true;
+      let acceptedBinding = draft;
+      if (existing && sameBindingRelationship(existing, draft)) {
+        acceptedBinding = existing;
+      } else if (existing) {
+        console.log(`Bot ${draft.bot.app_id} 已存在绑定：${bindingLabel(existing)}`);
+        console.log(`拟替换为：${bindingLabel(draft)}`);
+        if (!await confirm('是否替换绑定？', false)) {
+          accepted = false;
+          const reason = '用户取消替换已有绑定';
+          cancelled.push({ binding: draft, reason });
+          await setBindingStatus(draft, 'bind', 'cancelled', reason);
+          printBindingCancelled(draft, reason);
+        }
+      }
+      selectedBindings.push(accepted ? acceptedBinding : draft);
+      if (accepted) {
+        acceptedBindings.push(acceptedBinding);
+        if (acceptedBinding === draft) {
+          bindingIntents.push({
+            binding: draft,
+            expected: existing ? bindingExpectation(existing) : undefined,
+          });
+        }
+        console.log(`已选择：${bindingLabel(acceptedBinding)}`);
+      }
     } catch (error) {
       if (stopRequested) throw error;
       const reason = redact(error.message || error);
@@ -1727,97 +3186,147 @@ async function runBindingSession(mode) {
       console.error(`🔴 本次选择未完成：${reason}`);
     }
     throwIfStopping();
-    keepGoing = await confirm('是否继续选择本地智能体和 Bot？', false);
+    keepGoing = await confirm('是否继续选择智能体和 Bot？', false);
     throwIfStopping();
   }
 
-  if (!sessionDrafts.length) {
-    return { groups: new Map(), succeeded, failed, selectionFailures, running, selectedCount: 0 };
+  if (!acceptedBindings.length) {
+    return {
+      groups: new Map(),
+      saved: [],
+      acceptedBindings,
+      selectedBindings,
+      succeeded,
+      failed,
+      cancelled,
+      selectionFailures,
+      running,
+      selectedCount,
+      replacedCount: 0,
+    };
   }
 
-  if (mode === 'add') {
+  let persisted = { bindings: [], replacedCount: 0 };
+  if (bindingIntents.length) {
     console.log('\n=== 保存绑定配置 ===');
-    for (const draft of sessionDrafts) {
-      try {
-        await appendBinding(draft);
-        throwIfStopping();
-        succeeded.push(draft);
-        await setBindingStatus(draft, 'bind', 'saved');
-        console.log(`🟢 已保存：${bindingLabel(draft)}`);
-      } catch (error) {
-        if (stopRequested) throw error;
-        const reason = redact(error.message || error);
-        failed.push({ binding: draft, reason });
-        await setBindingStatus(draft, 'bind', 'failed', reason);
-        await recordError('binding', reason, draft);
-        console.error(`🔴 配置保存失败：${bindingLabel(draft)}\n   原因：${reason}`);
-        console.error('   已跳过该项，继续处理下一项。');
-      }
+    persisted = await upsertBindings(bindingIntents);
+    for (const binding of persisted.bindings) {
+      await setBindingStatus(binding, 'bind', 'saved');
+      console.log(`已保存：${bindingLabel(binding)}`);
     }
-    return { groups: new Map(), succeeded, failed, selectionFailures, running, selectedCount: sessionDrafts.length };
+  }
+  const saved = persisted.bindings;
+
+  if (mode === 'add') {
+    succeeded.push(...acceptedBindings);
+    return {
+      groups: new Map(),
+      saved,
+      acceptedBindings,
+      selectedBindings,
+      succeeded,
+      failed,
+      cancelled,
+      selectionFailures,
+      running,
+      selectedCount,
+      replacedCount: persisted.replacedCount,
+    };
   }
 
   console.log('\n=== 建立绑定并启动 ===');
   throwIfStopping();
-  const groups = await setupAgentGroups(sessionDrafts);
+  const groups = await setupAgentGroups(acceptedBindings);
   throwIfStopping();
-  for (const draft of sessionDrafts) {
-    throwIfStopping();
-    try {
-      const paired = await bindOneDraft(draft, groups, mode);
-      throwIfStopping();
-      if (mode === 'install' && !paired.process) throw new Error('完成绑定后未获得可监督的 Feishu Bridge 进程');
-      succeeded.push(paired.binding);
-      if (mode === 'install') {
-        running.push({ binding: paired.binding, process: paired.process, group: paired.group });
-      }
-    } catch (error) {
-      if (stopRequested) throw error;
-      const reason = redact(error.message || error);
-      failed.push({ binding: draft, reason });
-      await setBindingStatus(draft, 'bind', 'failed', reason);
-      await recordError('binding', reason, draft);
-      console.error(`🔴 绑定失败：${bindingLabel(draft)}\n   原因：${reason}`);
-      console.error('   已跳过该项，继续处理下一项。');
-    }
-  }
-  return { groups, succeeded, failed, selectionFailures, running, selectedCount: sessionDrafts.length };
+  const launched = await startBindingsWithGroups(acceptedBindings, groups, mode);
+  running.push(...launched.running);
+  succeeded.push(...launched.running.map(({ binding }) => binding));
+  failed.push(...launched.failed);
+  cancelled.push(...launched.cancelled);
+  return {
+    groups,
+    saved,
+    acceptedBindings,
+    selectedBindings,
+    succeeded,
+    failed,
+    cancelled,
+    selectionFailures,
+    running,
+    selectedCount,
+    replacedCount: persisted.replacedCount,
+  };
 }
 
 async function runInstall() {
   const result = await withMutationLock('install 绑定流程', async () => {
     const bound = await runBindingSession('install');
     throwIfStopping();
-    if (!bound.succeeded.length) {
-      await shutdownGroups(bound.groups);
-      throw new Error('没有配置完成绑定，现有新流程配置保持不变');
-    }
-    const reconciled = await reconcileRetainedBindings(bound.running);
-    throwIfStopping();
-    bound.running = reconciled.alive;
-    bound.runtimeFailures = reconciled.failed;
-    await replaceBindings(bound.succeeded);
+    const composed = await reconcileStartupResults(bound.selectedBindings, {
+      running: bound.running,
+      failed: bound.failed,
+      cancelled: bound.cancelled,
+    });
     throwIfStopping();
-    if (!bound.running.length) {
-      await shutdownGroups(bound.groups);
-      throw new Error(`全部已绑定配置启动失败；${bound.succeeded.length} 个真实配对配置已写入 ${CONFIG_FILE}`);
-    }
+    bound.running = composed.running;
+    bound.failed = composed.failed;
+    bound.cancelled = composed.cancelled;
+    bound.disposition = composed.disposition;
     return bound;
   });
-  console.log(`\n已成功建立绑定并启动 ${result.running.length}/${result.selectedCount} 个配置。`);
-  console.log('🟢 保持终端打开，你可以给 agent 派发飞书任务');
-  const failureCount = result.failed.length + result.selectionFailures.length + result.runtimeFailures.length;
-  if (failureCount) console.log(`另有 ${failureCount} 次选择或绑定失败，详情见上方信息和本地日志。`);
-  await supervise(result.running, result.groups);
+
+  if (!result.acceptedBindings.length) {
+    if (result.cancelled.length && !result.selectionFailures.length) {
+      printStartupSummary({
+        title: '已成功建立绑定并启动',
+        plannedCount: result.selectedCount,
+        running: [],
+        failed: [],
+        cancelled: result.cancelled,
+      });
+      return;
+    }
+    throw new Error('没有配置完成绑定，现有配置保持不变');
+  }
+  printStartupSummary({
+    title: '已成功建立绑定并启动',
+    plannedCount: result.selectedCount,
+    running: result.running,
+    failed: result.failed,
+    cancelled: result.cancelled,
+  });
+  await dispatchStartupResult(result, {
+    extraFailureCount: result.selectionFailures.length,
+    supervise: async (running, groups) => {
+      console.log('🟢 保持终端打开，你可以给 agent 派发飞书任务');
+      if (result.selectionFailures.length) {
+        console.log(`另有 ${result.selectionFailures.length} 次选择未完成，详情见上方信息和本地日志。`);
+      }
+      await supervise(running, groups);
+    },
+    shutdown: shutdownGroups,
+    onlyCancelled: async () => {},
+    allFailed: async () => {
+      throw new Error(`全部配置启动失败；${result.acceptedBindings.length} 个绑定配置已保存，可稍后运行 feishu-task-agent start 重试`);
+    },
+  });
 }
 
 async function runAdd() {
-  await withMutationLock('add 绑定流程', async () => {
-    const bound = await runBindingSession('add');
-    if (!bound.succeeded.length) throw new Error('没有配置完成绑定');
-    return bound;
+  const result = await withMutationLock('add 绑定流程', async () => {
+    return runBindingSession('add');
   });
-  console.log('配置添加成功，运行feishu-task-agent start启动时生效');
+  if (!result.acceptedBindings.length) {
+    if (result.cancelled.length && !result.selectionFailures.length) {
+      console.log(`已取消 ${result.cancelled.length} 个配置的绑定；现有配置保持不变。`);
+      return;
+    }
+    throw new Error('没有配置完成绑定');
+  }
+  if (result.replacedCount > 0 && await hasActiveAgentLease()) {
+    console.log('当前已运行的 Bridge 不受影响；替换将在下一次 feishu-task-agent start 时生效。');
+  }
+  console.log('配置添加成功，运行 feishu-task-agent start 启动时生效');
 }
 
 async function runList() {
@@ -1892,26 +3401,80 @@ for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
     if (stopRequested) return;
     stopRequested = true;
     stopSignal = signal;
-    if (terminal?.input?.isRaw) terminal.input.setRawMode(false);
-    terminal?.output?.write('\x1b[?25h');
-    void cleanupAll().finally(() => {
-      console.log(`\n已收到 ${signal}，本次启动的 Bridge 已停止。`);
-      process.exit(0);
-    });
+    const interruptedPrompt = promptInterrupter.interrupt(new Error(`已收到 ${signal}`));
+    if (!interruptedPrompt) {
+      if (terminal?.input?.isRaw) terminal.input.setRawMode(false);
+      terminal?.output?.write('\x1b[?25h');
+    }
+    void cleanupAll().catch(() => {});
   });
 }
 
-main()
-  .catch(async (error) => {
-    if (!stopRequested) {
-      const reason = redact(error?.message || error);
-      await recordError('controller', reason).catch(() => {});
-      console.error(`\n🔴 运行失败：${reason}`);
-      printLogHints(true);
-      process.exitCode = 1;
-    }
-  })
-  .finally(async () => {
-    await cleanupAll();
-    if (stopRequested && stopSignal) console.log(`\n已收到 ${stopSignal}，本次启动的 Bridge 已停止。`);
-  });
+let isMainModule = false;
+if (process.argv[1]) {
+  try {
+    isMainModule = fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    isMainModule = path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  }
+}
+
+if (isMainModule) {
+  main()
+    .catch(async (error) => {
+      if (!stopRequested) {
+        const reason = redact(error?.message || error);
+        await recordError('controller', reason).catch(() => {});
+        console.error(`\n🔴 运行失败：${reason}`);
+        printLogHints(true);
+        process.exitCode = 1;
+      }
+    })
+    .finally(async () => {
+      await cleanupAll();
+      if (stopRequested && stopSignal) console.log(`\n已收到 ${stopSignal}，本次启动的 Bridge 已停止。`);
+    });
+}
+
+export {
+  bindingExpectation,
+  acpBridgeAgentPolicy,
+  commitPreparedAgentBindings,
+  createPromptInterrupter,
+  createResourceCleanup,
+  dispatchStartupResult,
+  executePreparedBindingStart,
+  executePreparedPendingBindingStart,
+  executePreparedReadyBindingStart,
+  installHasOnlyCancellations,
+  initializeAgentGroups,
+  orderStartupItems,
+  prepareBindingStart,
+  prepareFeishuProcess,
+  readInitialRuntimeMetadata,
+  resolveConfiguredPendingPairingFile,
+  resolvePendingPairingFile,
+  feishuArgs,
+  prepareAndCommitAgentBindings,
+  probeReadyBindingProfiles,
+  reconcileStartupResults,
+  reconcileOverlappedReadyBindings,
+  recordPreparationFailure,
+  recordError,
+  recordStableAgentFailure,
+  resolvePreparedAgentBindings,
+  orchestrateStartupBindings,
+  runOverlappedStartup,
+  runPreparedBindingStarts,
+  sameBindingRelationship,
+  startBindingsWithGroups,
+  startAgentGroups,
+  startManagedProcess,
+  runBootstrapHelper,
+  setBindingStatus,
+  startupSummaryLines,
+  cleanupAll,
+  upsertBindings,
+  writeFeishuRuntimeProfile,
+  writeManifest,
+};