botmux 3.7.1 → 3.8.0

package/dist/cli.js

@@ -13,7 +13,7 @@
  *   botmux status         — show daemon status
  *   botmux upgrade|update — upgrade to latest version
  *   botmux device enroll|status|logout — manage the host desktop device credential
- *   botmux list           — interactive session picker (TUI), attach to tmux
+ *   botmux list           — interactive session picker (TUI), attach to managed tmux/ZMX sessions
  *   botmux list --plain   — plain table output (for piping / scripts)
  *   botmux delete <id>    — close a session by ID prefix
  *   botmux delete all     — close all active sessions
@@ -53,6 +53,7 @@ import { scheduleTimeZone } from './utils/timezone.js';
 import { expandHomePath, invalidWorkingDirs } from './utils/working-dir.js';
 import { firstPositional } from './cli/arg-utils.js';
 import { isColdResumeDormant, sessionListDisposition } from './cli/session-list-liveness.js';
+import { attachFrozenManagedZmxSession, freezeManagedZmxAttachTarget, } from './cli/zmx-managed-attach.js';
 import { dispatchPrimaryMessage, findStdinAliasAttachment, normalizeInteractiveCardInput, sendFileAttachments, sendVideoAttachments, shouldSendAsPureVideo, validateVideoAttachments } from './cli/send-dispatch.js';
 import { dispatchDeferredTopicSend } from './cli/deferred-topic-send.js';
 import { resolveDaemonEnv } from './cli/daemon-lifecycle-env.js';
@@ -70,11 +71,11 @@ import { rejectLikelyWindowsStdinMojibake, decodeStdinBytes } from './cli/stdin-
 import { 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 { isLocale, localeForBot, setDefaultLocale, SUPPORTED_LOCALES } from './i18n/index.js';
 import { chatAppLink, larkHosts, normalizeBrand, sdkDomain } 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 } from './services/bridge-fallback-gate.js';
+import { buildBridgeSendMarkerContent, buildBridgeSendPreviewText, } from './services/bridge-fallback-gate.js';
 import { bindRestartLeaseTo, writeManualIntentIfAbsentTo } from './services/restart-intent-store.js';
 import { repairMissingChatScope, stripLegacyPendingCardFields } from './services/session-store.js';
 import { evaluateVcMeetingManagedSend, isTrustedVcMeetingHostRelayParent, resolveVcMeetingImTurnOrigin, } from './services/vc-meeting-send-policy.js';
@@ -86,6 +87,7 @@ import { assertPluginBindingTransition, describePluginDependencyError, enabledPl
 import { authorizeV3DaemonCommand } from './workflows/v3/cli-daemon-command-authority.js';
 import { resolveDaemonIpcPort } from './utils/daemon-discovery.js';
 import { inspectBotmuxPm2Apps, isExactPm2BotActivationReceipt, managedActivationPm2Disposition, parsePm2JlistOutputStrict as parsePm2JlistOutput, stopExactPm2Process, } from './core/bot-live-control.js';
+import { isSuspendableBackendType, killPersistentBackendTarget, probePersistentBackendTarget, probePersistentSessions, resolvePersistentBackendTarget, } from './core/persistent-backend.js';
 // Resolve the CLI's UI locale once from the global config file, so subsequent
 // CLI output (and any t() callers that don't pass an explicit locale) honour
 // the user's chosen language. Daemon entrypoint sets this separately for the
@@ -329,6 +331,85 @@ function ensureUniqueBotProcessNames(bots) {
         }
     }
 }
+/**
+ * `botmux serve --api-only` — run a single-process, headless core-only service
+ * in the FOREGROUND (stdio inherited so a launcher can watch the ready line and
+ * the process lifetime IS the service). No pm2, no dashboard, no bots.json, no
+ * Feishu credentials. See src/index-core-only.ts for the full contract.
+ */
+async function cmdServe(args) {
+    const apiOnly = args.includes('--api-only');
+    if (!apiOnly) {
+        console.error('Usage: botmux serve --api-only [--port <PORT>] [--bot <local_slug>] [--cli <cliId>] [--state-dir <DIR>]');
+        console.error('  Only core-only (--api-only) serving is supported. It runs a headless HTTP');
+        console.error('  control-API service with no Feishu credentials (for riff sandbox / embedding).');
+        process.exit(2);
+    }
+    const getOpt = (flag) => {
+        const i = args.indexOf(flag);
+        return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+    };
+    const port = getOpt('--port') ?? process.env.BOTMUX_API_PORT;
+    if (!port || !/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535) {
+        console.error(`botmux serve --api-only: --port (or BOTMUX_API_PORT) must be a valid port; got: ${port ?? '(unset)'}`);
+        process.exit(2);
+    }
+    const bot = getOpt('--bot') ?? process.env.BOTMUX_API_ONLY_BOT;
+    const cli = getOpt('--cli') ?? process.env.BOTMUX_CORE_CLI;
+    const workingDir = getOpt('--working-dir') ?? process.env.BOTMUX_CORE_WORKING_DIR;
+    const stateDir = getOpt('--state-dir') ?? process.env.BOTMUX_CORE_STATE_DIR;
+    const coreScript = join(PKG_ROOT, 'dist', 'index-core-only.js');
+    const child = spawn(process.execPath, [coreScript], {
+        stdio: 'inherit',
+        env: (() => {
+            const e = {
+                ...process.env,
+                BOTMUX_CORE_ONLY: '1',
+                BOTMUX_API_PORT: port,
+                // Freeze worker HTTP to loopback here too (defense-in-depth with the
+                // entrypoint) so a stray parent/dotenv 0.0.0.0 never reaches the child.
+                BOTMUX_WORKER_HTTP_HOST: '127.0.0.1',
+                ...(bot ? { BOTMUX_API_ONLY_BOT: bot } : {}),
+                ...(cli ? { BOTMUX_CORE_CLI: cli } : {}),
+                ...(workingDir ? { BOTMUX_CORE_WORKING_DIR: workingDir } : {}),
+                ...(stateDir ? { BOTMUX_CORE_STATE_DIR: stateDir } : {}),
+            };
+            // Never hand an ambient BOTS_CONFIG / legacy worker-host alias / ambient
+            // SESSION_DATA_DIR to the core-only child — the entrypoint freezes/strips
+            // these too, but keep the spawn env clean from the start (codex P1: agent
+            // could read $BOTS_CONFIG; ambient SESSION_DATA_DIR would point at a host
+            // fleet's store). The entrypoint re-derives a dedicated core-only state root.
+            delete e.BOTS_CONFIG;
+            delete e.BOTMUX_WORKER_HOST;
+            delete e.SESSION_DATA_DIR;
+            return e;
+        })(),
+    });
+    // Foreground lifetime tracks the child: forward termination signals and exit
+    // with the child's code so a launcher/supervisor sees an honest status.
+    const forward = (sig) => { try {
+        child.kill(sig);
+    }
+    catch { /* */ } };
+    process.on('SIGTERM', () => forward('SIGTERM'));
+    process.on('SIGINT', () => forward('SIGINT'));
+    await new Promise((resolve) => {
+        child.on('exit', (code, signal) => {
+            if (signal) {
+                process.exitCode = 1;
+            }
+            else {
+                process.exitCode = code ?? 0;
+            }
+            resolve();
+        });
+        child.on('error', (err) => {
+            console.error(`[core-only] failed to spawn service: ${err.message}`);
+            process.exitCode = 1;
+            resolve();
+        });
+    });
+}
 function ecosystemConfig(activationAppId) {
     const daemonScript = join(PKG_ROOT, 'dist', 'index-daemon.js');
     const bots = loadBotsJson();
@@ -1188,9 +1269,9 @@ async function promptEditBotConfig(rl, bot) {
         input.model = null;
     }
     printInputHelp('会话后端 backendType', [
-        '可选。pty 更轻量；tmux 支持 adopt 和 Web Terminal 附着；herdr 支持托管持久会话；zellij 为实验后端（需 zellij >= 0.44）。',
+        '可选。pty 更轻量；tmux 支持 adopt 和 Web Terminal 附着；herdr 支持托管持久会话；zmx >= 0.7.0 提供纯文本持久会话 + 本机 attach（无 Web TUI）；zellij 为实验后端（需 zellij >= 0.44）。',
         '选择 traex + herdr 时，可在 Dashboard Settings 中开启 TraeX herdr plugin opt-in 并填写可信插件 spec；默认不会自动安装第三方插件。',
-        '留空保留当前值；输入 - 回到自动检测；接受 pty / tmux / herdr / zellij。',
+        '留空保留当前值；输入 - 回到全局默认（未设置 BACKEND_TYPE 时为 tmux）；接受 pty / tmux / herdr / zellij / zmx。',
     ]);
     input.backendType = await ask(rl, `会话后端 backendType [${formatOptionalValue(bot.backendType)}]: `);
     // 新话题工作目录：模式二选一（与 promptBotConfig 的新建流程同款问法）。
@@ -3103,7 +3184,7 @@ function loadBotConfigsForDisplay() {
     return [];
 }
 /** Format a single session row for display (used by both plain table and TUI). */
-function formatSessionRow(s, multiBot, botLabels, cols) {
+function formatSessionRow(s, multiBot, botLabels, cols, probeSnapshot) {
     const id = padEndDisplay(s.sessionId.substring(0, 8), cols.id);
     const parts = [id];
     if (multiBot) {
@@ -3117,12 +3198,12 @@ function formatSessionRow(s, multiBot, botLabels, cols) {
     const uptime = formatDuration(Date.now() - new Date(s.createdAt).getTime()).padEnd(cols.uptime);
     const alive = isSessionAliveForList(s);
     const status = padEndDisplay(sessionStatusLabel(s), cols.status);
-    const target = padEndDisplay(truncate(sessionTargetLabel(s), cols.target), cols.target);
+    const target = padEndDisplay(truncate(sessionTargetLabel(s, probeSnapshot), cols.target), cols.target);
     parts.push(title, dir, pid, uptime, status, target);
     return { text: parts.join(' │ '), alive };
 }
 /** Print plain session table (non-interactive). */
-function printSessionTable(active) {
+function printSessionTable(active, probeSnapshot) {
     const botConfigs = loadBotConfigsForDisplay();
     const multiBot = botConfigs.length > 1 || new Set(active.map(s => s.larkAppId).filter(Boolean)).size > 1;
     const botLabels = new Map();
@@ -3141,22 +3222,12 @@ function printSessionTable(active) {
     console.log(header);
     console.log(separator);
     for (const s of active) {
-        const { text } = formatSessionRow(s, multiBot, botLabels, cols);
+        const { text } = formatSessionRow(s, multiBot, botLabels, cols, probeSnapshot);
         console.log(text);
     }
     console.log(separator);
     console.log(`共 ${active.length} 个活跃会话`);
 }
-/** Check if a tmux session exists. */
-function tmuxSessionExists(name) {
-    try {
-        execSync(`tmux has-session -t ${name} 2>/dev/null`, { stdio: 'ignore', env: tmuxEnv() });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 function applyTmuxWindowSizeLargest(sessionName) {
     try {
         execFileSync('tmux', ['set-option', '-t', sessionName, 'window-size', 'largest'], {
@@ -3188,18 +3259,41 @@ function closeSessionOffline(s) {
     // Adopted panes belong to the user. Ordinary bmx-* sessions are botmux-owned
     // and still need direct cleanup when no daemon exists to run killWorker().
     if (!isAdoptedSession(s)) {
-        const tmuxName = `bmx-${s.sessionId.substring(0, 8)}`;
-        try {
-            execSync(`tmux kill-session -t '${tmuxName}' 2>/dev/null`, {
-                stdio: 'ignore',
-                env: tmuxEnv(),
-            });
+        if (isSuspendableBackendType(s.backendType)) {
+            const target = resolvePersistentBackendTarget(s.backendType, s.sessionId, s.persistentBackendTarget);
+            try {
+                killPersistentBackendTarget(target, s.sessionId);
+            }
+            catch (err) {
+                // ZMX destruction is identity-verified against the complete botmux
+                // session UUID and waits for confirmed disappearance. Swallowing an
+                // inconclusive/mismatched kill would hide the sole control row while
+                // its CLI remains alive. Older mux backends retain their historical
+                // best-effort offline-close compatibility.
+                if (target.backendType === 'zmx') {
+                    return {
+                        ok: false,
+                        error: `ZMX 离线删除未完成：${err instanceof Error ? err.message : String(err)}`,
+                    };
+                }
+            }
+        }
+        else {
+            // Legacy rows without backendType were historically tmux-backed.
+            const tmuxName = `bmx-${s.sessionId.substring(0, 8)}`;
+            try {
+                execSync(`tmux kill-session -t '${tmuxName}' 2>/dev/null`, {
+                    stdio: 'ignore',
+                    env: tmuxEnv(),
+                });
+            }
+            catch { /* no tmux session */ }
         }
-        catch { /* no tmux session */ }
     }
     s.status = 'closed';
     s.closedAt = new Date().toISOString();
     saveSession(s);
+    return { ok: true, via: 'offline' };
 }
 /** Close through the owning daemon whenever it is online. The IPC request is
  *  deliberately sent BEFORE any local kill: deleting the current bmx-* tmux
@@ -3221,8 +3315,7 @@ async function closeSessionForDelete(s, online = listOnlineDaemons()) {
     // port); it only keeps larkAppId-less legacy records on the offline fallback,
     // whose saveSession() persists to the legacy file correctly.
     if (!s.larkAppId) {
-        closeSessionOffline(s);
-        return { ok: true, via: 'offline' };
+        return closeSessionOffline(s);
     }
     const daemon = online.find(d => d.larkAppId === s.larkAppId);
     const isCurrentSession = process.env.BOTMUX_SESSION_ID === s.sessionId;
@@ -3244,8 +3337,7 @@ async function closeSessionForDelete(s, online = listOnlineDaemons()) {
             return { ok: false, error: `连接 daemon 失败: ${err?.message ?? err}` };
         }
     }
-    closeSessionOffline(s);
-    return { ok: true, via: 'offline' };
+    return closeSessionOffline(s);
 }
 function adoptTargetLabel(s) {
     if (!isAdoptedSession(s))
@@ -3282,15 +3374,117 @@ function sessionStatusLabel(s) {
         return 'dormant';
     return s.pid && isProcessAlive(s.pid) ? 'online' : s.pid ? 'stopped' : 'idle';
 }
-function sessionTargetLabel(s, tmuxName, hasTmux) {
+function backingProbeKey(target) {
+    const agentName = target.backendType === 'herdr' ? target.agentName ?? '' : '';
+    return `${target.backendType}\0${target.sessionName}\0${agentName}`;
+}
+function sessionPersistentTarget(s) {
+    if (isSuspendableBackendType(s.backendType)) {
+        return resolvePersistentBackendTarget(s.backendType, s.sessionId, s.persistentBackendTarget);
+    }
+    if (s.backendType === undefined) {
+        // Legacy rows predate backend stamping. Only tmux was externally
+        // attachable, and its deterministic target remains the compatibility path.
+        return {
+            backendType: 'tmux',
+            sessionName: `bmx-${s.sessionId.substring(0, 8)}`,
+        };
+    }
+    return undefined;
+}
+function persistentTargetDisplay(target) {
+    return target.backendType === 'herdr' && target.agentName
+        ? `${target.sessionName}/${target.agentName}`
+        : target.sessionName;
+}
+function buildBackingProbeSnapshot(sessions) {
+    const namesByBackend = new Map();
+    const directTargets = new Map();
+    const add = (target) => {
+        if (target.backendType === 'herdr' && target.agentName) {
+            directTargets.set(backingProbeKey(target), target);
+            return;
+        }
+        const backendType = target.backendType;
+        const name = target.sessionName;
+        const names = namesByBackend.get(backendType) ?? new Set();
+        names.add(name);
+        namesByBackend.set(backendType, names);
+    };
+    for (const session of sessions) {
+        if (isAdoptedSession(session) || session.backendType === 'pty')
+            continue;
+        const target = sessionPersistentTarget(session);
+        if (target)
+            add(target);
+    }
+    const snapshot = new Map();
+    // Agent-scoped Herdr targets cannot be collapsed into a host-session probe:
+    // the shared host may be healthy after this exact Botmux agent exited.
+    for (const [key, target] of directTargets) {
+        snapshot.set(key, probePersistentBackendTarget(target));
+    }
+    for (const [backendType, names] of namesByBackend) {
+        for (const [name, probe] of probePersistentSessions(backendType, names)) {
+            snapshot.set(backingProbeKey({ backendType, sessionName: name }), probe);
+        }
+    }
+    return snapshot;
+}
+function backingProbe(snapshot, target) {
+    return snapshot?.get(backingProbeKey(target))
+        ?? probePersistentBackendTarget(target);
+}
+function sessionBackingInfo(s, snapshot) {
+    if (isSuspendableBackendType(s.backendType)) {
+        const target = sessionPersistentTarget(s);
+        const probe = backingProbe(snapshot, target);
+        const suffix = probe === 'exists' ? '' : ` (${probe})`;
+        return {
+            backendType: s.backendType,
+            target,
+            probe,
+            label: `${s.backendType}: ${persistentTargetDisplay(target)}${suffix}`,
+            attachBackend: s.backendType === 'tmux' || s.backendType === 'zmx'
+                ? s.backendType
+                : undefined,
+        };
+    }
+    if (s.backendType === 'pty') {
+        return { backendType: 'pty', probe: 'missing', label: 'pty' };
+    }
+    // Legacy rows predate backend stamping. Only tmux was externally attachable.
+    const target = sessionPersistentTarget(s);
+    const probe = backingProbe(snapshot, target);
+    return {
+        backendType: 'tmux',
+        target,
+        probe,
+        label: probe === 'exists' ? `tmux: ${target.sessionName}` : '-',
+        attachBackend: 'tmux',
+    };
+}
+function sessionTargetLabel(s, snapshot) {
     if (isAdoptedSession(s))
         return adoptTargetLabel(s);
-    if (hasTmux === undefined) {
-        const name = tmuxName ?? `bmx-${s.sessionId.substring(0, 8)}`;
-        hasTmux = tmuxSessionExists(name);
-        tmuxName = name;
+    return sessionBackingInfo(s, snapshot).label;
+}
+function hasRecoverableBackingSession(s, snapshot) {
+    if (isSuspendableBackendType(s.backendType)) {
+        // Unknown means the backend probe itself was inconclusive; keep the session
+        // rather than closing a potentially recoverable conversation from `list`.
+        // ZMX has one daemon per session. A clean "missing" result cannot
+        // distinguish a host reboot from an individual CLI exit, so keep the
+        // transcript-backed row for lazy resume instead of auto-pruning it.
+        if (s.backendType === 'zmx')
+            return true;
+        const target = sessionPersistentTarget(s);
+        const probe = backingProbe(snapshot, target);
+        return probe === 'exists' || probe === 'unknown';
     }
-    return hasTmux ? `tmux: ${tmuxName}` : '-';
+    // Legacy sessions created before backendType stamping only had tmux recovery.
+    const target = sessionPersistentTarget(s);
+    return !!target && backingProbe(snapshot, target) === 'exists';
 }
 /** Shorten path for display: replace $HOME with ~. */
 function shortenPath(p) {
@@ -3298,7 +3492,7 @@ function shortenPath(p) {
     return p.startsWith(home) ? '~' + p.slice(home.length) : p;
 }
 /** Interactive TUI session picker — returns a promise that resolves when done. */
-function interactiveSessionPicker(active) {
+function interactiveSessionPicker(active, probeSnapshot) {
     const botConfigs = loadBotConfigsForDisplay();
     const multiBot = botConfigs.length > 1 || new Set(active.map(s => s.larkAppId).filter(Boolean)).size > 1;
     const botLabels = new Map();
@@ -3330,10 +3524,11 @@ function interactiveSessionPicker(active) {
     // Build row data — use shortened paths for TUI
     function buildRows() {
         return active.map(s => {
-            const tmuxName = `bmx-${s.sessionId.substring(0, 8)}`;
             const isAdopt = isAdoptedSession(s);
-            const hasTmux = !isAdopt && tmuxSessionExists(tmuxName);
-            const targetLabel = sessionTargetLabel(s, tmuxName, hasTmux);
+            const backing = isAdopt
+                ? { probe: 'missing', label: adoptTargetLabel(s) }
+                : sessionBackingInfo(s, probeSnapshot);
+            const targetLabel = backing.label;
             // Build row text with shortened dir
             const id = padEndDisplay(s.sessionId.substring(0, 8), cols.id);
             const parts = [id];
@@ -3350,7 +3545,20 @@ function interactiveSessionPicker(active) {
             const status = padEndDisplay(sessionStatusLabel(s), cols.status);
             const target = padEndDisplay(truncate(targetLabel, cols.target), cols.target);
             parts.push(title, dir, pid, uptime, status, target);
-            return { session: s, text: parts.join(' │ '), alive, tmuxName, hasTmux, isAdopt, targetLabel, canAttach: hasTmux && !isAdopt };
+            return {
+                session: s,
+                text: parts.join(' │ '),
+                alive,
+                backendTarget: 'target' in backing ? backing.target : undefined,
+                backingProbe: backing.probe,
+                attachBackend: 'attachBackend' in backing ? backing.attachBackend : undefined,
+                isAdopt,
+                targetLabel,
+                canAttach: !isAdopt
+                    && backing.probe === 'exists'
+                    && !!('attachBackend' in backing && backing.attachBackend)
+                    && !!('target' in backing && backing.target),
+            };
         });
     }
     let rows = buildRows();
@@ -3395,9 +3603,9 @@ function interactiveSessionPicker(active) {
         const selected = rows[cursor];
         const targetHint = selected.isAdopt
             ? `\x1b[33m${selected.targetLabel}\x1b[0m  \x1b[2mEnter 已禁用；请直接使用原 tmux/zellij/herdr 客户端。\x1b[0m`
-            : selected.hasTmux
-                ? `\x1b[32mtmux: ${selected.tmuxName}\x1b[0m`
-                : `\x1b[2mtmux: 无会话\x1b[0m`;
+            : selected.canAttach
+                ? `\x1b[32m${selected.attachBackend}: ${selected.backendTarget?.sessionName}\x1b[0m`
+                : `\x1b[2m${selected.targetLabel}（不可连接）\x1b[0m`;
         process.stdout.write(`\n  ${targetHint}\n`);
         // Flash message or confirmation prompt
         if (confirmDelete) {
@@ -3497,7 +3705,7 @@ function interactiveSessionPicker(active) {
                 render();
                 return;
             }
-            // Enter — attach to tmux
+            // Enter — attach to a managed persistent backend.
             if (key === '\r' || key === '\n') {
                 const selected = rows[cursor];
                 if (selected.isAdopt) {
@@ -3506,26 +3714,85 @@ function interactiveSessionPicker(active) {
                     return;
                 }
                 if (!selected.canAttach) {
-                    flashMsg = '\x1b[33m该会话没有 tmux，无法连接\x1b[0m';
+                    flashMsg = '\x1b[33m该会话没有可连接的持久后端\x1b[0m';
                     render();
                     return;
                 }
-                applyTmuxWindowSizeLargest(selected.tmuxName);
-                cleanup();
-                spawnSync('tmux', ['attach-session', '-t', selected.tmuxName], {
-                    stdio: 'inherit',
-                    env: tmuxEnv(),
-                });
+                if (selected.attachBackend === 'zmx') {
+                    const target = selected.backendTarget;
+                    if (!target || target.backendType !== 'zmx') {
+                        flashMsg = '\x1b[31mZMX attach target is missing or inconsistent\x1b[0m';
+                        render();
+                        return;
+                    }
+                    // First prove both complete Botmux labels while the picker is still
+                    // active, then freeze the PTY root generation across terminal
+                    // cleanup and re-prove it immediately before attach.
+                    const frozen = freezeManagedZmxAttachTarget(target.sessionName, selected.session.sessionId);
+                    if (!frozen.ok) {
+                        flashMsg = `\x1b[31m${frozen.message}\x1b[0m`;
+                        render();
+                        return;
+                    }
+                    cleanup();
+                    const attached = attachFrozenManagedZmxSession(target.sessionName, selected.session.sessionId, frozen.pid);
+                    if (!attached.ok)
+                        console.error(attached.message);
+                }
+                else {
+                    const target = selected.backendTarget;
+                    if (!target || target.backendType !== 'tmux') {
+                        flashMsg = '\x1b[31mtmux attach target is missing or inconsistent\x1b[0m';
+                        render();
+                        return;
+                    }
+                    cleanup();
+                    applyTmuxWindowSizeLargest(target.sessionName);
+                    spawnSync('tmux', ['attach-session', '-t', `=${target.sessionName}`], {
+                        stdio: 'inherit',
+                        env: tmuxEnv(),
+                    });
+                }
                 resolve();
                 return;
             }
         });
     });
 }
+/**
+ * Internal host-only bridge used by Dashboard "Open CLI" commands. The
+ * generated terminal shell executes this exact checkout's cli.js, keeping all
+ * ZMX ownership checks in TypeScript instead of approximating them with
+ * name-only shell pipelines.
+ */
+function cmdManagedZmxAttach(args) {
+    const [name, sessionId, ...extra] = args;
+    if (!name?.trim() || !sessionId?.trim() || extra.length > 0) {
+        console.error('internal usage: __zmx-attach-managed <session-name> <complete-session-id>');
+        process.exitCode = 2;
+        return;
+    }
+    const frozen = freezeManagedZmxAttachTarget(name, sessionId);
+    if (!frozen.ok) {
+        console.error(frozen.message);
+        process.exitCode = 1;
+        return;
+    }
+    const attached = attachFrozenManagedZmxSession(name, sessionId, frozen.pid);
+    if (!attached.ok) {
+        console.error(attached.message);
+        process.exitCode = 1;
+    }
+}
 async function cmdList() {
     const sessions = loadSessions();
     const active = [...sessions.values()].filter(s => s.status === 'active');
-    // Auto-prune unrecoverable sessions: process dead and no tmux session.
+    // One immutable control-plane snapshot per invocation. In particular, ZMX's
+    // full-list probe walks every per-session daemon, so running it once per row
+    // would make a large session list quadratic and amplify socket timeouts.
+    const probeSnapshot = buildBackingProbeSnapshot(active);
+    // Auto-prune unrecoverable sessions: process dead and no recoverable backing
+    // session (tmux/herdr/zellij/zmx).
     // Split into two buckets so a never-activated daemon-command scratch (e.g. an
     // unconfirmed /adopt that only posted a picker card, /help, an abandoned
     // /relay picker) isn't reported as a crashed CLI. Such a scratch never forked
@@ -3552,8 +3819,8 @@ async function cmdList() {
             continue;
         }
         const hasPid = !!(s.pid && isProcessAlive(s.pid));
-        const hasTmux = tmuxSessionExists(`bmx-${s.sessionId.substring(0, 8)}`);
-        const disposition = sessionListDisposition(s, { hasPid, hasBackingSession: hasTmux });
+        const hasBackingSession = hasRecoverableBackingSession(s, probeSnapshot);
+        const disposition = sessionListDisposition(s, { hasPid, hasBackingSession });
         if (disposition === 'prune_real')
             pruned.push(s);
         else if (disposition === 'prune_scratch')
@@ -3561,18 +3828,30 @@ async function cmdList() {
         else
             live.push(s);
     }
-    const closeNow = (arr) => {
+    const closeNow = async (arr, kind) => {
+        let closed = 0;
         for (const s of arr) {
-            s.status = 'closed';
-            s.closedAt = new Date().toISOString();
-            saveSession(s);
+            const result = await closeSessionForDelete(s);
+            if (result.ok) {
+                closed++;
+            }
+            else {
+                // Keep it visible: mutating only the store while a possible owner
+                // daemon still has the row in memory lets the next message resurrect
+                // exactly the session auto-prune claimed to close.
+                live.push(s);
+                console.warn(`⚠️ 未自动清理 ${kind === 'scratch' ? '占位' : '会话'} ${s.sessionId.substring(0, 8)}：${result.error}`);
+            }
         }
+        return closed;
     };
     // Scratches: close silently — they were placeholders, not dead sessions.
-    closeNow(prunedScratch);
+    await closeNow(prunedScratch, 'scratch');
     if (pruned.length > 0) {
-        closeNow(pruned);
-        console.log(`已自动清理 ${pruned.length} 个不可恢复的会话（进程已退出或无可恢复后端）`);
+        const closed = await closeNow(pruned, 'real');
+        if (closed > 0) {
+            console.log(`已自动清理 ${closed} 个不可恢复的会话（进程已退出或无可恢复后端）`);
+        }
     }
     // Sort by creation time, newest first
     live.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
@@ -3582,11 +3861,11 @@ async function cmdList() {
     }
     // Non-TTY (piped output) or explicit --plain flag: plain table
     if (!process.stdout.isTTY || process.argv.includes('--plain')) {
-        printSessionTable(live);
+        printSessionTable(live, probeSnapshot);
         return;
     }
     // Interactive TUI
-    await interactiveSessionPicker(live);
+    await interactiveSessionPicker(live, probeSnapshot);
 }
 async function cmdDelete() {
     const target = process.argv[3];
@@ -3596,6 +3875,7 @@ async function cmdDelete() {
     }
     const sessions = loadSessions();
     const active = [...sessions.values()].filter(s => s.status === 'active');
+    const probeSnapshot = buildBackingProbeSnapshot(active);
     if (active.length === 0) {
         console.log('没有活跃会话。');
         return;
@@ -3618,8 +3898,7 @@ async function cmdDelete() {
                 return pid ? !isProcessAlive(pid) : !(s.pid && isProcessAlive(s.pid));
             }
             const hasPid = !!(s.pid && isProcessAlive(s.pid));
-            const hasTmux = tmuxSessionExists(`bmx-${s.sessionId.substring(0, 8)}`);
-            return !hasPid && !hasTmux;
+            return !hasPid && !hasRecoverableBackingSession(s, probeSnapshot);
         });
         if (toDelete.length === 0) {
             console.log('没有 stopped 状态的会话。');
@@ -3809,6 +4088,50 @@ async function postSessionCliIpc(ipcPort, sessionId, route, payload) {
         ? fetchDaemonIpc(ipcPort, path, init, hostSecret)
         : fetch(`http://127.0.0.1:${ipcPort}${path}`, init);
 }
+async function cmdChat(argv) {
+    const sub = argv[0] ?? '';
+    if (sub !== 'rename') {
+        console.error('用法: botmux chat rename <新群名称> [--proactive]');
+        process.exitCode = 2;
+        return;
+    }
+    const proactive = argv.includes('--proactive');
+    const name = argv.slice(1).filter(arg => arg !== '--proactive').join(' ').trim();
+    if (!name) {
+        console.error('用法: botmux chat rename <新群名称> [--proactive]');
+        process.exitCode = 2;
+        return;
+    }
+    const ctx = findAncestorSessionContext();
+    const sid = ctx?.sessionId;
+    if (!sid) {
+        console.error(JSON.stringify({ ok: false, error: 'missing_session_context' }));
+        process.exitCode = 1;
+        return;
+    }
+    const sessions = loadSessions();
+    const session = [...sessions.values()].find(x => x.sessionId === sid || x.sessionId.startsWith(sid));
+    if (!session) {
+        console.error(JSON.stringify({ ok: false, error: 'missing_session_context' }));
+        process.exitCode = 1;
+        return;
+    }
+    const daemon = findDaemon(session.larkAppId);
+    if (!daemon) {
+        console.error(JSON.stringify({ ok: false, error: 'daemon_offline' }));
+        process.exitCode = 1;
+        return;
+    }
+    const response = await postSessionCliIpc(daemon.ipcPort, session.sessionId, 'chat-rename', { name, proactive });
+    const body = await response.json().catch(() => ({ ok: false, error: `HTTP ${response.status}` }));
+    const out = JSON.stringify(body, null, 2);
+    if (response.ok && body?.ok) {
+        console.log(out);
+        return;
+    }
+    console.error(out);
+    process.exitCode = 1;
+}
 /** botmux slash "<斜杠命令>"：请求 daemon 在本会话 idle 后把命令敲入自己的 CLI。
  *  自识别当前会话（pid marker → BOTMUX_SESSION_ID env），allowlist 由 daemon 侧校验。 */
 async function cmdSlash() {
@@ -3892,19 +4215,10 @@ async function cmdRoleSwitch(argv) {
     console.error(`✗ 切换被拒绝: ${body?.error ?? `HTTP ${res.status}`}`);
     process.exit(1);
 }
-/**
- * Discover online daemons. Mirrors the staleness rule used by
- * dashboard/registry.ts (90s heartbeat) so we don't try to talk to a daemon
- * that's been dead but left a stale descriptor behind. Uses resolveDataDir()
- * so SESSION_DATA_DIR / breadcrumb-overridden deployments find the right
- * descriptor directory.
- */
-function listOnlineDaemons() {
+function listDaemonDescriptors() {
     const regDir = join(resolveDataDir(), 'dashboard-daemons');
     if (!existsSync(regDir))
         return [];
-    const STALE_MS = 90_000;
-    const now = Date.now();
     const all = [];
     let names = [];
     try {
@@ -3920,30 +4234,131 @@ function listOnlineDaemons() {
             const d = JSON.parse(readFileSync(join(regDir, f), 'utf-8'));
             if (typeof d?.ipcPort !== 'number' || typeof d?.larkAppId !== 'string')
                 continue;
-            if (now - (d.lastHeartbeat ?? 0) > STALE_MS)
-                continue;
             all.push({
                 ipcPort: d.ipcPort,
                 larkAppId: d.larkAppId,
+                ...(typeof d.pid === 'number' ? { pid: d.pid } : {}),
                 ...(typeof d.bootInstanceId === 'string' && d.bootInstanceId
                     ? { bootInstanceId: d.bootInstanceId }
                     : {}),
                 ...(typeof d.workflowIpcProtocol === 'string' && d.workflowIpcProtocol
                     ? { workflowIpcProtocol: d.workflowIpcProtocol }
                     : {}),
-                lastHeartbeat: d.lastHeartbeat,
+                ...(typeof d.lastHeartbeat === 'number' ? { lastHeartbeat: d.lastHeartbeat } : {}),
             });
         }
         catch { /* skip malformed */ }
     }
     return all;
 }
+function listOnlineDaemons() {
+    const STALE_MS = 90_000;
+    const now = Date.now();
+    return listDaemonDescriptors().filter(d => now - (d.lastHeartbeat ?? 0) <= STALE_MS);
+}
 function findDaemon(larkAppId) {
     const all = listOnlineDaemons();
     if (larkAppId)
         return all.find(d => d.larkAppId === larkAppId) ?? null;
     return all[0] ?? null;
 }
+function normalizeCardUsageSnapshot(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const raw = value;
+    const rawContext = raw.context;
+    const rawTokens = raw.tokens;
+    let context = null;
+    if (rawContext && typeof rawContext === 'object' && !Array.isArray(rawContext)) {
+        const c = rawContext;
+        if (typeof c.usedTokens === 'number'
+            && Number.isFinite(c.usedTokens)
+            && c.usedTokens >= 0) {
+            context = {
+                usedTokens: c.usedTokens,
+                ...(typeof c.windowTokens === 'number'
+                    && Number.isFinite(c.windowTokens)
+                    && c.windowTokens > 0
+                    ? { windowTokens: c.windowTokens }
+                    : {}),
+                ...(typeof c.percentUsed === 'number'
+                    && Number.isFinite(c.percentUsed)
+                    && c.percentUsed >= 0
+                    ? { percentUsed: c.percentUsed }
+                    : {}),
+            };
+        }
+    }
+    let tokens = null;
+    if (rawTokens && typeof rawTokens === 'object' && !Array.isArray(rawTokens)) {
+        const u = rawTokens;
+        if (typeof u.in === 'number'
+            && Number.isFinite(u.in)
+            && u.in >= 0
+            && typeof u.out === 'number'
+            && Number.isFinite(u.out)
+            && u.out >= 0) {
+            tokens = { in: u.in, out: u.out };
+        }
+    }
+    return { context, tokens };
+}
+/** Prefer the resident daemon's incremental transcript cache. Older/offline
+ * daemons and isolated environments fall back to the local reader; either path
+ * degrades to explicit unavailable facts without blocking the reply. */
+async function readCardUsageSnapshotForSend(session, larkAppId) {
+    let daemonPort;
+    try {
+        daemonPort =
+            findDaemon(larkAppId)?.ipcPort
+                ?? resolveDaemonIpcPort(undefined, process.env.BOTMUX_DAEMON_IPC_PORT);
+    }
+    catch {
+        // A stale/unreadable daemon registry must not prevent the reply.
+    }
+    if (daemonPort) {
+        try {
+            const path = `/api/sessions/${encodeURIComponent(session.sessionId)}/usage`;
+            const response = await fetchDaemonIpc(daemonPort, path, {
+                method: 'GET',
+                signal: AbortSignal.timeout(1_500),
+            });
+            if (response.ok) {
+                const body = await response.json();
+                const normalized = normalizeCardUsageSnapshot(body.usage);
+                if (normalized)
+                    return normalized;
+            }
+        }
+        catch {
+            // No host secret, old daemon, timeout, or transient IPC failure: use the
+            // same bounded local parser below.
+        }
+    }
+    // Old/offline daemon fallback. Sandboxed panes receive this per-bot value
+    // explicitly from the worker because bots.json is intentionally unreadable.
+    // This send path renders into the reply-card FOOTER, so only the 'footer'
+    // display mode surfaces usage here; 'streaming' shows it on the daemon's live
+    // card (absent on this offline fallback) and 'off' shows nothing.
+    if (resolveUsageDisplay(larkAppId) !== 'footer') {
+        return { context: null, tokens: null };
+    }
+    try {
+        return getSessionUsageSnapshot({
+            cliId: (session.cliId ?? session.adoptedFrom?.cliId ?? 'unknown'),
+            sessionId: session.sessionId,
+            cliSessionId: session.cliSessionId ?? session.adoptedFrom?.sessionId,
+            cwd: session.workingDir ?? session.adoptedFrom?.cwd,
+            // BOT_HOME transcript fallback for CLI-data-redirected / sandboxed bots
+            // (parity with the daemon reader and the ledger/dashboard consumers).
+            larkAppId: larkAppId ?? session.larkAppId,
+            fresh: true,
+        });
+    }
+    catch {
+        return { context: null, tokens: null };
+    }
+}
 /**
  * Authenticate the human who opened this exact turn against the target run,
  * then return the only daemon app that may receive the mutation. Inherited
@@ -4361,6 +4776,9 @@ async function cmdResume() {
     else if (errCode === 'deferred_unmaterialized') {
         console.error('❌ 该静默定时轮次未创建话题，隐藏会话只保留审计记录，不能 resume。');
     }
+    else if (errCode === 'resume_cancelled') {
+        console.error('❌ 恢复过程中会话被关闭，本次 resume 已取消。');
+    }
     else {
         console.error(`❌ 恢复失败: ${errCode}`);
     }
@@ -4461,6 +4879,9 @@ async function cmdTermLink(rest) {
     else if (errCode === 'terminal_unavailable') {
         console.error('❌ 该会话终端尚未就绪（worker 未起或缺 token）。等会话起来再试。');
     }
+    else if (errCode === 'terminal_unsupported') {
+        console.error('❌ 该会话后端不提供 Web 终端；ZMX 会话请在本机运行 botmux list 或 zmx attach。');
+    }
     else if (errCode === 'no_owner') {
         console.error('❌ 该 bot 未配置 owner（allowedUsers 为空 / 全开放模式），没有可私密投递的对象。');
     }
@@ -4546,6 +4967,8 @@ botmux v${getVersion()} — IM ↔ AI 编程 CLI 桥接
   schedule run <id>                    标记立即执行
 
 飞书消息（在 CLI 会话内自动推断 session）:
+  chat rename <新群名称>               修改当前会话所在群的名称
+       --proactive                    标记为 AI 主动改名（应用 10 分钟防抖）
   send [content]                       发消息到当前话题（支持 stdin / --content-file）
        --images <path>                 内联图片（可重复）
        --files <path>                  附件（可重复）
@@ -5299,6 +5722,8 @@ async function resolveSessionAppId(sessionIdArg) {
     return { sid, larkAppId: s.larkAppId, session: s };
 }
 async function cmdHistory(rest) {
+    // No-transport turn has no Feishu chat history to read — central hard gate.
+    assertTurnTransportOrExit('history');
     // Read isolation: register this bot from its cred file so the Lark client is
     // available without reading the denied bots.json (same as cmdSend).
     await registerSelfFromCredFile();
@@ -5311,6 +5736,9 @@ async function cmdHistory(rest) {
     const scopeArg = argValue(rest, '--scope') ?? 'session';
     const sessionIdArg = argValue(rest, '--session-id');
     const { sid, larkAppId: appId, session: s } = await resolveSessionAppId(sessionIdArg);
+    // Target-aware gate: a --session-id pointing at a virtual/apiOnly session must
+    // be refused even from a normal turn (env gate above can't see the argument).
+    assertSessionTransportOrExit({ chatId: s.chatId, larkAppId: appId }, 'history');
     const validScopes = new Set(['session', 'thread', 'chat', 'ambient']);
     if (!validScopes.has(scopeArg)) {
         console.error(`无效 --scope: ${scopeArg}。可用: session | thread | chat | ambient`);
@@ -5438,6 +5866,8 @@ async function cmdHistory(rest) {
     }
 }
 async function cmdQuoted(rest) {
+    // No-transport turn cannot fetch a quoted Feishu message — central hard gate.
+    assertTurnTransportOrExit('quoted');
     const sessionIdArg = argValue(rest, '--session-id');
     // Positional message_id is required. The id comes verbatim from the
     // `[用户引用了消息 用 botmux quoted om_xxx 查看]` prompt prefix the daemon
@@ -5455,7 +5885,9 @@ async function cmdQuoted(rest) {
     // bots.json — same as cmdHistory / cmdSend. Missing this was why a sandboxed
     // isolated bot's `botmux quoted` failed "Bot not registered".
     await registerSelfFromCredFile();
-    const { larkAppId: appId } = await resolveSessionAppId(sessionIdArg);
+    const { larkAppId: appId, session: quotedSession } = await resolveSessionAppId(sessionIdArg);
+    // Target-aware gate (see cmdHistory).
+    assertSessionTransportOrExit({ chatId: quotedSession.chatId, larkAppId: appId }, 'quoted');
     const { getMessageDetail } = await import('./im/lark/client.js');
     const { expandMergeForward } = await import('./im/lark/merge-forward.js');
     const { renderQuotedMessage } = await import('./cli/quoted-render.js');
@@ -5566,34 +5998,33 @@ function argValues(args, ...flags) {
     }
     return out;
 }
-function withCustomCardMentionFooter(card, mentionOpenIds, sentToLabel) {
+function withCustomCardMentionFooter(card, mentionOpenIds, locale) {
     if (mentionOpenIds.length === 0)
         return { ok: true, card };
-    const cloned = JSON.parse(JSON.stringify(card));
-    const body = cloned.body;
-    if (!body || !Array.isArray(body.elements)) {
+    const deduped = [...new Set(mentionOpenIds.filter(Boolean))];
+    const cloned = appendReplyCardFooterToV2Card(card, {
+        brand: '',
+        recipientOpenIds: deduped,
+        locale,
+    });
+    if (!cloned) {
         return {
             ok: false,
-            error: '自定义卡片带 --mention/--mention-back 时必须是 schema 2.0 且包含 body.elements；或改用 --no-mention 并在卡片 JSON 内自行处理展示',
+            error: '自定义卡片带 --mention/--mention-back 时必须是 schema 2.0、包含 body.elements，且未占用 botmux_reply_footer 元素 ID；或改用 --no-mention 并在卡片 JSON 内自行处理展示',
         };
     }
-    const deduped = [...new Set(mentionOpenIds.filter(Boolean))];
-    body.elements.push({ tag: 'hr' }, {
-        tag: 'markdown',
-        text_size: 'notation_small_v2',
-        content: `<font color='grey'>${sentToLabel}${deduped.map(id => `<at id=${id}></at>`).join(' ')}</font>`,
-    });
     return { ok: true, card: cloned };
 }
 // Card v2 body builder helpers — extracted to im/lark/md-card.ts so the
 // daemon's bridge fallback path can produce identical cards. cmdSend
 // keeps using `buildImageCardElements` from there.
-import { buildImageCardElements, brandFooterSegment, prepareCardMarkdown } from './im/lark/md-card.js';
+import { appendReplyCardFooterToV2Card, buildImageCardElements, buildReplyCardFooter, prepareCardMarkdown, } from './im/lark/md-card.js';
 import { applyInlineMentions } from './im/lark/inline-mentions.js';
 import { renderBrandTemplate } from './im/lark/brand-template.js';
-import { resolveBrandLabel } from './bot-registry.js';
+import { resolveBrandLabel, resolveUsageDisplay } from './bot-registry.js';
 import { config } from './config.js';
-import { resolveQuoteTarget, validateMentionDecision, parseAttentionFlag, attentionUsageError, managedVcQuoteError, managedVcCustomCardError, managedVcSendControlError, managedVcSendPayloadError, containsLarkAtTag, } from './services/send-policy.js';
+import { getSessionUsageSnapshot } from './core/cost-calculator.js';
+import { resolveQuoteTarget, validateMentionDecision, shouldBlockMentionBackByParticipants, parseAttentionFlag, attentionUsageError, managedVcQuoteError, managedVcCustomCardError, managedVcSendControlError, managedVcSendPayloadError, containsLarkAtTag, } from './services/send-policy.js';
 /**
  * Sandbox relay mode for `botmux send`. Inside a file-sandbox the CLI cannot
  * read bots.json or reach Lark directly (creds are deliberately absent), so we
@@ -5759,6 +6190,98 @@ async function relaySend(rest, relayDir) {
     console.error('relay: 等待 daemon 投递超时（120s）');
     process.exit(1);
 }
+/** True if the running bot (by daemon-injected larkAppId) is core-only
+ *  (apiOnly). Read-only + never throws: used by `botmux send` to refuse early
+ *  with a clear message. Reads bots.json best-effort; an apiOnly bot runs
+ *  non-isolated (no Feishu secret to protect), so bots.json is readable here. */
+function currentBotIsApiOnly(larkAppId) {
+    try {
+        return loadBotsJson().some((b) => b?.larkAppId === larkAppId && b?.apiOnly === true);
+    }
+    catch {
+        return false;
+    }
+}
+/** Central CLI session-transport capability check. A turn has NO Feishu
+ *  transport when either the running bot is core-only (apiOnly) OR the turn runs
+ *  in an HTTP virtual session (BOTMUX_CHAT_ID starts with http_async_ or
+ *  http_wait_). This is the single source of truth every Feishu-touching CLI
+ *  command consults — send/dispatch (writes) AND history/quoted/bots (reads) —
+ *  so a normal bot in a virtual session can't reach Feishu by reloading
+ *  bots.json for a real client (the daemon side is already gated by
+ *  larkTransportEnabled; this closes the non-sandbox local-CLI path). Kept
+ *  read-only and total (never throws). */
+function currentTurnHasNoTransport() {
+    const chatId = process.env.BOTMUX_CHAT_ID ?? '';
+    if (chatId.startsWith('http_async_') || chatId.startsWith('http_wait_'))
+        return true;
+    const appId = process.env.BOTMUX_LARK_APP_ID;
+    return !!appId && currentBotIsApiOnly(appId);
+}
+/** Tamper-resistant managed-origin transport check for the root-dispatch gate.
+ *  Resolves the origin session via the pid-marker ANCESTRY (process.ppid walk),
+ *  NOT the mutable BOTMUX_SESSION_ID env, then loads that session's record and
+ *  judges transport from its chatId + its bot's apiOnly config. So `env -u
+ *  BOTMUX_SESSION_ID -u BOTMUX_CHAT_ID -u BOTMUX_LARK_APP_ID` cannot shed the
+ *  managed no-transport identity. Returns false (not gated) when no managed
+ *  origin resolves — a bare host-operator shell keeps full access. Total; on any
+ *  resolution error falls back to the env-based check (never throws). */
+function managedOriginHasNoTransport() {
+    try {
+        const ctx = resolveSessionContext(resolveDataDir(), process.env.BOTMUX_SESSION_ID);
+        if (!ctx?.sessionId) {
+            // No managed origin at all (bare operator). Still honor an explicit env
+            // signal if present (daemon-spawned turn whose marker was pruned), but a
+            // truly bare shell has neither → not gated.
+            return !!process.env.BOTMUX_SESSION_ID && currentTurnHasNoTransport();
+        }
+        const s = loadSessions().get(ctx.sessionId);
+        if (!s) {
+            // Marker resolved a session id but no record on disk (riff sandbox etc.) —
+            // fall back to the env view for that same managed turn.
+            return currentTurnHasNoTransport();
+        }
+        const chatId = s.chatId ?? '';
+        if (chatId.startsWith('http_async_') || chatId.startsWith('http_wait_'))
+            return true;
+        return !!s.larkAppId && currentBotIsApiOnly(s.larkAppId);
+    }
+    catch {
+        return !!process.env.BOTMUX_SESSION_ID && currentTurnHasNoTransport();
+    }
+}
+/** Refuse a Feishu-touching CLI command for a no-transport turn with a clear,
+ *  actionable message (not a deep client error), then exit. `op` names the
+ *  command for the message. Returns true if it refused+exited is imminent — but
+ *  it calls process.exit(2), so callers just `if (assertTurnTransportOrExit(...)) return;`
+ *  for type-flow clarity; execution never continues past the exit. */
+function assertTurnTransportOrExit(op) {
+    if (!currentTurnHasNoTransport())
+        return;
+    const chatId = process.env.BOTMUX_CHAT_ID ?? '';
+    const why = chatId.startsWith('http_async_') || chatId.startsWith('http_wait_')
+        ? 'this turn runs in an HTTP control-API session (no Feishu chat)'
+        : 'this is a core-only (apiOnly) bot with no Feishu connection';
+    console.error(`botmux ${op} is unavailable: ${why}.\n` +
+        `Feishu read/write is not possible here — the turn communicates only over the HTTP\n` +
+        `control API (input via trigger, output via trigger-result). Produce your normal answer.`);
+    process.exit(2);
+}
+/** Target-aware variant: gate on the RESOLVED session (its chatId + owning bot's
+ *  apiOnly), not just the calling process env. The env gate can't see a
+ *  `--session-id <other>` argument that targets a different (virtual) session, so
+ *  commands that accept --session-id must call this AFTER resolving the target to
+ *  close the cross-session bypass. Read-only + total (never throws besides exit). */
+function assertSessionTransportOrExit(session, op) {
+    const chatId = session.chatId ?? '';
+    const virtual = chatId.startsWith('http_async_') || chatId.startsWith('http_wait_');
+    const apiOnly = !!session.larkAppId && currentBotIsApiOnly(session.larkAppId);
+    if (!virtual && !apiOnly)
+        return;
+    console.error(`botmux ${op} is unavailable for the target session: ${virtual ? 'it is an HTTP control-API session (no Feishu chat)' : 'its bot is core-only (apiOnly)'}.\n` +
+        `Feishu read/write is not possible for that session.`);
+    process.exit(2);
+}
 /** Under read isolation the CLI is denied bots.json, so `loadBotConfigs()` reads
  *  nothing. The worker instead wrote THIS bot's own secret to a per-bot cred file
  *  (its own is readable; siblings' are denied). Register just this bot from that
@@ -5780,14 +6303,24 @@ async function registerSelfFromCredFile() {
     catch {
         return; // no cred file → not isolated (or first layer supplies creds elsewhere)
     }
-    if (!cred.larkAppSecret)
+    // apiOnly bots legitimately have an empty secret — don't bail on that, but DO
+    // carry the apiOnly flag through so the reconstructed config keeps the
+    // transport boundary (getBotClient throws for apiOnly). A non-apiOnly bot with
+    // no secret is still a no-op (nothing to register).
+    if (!cred.larkAppSecret && cred.apiOnly !== true)
         return;
     const { registerBot } = await import('./bot-registry.js');
     registerBot({
         larkAppId: appId,
-        larkAppSecret: cred.larkAppSecret,
+        larkAppSecret: cred.larkAppSecret ?? '',
+        apiOnly: cred.apiOnly === true || undefined,
         cliId: 'claude-code',
         brand: cred.brand,
+        usageDisplay: process.env.BOTMUX_USAGE_DISPLAY === 'streaming' ||
+            process.env.BOTMUX_USAGE_DISPLAY === 'footer' ||
+            process.env.BOTMUX_USAGE_DISPLAY === 'off'
+            ? process.env.BOTMUX_USAGE_DISPLAY
+            : undefined,
     });
 }
 /**
@@ -5846,9 +6379,15 @@ function riffModeSession(opts = {}) {
     const botConfig = {
         larkAppId: appId,
         larkAppSecret: appSecret,
+        apiOnly: process.env.BOTMUX_API_ONLY === '1' || undefined,
         brand,
         cliId: 'riff',
         allowedUsers: [],
+        usageDisplay: process.env.BOTMUX_USAGE_DISPLAY === 'streaming' ||
+            process.env.BOTMUX_USAGE_DISPLAY === 'footer' ||
+            process.env.BOTMUX_USAGE_DISPLAY === 'off'
+            ? process.env.BOTMUX_USAGE_DISPLAY
+            : undefined,
     };
     const session = {
         sessionId,
@@ -5893,6 +6432,10 @@ async function cmdSend(rest) {
             `chat-facing side effects belong in a hostExecutor activity, not a subagent.`);
         process.exit(2);
     }
+    // No-transport turn (apiOnly bot OR HTTP virtual session): refuse via the
+    // central session-capability gate — same hard door every Feishu-touching CLI
+    // command consults.
+    assertTurnTransportOrExit('send');
     // Managed output attribution must come from the live process-tree marker,
     // whose turn/attempt is refreshed by the worker. BOTMUX_TURN_ID is a
     // spawn-time fallback and can be stale in a detached child after a later
@@ -6146,6 +6689,11 @@ async function cmdSend(rest) {
         console.error(`session ${sid} 缺少 larkAppId`);
         process.exit(1);
     }
+    // Target-aware gate on the RESOLVED source session: `send --session-id <virtual>`
+    // (or an apiOnly bot's session) must be refused even if the ambient env looks
+    // transport-capable, and regardless of any `--chat-id` override — a no-transport
+    // turn may not originate ANY Feishu write. Closes the env-only gap for send.
+    assertSessionTransportOrExit({ chatId: s.chatId, larkAppId: s.larkAppId }, 'send');
     let deferredMaterializedByThisCommand = false;
     let deferredTopicRootMessageIdForOutput;
     // 本轮的回复锚点：优先按 turnId 精确取 per-turn 落点（排队/并发轮次不再被
@@ -6349,7 +6897,11 @@ async function cmdSend(rest) {
                     const markerDir = join(resolveDataDir(), 'turn-sends');
                     if (!existsSync(markerDir))
                         mkdirSync(markerDir, { recursive: true });
-                    appendFileSync(join(markerDir, `${sid}.jsonl`), JSON.stringify({ sentAtMs, messageId }) + '\n');
+                    const marker = { sentAtMs, messageId };
+                    const previewText = buildBridgeSendPreviewText(content);
+                    if (previewText)
+                        marker.previewText = previewText;
+                    appendFileSync(join(markerDir, `${sid}.jsonl`), JSON.stringify(marker) + '\n');
                 }
                 catch { /* best-effort：漏记只多一条兜底，不致命 */ }
             }
@@ -6435,7 +6987,15 @@ async function cmdSend(rest) {
                 const markerDir = join(resolveDataDir(), 'turn-sends');
                 if (!existsSync(markerDir))
                     mkdirSync(markerDir, { recursive: true });
-                appendFileSync(join(markerDir, `${sid}.jsonl`), JSON.stringify({ sentAtMs: Date.now(), messageId: `doc:${docTarget.commentId}`, contentLength: content.length }) + '\n');
+                const marker = {
+                    sentAtMs: Date.now(),
+                    messageId: `doc:${docTarget.commentId}`,
+                    contentLength: content.length,
+                };
+                const previewText = buildBridgeSendPreviewText(content);
+                if (previewText)
+                    marker.previewText = previewText;
+                appendFileSync(join(markerDir, `${sid}.jsonl`), JSON.stringify(marker) + '\n');
             }
             catch { /* best-effort：漏记只多一条兜底 */ }
             // 清理已消费的 per-turn 落点，避免 session 文件无限堆积。
@@ -6486,6 +7046,52 @@ async function cmdSend(rest) {
         console.error(mentionGate.error);
         process.exit(2);
     }
+    // Register bots so the Lark client works. MUST run before the participant
+    // gate below: that gate calls getGroupStats → getBotClient, which throws
+    // "Bot not registered" in this standalone `botmux send` process (a fresh
+    // process with an empty registry) — getGroupStats would then soft-fail to
+    // {999,999} and wrongly block --mention-back even in a true 1v1. registerBot
+    // is idempotent, so the downstream send path reuses these same clients.
+    // envPinnedRiffBot is re-registered LAST so a remote env credential is never
+    // clobbered by a stale bots.json entry for the same app.
+    const { registerBot, loadBotConfigs, findOncallChatForAnyBot } = await import('./bot-registry.js');
+    try {
+        for (const cfg of loadBotConfigs())
+            registerBot(cfg);
+    }
+    catch { /* */ }
+    if (envPinnedRiffBot) {
+        try {
+            registerBot(envPinnedRiffBot);
+        }
+        catch { /* */ }
+    }
+    // Participant gate for --mention-back: in a true 1v1 the triggerer is the
+    // only counterpart so auto-@-ing them back is unambiguous, but once a third
+    // party joins (humans + bots > 2) "who triggered this turn" is no longer
+    // reliably "who should be addressed". Force an explicit --mention there.
+    // Symmetric with the inbound un-@ gate (event-dispatcher getGroupStats).
+    // Only fetch when mention-back is actually requested AND the chat isn't a p2p
+    // DM (inherently 1v1) — keeps the common send path free of an API round-trip.
+    if (mentionBack && s.chatType !== 'p2p' && s.larkAppId && s.chatId && !sendTopLevel) {
+        try {
+            const { getGroupStats } = await import('./im/lark/event-dispatcher.js');
+            const { userCount, botCount } = await getGroupStats(s.larkAppId, s.chatId);
+            if (shouldBlockMentionBackByParticipants({ chatType: s.chatType, userCount, botCount })) {
+                console.error(`--mention-back 在多人会话（当前 ${userCount} 人 + ${botCount} bot）里不可用：`
+                    + '"回复触发这轮的人/bot" 在多方场景可能 @ 错对象。请改用 --mention <ou:Name> 显式点名，'
+                    + '或 --no-mention 不 @。');
+                process.exit(2);
+            }
+        }
+        catch (err) {
+            // getGroupStats already soft-fails to {999,999} (→ block) internally, so
+            // reaching here means the dynamic import itself failed. Fail-closed to a
+            // clear error rather than silently letting a possibly-wrong @ through.
+            console.error(`无法确认会话人数以校验 --mention-back：${err?.message ?? err}。请改用 --mention <ou:Name> 或 --no-mention。`);
+            process.exit(2);
+        }
+    }
     // --mention-back: @ the sender of the message this turn is replying to
     // (open_id from the session — model needn't know it). Bare-name form so it
     // renders as a trailing <at>.
@@ -6506,19 +7112,6 @@ async function cmdSend(rest) {
             process.exit(1);
         }
     }
-    // Register bots so Lark client works
-    const { registerBot, loadBotConfigs, findOncallChatForAnyBot } = await import('./bot-registry.js');
-    try {
-        for (const cfg of loadBotConfigs())
-            registerBot(cfg);
-    }
-    catch { /* */ }
-    if (envPinnedRiffBot) {
-        try {
-            registerBot(envPinnedRiffBot);
-        }
-        catch { /* */ }
-    }
     const { sendMessage, replyMessage, uploadImage, uploadFile, MessageWithdrawnError } = await import('./im/lark/client.js');
     const appId = s.larkAppId;
     // Effective target chat for top-level mode (defaults to session's chat)
@@ -6864,7 +7457,7 @@ async function cmdSend(rest) {
                 cc: footerAddressing.cc,
                 inlinedIds: [],
             });
-            const withFooter = withCustomCardMentionFooter(customCard, mentionFooter, t('card.sent_to', undefined, localeForBot(appId)));
+            const withFooter = withCustomCardMentionFooter(customCard, mentionFooter, localeForBot(appId));
             if (!withFooter.ok) {
                 console.error(`botmux send: ${withFooter.error}`);
                 process.exit(2);
@@ -6953,10 +7546,6 @@ async function cmdSend(rest) {
             // Brand segment honours this bot's configured brandLabel (unset →
             // default botmux, '' → suppressed, else custom). Same resolver/rule as
             // the daemon's card builders so both send paths render identically.
-            const footerParts = [];
-            const brandSeg = brandFooterSegment(renderBrandTemplate(resolveBrandLabel(appId), s.workingDir));
-            if (brandSeg)
-                footerParts.push(brandSeg);
             // All real mentions land on one footer line: human addressee first, then
             // explicit @ targets (incl. handoff bots), then cc. Ids already inlined in
             // the body prose are skipped. Top-level publish keeps sendTo empty.
@@ -6966,9 +7555,13 @@ async function cmdSend(rest) {
                 cc: footerAddressing.cc,
                 inlinedIds: usedIds,
             });
-            if (footerRecipients.length > 0) {
-                footerParts.push(`${t('card.sent_to', undefined, localeForBot(appId))}${footerRecipients.map(id => `<at id=${id}></at>`).join(' ')}`);
-            }
+            const usageSnapshot = await readCardUsageSnapshotForSend(s, appId);
+            const footer = buildReplyCardFooter({
+                brand: renderBrandTemplate(resolveBrandLabel(appId), s.workingDir),
+                recipientOpenIds: footerRecipients,
+                usage: usageSnapshot,
+                locale: localeForBot(appId),
+            });
             // Footer line (brand 个性签名 + 发送给) and the optional 🔊 语音总结 button
             // share ONE row: footer text on the left (weighted, fills), button pinned
             // to the far right (auto width). When voice isn't configured the footer
@@ -6985,9 +7578,7 @@ async function cmdSend(rest) {
                 }
                 catch { /* voice module/config unavailable → no button */ }
             }
-            const footerContent = footerParts.length > 0
-                ? `<font color='grey'>${footerParts.join(' · ')}</font>`
-                : '';
+            const footerContent = footer?.content ?? '';
             if (footerContent || voiceOn) {
                 elements.push({ tag: 'hr' });
                 if (voiceOn) {
@@ -6999,7 +7590,11 @@ async function cmdSend(rest) {
                         columns: [
                             {
                                 tag: 'column', width: 'weighted', weight: 1, vertical_align: 'center',
-                                elements: [{ tag: 'markdown', text_size: 'notation_small_v2', content: footerContent || ' ' }],
+                                elements: [footer?.element ?? {
+                                        tag: 'markdown',
+                                        text_size: 'notation_small_v2',
+                                        content: ' ',
+                                    }],
                             },
                             {
                                 tag: 'column', width: 'auto', vertical_align: 'center',
@@ -7017,11 +7612,8 @@ async function cmdSend(rest) {
                     });
                 }
                 else {
-                    elements.push({
-                        tag: 'markdown',
-                        text_size: 'notation_small_v2',
-                        content: footerContent,
-                    });
+                    if (footer)
+                        elements.push(footer.element);
                 }
             }
             const cardJson = JSON.stringify({
@@ -7168,6 +7760,9 @@ async function cmdDispatch(rest) {
   --session-id <id>     指定来源会话（默认自动推断）`);
         return;
     }
+    // dispatch opens a real Feishu topic + pulls bots into a chat (a write). A
+    // no-transport turn has no Feishu chat to dispatch into — central hard gate.
+    assertTurnTransportOrExit('dispatch');
     process.env.SESSION_DATA_DIR ??= resolveDataDir();
     const sessionIdArg = argValue(rest, '--session-id');
     const title = argValue(rest, '--title') ?? '';
@@ -7234,6 +7829,11 @@ async function cmdDispatch(rest) {
         console.error(`session ${sid} 缺少 larkAppId`);
         process.exit(1);
     }
+    // Target-aware gate on the RESOLVED source session: dispatch from a virtual /
+    // apiOnly source turn is refused even with a real --chat-id override (a
+    // no-transport turn may not originate a Feishu topic/write). Closes the
+    // `dispatch --session-id <virtual> --chat-id oc_real` env-only gap.
+    assertSessionTransportOrExit({ chatId: s.chatId, larkAppId: s.larkAppId }, 'dispatch');
     const targetChatId = overrideChatId ?? s.chatId;
     if (!targetChatId) {
         console.error(`session ${sid} 缺少 chatId，且未提供 --chat-id`);
@@ -7799,6 +8399,9 @@ botmux create-group — 用一组机器人新建飞书群
 `);
         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');
     process.env.SESSION_DATA_DIR ??= resolveDataDir();
     const botRefs = argValues(rest, '--bot');
     const name = argValue(rest, '--name');
@@ -8422,10 +9025,22 @@ async function cmdBots(sub, rest) {
         console.error('用法: botmux bots list [--session-id ID]');
         process.exit(1);
     }
+    // `bots list` reads the Feishu chat roster (listChatBotMembers). A no-transport
+    // turn has no chat roster — central hard gate (also stops the routing prompt
+    // from advertising a Feishu-dependent helper in this context).
+    assertTurnTransportOrExit('bots list');
     const sessionIdArg = argValue(rest, '--session-id');
-    // 与 history/quoted 同一前奏：本地会话解析 + riff sandbox env 合成会话兜底
-    //（远端沙箱无 sessions.json/bots.json 时 `botmux bots list` 照常可用）。
+    // 与 history/quoted 同一前奏：先从本 bot 自己的 send-cred 文件注册，让 Lark client
+    // 在**不读被 deny 的 bots.json** 的前提下可用，再做会话解析 + riff sandbox env
+    // 合成会话兜底。漏掉 registerSelfFromCredFile() 时读隔离 bot 的
+    // `botmux bots list` 会在 getBotClient() 上抛 "Bot not registered"，
+    // listChatBotMembers() 把它降级成 legacy discovery（configured 行同样来自
+    // bots.json）→ 返回 `total: 0`。**失败形态是静默的**：沙盒 bot 拿到空花名册会
+    // 按"只 @ mentionable 的"判定群里没人可 @，多 bot 协作直接不发生且不报错。
+    await registerSelfFromCredFile();
     const { sid, larkAppId: resolvedAppId, session: s } = await resolveSessionAppId(sessionIdArg);
+    // Target-aware gate (see cmdHistory).
+    assertSessionTransportOrExit({ chatId: s.chatId, larkAppId: resolvedAppId }, 'bots list');
     const appId = resolvedAppId;
     const dataDir = resolveDataDir();
     const botInfoPath = join(dataDir, 'bots-info.json');
@@ -9495,6 +10110,29 @@ async function runPluginCommandByName(rawCommand, commandArgs) {
         process.exitCode = result;
     return true;
 }
+// ─── Central root-dispatch transport gate ──────────────────────────────────
+// A MANAGED no-transport turn (a CLI turn the daemon spawned for an apiOnly bot
+// or an HTTP virtual session) must not run ANY Lark-facing command. The managed
+// origin is resolved via the pid-marker ANCESTRY (resolveSessionContext walks
+// process.ppid to a worker-written marker) — NOT the mutable BOTMUX_SESSION_ID
+// env — so `env -u BOTMUX_SESSION_ID … botmux create-group` cannot shed the
+// managed identity. We then load THAT session's record and gate on its chatId +
+// its bot's apiOnly (config, not env), so unsetting BOTMUX_CHAT_ID/LARK_APP_ID
+// also can't flip the verdict. Covers every Feishu-facing verb by construction.
+// A BARE host-operator shell (no ancestry marker, no env session) resolves no
+// managed origin → NOT gated: the operator keeps full access. per-command +
+// daemon-side getBotClient/larkTransportEnabled gates remain authoritative.
+const LARK_FACING_COMMANDS = new Set([
+    'send', 'dispatch', 'create-group', 'history', 'quoted', 'bots', 'grant', 'react', 'thread',
+    'vc-agent', 'report',
+]);
+if (LARK_FACING_COMMANDS.has(command) && managedOriginHasNoTransport()) {
+    console.error(`botmux ${command} is unavailable: this managed turn has no Feishu transport ` +
+        `(core-only apiOnly bot or HTTP control-API session).\n` +
+        `Feishu read/write is not possible for this turn — it communicates only over the HTTP\n` +
+        `control API (input via trigger, output via trigger-result). Produce your normal answer.`);
+    process.exit(2);
+}
 switch (command) {
     case '--version':
     case '-v':
@@ -9524,6 +10162,9 @@ switch (command) {
     case 'start':
         await cmdStart();
         break;
+    case 'serve':
+        await cmdServe(process.argv.slice(3));
+        break;
     case 'start-bot':
         await cmdStartBot(process.argv.slice(3));
         break;
@@ -9564,6 +10205,9 @@ switch (command) {
     case 'ls':
         await cmdList();
         break;
+    case '__zmx-attach-managed':
+        cmdManagedZmxAttach(process.argv.slice(3));
+        break;
     case 'delete':
     case 'del':
     case 'rm':
@@ -9642,7 +10286,9 @@ switch (command) {
             process.exitCode = 2;
             break;
         }
-        process.env.SESSION_DATA_DIR ??= resolveDataDir();
+        if (!process.env.SESSION_DATA_DIR?.trim()) {
+            process.env.SESSION_DATA_DIR = resolveDataDir();
+        }
         const { runMcpGateway } = await import('./core/plugins/mcp/gateway.js');
         await runMcpGateway();
         break;
@@ -9747,6 +10393,9 @@ switch (command) {
     case 'send':
         await cmdSend(process.argv.slice(3));
         break;
+    case 'chat':
+        await cmdChat(process.argv.slice(3));
+        break;
     case 'dispatch':
         await cmdDispatch(process.argv.slice(3));
         break;