botmux 3.14.0 → 3.16.0

package/dist/cli.js

@@ -9,22 +9,24 @@
  *   botmux start          — start daemon and auto plugin services
  *   botmux stop [--with-plugin] — stop daemon (optionally stop auto plugin services)
  *   botmux restart [--include-pm2] [--with-plugin] — restart daemon, then ensure auto plugin services;
- *     --include-pm2 is a zero-live-God admission fence, not authority to signal an existing PM2 God
+ *     --include-pm2 additionally retires the PM2 God after the fleet is verified retired
+ *     (socket-addressed `pm2 kill`, never a PID signal) so the whole tree restarts from a fresh env
  *   botmux restart --bootstrap-shutdown-protocol --yes — operator-approved one-time retirement
  *     of a pre-protocol fleet after independently confirming all Session/Riff work is idle
  *   botmux logs [--lines] — view daemon logs
  *   botmux status         — show daemon status
- *   botmux upgrade|update — upgrade to latest version
+ *   botmux upgrade|update — upgrade to latest version (本地 checkout 则 git pull --ff-only + rebuild + restart)
  *   botmux device enroll|status|logout — manage the host desktop device credential
  *   botmux list           — interactive session picker (TUI), attach to managed tmux/ZMX sessions
  *   botmux list --plain   — plain table output (for piping / scripts)
+ *   botmux preview <port> — register this session's loopback Web preview
  *   botmux delete <id>    — close a session by ID prefix
  *   botmux delete all     — close all active sessions
  *   botmux autostart enable|disable|status — manage boot-time autostart (launchd / user systemd / Windows Task Scheduler)
  *   botmux whiteboard status|enable|disable|current|list|read|update|write — local project whiteboard
  */
 import { execSync, execFileSync, spawnSync, spawn } from 'node:child_process';
-import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, renameSync, readdirSync, readlinkSync, symlinkSync, appendFileSync, statSync, unlinkSync, rmSync, realpathSync } from 'node:fs';
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, renameSync, readdirSync, readlinkSync, symlinkSync, appendFileSync, statSync, unlinkSync, rmSync, realpathSync, chmodSync } from 'node:fs';
 import { underReadIsolation, sendCredFilePath } from './adapters/cli/read-isolation.js';
 import { atomicWriteFileSync } from './utils/atomic-write.js';
 import { join, dirname, basename, resolve } from 'node:path';
@@ -34,6 +36,7 @@ import { createInterface } from 'node:readline';
 import { createRequire } from 'node:module';
 import { randomBytes, randomUUID } from 'node:crypto';
 import { validateWorkingDir } from './core/working-dir.js';
+import { closeResidualClause, parseCloseResidual } from './core/close-residual.js';
 import { findAncestorSessionContext as findLiveAncestorSessionContext, resolveSessionContext, } from './core/session-marker.js';
 import { resolveBotmuxDataDir } from './core/data-dir.js';
 import { dashboardSecretPath } from './core/dashboard-secret.js';
@@ -55,13 +58,15 @@ import { validateCodexAppManagedSendOrigin, } from './utils/codex-app-dispatch-l
 import { hasProtectedSessionMutationOwnership } from './core/session-mutation-guard.js';
 import { logger } from './utils/logger.js';
 import { withFileLock, withFileLockSync } from './utils/file-lock.js';
-import { scrubClaudeSessionMarkerEnv, scrubSessionCliHomeEnv, scrubWorkflowWorkerEnv } from './utils/child-env.js';
+import { pm2CallerEnv } from './cli/pm2-env.js';
 import { scheduleTimeZone } from './utils/timezone.js';
 import { expandHomePath, invalidWorkingDirs } from './utils/working-dir.js';
-import { firstPositional } from './cli/arg-utils.js';
+import { firstPositional, hasFlagOrEq } from './cli/arg-utils.js';
 import { isColdResumeDormant, isRealManagedSession, sessionListDisposition } from './cli/session-list-liveness.js';
 import { computeSessionPickerLayout, } from './cli/session-picker-layout.js';
 import { computeSessionPickerScrollWindow } from './cli/session-picker-viewport.js';
+import { canWakeDormantBackendForAttach, wakeDormantBackendForAttach, } from './cli/session-list-wake.js';
+import { SESSION_WAKE_DEADLINE_HEADER } from './core/session-wake-deadline.js';
 import { terminalCellWidth } from './cli/terminal-width.js';
 import { attachFrozenManagedZmxSession, freezeManagedZmxAttachTarget, } from './cli/zmx-managed-attach.js';
 import { readSupervisorProcessStartIdentity } from './core/process-start-identity.js';
@@ -81,13 +86,17 @@ import { assertPm2DaemonShutdownCapabilitiesIn } from './cli/pm2-shutdown-capabi
 import { evaluateRestartShutdownPreflight } from './cli/restart-shutdown-preflight.js';
 import { recordAndNotifyRestartBootstrapFailure, restartFailurePathIn, } from './cli/restart-failure-notification.js';
 import { resolveRestartFailureOwner } from './cli/restart-failure-owner.js';
-import { assertIncludePm2RestartAdmission } from './cli/pm2-god-admission.js';
+import { assertNoReplacementPm2God, assertPm2RegistryQuiescentForGodRetirement, retireSoleLivePm2God, } from './cli/pm2-god-retirement.js';
+import { pm2FleetMutationLockTarget, withPm2FleetMutationLock } from './cli/pm2-fleet-lock.js';
+import { LogFileFollower } from './cli/log-tail.js';
 import { requestAttestedDaemonShutdown, requestAttestedDaemonShutdownBatch, } from './cli/supervisor-shutdown-client.js';
 import { assertDaemonPm2GracefulExitPolicy, assertConfiguredPm2FleetReady, assertExactAttestedDaemonSet, classifyStartBotFleetAdmission, normalizeRawPm2StopExitCodes, reconcileLatePm2StartPublication, runBoundedPm2StartTransaction, } from './cli/pm2-start-transaction.js';
 import { callDashboard } from './cli/dashboard-endpoint.js';
-import { DASHBOARD_COMMAND_USAGE, executeDashboardCommand, formatDashboardFallbackFailure, } from './cli/dashboard-command.js';
-import { globalInstallUpdateLockTargetIn, installLatestBotmuxSync } from './core/maintenance.js';
+import { DASHBOARD_COMMAND_USAGE, executeDashboardCommand, formatDashboardFallbackFailure, formatDashboardSuccessLines, } from './cli/dashboard-command.js';
+import { globalInstallUpdateLockTarget, globalInstallUpdateLockTargetIn, installLatestBotmuxSync } from './core/maintenance.js';
 import { formatGlobalInstallCommand, resolveGlobalInstallPlan, UnsupportedGlobalInstallError, } from './utils/global-install.js';
+import { isLocalDevInstall, botmuxCliEntryAt } from './utils/install-info.js';
+import { resolveLocalDevCheckoutDir, isGitWorktree, gitPorcelainStatus, localDevUpdateSteps, describeSpawnFailure, } from './utils/local-dev-update.js';
 import { loadDashboardSecret } from './dashboard/auth.js';
 import { postWorkflowDaemonMutation, } from './workflows/v3/daemon-ipc-client.js';
 import { postWorkflowSessionRunMutation, readWorkflowSessionRelayContext, } from './workflows/v3/session-relay-client.js';
@@ -98,14 +107,14 @@ import { isRetryableAskHttpStatus } from './core/ask-types.js';
 import { hasManagedOriginIsolationMarker, managedOriginDataRootProbeAccess, managedOriginIsolationSentinelAccess, managedOriginLegacyIsolationProbeAccess, readManagedOriginRootLocator, readManagedOriginCapability, } from './core/managed-origin-capability.js';
 import { attestManagedOrigin, } from './core/managed-origin-attestation.js';
 import { rejectLikelyWindowsStdinMojibake, decodeStdinBytes } from './cli/stdin-encoding.js';
-import { formatBotInfoEntriesForCli, formatChatBotsForCli, } from './cli/bots-list-output.js';
+import { collaborationHelp, formatBotInfoEntriesForCli, formatChatBotsForCli, } from './cli/bots-list-output.js';
 import { ensureBotChatGrantMatrix, requestExactChatGrant } from './cli/exact-chat-grant-client.js';
 import { buildFooterAddressing, hasKnownBotMention, knownBotOpenIdsFromCrossRef, orderedFooterRecipients, stripCodeSpans, } from './utils/bot-routing.js';
 import { isLocale, localeForBot, setDefaultLocale, SUPPORTED_LOCALES, t } from './i18n/index.js';
 import { chatAppLink, larkHosts, normalizeBrand } from './im/lark/lark-hosts.js';
 import { mergeDashboardConfig, mergeGlobalConfig, readGlobalConfig, setGlobalLocale, globalConfigPath } from './global-config.js';
 import { createWhiteboard, ensureDefaultWhiteboard, getWhiteboard, listWhiteboards, readWhiteboard, whiteboardEnabled, whiteboardPath, } from './services/whiteboard-store.js';
-import { buildBridgeSendMarkerContent, buildBridgeSendPreviewText, } from './services/bridge-fallback-gate.js';
+import { buildBridgeSendMarkerContent, buildBridgeSendPreviewText, stripTrailingOaiMemoryCitation, } from './services/bridge-fallback-gate.js';
 import { bindRestartLeaseTo, commitRestartIntentAttemptTo, consumeRestartIntentTo, removeRestartIntentAttemptTo, writeRestartAttemptIntentTo, } from './services/restart-intent-store.js';
 import { loadAllSessionsSnapshot, mutateSessionRowOffline } from './services/session-store.js';
 import { evaluateVcMeetingManagedSend, isTrustedVcMeetingHostRelayParent, resolveVcMeetingImTurnOrigin, } from './services/vc-meeting-send-policy.js';
@@ -151,8 +160,12 @@ const PM2_NAME = 'botmux';
  * when those external pm2 installations get moved or removed.
  */
 const PM2_HOME = join(CONFIG_DIR, 'pm2');
-const PM2_FLEET_MUTATION_LOCK_TARGET = join(CONFIG_DIR, 'pm2-fleet-mutation');
+// Shared with plugin service-manager (src/cli/pm2-fleet-lock.ts): one lock
+// serializes every botmux-internal mutation of the shared PM2_HOME.
+const PM2_FLEET_MUTATION_LOCK_TARGET = pm2FleetMutationLockTarget();
 const PM2_START_COMMAND_TIMEOUT_MS = 30_000;
+// `pm2 kill` with an already-empty fleet only tears down the God + socket.
+const PM2_GOD_KILL_COMMAND_TIMEOUT_MS = 30_000;
 const PM2_START_VERIFY_MIN_TIMEOUT_MS = 60_000;
 const PM2_START_VERIFY_PER_PROCESS_MS = 2_000;
 const PM2_START_LATE_PUBLICATION_SETTLE_MS = 10_000;
@@ -190,28 +203,12 @@ function pm2Bin() {
         return symlink;
     return 'pm2';
 }
-/** Env for pm2 invocations with an isolated PM2_HOME. */
+/** Env for pm2 invocations with an isolated PM2_HOME. The scrub set (session
+ *  CLI homes, Claude/workflow markers, Dashboard H5 credentials, invoker
+ *  terminal fingerprints, turn-scoped session identity — plus the TERM
+ *  re-pin) lives in cli/pm2-env.ts so it stays assertable in a test. */
 function pm2Env(home = PM2_HOME) {
-    const env = { ...process.env, PM2_HOME: home };
-    // pm2 persists the caller's env into every managed app (and into dump.pm2
-    // for resurrect), so a `botmux start/restart` invoked from ANY process that
-    // carries a session-level CLI home pointer — most commonly a bot's own
-    // session during self-upgrade, whose env holds its injected
-    // CLAUDE_CONFIG_DIR — would poison ALL workers, making every non-isolated
-    // bot read/write a sibling bot's home. Strip at this boundary so the daemon
-    // stays session-agnostic; daemon/worker boot scrub the same keys against
-    // stale dumps (see SESSION_CLI_HOME_ENV_KEYS for the full story, including
-    // why GROK_HOME is exempt and why deleting beats pinning a default).
-    scrubSessionCliHomeEnv(env);
-    // Claude session markers ride the same pm2 env-persistence vector; baked in
-    // they eventually flip transcript saving off fleet-wide once the tmux server
-    // respawns from a poisoned daemon (see CLAUDE_SESSION_MARKER_ENV_KEYS).
-    scrubClaudeSessionMarkerEnv(env);
-    // Workflow/goal markers identify one short-lived node worker. Persisting
-    // them in PM2 would make every daemon — and then every ordinary chat worker
-    // it forks — run in workflow mode after a restart initiated from that node.
-    scrubWorkflowWorkerEnv(env);
-    return env;
+    return pm2CallerEnv(process.env, home);
 }
 function listPm2GodDaemonPids(home = PM2_HOME) {
     const marker = `God Daemon (${home})`;
@@ -716,7 +713,11 @@ function ecosystemConfig(bots = loadBotsJson(), activationAppId) {
     });
     apps.push({
         name: 'botmux-dashboard',
-        script: join(PKG_ROOT, 'dist', 'dashboard.js'),
+        // index-dashboard.ts, NOT dashboard.js: the entry dotenv-loads
+        // ~/.botmux/.env before dynamically importing the dashboard, which is how
+        // the Feishu H5 credential family reaches the dashboard WITHOUT being baked
+        // into this file's shared env block (see DAEMON_ENV_KEYS).
+        script: join(PKG_ROOT, 'dist', 'index-dashboard.js'),
         interpreter,
         cwd: PKG_ROOT,
         autorestart: true,
@@ -742,7 +743,22 @@ function ecosystemConfig(bots = loadBotsJson(), activationAppId) {
     });
     const cfg = { apps };
     const tmpFile = join(CONFIG_DIR, 'ecosystem.config.json');
-    writeFileSync(tmpFile, JSON.stringify(cfg, null, 2));
+    // Owner-only, same as bots.json — kept as defense in depth. The Dashboard
+    // Feishu H5 app secret is no longer baked into the env block (the dashboard
+    // dotenv-loads it via index-dashboard.ts; DAEMON_ENV_KEYS excludes the
+    // family), but this file still bakes operator-configured hosts/ports/paths,
+    // an older install's copy may still carry the secret until overwritten, and
+    // 0600 keeps any future env-block regression from becoming world-readable.
+    // writeFileSync's `mode` applies only when the file is CREATED — chmod as
+    // well, or an install that already wrote it 0644 keeps the world-readable
+    // mode forever.
+    writeFileSync(tmpFile, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+    if (process.platform !== 'win32') {
+        try {
+            chmodSync(tmpFile, 0o600);
+        }
+        catch { /* best-effort: exotic FS / mounted noperm */ }
+    }
     return tmpFile;
 }
 function hasConfig() {
@@ -2454,7 +2470,7 @@ async function cmdStart() {
             process.exit(1);
         }
     }
-    await withFileLock(PM2_FLEET_MUTATION_LOCK_TARGET, async () => {
+    await withPm2FleetMutationLock(async () => {
         await withFileLock(BOTS_JSON_FILE, async () => {
             const lockedBots = loadBotsJson();
             if (JSON.stringify(lockedBots) !== JSON.stringify(botsForCheck)) {
@@ -3088,7 +3104,7 @@ async function cmdStop() {
         throw new Error('[stop] --bootstrap-shutdown-protocol requires --yes after confirming every Session/Riff workload is idle');
     }
     ensureConfigDir();
-    await withFileLock(PM2_FLEET_MUTATION_LOCK_TARGET, async () => {
+    await withPm2FleetMutationLock(async () => {
         assertNoDuplicatePm2GodDaemons();
         cleanupLegacyPm2(bootstrapShutdownProtocol ? 'stop' : undefined);
         if (bootstrapShutdownProtocol) {
@@ -3186,7 +3202,7 @@ async function cmdRestart() {
         process.exit(1);
     }
     ensureConfigDir();
-    await withFileLock(PM2_FLEET_MUTATION_LOCK_TARGET, async () => {
+    await withPm2FleetMutationLock(async () => {
         const includePm2 = process.argv.includes('--include-pm2');
         const includePluginServices = process.argv.includes('--with-plugin');
         const bootstrapShutdownProtocol = process.argv.includes('--bootstrap-shutdown-protocol');
@@ -3197,9 +3213,6 @@ async function cmdRestart() {
         if (bootstrapShutdownProtocol && includePm2) {
             throw new Error('[restart] --bootstrap-shutdown-protocol cannot be combined with --include-pm2');
         }
-        if (includePm2) {
-            assertIncludePm2RestartAdmission(listPm2GodDaemonPids());
-        }
         const restartIntentDir = resolveDataDir();
         let stagedRestartIntent = null;
         try {
@@ -3210,20 +3223,17 @@ async function cmdRestart() {
         preflightNodeSanity();
         await ensureSystemDependencies();
         cleanupLegacyPm2(bootstrapShutdownProtocol ? 'restart' : undefined);
-        if (bootstrapShutdownProtocol || includePm2) {
-            // An include-pm2 restart was admitted only when no live PM2 God existed;
-            // a read-only jlist probe would start one and invalidate that admission.
-            // Keep the existing include-pm2 clean-start path unchanged.
-            if (bootstrapShutdownProtocol)
-                bootstrapDeleteAllBotmuxProcesses('restart');
-            else
-                deleteAllBotmuxProcesses();
+        if (bootstrapShutdownProtocol) {
+            bootstrapDeleteAllBotmuxProcesses('restart');
         }
         else {
             // This process is the newly installed code generation even when the
             // Dashboard that spawned it is still the old in-memory generation. Do
             // the policy probe here, before the generic retirement path throws, so
             // the first-upgrade failure becomes durable and reaches the owner.
+            // --include-pm2 takes this path too: the probe's lazy jlist may start a
+            // PM2 God, which is harmless now — God retirement below runs after the
+            // fleet is verified retired, against whichever God owns the home.
             const preflight = evaluateRestartShutdownPreflight();
             if (preflight.bootstrapRequired) {
                 const detail = 'current daemon PM2 policy requires the one-time shutdown-protocol bootstrap';
@@ -3235,8 +3245,24 @@ async function cmdRestart() {
             }
             deleteAllBotmuxProcesses();
         }
-        if (includePluginServices)
+        // --include-pm2 tears down the whole PM2_HOME, so ALL plugin services get
+        // a graceful stop first instead of dying with the God; auto ones are
+        // re-ensured after the restart, manually-started ones stay down. Stop
+        // errors are collected into reports rather than thrown (service-manager
+        // contract), so this path re-checks them: a service that failed to stop
+        // must block the God retirement below, not die with the God.
+        if (includePm2) {
+            const pluginStopReports = await stopPluginServicesForCli(undefined, {});
+            const failedStops = pluginStopReports.filter(report => report.action === 'failed');
+            if (failedStops.length > 0) {
+                throw new Error(`[restart --include-pm2] plugin service(s) failed to stop gracefully: `
+                    + `${failedStops.map(report => report.pluginId).join(', ')}; `
+                    + 'the PM2 God and every remaining process were left untouched — fix or delete these services, then rerun');
+            }
+        }
+        else if (includePluginServices) {
             await stopPluginServicesForCli(undefined, { autoOnly: true });
+        }
         cleanupStaleDaemonDescriptors();
         const retiredProjection = readVerifiedBotmuxPm2Projection('restart-start');
         assertNoUnregisteredLiveDaemonDescriptors('restart-start', retiredProjection);
@@ -3244,6 +3270,37 @@ async function cmdRestart() {
             throw new Error(`[restart-start] new PM2 core row(s) appeared after verified retirement: `
                 + retiredProjection.map(entry => `${entry.name}:${entry.pid}`).join(', '));
         }
+        // Only now — with the core fleet verified retired and plugin services
+        // stopped — is the God a stateless supervisor of nothing, safe to retire
+        // via its own control socket. The fresh `pm2 start` below then births a
+        // new God from this CLI's (pm2Env-scrubbed) environment, which is what
+        // makes --include-pm2 a genuinely complete restart.
+        if (includePm2) {
+            // Independent whole-registry proof, not just the core projection above:
+            // every row still known to the God (a plugin stop that failed, an
+            // orphaned row from an uninstalled plugin) blocks the kill fail-closed.
+            assertPm2RegistryQuiescentForGodRetirement(parsePm2JlistOutputStrict(pm2Capture(['jlist'])).map(row => ({
+                name: typeof row?.name === 'string' && row.name ? row.name : 'unknown',
+                status: typeof row?.pm2_env?.status === 'string' ? row.pm2_env.status : undefined,
+                pid: parsePm2Integer(row?.pid, { nonNegative: true }),
+            })));
+            const retired = await retireSoleLivePm2God({
+                listGodPids: () => listPm2GodDaemonPids(),
+                readStartIdentity: pid => readSupervisorProcessStartIdentity(pid),
+                isAlive: pid => { try {
+                    process.kill(pid, 0);
+                    return true;
+                }
+                catch {
+                    return false;
+                } },
+                pm2Kill: () => runPm2(['kill'], true, PM2_HOME, PM2_GOD_KILL_COMMAND_TIMEOUT_MS),
+                sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+                now: () => Date.now(),
+            });
+            if (retired)
+                console.log(`已退役 PM2 God (pid ${retired.pid})，fleet 将以当前干净环境全新启动`);
+        }
         await withFileLock(BOTS_JSON_FILE, async () => {
             const restartBots = loadBotsJson();
             const cfg = ecosystemConfig(restartBots);
@@ -3262,6 +3319,11 @@ async function cmdRestart() {
                     start: timeoutMs => {
                         assertBotsConfigSnapshotUnchanged('restart-start', restartBots);
                         assertNoDuplicatePm2GodDaemons();
+                        // After retiring the God this start must be the one to birth
+                        // its successor; a God that appeared in between came from some
+                        // other client's environment and is refused.
+                        if (includePm2)
+                            assertNoReplacementPm2God(listPm2GodDaemonPids());
                         preflightNodeSanity();
                         runPm2(['start', cfg], true, PM2_HOME, timeoutMs);
                     },
@@ -3318,7 +3380,7 @@ function retireExactBotmuxProcess(operation, target, fullProjection) {
 async function ensureBotDaemonStopped(appId, _opts = {}) {
     ensureConfigDir();
     try {
-        return await withFileLock(PM2_FLEET_MUTATION_LOCK_TARGET, async () => (withFileLock(BOTS_JSON_FILE, async () => {
+        return await withPm2FleetMutationLock(async () => (withFileLock(BOTS_JSON_FILE, async () => {
             assertNoDuplicatePm2GodDaemons();
             preflightNodeSanity();
             cleanupLegacyPm2();
@@ -3381,7 +3443,7 @@ async function ensureBotDaemonStopped(appId, _opts = {}) {
 async function ensureBotDaemonStarted(appId, opts = {}) {
     ensureConfigDir();
     try {
-        return await withFileLock(PM2_FLEET_MUTATION_LOCK_TARGET, async () => (withFileLock(BOTS_JSON_FILE, async () => {
+        return await withPm2FleetMutationLock(async () => (withFileLock(BOTS_JSON_FILE, async () => {
             assertNoDuplicatePm2GodDaemons();
             preflightNodeSanity();
             cleanupLegacyPm2();
@@ -3644,23 +3706,48 @@ function warnIfLegacyBotmuxAlive() {
     }
     if (!legacyPid)
         return;
+    // Deliberately NO PM2 client here: this helper runs at the top of read-only
+    // commands (status/logs), and a pm2 jlist against the legacy home would
+    // lazily REVIVE a legacy God the moment the recorded one exits between the
+    // kill(0) probe and the client's connect — a read command must never create
+    // one. The process-table marker scan also closes the stale-pid-file hole:
+    // kill(pid, 0) alone would accept an unrelated process that reused the pid.
     try {
-        process.kill(legacyPid, 0);
+        if (!listPm2GodDaemonPids(legacyHome).includes(legacyPid))
+            return;
     }
     catch {
         return;
     }
+    // "Still has botmux processes" from PM2's own pid files, not from a client:
+    // the legacy God maintains <name>-<id>.pid under <home>/pids while an app
+    // process runs.
     try {
-        const output = pm2Capture(['jlist'], legacyHome);
-        const apps = parsePm2JlistOutput(output);
-        const hasBotmux = apps.some(a => a.name === PM2_NAME || a.name.startsWith(`${PM2_NAME}-`));
-        if (hasBotmux) {
+        for (const entry of readdirSync(join(legacyHome, 'pids'))) {
+            if (!entry.startsWith(PM2_NAME) || !entry.endsWith('.pid'))
+                continue;
+            let appPid = 0;
+            try {
+                appPid = parseInt(readFileSync(join(legacyHome, 'pids', entry), 'utf-8').trim(), 10);
+            }
+            catch {
+                continue;
+            }
+            if (!appPid)
+                continue;
+            try {
+                process.kill(appPid, 0);
+            }
+            catch {
+                continue;
+            }
             console.warn('⚠️  检测到旧版 PM2_HOME (~/.pm2) 下仍有 botmux 进程,运行 `botmux restart` 完成迁移。\n');
+            return;
         }
     }
-    catch { /* ignore */ }
+    catch { /* no pids dir */ }
 }
-function cmdLogs() {
+async function cmdLogs() {
     warnIfLegacyBotmuxAlive();
     const lines = process.argv.includes('--lines')
         ? process.argv[process.argv.indexOf('--lines') + 1] || '50'
@@ -3670,7 +3757,16 @@ function cmdLogs() {
     const botIdx = process.argv.includes('--bot')
         ? process.argv[process.argv.indexOf('--bot') + 1]
         : undefined;
-    let target;
+    // No PM2 client at all: `pm2 logs` lazily births a God when none is alive
+    // (Client.start → pingDaemon false → launchDaemon), which made this read
+    // command a check/use race against `restart --include-pm2` — a God observed
+    // under the fleet lock could be retired before the spawned client connected,
+    // and the connecting client would then create a replacement God inside the
+    // kill→start window. Tailing the log files pm2 itself writes (the exact
+    // out_file/error_file paths ecosystemConfig pins) removes the raced resource
+    // entirely: no interleaving of `botmux logs` can create a God, no fleet lock
+    // is needed, and logs keep working while the fleet is stopped.
+    let sources;
     if (botIdx !== undefined) {
         const numericIdx = /^\d+$/.test(botIdx) ? Number(botIdx) : undefined;
         const selectedIdx = numericIdx === undefined
@@ -3678,31 +3774,94 @@ function cmdLogs() {
             : numericIdx >= 0 && numericIdx < bots.length
                 ? numericIdx
                 : undefined;
-        target = selectedIdx !== undefined
-            ? botProcessName(bots[selectedIdx], selectedIdx, PM2_NAME)
-            : numericIdx !== undefined
-                ? `${PM2_NAME}-${botIdx}`
-                : botIdx;
+        if (selectedIdx !== undefined) {
+            sources = coreBotLogSources(bots, selectedIdx);
+        }
+        else {
+            const wanted = numericIdx !== undefined ? `${PM2_NAME}-${botIdx}` : botIdx;
+            sources = allBotmuxLogSources(bots).filter(source => source.label === wanted);
+            if (sources.length === 0) {
+                console.error(`✗ 未找到 ${wanted} 的日志文件（可用：不带 --bot 查看全部，或用 0-based index / pm2 名 / appId）`);
+                process.exitCode = 1;
+                return;
+            }
+        }
     }
     else {
-        // Show all botmux logs via pm2 regex match
-        target = `/^${PM2_NAME}/`;
+        sources = allBotmuxLogSources(bots);
+    }
+    // Not `|| 50`: an explicit --lines 0 (follow-only) must stay 0.
+    const rawLines = Number.parseInt(lines, 10);
+    const parsedLines = Number.isSafeInteger(rawLines) && rawLines >= 0 ? rawLines : 50;
+    console.log(`跟踪 ${sources.length} 个日志文件（Ctrl+C 退出；fleet 停止时也能查看历史并等待新日志）`);
+    const follower = new LogFileFollower({ sources, writeLine: line => console.log(line) });
+    follower.printInitialTail(parsedLines);
+    follower.start();
+}
+/** Log files of one core bot daemon — the exact paths ecosystemConfig pins. */
+function coreBotLogSources(bots, index) {
+    const label = botProcessName(bots[index], index, PM2_NAME);
+    return [
+        { label, stream: 'out', file: join(LOG_DIR, `daemon-${index}-out.log`) },
+        { label, stream: 'err', file: join(LOG_DIR, `daemon-${index}-error.log`) },
+    ];
+}
+/** Every botmux log file: core daemons + dashboard (ecosystemConfig paths)
+ *  plus plugin services (PM2 default logs dir under the shared PM2_HOME). */
+function allBotmuxLogSources(bots) {
+    const sources = bots.flatMap((_bot, i) => coreBotLogSources(bots, i));
+    sources.push({ label: 'botmux-dashboard', stream: 'out', file: join(LOG_DIR, 'dashboard-out.log') }, { label: 'botmux-dashboard', stream: 'err', file: join(LOG_DIR, 'dashboard-error.log') });
+    const pluginLogsDir = join(PM2_HOME, 'logs');
+    try {
+        for (const entry of readdirSync(pluginLogsDir)) {
+            const match = entry.match(/^(botmux-plugin-.+?)-(out|error)(?:-\d+)?\.log$/);
+            if (!match)
+                continue;
+            sources.push({
+                label: match[1],
+                stream: match[2] === 'error' ? 'err' : 'out',
+                file: join(pluginLogsDir, entry),
+            });
+        }
     }
-    // Use spawn for streaming output. Windows cannot spawn a .js CLI script
-    // directly, so run the bundled pm2 script through the current node.exe.
-    const pm2 = buildPm2SpawnCommand(pm2Bin(), ['logs', target, '--lines', lines]);
-    const child = spawn(pm2.command, pm2.args, {
-        stdio: 'inherit',
-        env: pm2Env(),
-        shell: pm2.shell ?? false,
-    });
-    child.on('exit', code => process.exit(code ?? 0));
+    catch { /* no plugin logs yet */ }
+    return sources;
 }
-function cmdStatus() {
+async function cmdStatus() {
     warnIfLegacyBotmuxAlive();
-    runPm2(['status']);
+    // A pm2 client with no live God lazily births one from this process's env.
+    // During an include-pm2 restart's kill→start window that replacement God
+    // would abort the restart with the whole fleet offline, and in a normally
+    // stopped state it would silently resurrect a God nobody asked for — so a
+    // read-only status must check for a God under the fleet lock and never
+    // create one.
+    let entered = false;
+    try {
+        await withPm2FleetMutationLock(async () => {
+            entered = true;
+            if (listPm2GodDaemonPids().length === 0) {
+                console.log('PM2 God 未运行：fleet 已停止（status 不会隐式启动它；需要时运行 botmux start）。');
+                return;
+            }
+            runPm2(['status']);
+        }, { maxWaitMs: 3_000 });
+    }
+    catch (err) {
+        if (entered)
+            throw err;
+        // Non-zero so automation doesn't mistake "couldn't observe" for success.
+        console.log('fleet 停启操作进行中（fleet mutation 锁被占用），请稍后重试 botmux status。');
+        process.exitCode = 1;
+    }
 }
 function cmdUpgrade() {
+    // 本地 checkout（有 .git/src）：走 git pull --ff-only → 重新 build → 从本
+    // checkout 重启，而不是拿全局包管理器去升级（那对 dev 部署无效，见
+    // install-info.ts 的 isLocalDevInstall 说明）。
+    if (isLocalDevInstall()) {
+        cmdUpgradeLocalDev();
+        return;
+    }
     try {
         const plan = resolveGlobalInstallPlan();
         console.log(`🔄 升级中：${formatGlobalInstallCommand(plan)}`);
@@ -3719,6 +3878,82 @@ function cmdUpgrade() {
         process.exit(1);
     }
 }
+/** 在 checkout 目录里同步跑一条命令，stdio 直通；失败抛错。 */
+function runInCheckout(cwd, command, args) {
+    const result = spawnSync(command, args, {
+        cwd,
+        stdio: 'inherit',
+        shell: process.platform === 'win32',
+    });
+    if (result.error || result.status !== 0) {
+        throw new Error(describeSpawnFailure(command, args, result));
+    }
+}
+/**
+ * 本地 checkout 的更新流程：git 干净检查 → git pull --ff-only → pnpm build →
+ * 从本 checkout 的 dist/cli.js restart。dist/ 被 gitignore，只 pull 不 build
+ * 重启后跑的还是旧代码，故 build 步不可省。定位/干净检查/命令定义与 dashboard
+ * 共用 src/utils/local-dev-update.ts，避免两边逻辑漂移。
+ */
+function cmdUpgradeLocalDev() {
+    const dir = resolveLocalDevCheckoutDir();
+    if (!isGitWorktree(dir)) {
+        console.error(`❌ ${dir} 不是 git 工作树，无法用 git pull 更新。请手动更新或改用全局安装。`);
+        process.exit(1);
+    }
+    console.log(`🔄 本地 checkout 更新：${dir}`);
+    // git 干净检查 + pull + build 全程握同一把跨进程 update 锁（与 dashboard 的
+    // /api/update/run 用的是同一个 target），避免 CLI 与 dashboard 同时对同一
+    // checkout 交错跑 pnpm build 而互相清理/覆盖 dist。restart 不在锁内——它有
+    // 自己的 restart lease。
+    try {
+        const lockTarget = globalInstallUpdateLockTarget();
+        // daemon 正常会建好 dataDir；但 CLI 可能在 daemon 尚未起过的机器上先跑
+        // update，锁文件父目录不存在会让 withFileLockSync 报 ENOENT 而盖掉真实错误。
+        mkdirSync(dirname(lockTarget), { recursive: true });
+        withFileLockSync(lockTarget, () => {
+            // 1) fail closed：有未提交改动就中止（不偷偷 stash），让用户自己决定。
+            let status;
+            try {
+                status = gitPorcelainStatus(dir);
+            }
+            catch (error) {
+                throw new Error(`读取 git 状态失败：${error instanceof Error ? error.message : error}`);
+            }
+            if (status) {
+                const err = new Error('dirty');
+                err.dirtyStatus = status;
+                throw err;
+            }
+            // 2~3) git pull --ff-only（分叉/冲突直接报错停下，不自动 merge）+ pnpm build。
+            for (const { command, args } of localDevUpdateSteps()) {
+                console.log(`→ ${command} ${args.join(' ')}`);
+                runInCheckout(dir, command, args);
+            }
+        }, { maxWaitMs: 2_000 });
+    }
+    catch (error) {
+        const dirty = error.dirtyStatus;
+        if (dirty) {
+            console.error('❌ 工作区有未提交改动，已中止更新（不会自动 stash）。请先提交或清理：');
+            console.error(dirty);
+        }
+        else {
+            console.error(`❌ 更新失败：${error instanceof Error ? error.message : error}`);
+        }
+        process.exit(1);
+    }
+    // 4) 用本 checkout 的 cli.js 重启 daemon（不走 PATH，避免被更靠前的全局 botmux 抢先）。
+    try {
+        console.log('→ restart daemon');
+        runInCheckout(dir, process.execPath, [botmuxCliEntryAt(dir), 'restart']);
+        console.log('\n✅ 本地更新完成，daemon 已从最新代码重启。');
+    }
+    catch (error) {
+        console.error(`❌ 重启失败：${error instanceof Error ? error.message : error}`);
+        process.exit(1);
+    }
+}
 /**
  * Call one of the dashboard's loopback HMAC `/__cli/*` endpoints. Thin wrapper
  * over {@link callDashboard}, which handles 404 disambiguation and self-heals a
@@ -3792,10 +4027,10 @@ async function cmdDashboard(args) {
     }
     const { action, result: r } = execution;
     if (r.ok) {
-        // 首行保持纯 URL（脚本/复制取第一行即可）；走中心化平台时再补一行本地直连兜底。
-        console.log(r.url);
-        if (r.localUrl)
-            console.log(`本地直连(平台异常时可用): ${r.localUrl}`);
+        // 首行保持纯 URL（脚本/复制取第一行即可）；随后依次是工作台直达入口、以及走
+        // 中心化平台时的本地直连兜底。行顺序与首行契约见 formatDashboardSuccessLines。
+        for (const line of formatDashboardSuccessLines(r))
+            console.log(line);
         return;
     }
     const portFile = join(CONFIG_DIR, '.dashboard-port');
@@ -3967,6 +4202,7 @@ async function abandonSessionOffline(session) {
         delete latest.queuedActivationPending;
         delete latest.queuedActivationTail;
         delete latest.pendingRepoSetup;
+        delete latest.previewTarget;
         applied = true;
         return true;
     });
@@ -3984,6 +4220,7 @@ function pruneSessionOfflineIfLedgerEmpty(session) {
         current.closedAt = new Date().toISOString();
         delete current.codexAppDispatchLedger;
         delete current.codexAppGenerationCommits;
+        delete current.previewTarget;
         pruned = true;
         return true;
     });
@@ -4050,8 +4287,15 @@ async function abandonSessionAuthoritatively(session, online = listOnlineDaemons
                 // stays fail-closed at the daemon's sessionCliIpcAuth check.
                 const res = await postSessionCliIpc(ipcPort, session.sessionId, 'close', {});
                 const body = await res.json().catch(() => ({}));
-                if (res.ok && body.ok)
-                    return { ok: true, mode: 'daemon' };
+                if (res.ok && body.ok) {
+                    // Shared parser: a body that DECLARES a residual must warn even when the
+                    // `residual` object is missing/malformed, or a bad payload silently
+                    // becomes an ordinary success again.
+                    const residual = parseCloseResidual(body);
+                    return residual
+                        ? { ok: true, mode: 'daemon', residual }
+                        : { ok: true, mode: 'daemon' };
+                }
                 // Surface the daemon's own rejection reason (e.g. origin_unproven) and
                 // never fall back to a partial local kill: a fresh descriptor means the
                 // daemon may still hold authoritative in-memory state.
@@ -4366,14 +4610,19 @@ function sessionBackingInfo(s, snapshot) {
     if (s.backendType === 'pty') {
         return { backendType: 'pty', probe: 'missing', label: 'pty' };
     }
-    if (s.backendType === 'riff') {
-        // Riff runs the CLI on a remote sandbox, not a local multiplexer pane: there
-        // is nothing to probe, attach to, or name as a PersistentBackendTarget
-        // (sessionPersistentTarget returns undefined for it, by design). Surface a
-        // stable label and report the nonexistent local backing as missing — exactly
-        // like pty — so it never slips into the legacy tmux branch and dereferences an
-        // undefined target.
-        return { backendType: 'riff', probe: 'missing', label: 'riff' };
+    if (s.backendType === 'riff' || s.backendType === 'mojo') {
+        // A remote backend (riff / mojo) runs its agent off-box, not in a local
+        // multiplexer pane: there is nothing to probe, attach to, or name as a
+        // PersistentBackendTarget (sessionPersistentTarget returns undefined for it, by
+        // design). Surface a stable label and report the nonexistent local backing as
+        // missing — exactly like pty — so it never slips into the legacy tmux branch
+        // and dereferences an undefined target.
+        //
+        // Listed literally, not via isRemoteBackendType(): a boolean helper does not
+        // narrow the union, and the exhaustiveness guard at the end of this function
+        // depends on that narrowing. Adding a remote backend therefore fails to
+        // compile here until it is listed — which is how mojo was caught.
+        return { backendType: s.backendType, probe: 'missing', label: s.backendType };
     }
     if (s.backendType === undefined) {
         // Legacy rows predate backend stamping. Only tmux was externally attachable,
@@ -4417,6 +4666,35 @@ function hasRecoverableBackingSession(s, snapshot) {
     const target = sessionPersistentTarget(s);
     return !!target && backingProbe(snapshot, target) === 'exists';
 }
+async function requestDormantSessionWake(session, context) {
+    const online = listOnlineDaemons();
+    const daemon = session.larkAppId
+        ? online.find(d => d.larkAppId === session.larkAppId)
+        : online.length === 1 ? online[0] : undefined;
+    if (!daemon) {
+        return {
+            ok: false,
+            error: session.larkAppId || online.length === 0
+                ? '所属 daemon 不在线，请先运行 botmux status'
+                : '历史会话缺少 bot 归属，多 daemon 环境下无法安全唤醒',
+        };
+    }
+    try {
+        const path = `/api/sessions/${encodeURIComponent(session.sessionId)}/wake`;
+        const response = await fetchDaemonIpc(daemon.ipcPort, path, {
+            method: 'POST',
+            signal: context.signal,
+            headers: { [SESSION_WAKE_DEADLINE_HEADER]: String(context.deadlineMs) },
+        });
+        const body = await response.json().catch(() => ({}));
+        if (response.ok && body?.ok)
+            return { ok: true };
+        return { ok: false, error: body?.error ?? `HTTP ${response.status}` };
+    }
+    catch (err) {
+        return { ok: false, error: err?.message ?? String(err) };
+    }
+}
 /** Shorten path for display: replace $HOME with ~. */
 function shortenPath(p) {
     const home = homedir();
@@ -4474,6 +4752,13 @@ function interactiveSessionPicker(active, probeSnapshot) {
                     && backing.probe === 'exists'
                     && !!('attachBackend' in backing && backing.attachBackend)
                     && !!('target' in backing && backing.target),
+                canWake: canWakeDormantBackendForAttach({
+                    isAdopt,
+                    probe: backing.probe,
+                    realManagedSession: isRealManagedSession(s),
+                    attachBackend: 'attachBackend' in backing ? backing.attachBackend : undefined,
+                    target: 'target' in backing ? backing.target : undefined,
+                }),
             };
         });
     }
@@ -4621,6 +4906,9 @@ function interactiveSessionPicker(active, probeSnapshot) {
         else if (selected.canAttach) {
             footerLine = styledFooter('success', `${selected.attachBackend}: ${selected.backendTarget?.sessionName}`, width);
         }
+        else if (selected.canWake) {
+            footerLine = styledFooter('warn', `${selected.targetLabel}（Enter 恢复并连接）`, width);
+        }
         else {
             footerLine = styledFooter('dim', `${selected.targetLabel}（不可连接）`, width);
         }
@@ -4638,7 +4926,8 @@ function interactiveSessionPicker(active, probeSnapshot) {
             process.stdout.write('\n');
         }
         // Keybinding hints
-        const fullHints = `↑/↓ 选择  ⏎ ${selected?.canAttach ? '连接' : '不可连接'}  d 删除  q 退出`;
+        const enterAction = selected?.canAttach ? '连接' : selected?.canWake ? '恢复' : '不可连接';
+        const fullHints = `↑/↓ 选择  ⏎ ${enterAction}  d 删除  q 退出`;
         const compactHints = '↑/↓ 选择  ⏎  d  q';
         const hints = displayWidth(fullHints) <= width ? fullHints : compactHints;
         process.stdout.write(`\n${footerPrefix()}${styledFooter('dim', hints, width)}\n`);
@@ -4657,14 +4946,23 @@ function interactiveSessionPicker(active, probeSnapshot) {
             render();
         };
         process.stdout.on('resize', onResize);
+        let deleteInFlight = false;
+        let wakeInFlight = false;
+        let wakeAbortController = null;
+        let pickerClosed = false;
         function cleanup() {
+            if (pickerClosed)
+                return;
+            pickerClosed = true;
+            wakeAbortController?.abort();
+            wakeAbortController = null;
+            process.stdin.off('data', onInput);
             process.stdout.off('resize', onResize);
             process.stdin.setRawMode(false);
             process.stdin.pause();
             process.stdout.write('\x1b[?25h'); // show cursor
             process.stdout.write('\x1b[?1049l'); // leave alt screen
         }
-        let deleteInFlight = false;
         async function deleteSession(idx) {
             const r = rows[idx];
             const s = r.session;
@@ -4690,11 +4988,27 @@ function interactiveSessionPicker(active, probeSnapshot) {
             // abandonSessionAuthoritatively is `mode` (see its return type ~3573),
             // NOT master's `via` — that belongs to a different helper.
             flash = result.mode === 'daemon'
-                ? { style: 'success', text: `✓ 已删除 ${s.sessionId.substring(0, 8)}` }
+                ? (result.residual
+                    // Local row closed, remote session still running: never the green
+                    // "deleted" text, or the operator walks away from a live agent that
+                    // still holds the injected credential.
+                    ? {
+                        style: 'warn',
+                        text: `⚠ 本地已删除 ${s.sessionId.substring(0, 8)}，但${closeResidualClause(result.residual)}`,
+                    }
+                    : { style: 'success', text: `✓ 已删除 ${s.sessionId.substring(0, 8)}` })
                 : { style: 'warn', text: `✓ 已离线删除 ${s.sessionId.substring(0, 8)}` };
         }
-        process.stdin.on('data', async (key) => {
-            if (deleteInFlight)
+        async function onInput(key) {
+            // Exit always wins, including while the wake HTTP or backend probe is
+            // pending. cleanup aborts the shared deadline signal before restoring
+            // the terminal, so Ctrl-C/q/Esc can never be swallowed by in-flight work.
+            if (key === '\x03' || key === 'q' || key === '\x1b') {
+                cleanup();
+                resolve();
+                return;
+            }
+            if (deleteInFlight || wakeInFlight)
                 return;
             // Delete confirmation mode
             if (confirmDelete) {
@@ -4711,16 +5025,11 @@ function interactiveSessionPicker(active, probeSnapshot) {
                 else {
                     flash = { style: 'dim', text: '取消删除' };
                 }
-                render();
+                if (!pickerClosed)
+                    render();
                 return;
             }
             flash = null;
-            // Ctrl-C or q or Esc
-            if (key === '\x03' || key === 'q' || key === '\x1b') {
-                cleanup();
-                resolve();
-                return;
-            }
             if (rows.length === 0) {
                 // No sessions left, only q works
                 render();
@@ -4752,11 +5061,40 @@ function interactiveSessionPicker(active, probeSnapshot) {
                     render();
                     return;
                 }
-                if (!selected.canAttach) {
+                if (!selected.canAttach && !selected.canWake) {
                     flash = { style: 'warn', text: '该会话没有可连接的持久后端' };
                     render();
                     return;
                 }
+                if (selected.canWake) {
+                    const target = selected.backendTarget;
+                    if (!target) {
+                        flash = { style: 'error', text: '恢复目标缺失' };
+                        render();
+                        return;
+                    }
+                    wakeInFlight = true;
+                    const wakeController = new AbortController();
+                    wakeAbortController = wakeController;
+                    flash = { style: 'warn', text: `正在恢复 ${target.backendType}: ${persistentTargetDisplay(target)}…` };
+                    render();
+                    const recovered = await wakeDormantBackendForAttach({
+                        target,
+                        wake: context => requestDormantSessionWake(selected.session, context),
+                        probe: probePersistentBackendTarget,
+                        signal: wakeController.signal,
+                    });
+                    if (wakeAbortController === wakeController)
+                        wakeAbortController = null;
+                    wakeInFlight = false;
+                    if (pickerClosed)
+                        return;
+                    if (!recovered.ok) {
+                        flash = { style: 'error', text: `恢复失败: ${recovered.error}` };
+                        render();
+                        return;
+                    }
+                }
                 if (selected.attachBackend === 'zmx') {
                     const target = selected.backendTarget;
                     if (!target || target.backendType !== 'zmx') {
@@ -4795,7 +5133,8 @@ function interactiveSessionPicker(active, probeSnapshot) {
                 resolve();
                 return;
             }
-        });
+        }
+        process.stdin.on('data', onInput);
     });
 }
 /**
@@ -4974,6 +5313,7 @@ async function cmdDelete() {
     let closed = 0;
     let offline = 0;
     let failed = 0;
+    let residual = 0;
     for (const s of toDelete) {
         // Explicit abandon boundary: route through the owning daemon so the ledger
         // FIFO is cleared atomically with close; offline fallback rereads the row
@@ -4990,9 +5330,16 @@ async function cmdDelete() {
             if (result.cleanedBacking)
                 console.log(`  killed ${result.cleanedBacking}`);
         }
+        if (result.mode === 'daemon' && result.residual) {
+            // Local row closed, remote session NOT cancelled. Reported per session AND
+            // counted in the summary, so a bulk delete cannot bury it.
+            residual++;
+            console.warn(`⚠ ${s.sessionId.substring(0, 8)} ${s.title}：本地已关闭，但${closeResidualClause(result.residual)}`);
+            continue;
+        }
         console.log(`✓ ${s.sessionId.substring(0, 8)} ${s.title}${result.mode === 'offline' ? '（daemon 离线，本地收口）' : ''}`);
     }
-    console.log(`\n已关闭 ${closed} 个会话${offline ? `（${offline} 个离线收口）` : ''}${failed ? `，${failed} 个失败` : ''}`);
+    console.log(`\n已关闭 ${closed} 个会话${offline ? `（${offline} 个离线收口）` : ''}${failed ? `，${failed} 个失败` : ''}${residual ? `，${residual} 个有残留需人工清理` : ''}`);
     if (failed > 0)
         process.exitCode = 1;
 }
@@ -5200,7 +5547,7 @@ async function cmdSuspend() {
     if (failed > 0)
         process.exitCode = 1;
 }
-/** 会话级 CLI IPC（slash/cd/close）的 POST：与 postAsk 同款双路径——能读 host secret
+/** 会话级 CLI IPC（slash/cd/close/preview）的 POST：与 postAsk 同款双路径——能读 host secret
  *  （非隔离进程）走 trusted-host HMAC 签名；读不到（沙箱 BOTMUX_SEND_RELAY /
  *  macOS 读隔离 carve-out）改带本会话当前轮换的 origin capability，由 daemon
  *  handler 与活跃记录比对。两条路都不读 bots.json。 */
@@ -5233,6 +5580,82 @@ async function postSessionCliIpc(ipcPort, sessionId, route, payload) {
         ? fetchDaemonIpc(ipcPort, path, init, hostSecret)
         : fetch(`http://127.0.0.1:${ipcPort}${path}`, init);
 }
+/** `botmux preview <port>` registers a reachable loopback Web service for the
+ * exact current session. There is intentionally no `--session` escape hatch:
+ * ancestry/env resolution plus the rotating session capability prove which
+ * agent is volunteering the port. The daemon performs the authoritative port
+ * validation/probe and persists the result. */
+async function cmdPreview(rest) {
+    if (rest.length !== 1 || !/^\d+$/.test(rest[0])) {
+        console.error('用法: botmux preview <port>');
+        process.exit(1);
+    }
+    const port = Number(rest[0]);
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+        console.error('✗ 端口必须是 1-65535 的整数');
+        process.exit(1);
+    }
+    const ctx = findAncestorSessionContext();
+    if (!ctx?.sessionId) {
+        console.error('✗ 无法定位当前会话；preview 只能在 botmux 会话内注册');
+        process.exit(1);
+    }
+    let discoveredPort;
+    try {
+        discoveredPort = findDaemon(process.env.BOTMUX_LARK_APP_ID)?.ipcPort;
+    }
+    catch {
+        // Sandboxed/read-isolated sessions cannot enumerate daemon descriptors.
+    }
+    const ipcPort = resolveDaemonIpcPort(discoveredPort, process.env.BOTMUX_DAEMON_IPC_PORT);
+    if (!ipcPort) {
+        console.error('✗ 无法定位当前会话的 daemon；请确认 daemon 正在运行');
+        process.exit(1);
+    }
+    let response;
+    try {
+        response = await postSessionCliIpc(ipcPort, ctx.sessionId, 'preview', { port });
+    }
+    catch {
+        console.error('✗ 无法连接当前会话的 daemon');
+        process.exit(1);
+    }
+    const body = await response.json().catch(() => ({}));
+    if (response.ok && body.ok && typeof body.preview?.path === 'string') {
+        console.log(`✓ Web 预览已注册: ${body.preview.path}`);
+        return;
+    }
+    const error = body.error ?? `HTTP ${response.status}`;
+    if (error === 'preview_unreachable') {
+        console.error('✗ 端口不可达；请先让 Web 服务监听本机 loopback/0.0.0.0 后再注册');
+    }
+    else if (error === 'preview_owner_unverified') {
+        // P1-12：端口上确实有人在监听，但证明不了那是本会话起的进程。宁可没有预览，
+        // 也不把 Dashboard 用户代理进一个来路不明的本机服务。
+        console.error('✗ 无法确认该端口由本会话的进程持有；请在会话内直接启动 Web 服务后再注册'
+            + '（不要用 setsid/nohup 脱离进程树，也不要注册别的程序占用的端口）');
+    }
+    else if (error === 'preview_unsupported') {
+        console.error('✗ 当前会话后端（远端 sandbox）的 Web 服务不在本机，Dashboard 预览不支持');
+    }
+    else if (error === 'preview_generation_changed') {
+        console.error('✗ 注册期间会话已换代或已关闭；请在新一轮里重新注册');
+    }
+    else if (error === 'preview_target_changed') {
+        // P1-3：并发注册（例如同时注册两个端口）时，后到的一方不再无声覆盖先落地的那个。
+        console.error('✗ 注册期间本会话的预览目标已被另一次注册改写；同一时刻只能有一个预览目标，请确认后重试');
+    }
+    else if (error === 'remote_host_forbidden') {
+        console.error('✗ 只允许注册本机 loopback 服务');
+    }
+    else if (error === 'origin_unproven' || error === 'managed_action_required') {
+        console.error('✗ 当前会话归属校验失败');
+    }
+    else {
+        console.error(`✗ 预览注册失败: ${error}`);
+    }
+    process.exit(1);
+}
 async function cmdChat(argv) {
     const sub = argv[0] ?? '';
     if (sub !== 'rename') {
@@ -6048,7 +6471,7 @@ botmux v${getVersion()} — IM ↔ AI 编程 CLI 桥接
   start       启动 daemon，并启动 mode=auto 的插件 service
   stop        停止 daemon（默认不停止插件 service；--with-plugin 显式停止 mode=auto 的插件 service）
   restart     重启 daemon（默认不停止插件 service，core 启动后确保 mode=auto 正在运行；--with-plugin 显式先停再启动 auto service）
-              --include-pm2 仅允许“入场时没有 live PM2 God”的干净启动；若已有 live God，整条命令会在 fleet/breadcrumb 零改动处拒绝，且不会信号或重启现存 God
+              --include-pm2 在 fleet 安全退役并验证后，经 PM2_HOME socket 退役 PM2 God（绝不按 PID 发信号），再以当前干净环境全新启动——彻底重启整棵进程树；会先优雅停止全部插件 service（auto 的启动后自动恢复）
               首次升级若旧 daemon 缺少 shutdown protocol：先独立确认所有 Session/Riff 工作均 idle，再一次性运行
               botmux restart --bootstrap-shutdown-protocol --yes；普通 stop/restart 仍保持 fail-closed
   logs        查看 daemon 日志（--lines N, --bot <0-based-index|pm2-name|appId>）
@@ -6060,6 +6483,9 @@ botmux v${getVersion()} — IM ↔ AI 编程 CLI 桥接
               显式轮换 token，并打印新的登录 URL
   device enroll|status|logout
               在宿主终端注册、查看或清除 desktop device 凭证（AI CLI 会话内拒绝）
+  mojo-containment list|revoke
+              查看 / 显式撤销无法自证静止的 mojo containment handle（设备隔离
+              blocker 的可审计操作员出口；revoke 需 --yes，存活证据需 --force）
   list        列出活跃会话（交互式选择并连接 tmux）
               --plain  纯文本表格输出（管道/脚本场景）
   delete <id>      关闭指定会话（支持 ID 前缀匹配）
@@ -6077,6 +6503,10 @@ botmux v${getVersion()} — IM ↔ AI 编程 CLI 桥接
   term-link [id]   获取活跃会话的「可操作终端」（带写 token）。不回显链接，改由
                    daemon 把可操作卡片私密发给 owner（群内仅你可见，话题/单聊回退 DM）。
                    单个活跃会话可省略 id
+  preview <port>   （会话内）注册当前会话已启动的本机 Web 服务；Dashboard 登录后通过
+                   同源 /preview/<sessionId>/ 访问，不暴露本机地址或任何 token。
+                   端口必须由本会话的进程持有（在会话内直接启动，别 setsid/nohup
+                   脱离进程树）；换代/关闭后需重新注册，远端 sandbox 后端不支持
   autostart enable     注册开机自启（macOS launchd / Linux user systemd / Windows Task Scheduler，无需 sudo）
   autostart disable    注销开机自启
   autostart status     查看自启状态
@@ -7177,7 +7607,7 @@ import { resolveFeedbackPolicyForDelivery, resolveFeedbackTeamId } from './servi
 import { normalizeFeedbackPolicy } from './services/feedback-policy.js';
 import { applyInlineMentions } from './im/lark/inline-mentions.js';
 import { renderBrandTemplate } from './im/lark/brand-template.js';
-import { resolveBrandLabel, resolveUsageDisplay } from './bot-registry.js';
+import { effectiveDefaultWorkingDir, loadBotConfigs, resolveBrandLabel, resolveUsageDisplay } from './bot-registry.js';
 import { config } from './config.js';
 import { getSessionUsageSnapshot } from './core/cost-calculator.js';
 import { resolveQuoteTarget, validateMentionDecision, mentionBackAmbiguity, mentionBackAmbiguityError, parseAttentionFlag, attentionUsageError, managedVcQuoteError, managedVcCustomCardError, managedVcSendControlError, managedVcSendPayloadError, containsLarkAtTag, } from './services/send-policy.js';
@@ -7230,6 +7660,7 @@ async function relaySend(rest, relayDir) {
         const pos = positionals(rest, ['--card', '--text', '--top-level', '--no-quote', '--mention-back', '--no-mention', '--anyway', '--voice', '--slash']);
         content = pos.length > 0 ? pos.join(' ') : await readStdin();
     }
+    content = stripTrailingOaiMemoryCitation(content);
     const preparedCardContent = cardJsonArg === undefined && cardFile === undefined && !rest.includes('--voice')
         ? prepareCardMarkdown(extractCardText(content), process.cwd(), 'filesystem')
         : undefined;
@@ -8301,6 +8732,9 @@ async function cmdSend(rest) {
             content = await readStdin();
         }
     }
+    // Keep memory attribution in the model's rollout, but never render the
+    // complete internal suffix into Lark or count it in send markers.
+    content = stripTrailingOaiMemoryCitation(content);
     if (!contentFile && !customCardRequested)
         rejectLikelyWindowsStdinMojibake(content);
     const managedPayloadError = managedVcSendPayloadError({
@@ -8991,8 +9425,8 @@ async function cmdSend(rest) {
     };
     try {
         // A file-sandbox relay supplies a host-private copy normalized inside the
-        // sandbox namespace. Voice/doc-comment paths returned above and therefore
-        // continue using the untouched raw content.
+        // sandbox namespace. Voice/doc-comment paths returned above use the same
+        // already-sanitized outbound content, without card-markdown preparation.
         let text = extractCardText(content);
         const preparedContentFile = process.env.BOTMUX_CARD_PREPARED_CONTENT_FILE;
         if (preparedContentFile) {
@@ -9939,6 +10373,7 @@ async function cmdReport(rest) {
         const pos = positionals(rest, ['--top-level', '--legacy-dispatch']);
         content = pos.length ? pos.join(' ') : await readStdin();
     }
+    content = stripTrailingOaiMemoryCitation(content);
     if (!contentFile)
         rejectLikelyWindowsStdinMojibake(content);
     if (!content.trim()) {
@@ -10307,6 +10742,16 @@ botmux create-group — 用一组机器人新建飞书群
   --json-status    可选；在 chatId 后追加一行结构化完成状态。默认 stdout 无论完整成功或
                    部分失败都保持历史兼容，只输出单行 chatId；部分失败仍以非零退出表示。
 
+团队模式（跨机建聚焦新群，走中心化平台）:
+  botmux create-group --team <teamId> --agent <appId> [--agent ...] [--name "群名"]
+
+  用途：把「同团队、已 opt-in」的**别人机器上的** agent（用 bots list --scope team 发现到的 appId）
+  和它们各自的 owner 一起拉进一个平台代建的聚焦新群，全程 machine-auth。
+  正因为发起人在别人 bot 进群前 @不到它，这条只认 appId、不依赖任何飞书 @，天然绕开视角问题。
+  --agent 至少一个、可多次、按 appId 去重。团队模式忽略 --bot/--kickoff/--working-dir（那些是本机建群用的）。
+  未传 --team：本机唯一团队则自动用它，多个要求显式指定。
+  （往**已存在**的团队群补人是独立命令：botmux bots invite --chat <chatId> --team X --agent ...）
+
 行为:
   - 第一个解析到的 bot 作为 creator（决定建群身份 + 初始群主 + open_id app scope）。
   - 邀请用户 / 转让群主 / @通知 对象都从 creator 的 resolvedAllowedUsers 取首个 open_id（email 自动转换；
@@ -10325,6 +10770,21 @@ botmux create-group — 用一组机器人新建飞书群
 `);
         return;
     }
+    // Deprecation 闸：--chat 曾经是 create-group 的「往已有群补人」模式，现已拆成独立命令
+    // `bots invite`。若仍传 --chat，必须**报错早退**而不是静默忽略——否则用户本意补人、
+    // 却因 --chat 被丢弃照常建了个新群（真实副作用，多一个群）。放在 team 分流之前拦。
+    if (hasFlagOrEq(rest, '--chat')) {
+        console.error('create-group 不再支持 --chat（往已有群补人已拆成独立命令）。请改用：');
+        console.error('  botmux bots invite --chat <chatId> --team <id> --agent <appId>...');
+        process.exit(1);
+    }
+    // 团队模式：走平台端点3 建新群，与本机飞书建群是两条完全不同的路径。必须在 transport
+    // 闸门之前分流——平台代建群，本机 bot 不需要飞书传输身份（沙盒/apiOnly 也能发起）。
+    // 「往已有群补人」是独立的 `bots invite`，不在这里。
+    if (hasFlagOrEq(rest, '--team') || hasFlagOrEq(rest, '--agent')) {
+        await cmdCreateGroupTeam(rest);
+        return;
+    }
     // create-group builds a real Feishu group (cross-bot). A no-transport turn
     // (apiOnly bot or HTTP virtual session) may not originate one — central gate.
     assertTurnTransportOrExit('create-group');
@@ -10535,6 +10995,110 @@ botmux create-group — 用一组机器人新建飞书群
     if (!completion.success)
         process.exitCode = 1;
 }
+/**
+ * `botmux create-group --team <teamId> --agent <appId>...` — 跨机拉群（走中心化平台端点3）。
+ *
+ * 与本机飞书建群（cmdCreateGroup 主体）是两条不同路径：这里把「同团队、已 opt-in」的、
+ * **别人机器上的** agent（appId 从 bots list --scope team 发现而来）+ 各自 owner + 本机 owner
+ * 一起拉进一个平台代建的聚焦新群。全程 machine-auth、只认 appId、不依赖任何飞书 @。
+ *
+ * 硬约束：CLI 零授权判断（团队成员校验 + opt-in 闸 team.bots 全在平台）；平台把未 opt-in /
+ * 拉不动的对象放进 invalidBotIds / invalidOwnerUnionIds 原样带回，这里只如实展示、不解释成
+ * "失败"（未 opt-in 是对方 owner 没加进团队，不是本次调用错）。
+ *
+ * 输出协议对齐主命令：成功拿到 chatId → stdout 写单行 chatId（skill 友好）；--json-status
+ * 追加一行结构化 JSON（含 shareLink / invalid* / 部分失败标记）。有 invalid* 时 exit 非零，
+ * 但 stdout 的 chatId 已经可用（群已建，别重建）。
+ */
+/**
+ * 解析团队维度命令的目标 teamId：显式 --team 优先；否则打端点1，唯一即用、多个要求指定、
+ * 零个报错。用于「必须落到一个具体 team」的动作（建群 / 补人）——list 侧的空 team 是正常态、
+ * 输出空列表，不走这里。`action` 只用于文案（"拉群"/"补人"）。
+ */
+async function resolveSingleTeamIdOrExit(fetchTeams, describeTeamAgentsFailure, teamArg, action) {
+    if (teamArg)
+        return teamArg;
+    const teamsRes = await fetchTeams();
+    if (!teamsRes.ok) {
+        if (teamsRes.reason === 'unbound')
+            console.error(`本机未绑定平台。${action}需要先 botmux bind。`);
+        else if (teamsRes.reason === 'not_deployed')
+            console.error('平台尚未部署团队端点，等上线后重试。');
+        else
+            console.error(`拉取团队列表失败：${describeTeamAgentsFailure(teamsRes)}`);
+        process.exit(1);
+    }
+    const teams = teamsRes.value;
+    if (teams.length === 0) {
+        console.error(`本机未加入任何平台团队，无法${action}。`);
+        process.exit(1);
+    }
+    if (teams.length > 1) {
+        console.error('本机属于多个平台团队，请用 --team <id> 指定其一：');
+        for (const t of teams)
+            console.error(`  ${t.teamId}  ${t.teamName}`);
+        process.exit(1);
+    }
+    return teams[0].teamId;
+}
+async function cmdCreateGroupTeam(rest) {
+    const { fetchTeams, createTeamGroup, describeTeamAgentsFailure, rateLimitRetryHint } = await import('./platform/team-agents-client.js');
+    const jsonStatus = rest.includes('--json-status');
+    const name = argValue(rest, '--name');
+    const appIds = [...new Set(argValues(rest, '--agent').map(s => s.trim()).filter(Boolean))];
+    if (appIds.length === 0) {
+        console.error('团队模式需要至少一个 --agent <appId>（用 botmux bots list --scope team 发现 appId）。');
+        process.exit(1);
+    }
+    const teamId = await resolveSingleTeamIdOrExit(fetchTeams, describeTeamAgentsFailure, argValue(rest, '--team'), '拉群');
+    const res = await createTeamGroup({ teamId, appIds, ...(name !== undefined ? { name } : {}) });
+    if (!res.ok) {
+        if (res.reason === 'unbound')
+            console.error('本机未绑定平台。拉群需要先 botmux bind。');
+        else if (res.reason === 'not_deployed')
+            console.error('平台尚未部署拉群端点（/v1/machine/groups）。等平台上线后重试。');
+        else if (res.reason === 'rate_limited')
+            console.error(`拉群被限流，${rateLimitRetryHint(res)}。`);
+        else if (res.reason === 'client' && res.status === 403) {
+            // 403 not_in_team_bots：所选 agent（或本机 bot）没 opt-in 进团队。平台可能带回具体 appIds。
+            const which = res.appIds && res.appIds.length ? `：${res.appIds.join('、')}` : '';
+            console.error(`拉群被拒（403 ${res.error}）：请确认相关 bot 已由其 owner 在平台「管理机器人」加入该团队${which}。`);
+        }
+        else if (res.reason === 'client' && res.status === 404) {
+            console.error(`团队不存在或本机 owner 不是其成员：teamId=${teamId}`);
+        }
+        else {
+            console.error(`拉群失败：${describeTeamAgentsFailure(res)}`);
+        }
+        process.exit(1);
+    }
+    const { chatId, shareLink, invalidBotIds, invalidOwnerUnionIds } = res.value;
+    if (!chatId) {
+        // 平台回 ok 但没给 chatId：异常，别静默成功。
+        console.error(`平台未返回 chatId（ok=${res.value.ok}）。`);
+        if (jsonStatus)
+            console.log(JSON.stringify({ ...res.value, ok: false }));
+        process.exit(1);
+    }
+    // stdout 单行 chatId（skill 友好，主命令同款协议）。
+    console.log(chatId);
+    const hasInvalid = invalidBotIds.length > 0 || invalidOwnerUnionIds.length > 0;
+    if (jsonStatus) {
+        console.log(JSON.stringify({ ok: true, chatId, shareLink, invalidBotIds, invalidOwnerUnionIds, teamId }));
+    }
+    // 未 opt-in / 拉不动的对象走 stderr 提示（不污染 stdout 的 chatId 契约）。
+    if (invalidBotIds.length > 0) {
+        console.error(`⚠️ 以下 agent 未加入团队或拉取失败，未入群：${invalidBotIds.join('、')}`);
+    }
+    if (invalidOwnerUnionIds.length > 0) {
+        console.error(`⚠️ 以下 owner 未能拉入：${invalidOwnerUnionIds.join('、')}`);
+    }
+    if (shareLink)
+        console.error(`群分享链接：${shareLink}`);
+    // 部分失败 → 非零退出（但群已建、chatId 已在 stdout，调用方应复用不重建）。
+    if (hasInvalid)
+        process.exitCode = 1;
+}
 // ─── Bots subcommand ─────────────────────────────────────────────────────────
 // ─── botmux ask v0.1.7 ───────────────────────────────────────────────────────
 //
@@ -11179,8 +11743,28 @@ async function cmdUserPromptHook() {
 }
 async function cmdBots(sub, rest) {
     process.env.SESSION_DATA_DIR ??= resolveDataDir();
+    // `bots invite`：往**已存在的团队群**补人（同 team、已 opt-in 的 agent + 各自 owner），
+    // 打平台端点4（machine-auth）。独立子命令——与「建新群」的 create-group 语义分开，
+    // 不再靠 create-group --chat 区分（那个入口易被误读成"建群"）。在会话/transport 闸门前分流。
+    if (sub === 'invite') {
+        await cmdBotsInvite(rest);
+        return;
+    }
     if (sub !== 'list' && sub !== 'ls' && sub !== '') {
-        console.error('用法: botmux bots list [--session-id ID]');
+        console.error('用法: botmux bots list [--scope chat|team] [--team <id>] [--session-id ID]');
+        console.error('      botmux bots invite --chat <chatId> --team <id> --agent <appId>...');
+        process.exit(1);
+    }
+    // `--scope team`：跨机发现同团队、已 opt-in 的 agent（打平台端点2，machine-auth）。
+    // 与默认的 chat scope 完全不同——它不读飞书群花名册、不需要会话/传输身份，
+    // 所以在会话解析 / transport 闸门之前分流。空 team 列表是正常态（没别人 opt-in）。
+    const scope = (argValue(rest, '--scope') ?? 'chat').toLowerCase();
+    if (scope === 'team') {
+        await cmdBotsListTeam(rest);
+        return;
+    }
+    if (scope !== 'chat') {
+        console.error(`未知 --scope "${scope}"（仅支持 chat | team）`);
         process.exit(1);
     }
     // `bots list` reads the Feishu chat roster (listChatBotMembers). A no-transport
@@ -11208,6 +11792,26 @@ async function cmdBots(sub, rest) {
             botEntries = JSON.parse(readFileSync(botInfoPath, 'utf-8'));
     }
     catch { /* */ }
+    const collaborationFactsFor = (appIds) => {
+        const facts = Object.create(null);
+        const wanted = new Set(appIds.filter(Boolean));
+        try {
+            for (const cfg of loadBotConfigs()) {
+                if (!wanted.has(cfg.larkAppId))
+                    continue;
+                facts[cfg.larkAppId] = {
+                    workspaceSource: cfg.oncallChats?.some(c => c.chatId === s.chatId)
+                        ? 'oncall'
+                        : effectiveDefaultWorkingDir(cfg) ? 'default' : 'unknown',
+                    mentionMode: cfg.regularGroupMentionMode ?? 'always',
+                    replyMode: cfg.chatReplyModes?.[s.chatId] ?? cfg.regularGroupReplyMode ?? 'chat-topic',
+                    transport: cfg.apiOnly !== true,
+                };
+            }
+        }
+        catch { /* config unreadable under isolation: all facts stay unknown */ }
+        return facts;
+    };
     try {
         const { listChatBotMembers } = await import('./im/lark/client.js');
         const chatBots = await listChatBotMembers(appId, s.chatId);
@@ -11215,15 +11819,220 @@ async function cmdBots(sub, rest) {
         // botmux daemon on this host). 'introduce' = discovered via /introduce
         // collaboration command (external bot, possibly other-tenant). isSelf is
         // retained (not filtered) so the model can still identify itself when needed.
-        const result = formatChatBotsForCli(chatBots, appId);
-        console.log(JSON.stringify({ sessionId: sid, chatId: s.chatId, bots: result, total: result.length }, null, 2));
+        const result = formatChatBotsForCli(chatBots, appId, collaborationFactsFor(chatBots.map(bot => bot.larkAppId)));
+        console.log(JSON.stringify({ sessionId: sid, chatId: s.chatId, bots: result, total: result.length, collaborationHelp }, null, 2));
     }
     catch (err) {
         // Fallback to bots-info.json
-        const result = formatBotInfoEntriesForCli(botEntries, appId);
-        console.log(JSON.stringify({ sessionId: sid, bots: result, total: result.length, note: `chat query failed: ${err.message}` }, null, 2));
+        const result = formatBotInfoEntriesForCli(botEntries, appId, collaborationFactsFor(botEntries.map(bot => bot.larkAppId)));
+        console.log(JSON.stringify({ sessionId: sid, bots: result, total: result.length, collaborationHelp, note: `chat query failed: ${err.message}` }, null, 2));
     }
 }
+/**
+ * `botmux bots list --scope team [--team <id>]` — 跨机发现同团队、已 opt-in（owner
+ * 加进 team.bots）的 agent，打平台端点2（machine-auth，Bearer=machineToken）。
+ *
+ * 与 chat scope 的关键区别 + 硬约束：
+ *  - 走 machine-auth，不读飞书群花名册、不需要传输身份 → 沙盒/apiOnly bot 也能查。
+ *  - **CLI 不做任何授权判断**：团队成员校验 + opt-in 闸全在平台，这里只透传、只展示。
+ *  - specialties / mentionable 是 agent 自报 → 仅展示，不当可信凭据。
+ *  - 未传 --team：先打端点1 拉本机 owner 的团队；唯一就用它，多个要求显式 --team
+ *    （不猜），零个则提示本机没加入任何平台团队。
+ */
+async function cmdBotsListTeam(rest) {
+    const { fetchTeamAgents, fetchTeams, describeTeamAgentsFailure } = await import('./platform/team-agents-client.js');
+    const jsonOut = argFlag(rest, '--json');
+    let teamId = argValue(rest, '--team');
+    let teamNameHint;
+    if (!teamId) {
+        const teamsRes = await fetchTeams();
+        if (!teamsRes.ok) {
+            if (teamsRes.reason === 'unbound') {
+                console.error('本机未绑定平台（~/.botmux/platform.json 缺失）。团队发现需要先 botmux bind。');
+            }
+            else if (teamsRes.reason === 'not_deployed') {
+                console.error('平台尚未部署团队端点（/v1/machine/teams）。等平台上线后重试。');
+            }
+            else {
+                console.error(`拉取团队列表失败：${describeTeamAgentsFailure(teamsRes)}`);
+            }
+            process.exit(1);
+        }
+        const teams = teamsRes.value;
+        if (teams.length === 0) {
+            // 空不是错误：本机 owner 还没加入任何平台团队。
+            console.log(JSON.stringify({ scope: 'team', teams: [], agents: [], total: 0, note: '本机未加入任何平台团队' }, null, 2));
+            return;
+        }
+        if (teams.length > 1) {
+            console.error('本机属于多个平台团队，请用 --team <id> 指定其一：');
+            for (const t of teams)
+                console.error(`  ${t.teamId}  ${t.teamName}`);
+            process.exit(1);
+        }
+        teamId = teams[0].teamId;
+        teamNameHint = teams[0].teamName;
+    }
+    const res = await fetchTeamAgents(teamId);
+    if (!res.ok) {
+        if (res.reason === 'unbound') {
+            console.error('本机未绑定平台（~/.botmux/platform.json 缺失）。团队发现需要先 botmux bind。');
+        }
+        else if (res.reason === 'not_deployed') {
+            console.error('平台尚未部署团队 agent 发现端点（/v1/machine/agents）。等平台上线后重试。');
+        }
+        else if (res.reason === 'client' && res.status === 404) {
+            console.error(`团队不存在或本机 owner 不是其成员：teamId=${teamId}`);
+        }
+        else {
+            console.error(`拉取团队 agent 失败：${describeTeamAgentsFailure(res)}`);
+        }
+        process.exit(1);
+    }
+    const { teamName, agents } = res.value;
+    // 输出对齐 chat scope 的 JSON 形状（scope 标注 + total），字段是平台端点2 的原样透传。
+    // 提醒：发现列表只含**已加入 team.bots** 的 agent（owner 在平台「管理机器人」显式加入）。
+    console.log(JSON.stringify({
+        scope: 'team',
+        teamId,
+        teamName: teamName || teamNameHint || teamId,
+        agents,
+        total: agents.length,
+        note: '发现列表只含已加入团队（owner 在平台「管理机器人」opt-in）的 agent；specialties/mentionable 为 agent 自报，仅供参考不可信。',
+    }, null, jsonOut ? 0 : 2));
+}
+/**
+ * (a) 自动化辅助：把平台后端 app（platformAppId）拉进目标群 `chatId`。
+ *
+ * 飞书约束：加应用的 app 自己得在群里。所以找一个**已在该群、且本机可用凭据**的 bot 当代理
+ * （addBotToChat proxy）。优先用本会话 bot（它天然在本群且已注册），否则遍历 bots.json 里其它
+ * 非 apiOnly bot、逐个 isInChat 命中即用。全都不在群/加失败（无 scope、群需群主审批）→ 返回失败，
+ * 由调用方回退到手动引导。
+ */
+async function tryAutoAddPlatformBot(chatId, platformAppId) {
+    try {
+        const { findLocalBotInChat } = await import('./im/lark/client.js');
+        const { addBotToChat } = await import('./services/groups-store.js');
+        // 用安静探测客户端找一个「已在目标群」的本机 bot 当代理（本会话 bot 优先）。
+        // 不在群的 bot 探测 miss 被静音，不刷 axios 400 噪音（见 client.findLocalBotInChat）。
+        const proxy = await findLocalBotInChat(chatId, process.env.BOTMUX_LARK_APP_ID);
+        if (!proxy)
+            return { ok: false, reason: '本机没有已在该群的 bot 可当代理' };
+        // 代理 bot 需已在注册表（getBotClient 可用）——从 bots.json 注册一次（幂等）。
+        try {
+            const { loadBotConfigs, registerBot } = await import('./bot-registry.js');
+            const cfg = loadBotConfigs().find((c) => c.larkAppId === proxy.larkAppId);
+            if (cfg)
+                registerBot(cfg);
+        }
+        catch { /* 已注册或读配置失败 → addBotToChat 若拿不到 client 会报错并回退 */ }
+        const r = await addBotToChat(proxy.larkAppId, chatId, [platformAppId]);
+        const one = r[0];
+        if (one?.ok)
+            return { ok: true, proxyName: proxy.cliId ? `${proxy.cliId}/${proxy.larkAppId}` : proxy.larkAppId };
+        // 加失败（无 scope / 群需群主审批 / invalid）→ 回退手动引导。
+        return { ok: false, reason: `代理 ${proxy.larkAppId} 添加失败：${one?.error ?? 'unknown'}` };
+    }
+    catch (e) {
+        return { ok: false, reason: String(e?.message ?? e) };
+    }
+}
+/**
+ * `botmux bots invite --chat <chatId> --team <id> --agent <appId>...`
+ * —— 往**已存在的团队群**补人（同 team、已 opt-in 的 agent + 各自 owner），打平台端点4。
+ *
+ * 独立于 create-group（建新群）：语义是「群已经在了，往里加人」，不该跟建群混在一个命令里。
+ * 全程 machine-auth、只认 appId（发起人在别人 bot 进群前 @不到它，靠 appId 绕开视角问题）。
+ * 授权/opt-in 闸/大厅排除全在平台，CLI 零判断、只如实展示平台判定。
+ * 若平台回 platform_bot_not_in_chat 且带 platformAppId → 自动用群内本机 bot 把平台 app 拉进群、重试。
+ *
+ * 输出：stdout 单行 chatId（skill 友好，与 create-group 一致）；--json-status 追加
+ * {ok, chatId, invalidBotIds, invalidOwnerUnionIds, teamId}；invalid* 非空 → 非零退出。
+ */
+async function cmdBotsInvite(rest) {
+    const { addTeamGroupMembers, fetchTeams, describeTeamAgentsFailure, rateLimitRetryHint, shouldTryAutoAddPlatformBot } = await import('./platform/team-agents-client.js');
+    const jsonStatus = rest.includes('--json-status');
+    const chatArg = (argValue(rest, '--chat') ?? '').trim();
+    const appIds = [...new Set(argValues(rest, '--agent').map(s => s.trim()).filter(Boolean))];
+    if (!chatArg) {
+        console.error('用法: botmux bots invite --chat <chatId> --team <id> --agent <appId>...');
+        console.error('--chat 必填：目标群 chatId（须已有平台机器人 BotmuxPlatform 在场，且你本人已在该群，非机器人大厅）。');
+        console.error('补人恒把 agent + 各自 owner 一起拉进群。');
+        process.exit(1);
+    }
+    if (appIds.length === 0) {
+        console.error('至少一个 --agent <appId>（用 botmux bots list --scope team 发现 appId）。');
+        process.exit(1);
+    }
+    const teamId = await resolveSingleTeamIdOrExit(fetchTeams, describeTeamAgentsFailure, argValue(rest, '--team'), '补人');
+    let res = await addTeamGroupMembers({ chatId: chatArg, teamId, appIds });
+    // (a) 自动化：撞 platform_bot_not_in_chat 且平台回传了 platformAppId → 用群里已有的本机 bot
+    // 当代理，把平台后端 app 拉进目标群，再自动重试一次补人。让「往任意我在的群补人」尽量无感；
+    // 碰到「加 bot 需群主审批 / 代理 bot 无成员管理 scope」时 addBotToChat 会失败，落回下面的手动提示。
+    let autoAddAttempted = false;
+    if (shouldTryAutoAddPlatformBot(res)) {
+        const added = await tryAutoAddPlatformBot(chatArg, res.platformAppId);
+        if (added.ok) {
+            autoAddAttempted = true;
+            console.error(`（已用群内 bot「${added.proxyName}」把平台应用拉进群，重试补人…）`);
+            res = await addTeamGroupMembers({ chatId: chatArg, teamId, appIds });
+        }
+        else {
+            // 自动拉失败：给可操作的手动引导（用平台回传的 app 名/id），不静默。
+            const appLabel = res.platformAppName ? `${res.platformAppName}（${res.platformAppId}）` : res.platformAppId;
+            console.error(`补人前置：平台应用不在目标群，且自动添加未成功（${added.reason}）。`);
+            console.error(`请在群设置里手动添加应用：${appLabel}，然后重试 botmux bots invite。`);
+            process.exit(1);
+        }
+    }
+    if (!res.ok) {
+        if (res.reason === 'unbound')
+            console.error('本机未绑定平台。补人需要先 botmux bind。');
+        else if (res.reason === 'not_deployed')
+            console.error('平台尚未部署补人端点（/v1/machine/groups/:chatId/members）。等平台上线后重试。');
+        else if (res.reason === 'rate_limited')
+            console.error(`补人被限流，${rateLimitRetryHint(res)}。`);
+        else if (res.reason === 'client' && res.status === 403) {
+            // 403 分支（平台按 error code 返回）：可行性/归属/opt-in/大厅，各给可操作的提示。
+            const which = res.appIds && res.appIds.length ? `（${res.appIds.join('、')}）` : '';
+            const appLabel = res.platformAppName ? `${res.platformAppName}（${res.platformAppId ?? ''}）` : (res.platformAppId ?? '平台应用');
+            const hint = res.error === 'platform_bot_not_in_chat'
+                // 已自动拉过还撞它：飞书加 app 通常同步生效，多半是刚加完成员表还没刷新——提示稍等重试，
+                // 别让用户对着刚拉进去的 app 再手动加一遍（pi review nit）。没自动拉过才引导手动添加。
+                ? (autoAddAttempted
+                    ? `平台应用已自动拉进群、但补人仍报它不在——飞书成员同步通常几秒内完成，请稍等片刻重试 botmux bots invite`
+                    : `平台应用还不在目标群里——请在群设置添加应用：${appLabel}，再补人`)
+                : res.error === 'requester_not_in_chat' ? '你本人还不在目标群里——只能往「你自己已在场」的群补人（先加入该群）'
+                    : res.error === 'requester_bot_not_in_chat' ? '你本人还不在目标群里——只能往「你自己已在场」的群补人（先加入该群）'
+                        : res.error === 'chat_is_hall' ? '目标群是机器人大厅，不允许往里补人（大厅是 bot-only 身份登记群）'
+                            : res.error === 'chat_not_in_team' ? '目标群不是本团队的协作群'
+                                : `相关 bot${which} 未由其 owner 在平台「管理机器人」加入该团队`;
+            console.error(`补人被拒（403 ${res.error}）：${hint}。`);
+        }
+        else if (res.reason === 'client' && res.status === 404) {
+            console.error(`团队不存在或本机 owner 不是其成员：teamId=${teamId}`);
+        }
+        else {
+            console.error(`补人失败：${describeTeamAgentsFailure(res)}`);
+        }
+        process.exit(1);
+    }
+    const { invalidBotIds, invalidOwnerUnionIds } = res.value;
+    console.log(chatArg); // stdout 单行 chatId（与 create-group 一致）
+    const hasInvalid = invalidBotIds.length > 0 || invalidOwnerUnionIds.length > 0;
+    if (jsonStatus) {
+        console.log(JSON.stringify({ ok: true, chatId: chatArg, invalidBotIds, invalidOwnerUnionIds, teamId }));
+    }
+    // 补人幂等（已在群内视作成功）；平台 200 不列「实际加了谁」，成功即 invalid* 为空。
+    if (!hasInvalid)
+        console.error('✅ 补人成功（选中的 agent 及其 owner 均已在群内或已加入）。');
+    if (invalidBotIds.length > 0)
+        console.error(`⚠️ 以下 agent 未加入团队或补入失败：${invalidBotIds.join('、')}`);
+    if (invalidOwnerUnionIds.length > 0)
+        console.error(`⚠️ 以下 owner 未能补入：${invalidOwnerUnionIds.join('、')}`);
+    if (hasInvalid)
+        process.exitCode = 1;
+}
 // ─── botmux lang ─────────────────────────────────────────────────────────────
 /** Notify every online daemon to hot-reload its UI locale from disk, so a
  *  `botmux lang` change takes effect on live cards without a restart. Best
@@ -11551,6 +12360,9 @@ if (process.env.BOTMUX_WORKFLOW === '1') {
         'bots',
         'skill',
         'hook',
+        // Local-only, session-capability-bound preview registration. It has no chat,
+        // workflow, deployment, or external messaging effect.
+        'preview',
         'session-ready',
         'mcp',
         'ask', // dedicated cmdAsk guard emits the humanGate-specific guidance
@@ -11764,6 +12576,7 @@ async function stopPluginServicesForCli(pluginIds, options = {}) {
         console.log('\n插件 host service:');
         console.log(formatPluginServiceReports(reports));
     }
+    return reports;
 }
 function requirePluginId(raw) {
     const id = raw?.trim();
@@ -12339,10 +13152,10 @@ switch (command) {
         await cmdRestart();
         break;
     case 'logs':
-        cmdLogs();
+        await cmdLogs();
         break;
     case 'status':
-        cmdStatus();
+        await cmdStatus();
         break;
     case 'upgrade':
     case 'update':
@@ -12362,6 +13175,13 @@ switch (command) {
         process.exitCode = await runDeviceCommand(process.argv.slice(3));
         break;
     }
+    case 'mojo-containment': {
+        // The auditable operator exit for fail-closed containment blockers that can
+        // never self-release (weak handles on non-cgroup hosts, unprovable handles).
+        const { runMojoContainmentCommand } = await import('./core/mojo-containment-command.js');
+        process.exitCode = await runMojoContainmentCommand(process.argv.slice(3));
+        break;
+    }
     case 'list':
     case 'ls':
         await cmdList();
@@ -12409,6 +13229,9 @@ switch (command) {
     case 'term-link':
         await cmdTermLink(process.argv.slice(3));
         break;
+    case 'preview':
+        await cmdPreview(process.argv.slice(3));
+        break;
     case 'schedule':
         await cmdSchedule(process.argv[3] ?? '', process.argv.slice(4));
         break;