botmux 3.18.1-canary.1 → 3.18.1

package/dist/.runtime-build-id

@@ -1 +1 @@
-e8ef743d8ea764f65f1e939f4659498c9f230eea00a5ab50b65729c9a17b6513
+fe18e71ce88eb4d7f499718feca364ab691a40844341131b1eb806a5b2802e46

package/dist/cli/daemon-lifecycle-env.d.ts

@@ -1,4 +1,4 @@
-export declare const DAEMON_ENV_KEYS: readonly ["WEB_EXTERNAL_HOST", "BOTMUX_DASHBOARD_EXTERNAL_HOST", "BOTMUX_DASHBOARD_HOST", "BOTMUX_DASHBOARD_PORT", "BOTMUX_DAEMON_IPC_BASE_PORT", "BOTMUX_DASHBOARD_PUBLIC_READONLY", "BOTMUX_PUBLIC_URL", "BOTMUX_DASHBOARD_CONTROL_AUDIT_PATH", "BOTMUX_DASHBOARD_TERMINAL_CONTROL_TTL_MS"];
+export declare const DAEMON_ENV_KEYS: readonly ["WEB_EXTERNAL_HOST", "BOTMUX_DASHBOARD_EXTERNAL_HOST", "BOTMUX_DASHBOARD_HOST", "BOTMUX_DASHBOARD_PORT", "BOTMUX_DAEMON_IPC_BASE_PORT", "BOTMUX_DASHBOARD_PUBLIC_READONLY", "BOTMUX_PUBLIC_URL", "BOTMUX_DASHBOARD_CONTROL_AUDIT_PATH", "BOTMUX_DASHBOARD_TERMINAL_CONTROL_TTL_MS", "BOTMUX_DEVBOX_AUTO_EXPORT"];
 export type DaemonEnvKey = (typeof DAEMON_ENV_KEYS)[number];
 /**
  * Pin both PM2 apps to one deterministic ~/.botmux/.env snapshot. A restart

package/dist/cli/daemon-lifecycle-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daemon-lifecycle-env.d.ts","sourceRoot":"","sources":["../../src/cli/daemon-lifecycle-env.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,eAAe,+RAuBlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,CAAC,UAAU,EAC/B,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAe9B"}
+{"version":3,"file":"daemon-lifecycle-env.d.ts","sourceRoot":"","sources":["../../src/cli/daemon-lifecycle-env.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,eAAe,4TA6BlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,CAAC,UAAU,EAC/B,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAe9B"}

package/dist/cli/daemon-lifecycle-env.js

@@ -41,6 +41,12 @@ export const DAEMON_ENV_KEYS = [
     // keeps them on the deterministic resolveDaemonEnv snapshot semantics.
     'BOTMUX_DASHBOARD_CONTROL_AUDIT_PATH',
     'BOTMUX_DASHBOARD_TERMINAL_CONTROL_TTL_MS',
+    // Merlin Devbox auto-export switch (platform/devbox-dashboard-export.ts).
+    // The dashboard resolves it (dashboard-url / control-csrf run there), so it
+    // has to survive the allowlist copy — same reason BOTMUX_PUBLIC_URL is here.
+    // The CLI, which is the side that spawns merlin-cli, has no dotenv step at
+    // all and reads the key straight from ~/.botmux/.env instead.
+    'BOTMUX_DEVBOX_AUTO_EXPORT',
 ];
 /**
  * Pin both PM2 apps to one deterministic ~/.botmux/.env snapshot. A restart

package/dist/cli/daemon-lifecycle-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"daemon-lifecycle-env.js","sourceRoot":"","sources":["../../src/cli/daemon-lifecycle-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAE/B,+EAA+E;AAC/E,iFAAiF;AACjF,6EAA6E;AAC7E,gFAAgF;AAChF,0EAA0E;AAC1E,0CAA0C;AAC1C,EAAE;AACF,8EAA8E;AAC9E,iEAAiE;AACjE,yEAAyE;AACzE,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,+BAA+B;AAC/B,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,mBAAmB;IACnB,gCAAgC;IAChC,uBAAuB;IACvB,uBAAuB;IACvB,6BAA6B;IAC7B,kCAAkC;IAClC,8DAA8D;IAC9D,yEAAyE;IACzE,yEAAyE;IACzE,2EAA2E;IAC3E,8CAA8C;IAC9C,mBAAmB;IACnB,qEAAqE;IACrE,wEAAwE;IACxE,gFAAgF;IAChF,6EAA6E;IAC7E,2EAA2E;IAC3E,sEAAsE;IACtE,4EAA4E;IAC5E,uEAAuE;IACvE,qCAAqC;IACrC,0CAA0C;CAClC,CAAC;AAIX;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,YAA+B,EAC/B,WAAoB;IAEpB,MAAM,OAAO,GAAG,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACpE,MAAM,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,CAAC,GAAiB,EAAU,EAAE;QAC5C,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/E,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC,CAAC;IAEF,6EAA6E;IAC7E,oDAAoD;IACpD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CACjC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAChB,CAAC;IAClC,QAAQ,CAAC,qBAAqB,KAAK,SAAS,CAAC;IAC7C,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"daemon-lifecycle-env.js","sourceRoot":"","sources":["../../src/cli/daemon-lifecycle-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAE/B,+EAA+E;AAC/E,iFAAiF;AACjF,6EAA6E;AAC7E,gFAAgF;AAChF,0EAA0E;AAC1E,0CAA0C;AAC1C,EAAE;AACF,8EAA8E;AAC9E,iEAAiE;AACjE,yEAAyE;AACzE,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,+BAA+B;AAC/B,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,mBAAmB;IACnB,gCAAgC;IAChC,uBAAuB;IACvB,uBAAuB;IACvB,6BAA6B;IAC7B,kCAAkC;IAClC,8DAA8D;IAC9D,yEAAyE;IACzE,yEAAyE;IACzE,2EAA2E;IAC3E,8CAA8C;IAC9C,mBAAmB;IACnB,qEAAqE;IACrE,wEAAwE;IACxE,gFAAgF;IAChF,6EAA6E;IAC7E,2EAA2E;IAC3E,sEAAsE;IACtE,4EAA4E;IAC5E,uEAAuE;IACvE,qCAAqC;IACrC,0CAA0C;IAC1C,0EAA0E;IAC1E,4EAA4E;IAC5E,6EAA6E;IAC7E,2EAA2E;IAC3E,8DAA8D;IAC9D,2BAA2B;CACnB,CAAC;AAIX;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,YAA+B,EAC/B,WAAoB;IAEpB,MAAM,OAAO,GAAG,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACpE,MAAM,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,CAAC,GAAiB,EAAU,EAAE;QAC5C,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/E,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC,CAAC;IAEF,6EAA6E;IAC7E,oDAAoD;IACpD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CACjC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAChB,CAAC;IAClC,QAAQ,CAAC,qBAAqB,KAAK,SAAS,CAAC;IAC7C,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA8BA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AA6KhD,OAAO,EAAE,KAAK,KAAK,EAA0C,MAAM,yBAAyB,CAAC;AAujB7F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,GAAG,OAAO,CACpF;IACE,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,oDAAoD;IACpD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CACrC,CA6LA;AAmlDD,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,gBAAgB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtH,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,iBAAiB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AA6jQxG;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,qBAAqB,EAAE,SAAS,CAAC,EAC9F,KAAK,EAAE,MAAM,EACb,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,2BAA2B,EAAE,UAAU,GAAG,IAAI,CAAC;AAC1F;qDACqD;AACrD,wBAAwB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,2BAA2B,EAAE,UAAU,GAAG,IAAI,CAAC,GAClH,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAuL7B"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA8BA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAgLhD,OAAO,EAAE,KAAK,KAAK,EAA0C,MAAM,yBAAyB,CAAC;AAujB7F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,GAAG,OAAO,CACpF;IACE,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,oDAAoD;IACpD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CACrC,CA6LA;AAmlDD,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,gBAAgB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtH,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,iBAAiB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAmmQxG;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,qBAAqB,EAAE,SAAS,CAAC,EAC9F,KAAK,EAAE,MAAM,EACb,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,2BAA2B,EAAE,UAAU,GAAG,IAAI,CAAC;AAC1F;qDACqD;AACrD,wBAAwB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,2BAA2B,EAAE,UAAU,GAAG,IAAI,CAAC,GAClH,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAuL7B"}

package/dist/cli.js

@@ -55,7 +55,7 @@ import { buildPreset, serializePreset, presetFilename } from './setup/agent-pres
 import { validateCodexAppManagedSendOrigin, } from './utils/codex-app-dispatch-ledger.js';
 import { hasProtectedSessionMutationOwnership } from './core/session-mutation-guard.js';
 import { logger } from './utils/logger.js';
-import { reapLegacyPm2 } from './core/legacy-pm2-reaper.js';
+import { reapLegacyPm2, liveGodAt } from './core/legacy-pm2-reaper.js';
 import { withFileLock, withFileLockSync } from './utils/file-lock.js';
 import { scheduleTimeZone } from './utils/timezone.js';
 import { expandHomePath, invalidWorkingDirs } from './utils/working-dir.js';
@@ -72,6 +72,9 @@ import { buildCardPatchSuccessOutput, CARD_COMMAND_USAGE, CARD_PATCH_USAGE, card
 import { dispatchDeferredTopicSend, reusableDeferredTopicRoot } from './cli/deferred-topic-send.js';
 import { readDeferredTopicBinding } from './core/deferred-topic-binding.js';
 import { callDashboard } from './cli/dashboard-endpoint.js';
+import { ensureDevboxDashboardExport } from './platform/devbox-dashboard-export.js';
+import { platformMachineBaseUrl, publicReverseProxyBaseUrl } from './platform/binding.js';
+import { isRemoteAccessEnabled } from './global-config.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';
@@ -2525,14 +2528,18 @@ async function ensureSystemDependencies() {
  * supervisor view while old pm2-managed daemons keep running. Self-contained:
  * no pm2 CLI call. `botmux start`/`restart` will reap it (reapLegacyPm2).
  *
- * TWO SIGNALS, deliberately different per home — this must agree with
- * reapLegacyPm2's detection or the warning lies in one direction or the other:
+ * TWO SIGNALS, deliberately different per home. Both go through the reaper's own
+ * `liveGodAt` so the warning and the reaper cannot disagree — this used to be a
+ * second, hand-kept copy of that logic, and it drifted: it trusted a bare
+ * `kill(pid, 0)` (true for the ZOMBIE a fresh reap leaves behind) and a bare
+ * `existsSync(rpc.sock)` (which outlives `pm2 kill`), so the warning survived a
+ * SUCCESSFUL migration and no amount of re-running `restart` could clear it.
  *
  *  • The botmux-dedicated home (~/.botmux/pm2) is exclusively ours, so ANY live
- *    God there is a migration leftover. Detect it by pm2.pid OR rpc.sock: a real
- *    God was observed supervising 50 daemons with NO pm2.pid at all, and a
- *    pid-file-only probe stayed silent through exactly the situation this warning
- *    exists for.
+ *    God there is a migration leftover. `liveGodAt` detects it by pm2.pid OR a
+ *    held rpc.sock: a real God was observed supervising 50 daemons with NO
+ *    pm2.pid at all, and a pid-file-only probe stayed silent through exactly the
+ *    situation this warning exists for.
  *
  *  • The shared default (~/.pm2) may be the user's own pm2 running unrelated
  *    apps. A live God there means nothing by itself — MEASURED on this box: the
@@ -2543,32 +2550,10 @@ async function ensureSystemDependencies() {
  */
 function legacyBotmuxGodAlive() {
     const dedicated = join(CONFIG_DIR, 'pm2');
-    if (pm2GodAlive(dedicated))
+    if (liveGodAt(dedicated) !== null)
         return true;
     const shared = join(homedir(), '.pm2');
-    return pm2GodAlive(shared) && sharedHomeHasBotmuxRows(shared);
-}
-/** A God is alive at `home` if its pid file points at a live process, or (when
- *  the file is missing/stale) its RPC socket is still there. */
-function pm2GodAlive(home) {
-    const pidFile = join(home, 'pm2.pid');
-    if (existsSync(pidFile)) {
-        let pid = 0;
-        try {
-            pid = parseInt(readFileSync(pidFile, 'utf-8').trim(), 10);
-        }
-        catch {
-            pid = 0;
-        }
-        if (Number.isSafeInteger(pid) && pid > 1) {
-            try {
-                process.kill(pid, 0);
-                return true;
-            }
-            catch { /* stale — try the socket */ }
-        }
-    }
-    return existsSync(join(home, 'rpc.sock'));
+    return liveGodAt(shared) !== null && sharedHomeHasBotmuxRows(shared);
 }
 /** Does the SHARED pm2 home actually hold botmux apps? pm2 writes one pid file
  *  per app as `pids/<name>-<id>.pid`, so this answers it without running pm2.
@@ -2796,6 +2781,22 @@ async function callDashboardEndpoint(path) {
         path,
     });
 }
+/**
+ * Merlin Devbox 上为当前 dashboard 端口创建（或复用）私有短链。
+ *
+ * 端口取 dashboard 落盘的 `.dashboard-port`（端口探测可能落在 7891 之外），与
+ * `devboxDashboardBaseUrl()` 读侧用的是同一份判据，避免写 9002、读 9001。
+ * 非 Devbox / 已配置中心平台或自建反代 / `merlin-cli` 不可用时全部静默 no-op。
+ */
+async function ensureDevboxDashboardExportForCurrentPort() {
+    const portFile = join(CONFIG_DIR, '.dashboard-port');
+    const port = Number((existsSync(portFile) ? readFileSync(portFile, 'utf8').trim() : '')
+        || process.env.BOTMUX_DASHBOARD_PORT || '7891');
+    await ensureDevboxDashboardExport({
+        port,
+        remoteBaseConfigured: Boolean((isRemoteAccessEnabled() && platformMachineBaseUrl()) || publicReverseProxyBaseUrl()),
+    });
+}
 /**
  * Best-effort dashboard hint printed after start/restart. Reads the LIVE link
  * via /__cli/current (non-rotating) so an already-shared URL is preserved.
@@ -2807,6 +2808,10 @@ async function printDashboardHintWithRetry() {
     const stepMs = 500;
     const started = Date.now();
     let last = null;
+    // 只在轮询之前做一次：导出结果与「dashboard 起没起来」无关，放在循环体里每轮都会
+    // 重新 spawn 一次 merlin-cli，而失败路径最坏每轮付满 5s 超时——本函数自己的预算
+    // 才 6s，实测会把 start/restart 的这段拖到近两倍。
+    await ensureDevboxDashboardExportForCurrentPort();
     while (Date.now() - started < maxWaitMs) {
         last = await callDashboardEndpoint('/__cli/current');
         if (last.ok) {
@@ -2842,6 +2847,12 @@ async function printDashboardHintWithRetry() {
  * `dashboard` is the non-rotating get-or-create form; help and invalid
  * subcommands never call either credential endpoint. */
 async function cmdDashboard(args) {
+    const rawAction = args[0]?.toLowerCase();
+    const resolvesEndpoint = args.length <= 1
+        && !args.some(arg => ['--help', '-h', 'help'].includes(arg.toLowerCase()))
+        && (rawAction === undefined || rawAction === 'current' || rawAction === 'rotate');
+    if (resolvesEndpoint)
+        await ensureDevboxDashboardExportForCurrentPort();
     const execution = await executeDashboardCommand(args, callDashboardEndpoint);
     if (execution.kind === 'help') {
         console.log(DASHBOARD_COMMAND_USAGE);
@@ -6270,6 +6281,25 @@ async function cmdHistory(rest) {
                 ...(cardJson !== undefined ? { cardJson } : {}),
             };
         }));
+        // Range guidance, emitted at the moment the model is actually reading
+        // history. The decisive fact is `sessionScope` (this session's own scope),
+        // NOT the chat's `chat_mode`: a thread opened inside a 普通群 keeps
+        // chat_mode='group' while its session is thread-scope, so reasoning from the
+        // group type would wrongly conclude "I may search the whole chat". Both
+        // `--scope` gates above key on isChatScope for exactly that reason.
+        //
+        // Wording note: describe only what the model can OBSERVE. Daemon-side
+        // invocations (`/t` and friends) are stripped before the prompt is built, so
+        // the model never sees them — naming them here would be an instruction it
+        // cannot act on. Describe the symptom instead: the topic starts mid-discussion
+        // and its own history looks too short to explain the task.
+        const rangeHint = isChatScope
+            ? '范围：本次返回当前群整群最近 N 条（不限于 session 创建之后）。需要更早的消息就把 `--limit` 调大。当前是 chat-scope 会话，没有话题边界，`--scope thread` / `--scope ambient` 在此不适用。'
+            : effectiveScope === 'thread'
+                ? '范围：本次只返回当前话题内的消息。如果话题内的内容不足以说明任务背景（例如任务像是延续话题之外的讨论、出现没有出处的指代或结论），说明上下文在话题外的群聊里：用 `botmux history --scope ambient --limit 20` 读取本话题之外、话题根之前的群聊消息（自动排除本话题）。注意隐私边界：ambient 会读到话题外的群聊内容，仅在确实需要群聊背景时使用，并优先用较小的 limit。'
+                : effectiveScope === 'ambient'
+                    ? '范围：本次返回的是话题之外的群聊消息（话题根之前，已排除本话题）。要回到本话题内的消息用 `botmux history`（默认即本话题）。'
+                    : '范围：本次按 `--scope chat` 返回整群最近 N 条（含本话题内的消息）。只要本话题内的用 `botmux history`（默认即本话题）。';
         console.log(JSON.stringify({
             sessionId: sid,
             chatId: s.chatId,
@@ -6285,6 +6315,7 @@ async function cmdHistory(rest) {
             } : {}),
             messages,
             total: messages.length,
+            rangeHint,
             // Discoverability: agents reading history often need the actual image
             // bytes (alert charts) or the raw card JSON — both live one command away.
             ...(messages.some(m => m.resources?.length || m.msgType === 'interactive') ? {