botmux 3.15.0 → 3.16.0

package/dist/core/session-model.js

@@ -0,0 +1,42 @@
+/**
+ * The model botmux passes to the CLI for a given session's next spawn.
+ *
+ * Unlike `cliId` / `cliRuntime` / `wrapperCli` — which are frozen onto the
+ * session at creation so a live conversation never has its runtime swapped
+ * underneath it — the model is resolved from the LIVE bot config on every
+ * spawn, resume included. Rationale: the model configured in the dashboard is
+ * an explicit human choice, and it used to be silently outranked forever by
+ * whatever default the session happened to inherit when it was created (the old
+ * `session.model` freeze), so a long-running session could never be moved off
+ * its original model.
+ *
+ * Precedence:
+ *   1. `spawnModelOverride` — an explicit per-trigger choice (trigger API
+ *      `options.model`), in-memory only, see DaemonSession.
+ *   2. the live bot config, **only when the session's frozen `cliId` still
+ *      matches the bot's** — a session pinned to another CLI (a bot that
+ *      switched CLI later, or a Codex App thread takeover that forces
+ *      `codex-app`) must not be handed a model string meant for a different
+ *      CLI.
+ *   3. the model this session was last launched with (`session.model`, stamped
+ *      by sessionAgentConfig on every spawn), as a last resort for exactly that
+ *      mismatch case: it is the value that CLI actually ran with. Never
+ *      consulted while the live config applies, which is what makes a dashboard
+ *      edit effective on old sessions.
+ *
+ * `undefined` → botmux passes no model flag and the CLI resolves its own
+ * default (for `claude --resume`, that means the model recorded in the
+ * transcript).
+ */
+export function resolveSessionLaunchModel(ds, botCfg) {
+    if (ds.spawnModelOverride)
+        return ds.spawnModelOverride;
+    // No live config to consult (deregistered bot / display surfaces that tolerate
+    // a missing registry entry) → the session's own record is the best we have.
+    if (!botCfg)
+        return ds.session.model;
+    const sessionCliId = ds.session.cliId;
+    const cliMatchesBot = !sessionCliId || !botCfg.cliId || sessionCliId === botCfg.cliId;
+    return cliMatchesBot ? botCfg.model : ds.session.model;
+}
+//# sourceMappingURL=session-model.js.map

package/dist/core/session-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-model.js","sourceRoot":"","sources":["../../src/core/session-model.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,yBAAyB,CACvC,EAAsB,EACtB,MAA6B;IAE7B,IAAI,EAAE,CAAC,kBAAkB;QAAE,OAAO,EAAE,CAAC,kBAAkB,CAAC;IACxD,+EAA+E;IAC/E,4EAA4E;IAC5E,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACrC,MAAM,YAAY,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACtC,MAAM,aAAa,GAAG,CAAC,YAAY,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,YAAY,KAAK,MAAM,CAAC,KAAK,CAAC;IACtF,OAAO,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;AACzD,CAAC"}

package/dist/core/session-owner-reminder.d.ts

@@ -0,0 +1,63 @@
+import type { DaemonSession } from './types.js';
+export declare const SESSION_OWNER_REMINDER_STATES: readonly ["idle", "dormant", "pending_repo", "tui_prompt", "agent_attention", "limited"];
+export type SessionOwnerReminderState = typeof SESSION_OWNER_REMINDER_STATES[number];
+export interface SessionOwnerReminderConfig {
+    enabled: boolean;
+    intervalMinutes: number;
+    text: string;
+    states: SessionOwnerReminderState[];
+}
+export interface SessionOwnerReminderRecord {
+    sessionId: string;
+    stateFingerprint: string;
+    actionableSince: number;
+    lastObservedActivityAt: number;
+    lastRemindedAt?: number;
+    retryAfterAt?: number;
+}
+export type SessionOwnerReminderRecords = Record<string, SessionOwnerReminderRecord>;
+export declare const DEFAULT_SESSION_OWNER_REMINDER: SessionOwnerReminderConfig;
+/** Strict normalizer shared by config loading and write validation. */
+export declare function normalizeSessionOwnerReminderConfig(raw: unknown): SessionOwnerReminderConfig | undefined;
+export declare function deriveSessionOwnerReminderStates(ds: DaemonSession): SessionOwnerReminderState[];
+/**
+ * Observation fingerprint used both to detect a state transition (reset the
+ * quiet period) and to seed the per-cycle delivery UUID. It must capture not
+ * only WHICH runtime signals are present but also their INSTANCE identity for
+ * the signals that get replaced in place while the label stays constant:
+ *
+ *   - `agent_attention` → a fresh `{kind, reason, at}` is written on every new
+ *     attention raise, so key on `agentAttention.at`.
+ *   - `tui_prompt`      → an old TUI prompt card is cleared and a new
+ *     `tuiPromptCardId` set between scans, so key on that id.
+ *
+ * Without the instance component, the old signal being resolved and a brand-new
+ * same-category signal appearing (e.g. a second, unrelated attention request)
+ * would inherit the previous signal's elapsed quiet time and could @ the owner
+ * almost immediately — undercutting the "give N minutes to handle THIS" promise.
+ *
+ * The remaining states (idle / dormant / pending_repo / limited) have no
+ * distinct replaceable instance, so their label alone is a faithful key.
+ *
+ * INVARIANT: for a fixed instance the fingerprint is stable across scans, so a
+ * within-cycle failed-send retry recomputes the SAME fingerprint → the same
+ * delivery UUID → the existing Lark dedupe window still suppresses duplicates.
+ * A new instance changes the fingerprint, which resets the record and thereby
+ * starts a fresh cycle whose eventual UUID is legitimately different.
+ */
+export declare function sessionOwnerReminderObservationFingerprint(ds: DaemonSession, states: SessionOwnerReminderState[]): string;
+export interface SessionOwnerReminderControllerDeps {
+    load(): SessionOwnerReminderRecords;
+    save(records: SessionOwnerReminderRecords): void;
+    send(ds: DaemonSession, text: string, uuid: string): Promise<void>;
+    canSend(ds: DaemonSession): boolean;
+    onError?(ds: DaemonSession, error: unknown): void;
+}
+export declare function sessionOwnerReminderDeliveryUuid(sessionId: string, stateFingerprint: string, dueBase: number): string;
+/** Durable, deterministic scan engine. Scheduling and Lark IO are injected. */
+export declare class SessionOwnerReminderController {
+    private readonly deps;
+    constructor(deps: SessionOwnerReminderControllerDeps);
+    scan(sessions: Iterable<DaemonSession>, config: SessionOwnerReminderConfig, now?: number): Promise<void>;
+}
+//# sourceMappingURL=session-owner-reminder.d.ts.map

package/dist/core/session-owner-reminder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-owner-reminder.d.ts","sourceRoot":"","sources":["../../src/core/session-owner-reminder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,6BAA6B,0FAOhC,CAAC;AAEX,MAAM,MAAM,yBAAyB,GAAG,OAAO,6BAA6B,CAAC,MAAM,CAAC,CAAC;AAErF,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,yBAAyB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;AAErF,eAAO,MAAM,8BAA8B,EAAE,0BAK5C,CAAC;AAYF,uEAAuE;AACvE,wBAAgB,mCAAmC,CACjD,GAAG,EAAE,OAAO,GACX,0BAA0B,GAAG,SAAS,CAoBxC;AAED,wBAAgB,gCAAgC,CAAC,EAAE,EAAE,aAAa,GAAG,yBAAyB,EAAE,CAY/F;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,0CAA0C,CACxD,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,yBAAyB,EAAE,GAClC,MAAM,CAQR;AAED,MAAM,WAAW,kCAAkC;IACjD,IAAI,IAAI,2BAA2B,CAAC;IACpC,IAAI,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,OAAO,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC;IACpC,OAAO,CAAC,CAAC,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACnD;AAMD,wBAAgB,gCAAgC,CAC9C,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM,GACd,MAAM,CAMR;AAED,+EAA+E;AAC/E,qBAAa,8BAA8B;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,kCAAkC;IAE/D,IAAI,CACR,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,EACjC,MAAM,EAAE,0BAA0B,EAClC,GAAG,GAAE,MAAmB,GACvB,OAAO,CAAC,IAAI,CAAC;CA2EjB"}

package/dist/core/session-owner-reminder.js

@@ -0,0 +1,196 @@
+import { createHash } from 'node:crypto';
+export const SESSION_OWNER_REMINDER_STATES = [
+    'idle',
+    'dormant',
+    'pending_repo',
+    'tui_prompt',
+    'agent_attention',
+    'limited',
+];
+export const DEFAULT_SESSION_OWNER_REMINDER = {
+    enabled: false,
+    intervalMinutes: 30,
+    text: '该会话已等待处理，请继续跟进。',
+    states: [...SESSION_OWNER_REMINDER_STATES],
+};
+const MIN_INTERVAL_MINUTES = 1;
+const MAX_INTERVAL_MINUTES = 10_080;
+const MAX_TEXT_CHARS = 500;
+const FAILURE_RETRY_MAX_MS = 5 * 60_000;
+function isState(value) {
+    return typeof value === 'string'
+        && SESSION_OWNER_REMINDER_STATES.includes(value);
+}
+/** Strict normalizer shared by config loading and write validation. */
+export function normalizeSessionOwnerReminderConfig(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const value = raw;
+    if (typeof value.enabled !== 'boolean')
+        return undefined;
+    if (!Number.isInteger(value.intervalMinutes)
+        || value.intervalMinutes < MIN_INTERVAL_MINUTES
+        || value.intervalMinutes > MAX_INTERVAL_MINUTES)
+        return undefined;
+    if (typeof value.text !== 'string')
+        return undefined;
+    const text = value.text.trim();
+    if (!text || Array.from(text).length > MAX_TEXT_CHARS || /<\s*at\b/i.test(text))
+        return undefined;
+    if (!Array.isArray(value.states))
+        return undefined;
+    const states = [...new Set(value.states.filter(isState))];
+    if (states.length !== value.states.length)
+        return undefined;
+    if (value.enabled && states.length === 0)
+        return undefined;
+    return {
+        enabled: value.enabled,
+        intervalMinutes: value.intervalMinutes,
+        text,
+        states,
+    };
+}
+export function deriveSessionOwnerReminderStates(ds) {
+    const states = [];
+    const workerAlive = !!ds.worker && !ds.worker.killed;
+    if (workerAlive && ds.lastScreenStatus === 'idle')
+        states.push('idle');
+    // A pre-spawn repository picker is its own actionable state, not a released
+    // CLI. Likewise stale screen status belongs to the old worker lifetime.
+    if (!workerAlive && !ds.pendingRepo)
+        states.push('dormant');
+    if (ds.pendingRepo)
+        states.push('pending_repo');
+    if (ds.tuiPromptCardId)
+        states.push('tui_prompt');
+    if (ds.agentAttention)
+        states.push('agent_attention');
+    if (workerAlive && ds.lastScreenStatus === 'limited')
+        states.push('limited');
+    return states;
+}
+/**
+ * Observation fingerprint used both to detect a state transition (reset the
+ * quiet period) and to seed the per-cycle delivery UUID. It must capture not
+ * only WHICH runtime signals are present but also their INSTANCE identity for
+ * the signals that get replaced in place while the label stays constant:
+ *
+ *   - `agent_attention` → a fresh `{kind, reason, at}` is written on every new
+ *     attention raise, so key on `agentAttention.at`.
+ *   - `tui_prompt`      → an old TUI prompt card is cleared and a new
+ *     `tuiPromptCardId` set between scans, so key on that id.
+ *
+ * Without the instance component, the old signal being resolved and a brand-new
+ * same-category signal appearing (e.g. a second, unrelated attention request)
+ * would inherit the previous signal's elapsed quiet time and could @ the owner
+ * almost immediately — undercutting the "give N minutes to handle THIS" promise.
+ *
+ * The remaining states (idle / dormant / pending_repo / limited) have no
+ * distinct replaceable instance, so their label alone is a faithful key.
+ *
+ * INVARIANT: for a fixed instance the fingerprint is stable across scans, so a
+ * within-cycle failed-send retry recomputes the SAME fingerprint → the same
+ * delivery UUID → the existing Lark dedupe window still suppresses duplicates.
+ * A new instance changes the fingerprint, which resets the record and thereby
+ * starts a fresh cycle whose eventual UUID is legitimately different.
+ */
+export function sessionOwnerReminderObservationFingerprint(ds, states) {
+    return states
+        .map(state => {
+        if (state === 'agent_attention')
+            return `agent_attention:${ds.agentAttention?.at ?? ''}`;
+        if (state === 'tui_prompt')
+            return `tui_prompt:${ds.tuiPromptCardId ?? ''}`;
+        return state;
+    })
+        .join(',');
+}
+function recordsSnapshot(value) {
+    return JSON.stringify(value);
+}
+export function sessionOwnerReminderDeliveryUuid(sessionId, stateFingerprint, dueBase) {
+    const digest = createHash('sha256')
+        .update(`${sessionId}\0${stateFingerprint}\0${dueBase}`, 'utf8')
+        .digest('hex')
+        .slice(0, 32);
+    return `owner-reminder-${digest}`;
+}
+/** Durable, deterministic scan engine. Scheduling and Lark IO are injected. */
+export class SessionOwnerReminderController {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async scan(sessions, config, now = Date.now()) {
+        const current = this.deps.load();
+        const before = recordsSnapshot(current);
+        if (!config.enabled || config.states.length === 0) {
+            if (Object.keys(current).length > 0)
+                this.deps.save({});
+            return;
+        }
+        const configured = new Set(config.states);
+        const seen = new Set();
+        const intervalMs = config.intervalMinutes * 60_000;
+        for (const ds of sessions) {
+            const sessionId = ds.session.sessionId;
+            if (ds.session.status !== 'active'
+                || ds.session.queued === true
+                || (ds.scope ?? ds.session.scope) !== 'thread'
+                || !ds.session.ownerOpenId
+                || !this.deps.canSend(ds)) {
+                delete current[sessionId];
+                continue;
+            }
+            const projectedStates = deriveSessionOwnerReminderStates(ds);
+            const matched = projectedStates.filter(state => configured.has(state));
+            if (matched.length === 0) {
+                delete current[sessionId];
+                continue;
+            }
+            seen.add(sessionId);
+            // Eligibility follows the configured subset, but timer resets follow the
+            // complete runtime state. An unselected attention signal still represents
+            // a state transition and starts a fresh quiet period. The fingerprint also
+            // captures instance identity (attention.at / tuiPromptCardId) so a NEW
+            // same-category signal replacing a resolved one resets the timer instead
+            // of inheriting the old quiet period — see the fingerprint helper above.
+            const stateFingerprint = sessionOwnerReminderObservationFingerprint(ds, projectedStates);
+            const activityAt = Number.isFinite(ds.lastMessageAt) ? ds.lastMessageAt : 0;
+            let record = current[sessionId];
+            if (!record
+                || record.stateFingerprint !== stateFingerprint
+                || activityAt > record.lastObservedActivityAt) {
+                record = current[sessionId] = {
+                    sessionId,
+                    stateFingerprint,
+                    actionableSince: Math.max(now, activityAt),
+                    lastObservedActivityAt: activityAt,
+                };
+                continue;
+            }
+            const dueBase = record.lastRemindedAt ?? record.actionableSince;
+            if (now - dueBase < intervalMs)
+                continue;
+            if (record.retryAfterAt !== undefined && now < record.retryAfterAt)
+                continue;
+            try {
+                await this.deps.send(ds, config.text, sessionOwnerReminderDeliveryUuid(sessionId, stateFingerprint, dueBase));
+                record.lastRemindedAt = now;
+                record.retryAfterAt = undefined;
+            }
+            catch (error) {
+                record.retryAfterAt = now + Math.max(60_000, Math.min(intervalMs, FAILURE_RETRY_MAX_MS));
+                this.deps.onError?.(ds, error);
+            }
+        }
+        for (const sessionId of Object.keys(current)) {
+            if (!seen.has(sessionId))
+                delete current[sessionId];
+        }
+        if (recordsSnapshot(current) !== before)
+            this.deps.save(current);
+    }
+}
+//# sourceMappingURL=session-owner-reminder.js.map

package/dist/core/session-owner-reminder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-owner-reminder.js","sourceRoot":"","sources":["../../src/core/session-owner-reminder.ts"],"names":[],"mappings":"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"}

package/dist/core/session-preview-registry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * P1-13：previewTarget 的生命周期收口。
+ *
+ * previewTarget 是**当代 worker 的路由状态**，不是会话的持久属性：它指向那一代
+ * CLI 在本机 loopback 上拉起来的 Web 服务。worker 一换代（refork / 切 CLI / adopt /
+ * 崩溃退出 / suspend），或者会话被关闭，那个进程就没了，端口号随时可能被别的本机
+ * 进程抢走 —— 留着它等于把一条已登录用户可达的同源代理路由，交给一个我们不再认识
+ * 的进程。
+ *
+ * 所以每个「权威换代边界」都必须做两件事，缺一不可：
+ *   1. **原子地**把 previewTarget 从内存与磁盘上同时抹掉（并进调用方自己的那次
+ *      `updateSession`，失败可回滚，不留下「内存清了磁盘没清」的中间态）；
+ *   2. 向 Dashboard 广播 `preview: null`，否则浏览器侧的会话卡片会继续显示预览入口，
+ *      SSE/WS 也没有信号去断开既有的预览长连接。
+ *
+ * 这里只提供这两个动作的最小原语，好让每个边界按自己的事务形状组合：
+ *   - `takeSessionPreviewTarget` —— 只摘字段（调用方随后自己 save，可回滚）；
+ *   - `publishSessionPreviewCleared` —— 只广播；
+ *   - `clearSessionPreviewTarget` —— 自带 save + 广播，给没有自带事务的边界用。
+ */
+import type { Session } from '../types.js';
+/**
+ * 摘掉内存里的 previewTarget，返回被摘掉的旧值（本来就没有则返回 undefined）。
+ * 不落盘、不广播：调用方要把它并进自己的原子 `updateSession`，并在 save 失败时用
+ * 返回值回滚。
+ *
+ * P1-3：`expectedRegisteredAt` 是可选的 revision 门槛——「作废我判定失效的那一次注册」，
+ * 而不是「清空此刻的值」。判定失效与清理落地之间隔着一次跨进程往返，这中间会话完全
+ * 可以合法地重注册一个新目标；无条件清空会把它一并抹掉，agent 刚拿到的
+ * 「✓ Web 预览已注册」立刻变成空。`registeredAt` 是 ISO 串，天然就是这次注册的
+ * revision。不传时保持原来的无条件语义（换代 / 关闭 / suspend 这些权威边界本来就
+ * 该清掉「当前那个」，无论它是哪一次注册）。
+ */
+export declare function takeSessionPreviewTarget(session: Session, expectedRegisteredAt?: string): Session['previewTarget'];
+/**
+ * 广播「这个会话已经没有预览目标了」。走 `previewTarget: null` 而不是省略字段——
+ * preview-contract 的投影把它翻译成浏览器可见的 `preview: null`，浏览器 store 据此
+ * 丢弃旧描述符；省略字段则会被当成「本次 patch 不涉及预览」而保留旧值。
+ */
+export declare function publishSessionPreviewCleared(sessionId: string): void;
+/**
+ * 清 + 落盘 + 广播。返回是否真的清掉了东西（没有目标时不产生任何事件与写盘）。
+ *
+ * 落盘失败**不**回滚内存：此刻内存里的会话已经不再持有那个目标（这正是我们要的
+ * fail-closed 方向），而下一次成功的 save 会让磁盘收敛。广播照发，Dashboard 立刻
+ * 停止把用户导向一个已经不属于本会话的端口。
+ *
+ * P1-3：`expectedRegisteredAt` 见 `takeSessionPreviewTarget`。revision 不匹配时整条
+ * 是 no-op（不写盘、不广播、返回 false），幂等语义不变——「本来就没有」与「已经不是
+ * 那一个了」对调用方是同一件事：这次清理没有需要做的事。
+ */
+export declare function clearSessionPreviewTarget(session: Session, why: string, expectedRegisteredAt?: string): boolean;
+//# sourceMappingURL=session-preview-registry.d.ts.map

package/dist/core/session-preview-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-preview-registry.d.ts","sourceRoot":"","sources":["../../src/core/session-preview-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAI3C;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,oBAAoB,CAAC,EAAE,MAAM,GAC5B,OAAO,CAAC,eAAe,CAAC,CAQ1B;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAKpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,EACX,oBAAoB,CAAC,EAAE,MAAM,GAC5B,OAAO,CAaT"}

package/dist/core/session-preview-registry.js

@@ -0,0 +1,82 @@
+/**
+ * P1-13：previewTarget 的生命周期收口。
+ *
+ * previewTarget 是**当代 worker 的路由状态**，不是会话的持久属性：它指向那一代
+ * CLI 在本机 loopback 上拉起来的 Web 服务。worker 一换代（refork / 切 CLI / adopt /
+ * 崩溃退出 / suspend），或者会话被关闭，那个进程就没了，端口号随时可能被别的本机
+ * 进程抢走 —— 留着它等于把一条已登录用户可达的同源代理路由，交给一个我们不再认识
+ * 的进程。
+ *
+ * 所以每个「权威换代边界」都必须做两件事，缺一不可：
+ *   1. **原子地**把 previewTarget 从内存与磁盘上同时抹掉（并进调用方自己的那次
+ *      `updateSession`，失败可回滚，不留下「内存清了磁盘没清」的中间态）；
+ *   2. 向 Dashboard 广播 `preview: null`，否则浏览器侧的会话卡片会继续显示预览入口，
+ *      SSE/WS 也没有信号去断开既有的预览长连接。
+ *
+ * 这里只提供这两个动作的最小原语，好让每个边界按自己的事务形状组合：
+ *   - `takeSessionPreviewTarget` —— 只摘字段（调用方随后自己 save，可回滚）；
+ *   - `publishSessionPreviewCleared` —— 只广播；
+ *   - `clearSessionPreviewTarget` —— 自带 save + 广播，给没有自带事务的边界用。
+ */
+import { dashboardEventBus } from './dashboard-events.js';
+import * as sessionStore from '../services/session-store.js';
+import { logger } from '../utils/logger.js';
+/**
+ * 摘掉内存里的 previewTarget，返回被摘掉的旧值（本来就没有则返回 undefined）。
+ * 不落盘、不广播：调用方要把它并进自己的原子 `updateSession`，并在 save 失败时用
+ * 返回值回滚。
+ *
+ * P1-3：`expectedRegisteredAt` 是可选的 revision 门槛——「作废我判定失效的那一次注册」，
+ * 而不是「清空此刻的值」。判定失效与清理落地之间隔着一次跨进程往返，这中间会话完全
+ * 可以合法地重注册一个新目标；无条件清空会把它一并抹掉，agent 刚拿到的
+ * 「✓ Web 预览已注册」立刻变成空。`registeredAt` 是 ISO 串，天然就是这次注册的
+ * revision。不传时保持原来的无条件语义（换代 / 关闭 / suspend 这些权威边界本来就
+ * 该清掉「当前那个」，无论它是哪一次注册）。
+ */
+export function takeSessionPreviewTarget(session, expectedRegisteredAt) {
+    const previous = session.previewTarget;
+    if (previous === undefined)
+        return undefined;
+    if (expectedRegisteredAt !== undefined && previous.registeredAt !== expectedRegisteredAt) {
+        return undefined;
+    }
+    session.previewTarget = undefined;
+    return previous;
+}
+/**
+ * 广播「这个会话已经没有预览目标了」。走 `previewTarget: null` 而不是省略字段——
+ * preview-contract 的投影把它翻译成浏览器可见的 `preview: null`，浏览器 store 据此
+ * 丢弃旧描述符；省略字段则会被当成「本次 patch 不涉及预览」而保留旧值。
+ */
+export function publishSessionPreviewCleared(sessionId) {
+    dashboardEventBus.publish({
+        type: 'session.update',
+        body: { sessionId, patch: { previewTarget: null } },
+    });
+}
+/**
+ * 清 + 落盘 + 广播。返回是否真的清掉了东西（没有目标时不产生任何事件与写盘）。
+ *
+ * 落盘失败**不**回滚内存：此刻内存里的会话已经不再持有那个目标（这正是我们要的
+ * fail-closed 方向），而下一次成功的 save 会让磁盘收敛。广播照发，Dashboard 立刻
+ * 停止把用户导向一个已经不属于本会话的端口。
+ *
+ * P1-3：`expectedRegisteredAt` 见 `takeSessionPreviewTarget`。revision 不匹配时整条
+ * 是 no-op（不写盘、不广播、返回 false），幂等语义不变——「本来就没有」与「已经不是
+ * 那一个了」对调用方是同一件事：这次清理没有需要做的事。
+ */
+export function clearSessionPreviewTarget(session, why, expectedRegisteredAt) {
+    if (takeSessionPreviewTarget(session, expectedRegisteredAt) === undefined)
+        return false;
+    try {
+        sessionStore.updateSession(session);
+    }
+    catch (err) {
+        logger.error(`[${session.sessionId.substring(0, 8)}] Could not persist preview-target cleanup (${why}): `
+            + `${err instanceof Error ? err.message : String(err)}`);
+    }
+    publishSessionPreviewCleared(session.sessionId);
+    logger.debug(`[${session.sessionId.substring(0, 8)}] Dropped preview target (${why})`);
+    return true;
+}
+//# sourceMappingURL=session-preview-registry.js.map

package/dist/core/session-preview-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-preview-registry.js","sourceRoot":"","sources":["../../src/core/session-preview-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,KAAK,YAAY,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAgB,EAChB,oBAA6B;IAE7B,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC;IACvC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC7C,IAAI,oBAAoB,KAAK,SAAS,IAAI,QAAQ,CAAC,YAAY,KAAK,oBAAoB,EAAE,CAAC;QACzF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAClC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,SAAiB;IAC5D,iBAAiB,CAAC,OAAO,CAAC;QACxB,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE;KACpD,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAgB,EAChB,GAAW,EACX,oBAA6B;IAE7B,IAAI,wBAAwB,CAAC,OAAO,EAAE,oBAAoB,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxF,IAAI,CAAC;QACH,YAAY,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CACV,IAAI,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,+CAA+C,GAAG,KAAK;cAC1F,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACxD,CAAC;IACJ,CAAC;IACD,4BAA4B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,6BAA6B,GAAG,GAAG,CAAC,CAAC;IACvF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/core/session-preview.d.ts

@@ -0,0 +1,114 @@
+import { type LiteralLoopbackHost } from './loopback-target.js';
+import { type PreviewPortOwnerFailure, type PreviewPortOwnerProof } from './preview-port-owner.js';
+export declare const PREVIEW_ROUTE_PREFIX = "/preview";
+/**
+ * Reserved path segment that introduces the sandboxed content stream:
+ * `/preview/<sessionId>/__botmux_preview_content/<capability>/…`.
+ *
+ * It is a path segment rather than a query flag on purpose. The preview
+ * document is served into an opaque-origin sandbox, so its own relative
+ * subresources and WebSockets carry no dashboard cookie; a capability that
+ * lives in the path is inherited by every relative URL the app resolves,
+ * while a query flag would be dropped by the first `./app.js`.
+ */
+export declare const PREVIEW_CONTENT_SEGMENT = "__botmux_preview_content";
+export declare const PREVIEW_PROBE_TIMEOUT_MS = 750;
+/** DNS names are deliberately excluded: resolving even `localhost` would add a
+ * rebinding/configuration surface to an SSRF boundary. */
+export type PreviewLoopbackHost = LiteralLoopbackHost;
+export interface SessionPreviewTarget {
+    host: PreviewLoopbackHost;
+    port: number;
+    registeredAt: string;
+    /**
+     * P1-12：注册那一刻「谁在持有这个端口」的证明。没有它就只有一次 TCP connect 的
+     * 事实，代理无法分辨自己连的是本会话的 dev server 还是端口号被回收后顶上来的
+     * 任意本机进程，所以它是必填字段——老版本写下的、缺证明的 target 在这里直接归零
+     * （fail closed，会话重新 `botmux preview <port>` 即可）。
+     */
+    owner: PreviewPortOwnerProof;
+    /**
+     * P1-13：注册时的 worker 代次。worker 换代（refork / 切 CLI / adopt / exit）会
+     * 原子清掉 target，这个字段是「万一漏清」时的第二道判据，也是注册路由 probe
+     * await 之后做 CAS 复核的锚点。
+     */
+    workerGeneration: number;
+}
+export interface SessionPreviewDescriptor {
+    path: string;
+    registeredAt: string;
+}
+export declare function isPreviewPort(value: unknown): value is number;
+export declare function isPreviewLoopbackHost(value: unknown): value is PreviewLoopbackHost;
+/** Re-validate persisted/SSE data at every trust boundary. Invalid legacy or
+ * attacker-shaped objects collapse to undefined and are never dialled. */
+export declare function safeSessionPreviewTarget(value: unknown): SessionPreviewTarget | undefined;
+/**
+ * P1-1：一次注册的指纹。空串表示「这个会话此刻没有合法的预览目标」。
+ *
+ * host:port 不足以当身份：端口被回收后重注册、worker 换代后在同一端口重注册，都会
+ * 产生同一个 host:port，但那是另一次注册、另一个进程。registeredAt（ISO 串，天然可
+ * 当 revision）、workerGeneration、以及 owner 三元证明合起来才唯一确定「哪一次」。
+ */
+export declare function sessionPreviewFingerprint(previewTarget: unknown): string;
+/** P1-1：两个 target 是不是同一次注册（见 `sessionPreviewFingerprint`）。 */
+export declare function sameSessionPreviewTarget(a: SessionPreviewTarget, b: SessionPreviewTarget): boolean;
+/**
+ * P1-12：目标是否仍由注册时那个进程持有。probe 之后与**每次代理落地之前**都要过
+ * 这一关；`changed`/`unverifiable` 一律按失效处理（返回 false），调用方负责清 target
+ * 并广播 `preview: null`。
+ */
+export declare function sessionPreviewTargetStillOwned(target: SessionPreviewTarget, opts?: {
+    procRoot?: string;
+}): boolean;
+/**
+ * Riff 矩阵：哪些会话后端的 Web 服务在 daemon 的 loopback 上**根本不可能**出现。
+ *
+ * riff 是远端 sandbox——CLI 与它启动的 dev server 都跑在远程主机上，daemon 这一侧
+ * 的 127.0.0.1 上永远没有对应监听。此时必须明确回 `preview_unsupported`，而不是
+ * 让它落进 `preview_unreachable` 冒充「偶发故障」让用户反复重试；前端据此隐藏入口。
+ * pty / tmux / zellij / herdr / zmx 都是本机后端，行为不变。
+ */
+export declare function previewBackendSupported(backendType: unknown): boolean;
+export declare function sessionPreviewPath(sessionId: string): string;
+/** Base path of the sandboxed content stream. Every relative URL the framed
+ *  app resolves stays under it, which is how the capability survives without
+ *  cookies or query strings. */
+export declare function sessionPreviewContentPath(sessionId: string, capability: string): string;
+export declare function sessionPreviewDescriptor(sessionId: string, value: unknown): SessionPreviewDescriptor | undefined;
+export type SessionPreviewProbeError = 'invalid_port'
+/** 没有任何 loopback 地址上有人监听这个端口。 */
+ | 'preview_unreachable'
+/** 有人在监听，但拿不到「属于本会话」的持有证明 → fail closed。 */
+ | 'preview_owner_unverified';
+export type SessionPreviewProbeResult = {
+    ok: true;
+    target: SessionPreviewTarget;
+} | {
+    ok: false;
+    error: SessionPreviewProbeError;
+    reason?: PreviewPortOwnerFailure;
+};
+/**
+ * Validate that a caller-selected port is reachable through a literal loopback
+ * address AND held by a process inside this session's lineage. With no
+ * requested host, IPv4 is preferred and IPv6 is a fallback so
+ * `botmux preview <port>` works for either bind family.
+ *
+ * P1-12：可达性与归属是两件事，两件都必须成立才产出 target——connect 通过只说明
+ * 「此刻这个号码上有人」，`resolvePreviewPortOwner` 才回答「那个人是不是本会话的
+ * 进程」。归属拿不到时宁可没有预览，也不给出一条指向不明进程的代理路由。
+ */
+export declare function probeSessionPreviewTarget(input: {
+    port: number;
+    host?: PreviewLoopbackHost;
+    timeoutMs?: number;
+    now?: () => Date;
+    /** 会话血缘的根 pid（worker fork pid / CLI pid / adopt CLI pid）。 */
+    ownerPids: Array<number | undefined>;
+    /** 注册时的 worker 代次，随 target 落盘供后续 CAS 与换代清理比对。 */
+    workerGeneration: number;
+    /** 测试注入的假 procfs 根；生产恒为 '/proc'。 */
+    procRoot?: string;
+}): Promise<SessionPreviewProbeResult>;
+//# sourceMappingURL=session-preview.d.ts.map

package/dist/core/session-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-preview.d.ts","sourceRoot":"","sources":["../../src/core/session-preview.ts"],"names":[],"mappings":"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"}