publishport-opencli 1.8.5-pp.6 → 1.8.5-pp.7

package/dist/src/browser-session-lock.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 在机器级浏览器会话锁的保护下执行 fn。并发调用会排队串行；顺序调用无等待。
+ * fn 抛出会原样冒泡，锁始终在 finally 里释放。
+ */
+export declare function withBrowserSessionLock<T>(fn: () => Promise<T>): Promise<T>;
+/** 条件加锁：locked 为真时走串行锁，否则直接执行（前台/交互命令用独立窗口，无需串行）。 */
+export declare function withBrowserSessionLockIf<T>(locked: boolean, fn: () => Promise<T>): Promise<T>;
+export declare const __lockInternals: {
+    LOCK_PATH: string;
+    ACQUIRE_TIMEOUT_MS: number;
+    STALE_AFTER_MS: number;
+};

package/dist/src/browser-session-lock.js

@@ -0,0 +1,118 @@
+// [pp-only] 机器级浏览器会话串行锁。
+//
+// PublishPort 的后台自动化窗口物理上一次只能安全服务一条命令：多条命令并发驱动同一个
+// 窗口时，官方扩展的 rebind/关窗逻辑会把正在跑的命令的调试器扯掉（表现为
+// `Debugger is not attached` / `Detached while handling command`），还会 race 出多余窗口。
+// 由于并发的浏览器命令是各自独立的 opencli 进程，进程内的锁不够，必须跨进程串行。
+//
+// 这里用一个 O_EXCL 锁文件做机器级互斥：并发命令排队，一条条跑完，复用同一个窗口，
+// 既不 churn 也不互相拆台。顺序命令锁立即可得、无影响。
+//
+// 稳定性要点（针对历史上「陈旧锁导致持续 DEVICE_BUSY」的坑）：
+//  - 锁文件写入持有者 PID；等待方发现持有者进程已死（process.kill(pid,0) 抛 ESRCH）
+//    立即抢占，不会被崩溃残留的锁永久卡死；
+//  - 再加一层 mtime 兜底：锁文件过老（默认 10min）也视为陈旧，防 PID 复用的极端情况；
+//  - 进程正常退出 finally 删锁；异常退出靠上面两层兜底自愈。
+import { openSync, closeSync, writeSync, readFileSync, unlinkSync, statSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const LOCK_DIR = join(homedir(), '.opencli');
+const LOCK_PATH = join(LOCK_DIR, 'browser-adapter-session.lock');
+// 等待前面排队命令的最长时间。设得比单条浏览器命令的运行上限更宽，好让后面的命令
+// 排到队即可，而不是提前放弃。持有者若卡死，会先命中它自己命令的超时而释放锁。
+const ACQUIRE_TIMEOUT_MS = 180_000;
+// mtime 兜底：锁文件比这更老就视为陈旧可抢（正常命令远到不了这个量级）。
+const STALE_AFTER_MS = 10 * 60_000;
+const POLL_MS = 60;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH = 进程不存在；EPERM = 存在但无权限发信号（仍算活着）。
+        return err?.code === 'EPERM';
+    }
+}
+function readLockPid() {
+    try {
+        const pid = parseInt(readFileSync(LOCK_PATH, 'utf8').trim(), 10);
+        return Number.isFinite(pid) ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 原子占锁：O_EXCL 创建成功即获得锁。已存在返回 false（不抛）。 */
+function tryAcquire() {
+    try {
+        const fd = openSync(LOCK_PATH, 'wx');
+        try {
+            writeSync(fd, String(process.pid));
+        }
+        finally {
+            closeSync(fd);
+        }
+        return true;
+    }
+    catch (err) {
+        if (err?.code === 'EEXIST')
+            return false;
+        throw err;
+    }
+}
+/** 持有者已死 / 锁文件过老 → 删掉陈旧锁，让后续 tryAcquire 抢占。 */
+function reapStaleLock() {
+    try {
+        const pid = readLockPid();
+        const age = Date.now() - statSync(LOCK_PATH).mtimeMs;
+        if ((pid !== null && !isAlive(pid)) || age > STALE_AFTER_MS) {
+            unlinkSync(LOCK_PATH);
+        }
+    }
+    catch {
+        // 锁文件刚被别人释放/删除：忽略，下一轮 tryAcquire 会重试。
+    }
+}
+/**
+ * 在机器级浏览器会话锁的保护下执行 fn。并发调用会排队串行；顺序调用无等待。
+ * fn 抛出会原样冒泡，锁始终在 finally 里释放。
+ */
+export async function withBrowserSessionLock(fn) {
+    try {
+        mkdirSync(LOCK_DIR, { recursive: true });
+    }
+    catch {
+        // 目录已存在或无法创建（后者会在 openSync 时暴露真实错误）。
+    }
+    const deadline = Date.now() + ACQUIRE_TIMEOUT_MS;
+    while (!tryAcquire()) {
+        reapStaleLock();
+        if (tryAcquire())
+            break;
+        if (Date.now() >= deadline) {
+            throw new Error(`browser session lock busy: waited ${Math.round(ACQUIRE_TIMEOUT_MS / 1000)}s for another browser command to finish`);
+        }
+        await sleep(POLL_MS);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        try {
+            unlinkSync(LOCK_PATH);
+        }
+        catch {
+            // 已被陈旧抢占逻辑删除或从未创建：无所谓。
+        }
+    }
+}
+/** 条件加锁：locked 为真时走串行锁，否则直接执行（前台/交互命令用独立窗口，无需串行）。 */
+export async function withBrowserSessionLockIf(locked, fn) {
+    return locked ? withBrowserSessionLock(fn) : fn();
+}
+// 供测试用的常量导出。
+export const __lockInternals = { LOCK_PATH, ACQUIRE_TIMEOUT_MS, STALE_AFTER_MS };

package/dist/src/browser-session-lock.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser-session-lock.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { existsSync, unlinkSync, writeFileSync } from 'node:fs';
+import { withBrowserSessionLock, withBrowserSessionLockIf, __lockInternals } from './browser-session-lock.js';
+const LOCK = __lockInternals.LOCK_PATH;
+function cleanupLock() {
+    try {
+        if (existsSync(LOCK))
+            unlinkSync(LOCK);
+    }
+    catch { /* ignore */ }
+}
+describe('browser-session-lock', () => {
+    afterEach(cleanupLock);
+    it('serializes concurrent holders — no overlap', async () => {
+        const events = [];
+        let active = 0;
+        let maxActive = 0;
+        const task = (id) => withBrowserSessionLock(async () => {
+            active++;
+            maxActive = Math.max(maxActive, active);
+            events.push(`enter:${id}`);
+            await new Promise((r) => setTimeout(r, 30));
+            events.push(`exit:${id}`);
+            active--;
+        });
+        await Promise.all([task('a'), task('b'), task('c')]);
+        // 任一时刻只有一个持有者 → 临界区不重叠。
+        expect(maxActive).toBe(1);
+        // enter/exit 必须严格配对相邻（a 进 a 出、b 进 b 出…），不会交错。
+        for (let i = 0; i < events.length; i += 2) {
+            expect(events[i]).toMatch(/^enter:/);
+            expect(events[i + 1]).toMatch(/^exit:/);
+            expect(events[i].split(':')[1]).toBe(events[i + 1].split(':')[1]);
+        }
+        // 锁在最后被释放。
+        expect(existsSync(LOCK)).toBe(false);
+    });
+    it('releases the lock even when the body throws', async () => {
+        await expect(withBrowserSessionLock(async () => { throw new Error('boom'); })).rejects.toThrow('boom');
+        expect(existsSync(LOCK)).toBe(false);
+    });
+    it('steals a stale lock whose owner PID is dead', async () => {
+        // 写一个持有者 PID = 一个几乎不可能存在的进程号的锁文件（模拟崩溃残留）。
+        writeFileSync(LOCK, '2147483646');
+        let ran = false;
+        await withBrowserSessionLock(async () => { ran = true; });
+        expect(ran).toBe(true);
+        expect(existsSync(LOCK)).toBe(false);
+    });
+    it('withBrowserSessionLockIf(false) runs without touching the lock file', async () => {
+        let ran = false;
+        await withBrowserSessionLockIf(false, async () => {
+            ran = true;
+            // 未加锁：临界区内锁文件不应存在。
+            expect(existsSync(LOCK)).toBe(false);
+        });
+        expect(ran).toBe(true);
+    });
+    it('withBrowserSessionLockIf(true) does acquire the lock', async () => {
+        let sawLock = false;
+        await withBrowserSessionLockIf(true, async () => {
+            sawLock = existsSync(LOCK);
+        });
+        expect(sawLock).toBe(true);
+        expect(existsSync(LOCK)).toBe(false);
+    });
+});

package/dist/src/cli.js

@@ -32,7 +32,7 @@ import { buildHtmlTreeJs } from './browser/html-tree.js';
 import { buildExtractHtmlJs, runExtractFromHtml } from './browser/extract.js';
 import { analyzeSite } from './browser/analyze.js';
 import { registerAuthCommands } from './commands/auth.js';
-import { daemonRestart, daemonStatus, daemonStop } from './commands/daemon.js';
+import { daemonRestart, daemonStatus, daemonStop, daemonWarm } from './commands/daemon.js';
 import { log } from './logger.js';
 import { bindTab, BrowserCommandError, fetchDaemonStatus, sendCommand } from './browser/daemon-client.js';
 import { aliasForContextId, loadProfileConfig, renameProfile, resolveProfileContextId, setDefaultProfile } from './browser/profile.js';
@@ -3155,6 +3155,11 @@ cli({
         .command('restart')
         .description('Restart the daemon')
         .action(async () => { await daemonRestart(); });
+    daemonCmd
+        .command('warm')
+        .description('Pre-open the background automation window (keeps a tab alive for reuse)')
+        .option('--url <url>', 'http(s) info page to keep in the warm tab (falls back to about:blank)')
+        .action(async (opts) => { await daemonWarm(opts.url); });
     // ── External CLIs ─────────────────────────────────────────────────────────
     const externalClis = loadExternalClis();
     const externalCmd = program

package/dist/src/cli.test.js

@@ -55,7 +55,7 @@ describe('createProgram root help descriptions', () => {
         expect(descriptionFor(program, 'plugin')).toBe('create, install, list, uninstall, update');
         expect(descriptionFor(program, 'adapter')).toBe('eject, reset, status');
         expect(descriptionFor(program, 'profile')).toBe('list, rename, use');
-        expect(descriptionFor(program, 'daemon')).toBe('restart, status, stop');
+        expect(descriptionFor(program, 'daemon')).toBe('restart, status, stop, warm');
         expect(descriptionFor(program, 'external')).toBe('install, list, register');
     });
     it('renders auth namespace structured help', () => {
@@ -623,11 +623,11 @@ describe('createProgram root help descriptions', () => {
                 command: 'opencli daemon',
                 usage: 'opencli daemon <command> [args] [options]',
                 description: 'Manage the opencli daemon',
-                command_count: 3,
+                command_count: 4,
                 namespace_options: [],
                 structured_help: { usage: 'opencli daemon --help -f yaml' },
             });
-            expect(data.commands.map((cmd) => cmd.name)).toEqual(['restart', 'status', 'stop']);
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['restart', 'status', 'stop', 'warm']);
             expect(data.global_options.map((option) => option.name)).toEqual(expect.arrayContaining(['version', 'profile']));
         }
         finally {

package/dist/src/commands/auth.js

@@ -222,6 +222,16 @@ function refreshRowForError(site, entry, error) {
         error: code ? `${code}: ${message}` : message,
     };
 }
+// [pp-only] auth 探测默认走 persistent —— 桌面每 20s 的 quick/full 探测若用 ephemeral
+// 会爆一批临时窗口又关，是「窗口不停开又关」的一大来源。persistent 让轮询复用同一批
+// 常驻标签（每平台一个，官方扩展永不 idle 关闭），零 churn。keepTab 跟随 session。
+// 与 resolveSiteSession 一致：默认 persistent，不依赖 env；仅
+// PUBLISHPORT_SITE_SESSION=ephemeral 时才显式退回一次性会话。
+function authProbeSessionOpts() {
+    return process.env.PUBLISHPORT_SITE_SESSION === 'ephemeral'
+        ? { siteSession: 'ephemeral', keepTab: 'false' }
+        : { siteSession: 'persistent', keepTab: 'true' };
+}
 async function runQuick(cmd, opts) {
     try {
         const loaded = await loadLazyCommand(cmd);
@@ -247,8 +257,7 @@ async function runQuick(cmd, opts) {
             };
         }
         const result = await executeCommand(quickCmd, { timeout: opts.timeoutSeconds }, false, {
-            siteSession: 'ephemeral',
-            keepTab: 'false',
+            ...authProbeSessionOpts(),
             windowMode: 'background',
             ...(opts.profile ? { profile: opts.profile } : {}),
         });
@@ -277,8 +286,7 @@ async function runFull(cmd, opts) {
         const loaded = await loadLazyCommand(cmd);
         const fullCmd = withTimeoutArg(loaded, opts.timeoutSeconds);
         const result = await executeCommand(fullCmd, { timeout: opts.timeoutSeconds }, false, {
-            siteSession: 'ephemeral',
-            keepTab: 'false',
+            ...authProbeSessionOpts(),
             windowMode: 'background',
             ...(opts.profile ? { profile: opts.profile } : {}),
         });

package/dist/src/commands/daemon.d.ts

@@ -3,7 +3,23 @@
  *   opencli daemon status — show daemon state
  *   opencli daemon stop   — graceful shutdown
  *   opencli daemon restart — graceful shutdown, then start a fresh daemon
+ *   opencli daemon warm — [pp-only] 预热后台自动化窗口（挂一个持久空白标签）
  */
 export declare function daemonStatus(): Promise<void>;
 export declare function daemonStop(): Promise<void>;
 export declare function daemonRestart(): Promise<void>;
+/**
+ * [pp-only] 预热后台自动化窗口。
+ *
+ * 用一个持久（persistent）会话在后台打开自动化窗口并挂一个标签，让「后台常驻窗口」在
+ * **任何真实命令之前**就已经存在——之后各平台命令只是往这个窗口里加/复用标签，永远不会
+ * 「一有动作就弹一个新窗口」。桌面客户端在启动、且检测到扩展已连接后调用一次即可。
+ *
+ * `url` 传一个说明页（如 https://publishport.app/automation）时，这个常驻标签会停在
+ * 说明页上，告诉用户「此窗口用于自动化、请勿关闭」——用户不关它，Chrome 与扩展就一直
+ * 在线，PublishPort 也能稳定检测到浏览器。不传则回退到 about:blank。
+ *
+ * 窗口走 background 模式（不聚焦、不抢焦点），标签因 persistent 永不 idle 关闭，会一直
+ * 挂着。重复调用是幂等的（复用同一个已存在的窗口/标签）。
+ */
+export declare function daemonWarm(url?: string): Promise<void>;

package/dist/src/commands/daemon.js

@@ -3,6 +3,7 @@
  *   opencli daemon status — show daemon state
  *   opencli daemon stop   — graceful shutdown
  *   opencli daemon restart — graceful shutdown, then start a fresh daemon
+ *   opencli daemon warm — [pp-only] 预热后台自动化窗口（挂一个持久空白标签）
  */
 import { fetchDaemonStatus, requestDaemonShutdown } from '../browser/daemon-client.js';
 import { restartDaemon } from '../browser/daemon-lifecycle.js';
@@ -10,6 +11,7 @@ import { formatDuration } from '../download/progress.js';
 import { log } from '../logger.js';
 import { PKG_VERSION } from '../version.js';
 import { formatDaemonVersion, isDaemonStale } from '../browser/daemon-version.js';
+import { browserSession, getBrowserFactory } from '../runtime.js';
 export async function daemonStatus() {
     const status = await fetchDaemonStatus();
     if (!status) {
@@ -96,3 +98,43 @@ export async function daemonRestart() {
         log.warn('Daemon is running, but the Browser Bridge extension has not connected yet.');
     }
 }
+/**
+ * [pp-only] 预热后台自动化窗口。
+ *
+ * 用一个持久（persistent）会话在后台打开自动化窗口并挂一个标签，让「后台常驻窗口」在
+ * **任何真实命令之前**就已经存在——之后各平台命令只是往这个窗口里加/复用标签，永远不会
+ * 「一有动作就弹一个新窗口」。桌面客户端在启动、且检测到扩展已连接后调用一次即可。
+ *
+ * `url` 传一个说明页（如 https://publishport.app/automation）时，这个常驻标签会停在
+ * 说明页上，告诉用户「此窗口用于自动化、请勿关闭」——用户不关它，Chrome 与扩展就一直
+ * 在线，PublishPort 也能稳定检测到浏览器。不传则回退到 about:blank。
+ *
+ * 窗口走 background 模式（不聚焦、不抢焦点），标签因 persistent 永不 idle 关闭，会一直
+ * 挂着。重复调用是幂等的（复用同一个已存在的窗口/标签）。
+ */
+export async function daemonWarm(url) {
+    const status = await fetchDaemonStatus();
+    if (!status) {
+        // 没连上扩展时 browserSession 会自行拉起 daemon 并等待；但扩展没连上就没法建窗，
+        // 这里只提示、不报错，交由桌面在扩展就绪后重试。
+        log.warn('Daemon/extension not ready; skip warm (retry after the browser extension connects).');
+        return;
+    }
+    if (!status.extensionConnected) {
+        log.warn('Browser extension not connected yet; skip warm.');
+        return;
+    }
+    // 扩展只放行 http/https 导航；其它一律回退 about:blank，避免报错。
+    const target = url && /^https?:\/\//i.test(url) ? url : 'about:blank';
+    const BrowserFactory = getBrowserFactory('__warm__');
+    try {
+        await browserSession(BrowserFactory, async (page) => {
+            // 一次导航即可强制扩展创建自动化窗口 + 标签并登记 persistent 租约。
+            await page.goto(target).catch(() => { });
+        }, { session: 'site:__warm__', windowMode: 'background', surface: 'adapter', siteSession: 'persistent' });
+        log.success(`Automation window warmed (${target}, kept alive for reuse).`);
+    }
+    catch (err) {
+        log.warn(`Warm failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/src/execution.js

@@ -18,6 +18,7 @@ import { executePipeline } from './pipeline/index.js';
 import { adapterLoadError, ArgumentError, CommandExecutionError, attachTraceReceipt, getErrorMessage } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
+import { withBrowserSessionLockIf } from './browser-session-lock.js';
 import { resolveProfileContextId } from './browser/profile.js';
 import { emitHook } from './hooks.js';
 import { log } from './logger.js';
@@ -219,7 +220,10 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
             const session = resolveAdapterBrowserSession(cmd, siteSession);
             const keepTab = resolveKeepTab(siteSession, opts.keepTab);
             const windowMode = resolveBrowserWindowMode(cmd.defaultWindowMode ?? 'background', opts.windowMode);
-            result = await browserSession(BrowserFactory, async (page) => {
+            // [pp-only] 后台自动化命令共用同一个窗口，物理上一次只能安全跑一条——用机器级锁
+            // 把并发命令串行化（排队复用同一窗口），避免互相拆窗/扯掉调试器。前台/交互命令走
+            // 独立窗口，不参与串行。见 browser-session-lock.ts。
+            result = await withBrowserSessionLockIf(windowMode !== 'foreground', () => browserSession(BrowserFactory, async (page) => {
                 const observation = traceMode === 'off'
                     ? null
                     : new ObservationSession({
@@ -334,7 +338,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { session, cdpEndpoint, contextId, windowMode, surface: 'adapter', siteSession });
+            }, { session, cdpEndpoint, contextId, windowMode, surface: 'adapter', siteSession }));
         }
         else {
             // Non-browser commands: enforce a timeout only when the command exposes
@@ -451,8 +455,26 @@ function normalizeSiteSession(raw) {
         return raw;
     throw new ArgumentError(`--site-session must be one of: ephemeral, persistent. Received: "${String(raw)}"`);
 }
+// [pp-only] PublishPort 是「单机单用户 + 复用真实登录态」模型：它希望所有浏览器
+// 命令长期复用同一个后台自动化窗口，而不是上游默认的 ephemeral（每条命令开标签→
+// 干活→30s idle 后关标签，AI 命令间隔一超过 30s 就变成「窗口又开又关」）。
+// 官方扩展对 persistent 会话本来就永不 idle 关闭、且 SW 重启后能从存活标签反查回
+// 窗口复用——所以只要把默认会话抬成 persistent，无需改扩展即可复用窗口。
+//
+// 关键：默认就是 persistent，**不依赖任何环境变量**。早先版本靠桌面注入
+// PUBLISHPORT_SITE_SESSION=persistent 才开启，实测太脆——同一台机可能同时跑着
+// 「注入了 env 的 dev 构建」和「没注入的正式构建」，后者 fallback 回 ephemeral 照样
+// churn。所以直接把 fork 默认焊成 persistent；只保留 PUBLISHPORT_SITE_SESSION=ephemeral
+// 作为显式反向开关（极少用），供个别场景强制回到一次性会话。
+// 优先级：显式 `--site-session` flag > 环境变量（仅用于强制 ephemeral）> 适配器 cmd.siteSession > 'persistent'。
+function envDefaultSiteSession() {
+    const raw = process.env.PUBLISHPORT_SITE_SESSION;
+    if (raw === 'persistent' || raw === 'ephemeral')
+        return raw;
+    return null;
+}
 function resolveSiteSession(cmd, rawOption) {
-    return normalizeSiteSession(rawOption) ?? cmd.siteSession ?? 'ephemeral';
+    return normalizeSiteSession(rawOption) ?? envDefaultSiteSession() ?? cmd.siteSession ?? 'persistent';
 }
 function resolveAdapterBrowserSession(cmd, siteSession) {
     if (siteSession === 'persistent')

package/dist/src/execution.test.js

@@ -164,7 +164,12 @@ describe('executeCommand — non-browser timeout', () => {
         expect(closeWindow).not.toHaveBeenCalled();
         vi.restoreAllMocks();
     });
-    it('keeps default browser commands on one-shot adapter sessions', async () => {
+    // [pp-only] PublishPort 把默认会话焊成 persistent（见 resolveSiteSession），所以
+    // 无 flag、无 env、适配器也没标 siteSession 时，浏览器命令默认复用同一个 site 会话、
+    // 保留标签、跨命令复用窗口 —— 而不是上游默认的一次性 ephemeral。
+    it('defaults browser commands to persistent site sessions (pp-only)', async () => {
+        const prev = process.env.PUBLISHPORT_SITE_SESSION;
+        delete process.env.PUBLISHPORT_SITE_SESSION; // 确保不受外部 env 干扰，测的是「纯默认」
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };
         const sessionOpts = [];
@@ -173,26 +178,66 @@ describe('executeCommand — non-browser timeout', () => {
             sessionOpts.push(opts ?? {});
             return fn(mockPage);
         });
-        const cmd = cli({
-            site: 'test-execution',
-            name: 'site-session-default', access: 'read',
-            description: 'test default one-shot browser session',
-            browser: true,
-            strategy: Strategy.PUBLIC,
-            func: async () => [{ ok: true }],
+        try {
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'site-session-default', access: 'read',
+                description: 'test default persistent browser session',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                func: async () => [{ ok: true }],
+            });
+            await executeCommand(cmd, {});
+            await executeCommand(cmd, {});
+            expect(sessionOpts).toHaveLength(2);
+            // 两条命令落到同一个稳定 site 会话（无 UUID）→ 复用同一标签/窗口。
+            expect(sessionOpts[0]).toMatchObject({ session: 'site:test-execution', windowMode: 'background', siteSession: 'persistent' });
+            expect(sessionOpts[1]).toMatchObject({ session: 'site:test-execution', windowMode: 'background', siteSession: 'persistent' });
+            // persistent → keepTab=true → 命令跑完不关窗。
+            expect(closeWindow).not.toHaveBeenCalled();
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.PUBLISHPORT_SITE_SESSION;
+            else
+                process.env.PUBLISHPORT_SITE_SESSION = prev;
+            vi.restoreAllMocks();
+        }
+    });
+    // [pp-only] 反向开关：PUBLISHPORT_SITE_SESSION=ephemeral 时退回一次性会话。
+    it('env PUBLISHPORT_SITE_SESSION=ephemeral forces one-shot sessions back', async () => {
+        const prev = process.env.PUBLISHPORT_SITE_SESSION;
+        process.env.PUBLISHPORT_SITE_SESSION = 'ephemeral';
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        const sessionOpts = [];
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+            sessionOpts.push(opts ?? {});
+            return fn(mockPage);
         });
-        await executeCommand(cmd, {});
-        await executeCommand(cmd, {});
-        expect(sessionOpts).toHaveLength(2);
-        expect(sessionOpts[0]?.session).toMatch(/^site:test-execution:/);
-        expect(sessionOpts[1]?.session).toMatch(/^site:test-execution:/);
-        expect(sessionOpts[0]?.session).not.toBe(sessionOpts[1]?.session);
-        expect(sessionOpts[0]?.idleTimeout).toBeUndefined();
-        expect(sessionOpts[1]?.idleTimeout).toBeUndefined();
-        expect(sessionOpts[0]?.windowMode).toBe('background');
-        expect(sessionOpts[1]?.windowMode).toBe('background');
-        expect(closeWindow).toHaveBeenCalledTimes(2);
-        vi.restoreAllMocks();
+        try {
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'site-session-force-ephemeral', access: 'read',
+                description: 'test env forces ephemeral',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                func: async () => [{ ok: true }],
+            });
+            await executeCommand(cmd, {});
+            await executeCommand(cmd, {});
+            expect(sessionOpts[0]?.session).toMatch(/^site:test-execution:/);
+            expect(sessionOpts[0]?.session).not.toBe(sessionOpts[1]?.session);
+            expect(closeWindow).toHaveBeenCalledTimes(2);
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.PUBLISHPORT_SITE_SESSION;
+            else
+                process.env.PUBLISHPORT_SITE_SESSION = prev;
+            vi.restoreAllMocks();
+        }
     });
     it('lets user --site-session ephemeral override adapter persistent metadata', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
@@ -223,6 +268,78 @@ describe('executeCommand — non-browser timeout', () => {
             vi.restoreAllMocks();
         }
     });
+    // [pp-only] PUBLISHPORT_SITE_SESSION 环境变量把默认会话抬成 persistent，且刻意
+    // 压过 cmd.siteSession，好让 auth quickCheck 那种把 ephemeral 焊死的命令也复用窗口。
+    it('env PUBLISHPORT_SITE_SESSION=persistent lifts an ephemeral-baked command to persistent', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        const sessionOpts = [];
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+            sessionOpts.push(opts ?? {});
+            return fn(mockPage);
+        });
+        const prev = process.env.PUBLISHPORT_SITE_SESSION;
+        process.env.PUBLISHPORT_SITE_SESSION = 'persistent';
+        try {
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'site-session-env-persistent', access: 'read',
+                description: 'test env-driven persistent session',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                siteSession: 'ephemeral',
+                func: async () => [{ ok: true }],
+            });
+            await executeCommand(cmd, {});
+            await executeCommand(cmd, {});
+            expect(sessionOpts).toHaveLength(2);
+            expect(sessionOpts[0]).toMatchObject({ session: 'site:test-execution', siteSession: 'persistent' });
+            expect(sessionOpts[1]).toMatchObject({ session: 'site:test-execution', siteSession: 'persistent' });
+            // persistent → keepTab=true → 窗口不释放，跨命令复用同一标签。
+            expect(closeWindow).not.toHaveBeenCalled();
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.PUBLISHPORT_SITE_SESSION;
+            else
+                process.env.PUBLISHPORT_SITE_SESSION = prev;
+            vi.restoreAllMocks();
+        }
+    });
+    it('explicit --site-session ephemeral still overrides the env persistent default', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        const sessionOpts = [];
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+            sessionOpts.push(opts ?? {});
+            return fn(mockPage);
+        });
+        const prev = process.env.PUBLISHPORT_SITE_SESSION;
+        process.env.PUBLISHPORT_SITE_SESSION = 'persistent';
+        try {
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'site-session-env-flag-override', access: 'read',
+                description: 'test explicit flag beats env',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                func: async () => [{ ok: true }],
+            });
+            await executeCommand(cmd, {}, false, { siteSession: 'ephemeral' });
+            expect(sessionOpts).toHaveLength(1);
+            expect(sessionOpts[0]?.session).toMatch(/^site:test-execution:/);
+            expect(closeWindow).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.PUBLISHPORT_SITE_SESSION;
+            else
+                process.env.PUBLISHPORT_SITE_SESSION = prev;
+            vi.restoreAllMocks();
+        }
+    });
     it('skips repeated domain pre-navigation for persistent site sessions', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const goto = vi.fn().mockResolvedValue(undefined);
@@ -366,7 +483,9 @@ describe('executeCommand — non-browser timeout', () => {
             strategy: Strategy.PUBLIC,
             func: async () => { throw new Error('adapter failure'); },
         });
-        await expect(executeCommand(cmd, {})).rejects.toThrow('adapter failure');
+        // [pp-only] 默认已是 persistent（不关窗）；本例专测「失败路径会释放标签」，故显式
+        // 走 ephemeral 才有 closeWindow 可断言。
+        await expect(executeCommand(cmd, {}, false, { siteSession: 'ephemeral' })).rejects.toThrow('adapter failure');
         expect(closeWindow).toHaveBeenCalledTimes(1);
         vi.restoreAllMocks();
     });
@@ -512,7 +631,8 @@ describe('executeCommand — non-browser timeout', () => {
                 strategy: Strategy.PUBLIC,
                 func: async () => { throw new Error('adapter failure'); },
             });
-            const thrown = await executeCommand(cmd, {}, false, { trace: 'retain-on-failure' }).catch((err) => err);
+            // [pp-only] 默认 persistent 不关窗；本例断言失败路径 closeWindow，故显式 ephemeral。
+            const thrown = await executeCommand(cmd, {}, false, { trace: 'retain-on-failure', siteSession: 'ephemeral' }).catch((err) => err);
             expect(thrown).toBeInstanceOf(Error);
             expect(thrown.message).toContain('adapter failure');
             const tracesRoot = path.join(baseDir, 'profiles', 'default', 'traces');
@@ -572,7 +692,8 @@ describe('executeCommand — non-browser timeout', () => {
                 strategy: Strategy.PUBLIC,
                 func: async () => [{ ok: true }],
             });
-            await expect(executeCommand(cmd, {}, false, { trace: 'on', onTraceExport })).resolves.toEqual([{ ok: true }]);
+            // [pp-only] 默认 persistent 不关窗；本例断言成功路径 closeWindow，故显式 ephemeral。
+            await expect(executeCommand(cmd, {}, false, { trace: 'on', onTraceExport, siteSession: 'ephemeral' })).resolves.toEqual([{ ok: true }]);
             const stderr = stderrSpy.mock.calls.flat().join('\n');
             expect(stderr).toContain('OpenCLI trace artifact:');
             const tracesRoot = path.join(baseDir, 'profiles', 'default', 'traces');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "publishport-opencli",
-  "version": "1.8.5-pp.6",
+  "version": "1.8.5-pp.7",
   "publishConfig": {
     "access": "public"
   },