@angelky7/dsh-browser-control 1.7.7 → 1.7.9

package/lib/types/audit.js

@@ -8,6 +8,50 @@ const AUDIT_ERROR_MAX_CHARS = 200;
 const AUDIT_EXPRESSION_MAX_CHARS = 120;
 /** 参数里这些键的值一律打码（大小写不敏感）。 */
 const SECRET_KEY = /^(token|authorization|password|passwd|secret|apikey|api_key|cookie)$/i;
+/**
+ * URL 里的秘密不能靠「截断」处理：`?token=…&code=…` 截到 120 字符照样是明文。
+ * 审计的用途是「做了什么」，所以保留 scheme/host/path 与查询键名，**查询值一律打码**；
+ * 片段（#）只在看起来像参数（含 `=` 或 token/secret 字样）时整体打码——SPA 路由
+ * （`#/inbox`）要留住，OAuth 隐式流的 `#access_token=…` 不能留。
+ */
+const URL_PATTERN = /https?:\/\/[^\s"'<>]+/g;
+function redactUrlMatch(match) {
+    // 错误文本里的 URL 常跟着标点（"...?token=x." / "...(https://…)")，先剥掉再原样接回。
+    const trailing = match.match(/[).,;:!?]+$/);
+    const core = trailing === null ? match : match.slice(0, -trailing[0].length);
+    const tail = trailing === null ? '' : trailing[0];
+    const queryAt = core.indexOf('?');
+    const hashAt = core.indexOf('#');
+    const base = queryAt >= 0 ? core.slice(0, queryAt) : (hashAt >= 0 ? core.slice(0, hashAt) : core);
+    const query = queryAt >= 0 ? core.slice(queryAt + 1, hashAt >= 0 ? hashAt : undefined) : '';
+    const hash = hashAt >= 0 ? core.slice(hashAt) : '';
+    let changed = false;
+    const redactedQuery = query.length === 0 ? '' : query.split('&').map((pair) => {
+        const eq = pair.indexOf('=');
+        if (eq < 0)
+            return pair;
+        const key = pair.slice(0, eq);
+        let value = pair.slice(eq + 1);
+        try {
+            value = decodeURIComponent(value);
+        }
+        catch { /* 解码失败就按原文字符数 */ }
+        changed = true;
+        return `${key}=[redacted:${[...value].length} chars]`;
+    }).join('&');
+    let redactedHash = hash;
+    if (hash.length > 1 && (/=/.test(hash) || /token|secret|access_token/i.test(hash))) {
+        redactedHash = '#[redacted]';
+        changed = true;
+    }
+    if (!changed)
+        return core + tail;
+    return `${base}${redactedQuery.length > 0 ? `?${redactedQuery}` : ''}${redactedHash}${tail}`;
+}
+/** 把一段文本里所有 URL 的查询值/敏感片段打码（用于参数摘要与错误文本）。 */
+export function redactAuditText(text) {
+    return text.replace(URL_PATTERN, redactUrlMatch);
+}
 /**
  * 哪个命令的 `value` 字段是敏感内容：`input` 是往页面里打的字（可能是密码），
  * `cookies.set` 直接写凭据。其余命令的 value 字段（如果有）不动。
@@ -29,8 +73,13 @@ export function summarizeAuditParams(command, params) {
                 return '[redacted]';
             if (key === 'value' && VALUE_REDACTED_COMMANDS.has(command))
                 return redactValue(value);
-            if (key === 'expression' && typeof value === 'string' && [...value].length > AUDIT_EXPRESSION_MAX_CHARS) {
-                return `${[...value].slice(0, AUDIT_EXPRESSION_MAX_CHARS).join('')}…[+${[...value].length - AUDIT_EXPRESSION_MAX_CHARS} chars]`;
+            if (typeof value === 'string') {
+                // URL query 与敏感片段先打码，再做表达式截断/整体限长：截断不是脱敏。
+                const redacted = redactAuditText(value);
+                if (key === 'expression' && [...redacted].length > AUDIT_EXPRESSION_MAX_CHARS) {
+                    return `${[...redacted].slice(0, AUDIT_EXPRESSION_MAX_CHARS).join('')}…[+${[...redacted].length - AUDIT_EXPRESSION_MAX_CHARS} chars]`;
+                }
+                return redacted;
             }
             return value;
         }) ?? '{}';
@@ -70,9 +119,10 @@ export class AuditLog {
         if (input.effectState !== undefined)
             entry.effectState = input.effectState;
         if (input.error !== undefined) {
-            entry.error = [...input.error].length > AUDIT_ERROR_MAX_CHARS
-                ? `${[...input.error].slice(0, AUDIT_ERROR_MAX_CHARS).join('')}…`
-                : input.error;
+            const redacted = redactAuditText(input.error);
+            entry.error = [...redacted].length > AUDIT_ERROR_MAX_CHARS
+                ? `${[...redacted].slice(0, AUDIT_ERROR_MAX_CHARS).join('')}…`
+                : redacted;
         }
         this.entries.push(entry);
         // 环形缓冲：超出上限从最旧的一端丢。seq 不回收——调用方拿 seq 分页时

package/lib/types/errors.d.ts

@@ -60,5 +60,8 @@ export declare class BridgeError extends Error {
 /**
  * 把任意底层抛出的错误归类成 BridgeError。已经分类过的原样返回，
  * 保证多次包裹不会把 code 洗掉。
+ * @param params - 这次调用的参数。只有 `wait` 需要它：`fn` 是在页面里执行任意 JS，
+ *   超时/掉线时与写命令同档报 `unknown`（谓词跑过就不能断言页面没被动过）；
+ *   不带 `fn` 的 wait 仍是只读。
  */
-export declare function classify(command: string, error: unknown): BridgeError;
+export declare function classify(command: string, error: unknown, params?: Record<string, unknown>): BridgeError;

package/lib/types/errors.js

@@ -69,7 +69,7 @@ const HINTS = {
     extension_offline: '浏览器扩展没连上：让用户打开装了 DSH Browser Control 的那个浏览器（扩展图标应为绿色），确认端口与 Token 两边一致后再试。',
     command_timeout: '扩展超时未回应：先别重试。用 browser_find / browser_snapshot 看页面当前状态，判断动作是否其实已经生效。',
     link_lost: '命令在途时链路断了：动作可能已经落到页面上。先用只读工具确认页面状态，再决定是否重做。',
-    cancelled: '调用被取消：按需重新发起，不必当作错误处理。',
+    cancelled: '调用被取消：effectState=not_started 时命令确定没发出去，可以按需重新发起；unknown 时动作可能已经执行，先确认页面状态再决定，不要直接重做。',
     not_configured: '插件还没读到配置：确认 dsh 已加载本插件（dsh plugin list）后再试。',
     held_by_user: '这是用户在页面上的接管浮层里按下的「中止操作」，不是故障：命令一条都没有发出。先与用户确认；他同意继续之后调用 browser_hold action=off 解除，然后再继续原来的步骤。不要重试，也不要换成别的工具绕过它。',
     blocked_by_policy: '这是本机策略拦下的，不是故障：命令没有发给浏览器（零副作用）。要放开改 profile 的 cordis.patch.yml（browser-bridge 的 readOnly / allowScript）并重启 dsh，或换成本机允许的只读工具；不要原地重试。',
@@ -126,8 +126,11 @@ export class BridgeError extends Error {
 /**
  * 把任意底层抛出的错误归类成 BridgeError。已经分类过的原样返回，
  * 保证多次包裹不会把 code 洗掉。
+ * @param params - 这次调用的参数。只有 `wait` 需要它：`fn` 是在页面里执行任意 JS，
+ *   超时/掉线时与写命令同档报 `unknown`（谓词跑过就不能断言页面没被动过）；
+ *   不带 `fn` 的 wait 仍是只读。
  */
-export function classify(command, error) {
+export function classify(command, error, params) {
     if (error instanceof BridgeError)
         return error;
     const raw = error instanceof Error ? error.message : String(error);
@@ -144,7 +147,9 @@ export function classify(command, error) {
                 : 0;
     const message = locked ? raw.slice(markerLength).trim() : raw;
     // 写操作一旦超时或掉线，结果就是未知的；读操作永远可以安全重试。
-    const unknownIsPossible = isWriteCommand(command);
+    // wait(fn) 例外：谓词是任意 JS，按写命令同档处理（见函数顶部 @param params）。
+    const unknownIsPossible = isWriteCommand(command)
+        || (command === 'wait' && typeof params?.fn === 'string' && params.fn.trim().length > 0);
     let code;
     if (locked !== undefined)
         code = locked;
@@ -166,6 +171,10 @@ export function classify(command, error) {
         ? (unknownIsPossible ? 'unknown' : 'not_started')
         : code === 'command_failed'
             ? (unknownIsPossible ? 'unknown' : 'not_started')
-            : 'not_started';
+            // 取消分两段：写命令在 socket.write 之后才被取消时，帧已经出去了，结果未知；
+            // 「before send」的那一条确定没发，仍是 not_started。读命令没有页面副作用。
+            : code === 'cancelled'
+                ? (/cancelled before send/.test(message) ? 'not_started' : (unknownIsPossible ? 'unknown' : 'not_started'))
+                : 'not_started';
     return new BridgeError(command, code, effectState, message);
 }

package/lib/types/index.js

@@ -163,6 +163,7 @@ class BridgeController {
     current;
     journal;
     journalKey = '';
+    journalError;
     /** 操作审计账本（内存环形缓冲，200 条；命令层记录，见 audit.ts 顶部注释）。 */
     audit = new AuditLog();
     /** 多 session 隔离：每个 dsh 会话的工作标签页（见 sessions.ts）。 */
@@ -178,12 +179,25 @@ class BridgeController {
     get stateDir() {
         return this.current === undefined ? undefined : path.resolve(this.current.stateDir);
     }
+    /**
+     * Whether THIS run is persisting the journal, and why not. `browser_audit` /
+     * `browser_journal` surface this: a memory-only run used to be visible only in
+     * one log line, so a missing journal looked like "nothing happened".
+     */
+    get journalStatus() {
+        if (this.journal !== undefined)
+            return { enabled: true };
+        return this.journalError === undefined ? { enabled: false } : { enabled: false, error: this.journalError };
+    }
     /**
      * Record one audit entry in memory and, when the journal is open, on disk.
      * Journal appends are queued and never block the command path.
      */
     recordAudit(input) {
-        this.journal?.append(this.audit.record(input));
+        // 先记账再落盘：`this.journal?.append(this.audit.record(input))` 会让可选链
+        // 短路掉 audit.record —— journal 没开（默认就是关的）时内存审计整本丢失。
+        const entry = this.audit.record(input);
+        this.journal?.append(entry);
     }
     /**
      * Current policy flags. Tools that compose several commands (browser_drag
@@ -264,10 +278,13 @@ class BridgeController {
             await previousJournal?.close();
             try {
                 this.journal = await Journal.open(stateDir, this.log);
+                this.journalError = undefined;
             }
             catch (error) {
                 // 账本打不开不是让桥起不来的理由：降级为纯内存审计。
-                this.log(`journal: disabled — ${errorMessage(error)}`);
+                // 降级状态必须能被调用方看见（audit/journal 工具的回执），不能只写一行日志。
+                this.journalError = errorMessage(error);
+                this.log(`journal: disabled — ${this.journalError}`);
             }
         }
         const key = config.enabled ? `${config.port}|${config.token}|${shotsDir}` : '';
@@ -281,7 +298,15 @@ class BridgeController {
             this.lastError = undefined;
             return;
         }
-        const server = new BridgeServer({ port: config.port, token: config.token, shotsDir, log: this.log });
+        const server = new BridgeServer({
+            port: config.port,
+            token: config.token,
+            shotsDir,
+            log: this.log,
+            // HTTP /api/command 与工具走同一条闸门与账本：裸 server.execute() 会绕开
+            // 只读档/allowScript，而且不在审计里留下痕迹（默认 token 还是公开的那一个）。
+            httpCommand: (command, params, options) => this.execute(command, params, new AbortController().signal, options.timeoutMs),
+        });
         try {
             await server.start();
         }
@@ -349,12 +374,23 @@ class BridgeController {
      * to work; when it is gone we forget it and let the browser's active tab
      * answer, exactly like before this feature existed.
      */
-    async isolateParams(command, params, sessionId, signal) {
-        if (typeof params.tabId === 'number' || NO_TAB_DEFAULT_COMMANDS.has(command))
-            return params;
+    /**
+     * The calling session's working tab, after the same liveness probe isolateParams
+     * uses. Tools that compose several commands (browser_drag) need the id *before*
+     * issuing anything, so they must not fall back to the browser's active tab on
+     * their own — that would silently bypass session isolation.
+     */
+    async sessionTab(signal) {
+        const sessionId = TOOL_SESSION.getStore();
+        if (sessionId === undefined)
+            return undefined;
+        return await this.liveRecordedTab(sessionId, signal);
+    }
+    /** Recorded working tab if it is still open; a gone tab is forgotten here. */
+    async liveRecordedTab(sessionId, signal) {
         const recorded = this.sessions.workingTab(sessionId);
         if (recorded === undefined)
-            return params;
+            return undefined;
         const server = this.server;
         if (server !== undefined) {
             try {
@@ -362,11 +398,19 @@ class BridgeController {
                 const live = Array.isArray(listing?.tabs) && listing.tabs.some((tab) => tab?.id === recorded);
                 if (!live) {
                     this.sessions.release(sessionId);
-                    return params;
+                    return undefined;
                 }
             }
             catch { /* 列不出来就按旧行为走活动标签页 */ }
         }
+        return recorded;
+    }
+    async isolateParams(command, params, sessionId, signal) {
+        if (typeof params.tabId === 'number' || NO_TAB_DEFAULT_COMMANDS.has(command))
+            return params;
+        const recorded = await this.liveRecordedTab(sessionId, signal);
+        if (recorded === undefined)
+            return params;
         return { ...params, tabId: recorded };
     }
     /** Record the call and adopt the tab it actually touched (params or result). */
@@ -1936,21 +1980,44 @@ async function resolveDragPoint(ctrl, tabId, target, signal) {
     if (nodeId === 0)
         throw new Error(`no element matches selector ${JSON.stringify(selector)} (top document only)`);
     await cdpCall(ctrl, tabId, 'DOM.scrollIntoViewIfNeeded', { nodeId }, signal);
+    return await measureDragNode(ctrl, tabId, nodeId, selector, signal);
+}
+/**
+ * Read a node's **current** viewport geometry without scrolling. Needed after the
+ * *other* endpoint's scrollIntoViewIfNeeded: that scroll can move the first
+ * endpoint (and this one), so coordinates measured before it are stale. DOM
+ * geometry is viewport-relative; dispatching the old numbers would drag from
+ * wherever the element used to be.
+ */
+async function measureDragNode(ctrl, tabId, nodeId, label, signal) {
     let box;
     try {
         box = await cdpCall(ctrl, tabId, 'DOM.getBoxModel', { nodeId }, signal);
     }
     catch (error) {
-        throw new Error(`cannot measure ${JSON.stringify(selector)} — hidden, zero-size or detached? (${error instanceof Error ? error.message : String(error)})`);
+        throw new Error(`cannot measure ${JSON.stringify(label)} — hidden, zero-size or detached? (${error instanceof Error ? error.message : String(error)})`);
     }
     const q = box?.model?.content;
     if (!Array.isArray(q) || q.length < 8)
-        throw new Error(`DOM.getBoxModel returned no quad for ${JSON.stringify(selector)}`);
+        throw new Error(`DOM.getBoxModel returned no quad for ${JSON.stringify(label)}`);
     const x = (q[0] + q[2] + q[4] + q[6]) / 4;
     const y = (q[1] + q[3] + q[5] + q[7]) / 4;
     const width = typeof box?.model?.width === 'number' ? box.model.width : Math.hypot(q[2] - q[0], q[3] - q[1]);
     const height = typeof box?.model?.height === 'number' ? box.model.height : Math.hypot(q[4] - q[2], q[5] - q[3]);
-    return { selector, x, y, width, height, nodeId };
+    return { selector: label, x, y, width, height, nodeId };
+}
+/** CSS viewport size via Page.getLayoutMetrics (no page JS, works with allowScript off). */
+async function viewportSize(ctrl, tabId, signal) {
+    try {
+        const metrics = await cdpCall(ctrl, tabId, 'Page.getLayoutMetrics', {}, signal);
+        const viewport = metrics?.cssVisualViewport ?? metrics?.cssLayoutViewport;
+        const width = Number(viewport?.clientWidth);
+        const height = Number(viewport?.clientHeight);
+        if (Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0)
+            return { width, height };
+    }
+    catch { /* 量不出视口就跳过边界检查，不让一条查询失败挡掉拖拽本身 */ }
+    return undefined;
 }
 /** Whether the source declares the native HTML5 `draggable` attribute. */
 async function sourceIsDraggable(ctrl, tabId, nodeId, signal) {
@@ -2098,6 +2165,8 @@ function registerDragTool(ctx, controller) {
             if (controller.policy.readOnly)
                 throw new Error('browser_drag changes page state and read-only mode is on — turn readOnly off in the browser-bridge config to drag');
             let tabId = args.tabId;
+            if (tabId === undefined)
+                tabId = await controller.sessionTab(exec.signal);
             if (tabId === undefined) {
                 const listing = await controller.execute('tabs.list', {}, exec.signal);
                 if (typeof listing?.activeTabId !== 'number')
@@ -2114,24 +2183,59 @@ function registerDragTool(ctx, controller) {
             }
             if (resolvedMode === 'mouse') {
                 const target = await resolveDragPoint(controller, tabId, to, exec.signal);
+                // 目标端点的 scrollIntoViewIfNeeded 会把页面滚走，源端点先前的视口坐标就失效了；
+                // 两端都是选择器时按当前几何重测一次（getBoxModel 不滚动，不会再次互相干扰）。
+                // 若滚完后两端不在同一视口里，宁可拒绝，也不盲发一组越界坐标去拖错东西。
+                let sourcePoint = source;
+                let targetPoint = target;
+                if (source?.nodeId !== undefined && target.nodeId !== undefined) {
+                    sourcePoint = await measureDragNode(controller, tabId, source.nodeId, String(from.selector), exec.signal);
+                    targetPoint = await measureDragNode(controller, tabId, target.nodeId, String(to.selector), exec.signal);
+                }
+                const viewport = await viewportSize(controller, tabId, exec.signal);
+                if (viewport !== undefined) {
+                    const describe = (p) => `${p.selector !== undefined ? JSON.stringify(p.selector) : 'point'} at (${Math.round(p.x)},${Math.round(p.y)})`;
+                    const outside = (p) => p.x < 0 || p.y < 0 || p.x > viewport.width || p.y > viewport.height;
+                    if (outside(sourcePoint) || outside(targetPoint)) {
+                        throw new Error(`drag endpoints are not both visible in the viewport (${describe(sourcePoint)} → ${describe(targetPoint)}, viewport ${Math.round(viewport.width)}×${Math.round(viewport.height)}) — scroll so both fit, then retry; mode:"html5" takes selectors and needs no viewport coordinates`);
+                    }
+                }
                 const steps = Math.min(50, Math.max(1, Math.trunc(typeof args.steps === 'number' ? args.steps : 12)));
-                const sx = source.x, sy = source.y, tx = target.x, ty = target.y;
+                const sx = sourcePoint.x, sy = sourcePoint.y, tx = targetPoint.x, ty = targetPoint.y;
                 const dispatch = async (params) => {
                     await cdpCall(controller, tabId, 'Input.dispatchMouseEvent', params, exec.signal);
                 };
-                await dispatch({ type: 'mouseMoved', x: sx, y: sy, button: 'none', buttons: 0 });
-                await dispatch({ type: 'mousePressed', x: sx, y: sy, button: 'left', buttons: 1, clickCount: 1 });
-                for (let i = 1; i <= steps; i++) {
-                    const f = i / steps;
-                    await dispatch({ type: 'mouseMoved', x: sx + (tx - sx) * f, y: sy + (ty - sy) * f, button: 'left', buttons: 1 });
+                // 按住之后任何一步失败（取消、超时、CDP 报错）都必须尽力抬起：否则页面会
+                // 停在「鼠标左键按着」的状态，用户下一次点击会被当成拖拽的延续。
+                let pressedAt;
+                try {
+                    await dispatch({ type: 'mouseMoved', x: sx, y: sy, button: 'none', buttons: 0 });
+                    await dispatch({ type: 'mousePressed', x: sx, y: sy, button: 'left', buttons: 1, clickCount: 1 });
+                    pressedAt = { x: sx, y: sy };
+                    for (let i = 1; i <= steps; i++) {
+                        const f = i / steps;
+                        await dispatch({ type: 'mouseMoved', x: sx + (tx - sx) * f, y: sy + (ty - sy) * f, button: 'left', buttons: 1 });
+                        pressedAt = { x: sx + (tx - sx) * f, y: sy + (ty - sy) * f };
+                    }
+                    await dispatch({ type: 'mouseReleased', x: tx, y: ty, button: 'left', buttons: 0, clickCount: 1 });
+                    pressedAt = undefined;
+                    await dispatch({ type: 'mouseMoved', x: tx, y: ty, button: 'none', buttons: 0 });
+                }
+                catch (error) {
+                    if (pressedAt !== undefined) {
+                        // 独立信号：调用方的 signal 可能已经 abort，清扫仍要发出去。
+                        try {
+                            await cdpCall(controller, tabId, 'Input.dispatchMouseEvent', { type: 'mouseReleased', x: pressedAt.x, y: pressedAt.y, button: 'left', buttons: 0, clickCount: 1 }, new AbortController().signal);
+                        }
+                        catch { /* 清扫失败不能盖掉原始错误 */ }
+                    }
+                    throw error;
                 }
-                await dispatch({ type: 'mouseReleased', x: tx, y: ty, button: 'left', buttons: 0, clickCount: 1 });
-                await dispatch({ type: 'mouseMoved', x: tx, y: ty, button: 'none', buttons: 0 });
                 const receipt = {
                     tabId,
                     mode: 'mouse',
-                    from: roundDragPoint(source),
-                    to: roundDragPoint(target),
+                    from: roundDragPoint(sourcePoint),
+                    to: roundDragPoint(targetPoint),
                     steps,
                     dispatched: steps + 4,
                     elapsedMs: Date.now() - started,
@@ -2165,10 +2269,15 @@ function registerDragTool(ctx, controller) {
         },
     }));
 }
+function journalWarning(status) {
+    return status.enabled
+        ? ''
+        : `\nJournal write: disabled${status.error === undefined ? '' : ` — ${status.error}`} — this run is memory-only; entries are not being written to disk.`;
+}
 function registerAuditTool(ctx, controller) {
     ctx.tools.register(defineTool({
         name: 'browser_audit',
-        description: 'Read this plugin session\'s in-memory audit trail: every command sent to the browser extension (and every policy/gate refusal), with redacted params, outcome code and duration. Newest last; capped at 200 entries and wiped when dsh restarts. Values typed into pages and cookie values are redacted; eval expressions are truncated. Plugin-local read — works in read-only mode.',
+        description: 'Read this plugin session\'s in-memory audit trail: every command sent to the browser extension (and every policy/gate refusal), with redacted params, outcome code and duration. Newest last; capped at 200 entries and wiped when dsh restarts. Values typed into pages and cookie values are redacted; URL query values and URLs inside error text are redacted; eval expressions are truncated. The `journal` field says whether this run is also being written to disk (enabled:false + error = memory-only). Plugin-local read — works in read-only mode.',
         parameters: {
             command: { type: 'string', description: 'Only entries whose command contains this substring (e.g. "nav", "cookies", "tabs").' },
             tabId: { type: 'number', description: 'Only entries that carried this tabId.' },
@@ -2182,6 +2291,14 @@ function registerAuditTool(ctx, controller) {
                 properties: {
                     total: { type: 'number', required: true },
                     shown: { type: 'number', required: true },
+                    journal: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            enabled: { type: 'boolean', required: true },
+                            error: { type: 'string' },
+                        },
+                    },
                     entries: {
                         type: 'array',
                         required: true,
@@ -2206,8 +2323,9 @@ function registerAuditTool(ctx, controller) {
             },
             render: (_args, value) => {
                 const v = value;
+                const warn = v.journal === undefined ? '' : journalWarning(v.journal);
                 if (v.entries.length === 0) {
-                    return [{ type: 'text', text: `Audit: ${v.total} entries, none match — the trail starts when a command is executed.` }];
+                    return [{ type: 'text', text: `Audit: ${v.total} entries, none match — the trail starts when a command is executed.${warn}` }];
                 }
                 const lines = v.entries.map((e) => {
                     const tab = e.tabId === undefined ? '' : ` tab ${e.tabId}`;
@@ -2215,7 +2333,7 @@ function registerAuditTool(ctx, controller) {
                     const err = e.ok || e.error === undefined ? '' : ` — ${e.error}`;
                     return `#${e.seq} ${formatClock(e.t)} ${e.command}${tab} ${outcome} ${e.durationMs}ms ${e.params}${err}`;
                 });
-                return [{ type: 'text', text: clampRendered(`Audit: ${v.total} entries (showing ${v.shown})\n${lines.join('\n')}`) }];
+                return [{ type: 'text', text: clampRendered(`Audit: ${v.total} entries (showing ${v.shown})\n${lines.join('\n')}${warn}`) }];
             },
         },
         presentCall: () => ({ card: 'generic', title: 'Browser audit', kind: 'other' }),
@@ -2226,14 +2344,14 @@ function registerAuditTool(ctx, controller) {
                 sinceSeq: args.sinceSeq,
                 limit: args.limit,
             });
-            return { total: controller.audit.size(), shown: entries.length, entries };
+            return { total: controller.audit.size(), shown: entries.length, entries, journal: controller.journalStatus };
         },
     }));
 }
 function registerJournalTool(ctx, controller) {
     ctx.tools.register(defineTool({
         name: 'browser_journal',
-        description: 'Read the persistent command journal across dsh restarts: every command from previous runs of this plugin (written to <stateDir>/journal.jsonl, last 1000 entries), grouped by run. Same redaction as browser_audit. Plugin-local disk read — works with the extension offline and in read-only mode, so it is the way to recover "what was I doing" after a restart.',
+        description: 'Read the persistent command journal across dsh restarts: every command from previous runs of this plugin (written to <stateDir>/journal.jsonl, last 1000 entries), grouped by run. Same redaction as browser_audit. The `journal` field says whether the CURRENT run is writing (enabled:false + error = this run is memory-only; what you see is from earlier runs). Plugin-local disk read — works with the extension offline and in read-only mode, so it is the way to recover "what was I doing" after a restart.',
         parameters: {
             command: { type: 'string', description: 'Only entries whose command contains this substring.' },
             tabId: { type: 'number', description: 'Only entries that carried this tabId.' },
@@ -2247,6 +2365,14 @@ function registerJournalTool(ctx, controller) {
                     total: { type: 'number', required: true },
                     shown: { type: 'number', required: true },
                     runs: { type: 'number', required: true },
+                    journal: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            enabled: { type: 'boolean', required: true },
+                            error: { type: 'string' },
+                        },
+                    },
                     entries: {
                         type: 'array',
                         required: true,
@@ -2272,8 +2398,9 @@ function registerJournalTool(ctx, controller) {
             },
             render: (_args, value) => {
                 const v = value;
+                const warn = v.journal === undefined ? '' : journalWarning(v.journal);
                 if (v.entries.length === 0) {
-                    return [{ type: 'text', text: `Journal: ${v.total} entries on disk, none match — nothing recorded across runs yet.` }];
+                    return [{ type: 'text', text: `Journal: ${v.total} entries on disk, none match — nothing recorded across runs yet.${warn}` }];
                 }
                 const lines = [];
                 let run = '';
@@ -2286,7 +2413,7 @@ function registerJournalTool(ctx, controller) {
                     const outcome = e.ok ? 'ok' : `FAIL ${e.code ?? 'error'}`;
                     lines.push(`#${e.seq} ${formatClock(e.t)} ${e.command}${tab} ${outcome} ${e.durationMs}ms ${e.params}`);
                 }
-                return [{ type: 'text', text: clampRendered(`Journal: ${v.total} entries in ${v.runs} run(s) (showing ${v.shown})\n${lines.join('\n')}`) }];
+                return [{ type: 'text', text: clampRendered(`Journal: ${v.total} entries in ${v.runs} run(s) (showing ${v.shown})\n${lines.join('\n')}${warn}`) }];
             },
         },
         presentCall: () => ({ card: 'generic', title: 'Browser journal', kind: 'other' }),
@@ -2295,7 +2422,7 @@ function registerJournalTool(ctx, controller) {
             if (dir === undefined)
                 throw new Error('browser-bridge is not configured yet — the journal has no stateDir to read');
             const { total, entries } = await readJournal(dir, { command: args.command, tabId: args.tabId, limit: args.limit });
-            return { total, shown: entries.length, runs: new Set(entries.map((e) => e.run)).size, entries };
+            return { total, shown: entries.length, runs: new Set(entries.map((e) => e.run)).size, entries, journal: controller.journalStatus };
         },
     }));
 }

package/lib/types/policy.d.ts

@@ -21,6 +21,11 @@ export declare const READ_ONLY_ALLOWED: ReadonlySet<string>;
 /**
  * 会执行**任意页面脚本**的扩展命令。这条与只读档分开管，因为用户可能想「可以读、
  * 也可以点，但别在我页面里跑任意 JS」——`browser_evaluate` 能绕开其他所有工具做的事。
+ *
+ * **按命令名判不够**：`wait` 的 `fn` 参数同样是在页面里执行任意 JS（扩展侧用
+ * `(${fn})()` 求出谓词），只按名字看它会从只读白名单和脚本开关两道门缝里同时漏过去。
+ * 所以真正判「是不是脚本」的是下面 `isScriptCall()`：命令名 + 参数一起看，
+ * `wait(selector)` / `wait(text)` 仍按只读处理，`wait({fn})` 与 `eval` 同档。
  */
 export declare const SCRIPT_COMMANDS: ReadonlySet<string>;
 /**

package/lib/types/policy.js

@@ -35,8 +35,22 @@ export const READ_ONLY_ALLOWED = new Set([
 /**
  * 会执行**任意页面脚本**的扩展命令。这条与只读档分开管，因为用户可能想「可以读、
  * 也可以点，但别在我页面里跑任意 JS」——`browser_evaluate` 能绕开其他所有工具做的事。
+ *
+ * **按命令名判不够**：`wait` 的 `fn` 参数同样是在页面里执行任意 JS（扩展侧用
+ * `(${fn})()` 求出谓词），只按名字看它会从只读白名单和脚本开关两道门缝里同时漏过去。
+ * 所以真正判「是不是脚本」的是下面 `isScriptCall()`：命令名 + 参数一起看，
+ * `wait(selector)` / `wait(text)` 仍按只读处理，`wait({fn})` 与 `eval` 同档。
  */
 export const SCRIPT_COMMANDS = new Set(['eval']);
+/**
+ * 这次调用会不会在页面里执行任意 JS。判据是「这次实际要做的动作」，不是命令名：
+ * `wait` 只有带 `fn` 时才升级为脚本调用（`selector` / `text` 是纯查询）。
+ */
+function isScriptCall(command, params) {
+    if (SCRIPT_COMMANDS.has(command))
+        return true;
+    return command === 'wait' && typeof params?.fn === 'string' && params.fn.trim().length > 0;
+}
 /**
  * 不经过扩展、直接在插件进程里改动本机文件的命令名。
  *
@@ -69,9 +83,19 @@ const CONFIG_HINT = '开关在 profile 的 cordis.patch.yml 里（browser-bridge
  * @returns 拒绝时写给 agent 的整句理由；放行时 `undefined`。
  */
 export function policyRefusal(command, flags, params) {
-    if (!flags.allowScript && SCRIPT_COMMANDS.has(command)) {
-        return `在页面里执行任意脚本已被关闭（allowScript: false）：命令 ${command} 被拒绝，没有向浏览器发出任何操作。`
-            + `要读页面内容请改用 browser_read / browser_snapshot / browser_find；确实需要执行脚本时，${CONFIG_HINT}之后再说。`;
+    const scriptCall = isScriptCall(command, params);
+    if (!flags.allowScript && scriptCall) {
+        const what = command === 'wait'
+            ? '命令 wait 的 fn 参数（会在页面里执行任意 JS）被拒绝'
+            : `命令 ${command} 被拒绝`;
+        return `在页面里执行任意脚本已被关闭（allowScript: false）：${what}，没有向浏览器发出任何操作。`
+            + `要等页面就绪请改用 wait 的 selector / text（只读），读页面内容用 browser_read / browser_snapshot / browser_find；确实需要执行脚本时，${CONFIG_HINT}之后再说。`;
+    }
+    // wait 白名单是按命令名放的，但带 fn 的那一种和 eval 同档：任意 JS 可以改页面，
+    // 只读档不能因为「它叫 wait」就放行。不带 fn 的 wait 仍走下面的白名单。
+    if (flags.readOnly && command === 'wait' && scriptCall) {
+        return `只读模式已开启（readOnly: true）：命令 wait 的 fn 参数会在页面里执行任意 JS（可能改变页面状态），已被拒绝，没有向浏览器发出任何操作。`
+            + `要等页面就绪请改用 wait 的 selector / text（只读）；要放开请由用户关掉 readOnly，${CONFIG_HINT}不要原地重试本命令。`;
     }
     if (flags.readOnly && LOCAL_DESTRUCTIVE_COMMANDS.has(command)) {
         return `只读模式已开启（readOnly: true）：命令 ${command} 会删除本机保存的截图与临时文件，删除不可逆，所以已被拒绝，没有任何文件被删除。`

package/lib/types/server.d.ts

@@ -90,6 +90,12 @@ export interface BridgeServerOptions {
     readonly scratchDir?: string;
     /** Optional line logger for lifecycle diagnostics. */
     readonly log?: (line: string) => void;
+    /**
+     * Executor for the HTTP command face. The plugin passes its controller so
+     * `/api/command` goes through the same policy gate and audit trail as tools;
+     * without it (bare BridgeServer users, tests) the face stays raw.
+     */
+    readonly httpCommand?: (command: string, params: Record<string, unknown>, options: BridgeExecuteOptions) => Promise<unknown>;
 }
 /**
  * Clear the screenshots directory and delete agent scratch files. Only the
@@ -116,7 +122,12 @@ export declare class BridgeServer {
     private connectedAt;
     private readonly pending;
     private lastError;
-    private continuationRemainder;
+    /**
+     * Payloads of the message being reassembled. **Buffers, not strings**: decoding
+     * each fragment with `toString('utf8')` corrupts any multi-byte character that
+     * straddles a fragment boundary. Decode once, at FIN.
+     */
+    private continuationChunks;
     private continuationOpen;
     constructor(options: BridgeServerOptions);
     /** Current link state, also served verbatim as `/api/status`. */