dsh-openai-subscription 0.1.3 → 0.1.4

package/dist/host.js

@@ -1,7 +1,9 @@
 // Host service for ChatGPT subscription authorization in DSH.
 // OAuth is delegated to the OpenAI Codex integration bundled with DSH.
-import { existsSync } from 'node:fs';
-import { delimiter as pathDelimiter, dirname, join, resolve } from 'node:path';
+import { resolveAuthModule, buildNodeCommand, runtimeSupported } from './platform.js';
+export { authModuleCandidates } from './platform.js';
+import { DRIVER_REFRESH, parseDriverMessage, runDeviceDriver } from './driver.js';
+import { SubscriptionError, failureCode, oauthFailureCode, logFailure } from './errors.js';
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { normalizeOAuthCredential } from './oauth.js';
 import { discoverOpenAIModels, mergeModelCatalog, removeManagedModels, } from './models.js';
@@ -9,69 +11,9 @@ import { discoverOpenAIModels, mergeModelCatalog, removeManagedModels, } from '.
 const KEY = 'dsh-openai-subscription/chatgpt';
 /** Credential consumed by the `openai-codex` model provider. */
 const PI_AI_RECORD = 'llm-pi-ai/openai-codex';
-const LOCATE_SCRIPT = [
-    'set -eu',
-    'CAND=""',
-    'B="$(command -v pi 2>/dev/null || true)"',
-    'if [ -n "$B" ]; then',
-    '  R="$(readlink -f "$B" 2>/dev/null || printf "%s" "$B")"',
-    '  D="$(dirname "$R")"',
-    '  while [ "$D" != "/" ] && [ -n "$D" ]; do',
-    '    if [ -f "$D/node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js" ]; then',
-    '      CAND="$D/node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js"',
-    '      break',
-    '    fi',
-    '    D="$(dirname "$D")"',
-    '  done',
-    'fi',
-    'if [ -z "$CAND" ] && [ -n "${HOME:-}" ] && [ -f "$HOME/.bun/install/global/node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js" ]; then',
-    '  CAND="$HOME/.bun/install/global/node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js"',
-    'fi',
-    'printf "%s" "$CAND"',
-].join('\n');
-/**
- * The OpenAI Codex OAuth implementation, relative to a `node_modules` root.
- * DSH's `llm-pi-ai` adapter already depends on this package, so the copy that
- * matches the running DSH is the preferred source for device authorization.
- */
-const AUTH_MODULE_PACKAGE_RELATIVE = '@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js';
-const DRIVER_DEVICE = [
-    "import { pathToFileURL } from 'node:url'",
-    "const { openaiCodexOAuth } = await import(pathToFileURL(process.argv[1]).href)",
-    "const out = (o) => { try { process.stdout.write(JSON.stringify(o) + '\\n') } catch {} }",
-    "process.stdout.on('error', () => {})",
-    "const signal = AbortSignal.timeout(15 * 60 * 1000)",
-    "const interaction = {",
-    "  signal,",
-    "  notify: (n) => out({ type: 'notice', ...n }),",
-    "  prompt: async (p) => (p.type === 'select' ? 'device_code' : ''),",
-    "}",
-    "try {",
-    "  const credential = await openaiCodexOAuth.login(interaction)",
-    "  out({ type: 'result', credential })",
-    "} catch (error) {",
-    "  out({ type: 'error', message: error instanceof Error ? error.message : String(error) })",
-    "}",
-].join('\n');
-const DRIVER_REFRESH = [
-    "import { readFileSync } from 'node:fs'",
-    "import { pathToFileURL } from 'node:url'",
-    "const { openaiCodexOAuth } = await import(pathToFileURL(process.argv[1]).href)",
-    "const out = (o) => { try { process.stdout.write(JSON.stringify(o) + '\\n') } catch {} }",
-    "process.stdout.on('error', () => {})",
-    "const credential = JSON.parse(readFileSync(0, 'utf8') || '{}')",
-    "const signal = AbortSignal.timeout(90 * 1000)",
-    "try {",
-    "  const refreshed = await openaiCodexOAuth.refresh(credential, signal)",
-    "  out({ type: 'result', credential: refreshed })",
-    "} catch (error) {",
-    "  out({ type: 'error', message: error instanceof Error ? error.message : String(error) })",
-    "}",
-].join('\n');
-/** Format an unknown error for logs and user-facing messages. */
+/** Log only machine-readable categories, never raw service diagnostics. */
 function errorMessage(error) {
-    const message = error?.message;
-    return message ? String(message) : String(error);
+    return failureCode(error);
 }
 function recordOf(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value)
@@ -122,68 +64,6 @@ function unionModelCatalog(remote, builtin) {
 function settingsConflict(error) {
     return recordOf(error)?.code === 'SETTINGS_CONFLICT';
 }
-/**
- * Filesystem candidates for the OpenAI auth module, derived from the running
- * DSH process. The first candidate that exists is used, so the module always
- * matches the pi-ai version bundled with the installed DSH regardless of how
- * `pi` (or DSH itself) was installed; the shell locator below only runs when
- * none of these probes hit.
- */
-export function authModuleCandidates(entryScript, nodeBinary, env) {
-    const candidates = [];
-    const seen = new Set();
-    const push = (value) => {
-        if (!value)
-            return;
-        const normalized = resolve(value);
-        if (seen.has(normalized))
-            return;
-        seen.add(normalized);
-        candidates.push(normalized);
-    };
-    // Walk up from the running DSH entry script. This finds the pi-ai copy
-    // bundled inside DSH's own installation for npm-, nvm-, and yarn-style
-    // layouts (global or workspace), even when `pi` is a standalone binary
-    // or missing entirely.
-    if (entryScript) {
-        let dir = dirname(entryScript);
-        for (let depth = 0; depth < 40 && dir; depth++) {
-            push(join(dir, 'node_modules', AUTH_MODULE_PACKAGE_RELATIVE));
-            const parent = dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
-    }
-    // Node's global module roots, mirroring how `module.globalPaths` is built:
-    // NODE_PATH entries plus the lib/node_modules directory beside the Node
-    // binary (also covers nvm-managed Node on macOS and Linux).
-    const globalRoots = [];
-    if (nodeBinary) {
-        globalRoots.push(resolve(dirname(nodeBinary), '../lib/node_modules'));
-        globalRoots.push(join(dirname(nodeBinary), 'node_modules'));
-    }
-    const nodePath = env?.NODE_PATH;
-    if (nodePath) {
-        for (const entry of nodePath.split(pathDelimiter)) {
-            if (entry)
-                globalRoots.push(entry);
-        }
-    }
-    for (const root of globalRoots) {
-        // A directly installed pi-ai, or the hoisted copy under a globally
-        // installed DSH (npm hoists transitive dependencies into DSH's own
-        // node_modules; the nested path covers version-conflicted installs).
-        push(join(root, 'node_modules', AUTH_MODULE_PACKAGE_RELATIVE));
-        push(join(root, AUTH_MODULE_PACKAGE_RELATIVE));
-        push(join(root, '@deepseek-ai/dsh/node_modules', AUTH_MODULE_PACKAGE_RELATIVE));
-        push(join(root, '@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-llm-pi-ai/node_modules', AUTH_MODULE_PACKAGE_RELATIVE));
-    }
-    // bun's global install root, matching the shell locator fallback.
-    if (env?.HOME)
-        push(join(env.HOME, '.bun/install/global/node_modules', AUTH_MODULE_PACKAGE_RELATIVE));
-    return candidates;
-}
 //#endregion
 /** Register source-mode remote methods without decorator syntax. */
 const REMOTE_METHODS = ['status', 'authorize', 'poll', 'cancel', 'syncModels', 'logout'];
@@ -213,9 +93,16 @@ class OpenAISubscriptionController extends TypertRemoteService {
     syncingModels = null;
     modelSyncController = null;
     modelDiscovery = discoverOpenAIModels;
+    disconnecting = null;
     constructor(ctx) {
         super(ctx, 'openaiSubscription', { namespace: 'openaiSubscription' });
         // Resolve optional services per operation so late mounts and reloads work.
+        ctx.effect(() => async () => {
+            this.pendingBridge?.controller.abort();
+            this.modelSyncController?.abort();
+            await Promise.allSettled([this.pendingBridge?.task, this.syncingModels, this.disconnecting]);
+            this.pendingBridge = null;
+        });
     }
     credentials() {
         return this.ctx.get('credentials');
@@ -223,9 +110,6 @@ class OpenAISubscriptionController extends TypertRemoteService {
     shell() {
         return this.ctx.get('shell');
     }
-    timer() {
-        return this.ctx.get('timer');
-    }
     authorization() {
         return this.ctx.get('authorization');
     }
@@ -247,19 +131,7 @@ class OpenAISubscriptionController extends TypertRemoteService {
      * copy shipped inside the running DSH first; returns '' when nothing hits.
      */
     probeInProcessModule() {
-        if (typeof process === 'undefined' || !Array.isArray(process.argv))
-            return '';
-        const candidates = authModuleCandidates(process.argv[1], process.execPath, process.env);
-        for (const candidate of candidates) {
-            try {
-                if (existsSync(candidate))
-                    return candidate;
-            }
-            catch {
-                // Unreadable or unavailable path: keep probing the remaining roots.
-            }
-        }
-        return '';
+        return resolveAuthModule();
     }
     async locateAuthModule() {
         if (this.cachedModule !== null)
@@ -267,23 +139,7 @@ class OpenAISubscriptionController extends TypertRemoteService {
         if (this.locatingModule !== null)
             return this.locatingModule;
         const pending = (async () => {
-            const probed = this.probeInProcessModule();
-            if (probed)
-                return probed;
-            const shell = this.shell();
-            if (shell === undefined)
-                return '';
-            try {
-                const spec = shell.resolve({ command: LOCATE_SCRIPT, timeoutMs: 20000, stdoutMaxBytes: 4096 });
-                const result = await shell.run(spec);
-                if (result.exitCode !== 0)
-                    return '';
-                return (result.stdout.text || '').trim();
-            }
-            catch (error) {
-                console.error('[openai-subscription] locate OpenAI auth module failed: ' + errorMessage(error));
-                return '';
-            }
+            return this.probeInProcessModule();
         })();
         this.locatingModule = pending;
         try {
@@ -302,122 +158,22 @@ class OpenAISubscriptionController extends TypertRemoteService {
         const credentials = this.credentials();
         if (credentials === undefined) {
             notify({ message: 'DSH 凭证服务不可用，请重启后重试。' });
-            throw new Error('DSH credential service unavailable');
+            throw new SubscriptionError('credentials-unavailable');
         }
         const modulePath = await this.locateAuthModule();
         const shell = this.shell();
-        if (!modulePath || shell === undefined) {
-            notify({ message: '当前 DSH 环境缺少 OpenAI 登录组件，请更新 DSH 后重试。' });
-            throw new Error('OpenAI login component unavailable');
-        }
+        if (shell === undefined)
+            throw new SubscriptionError('shell-unavailable');
+        if (!modulePath)
+            throw new SubscriptionError('component-unavailable');
+        if (!runtimeSupported())
+            throw new SubscriptionError('runtime-unsupported');
         notify({ kind: 'requesting-code', message: '正在向 OpenAI 请求设备登录码…' });
-        const spec = shell.resolve({
-            command: 'node --input-type=module --eval ' + this.shq(DRIVER_DEVICE) + ' ' + this.shq(modulePath),
-            timeoutMs: 16 * 60 * 1000,
-            stdoutMaxBytes: 262144,
-            signal: control.signal,
+        const granted = await runDeviceDriver(shell, modulePath, control.signal, (code, url) => {
+            notify({ kind: 'enter-code', message: '请在 OpenAI 验证页面输入设备码。', code, url });
         });
-        const proc = shell.start(spec);
-        let buffer = '';
-        let credential = null;
-        let failure = null;
-        const deadline = Date.now() + 15 * 60 * 1000;
-        while (credential === null && failure === null) {
-            if (control.aborted()) {
-                try {
-                    proc.kill();
-                }
-                catch { }
-                await proc.done;
-                return null;
-            }
-            let read;
-            try {
-                read = proc.readOutput();
-            }
-            catch {
-                read = { delta: '' };
-            }
-            buffer += read.delta || '';
-            let nl;
-            while ((nl = buffer.indexOf('\n')) >= 0) {
-                const line = buffer.slice(0, nl).trim();
-                buffer = buffer.slice(nl + 1);
-                if (!line)
-                    continue;
-                let msg = null;
-                try {
-                    msg = JSON.parse(line);
-                }
-                catch {
-                    continue;
-                }
-                if (typeof msg.userCode === 'string' && msg.userCode) {
-                    notify({
-                        kind: 'enter-code',
-                        message: '请打开链接，使用有 Codex 权限的 ChatGPT 账号登录并输入设备码。',
-                        url: typeof msg.verificationUri === 'string' ? msg.verificationUri : 'https://auth.openai.com/codex/device',
-                        code: msg.userCode,
-                    });
-                }
-                else if (msg.type === 'result') {
-                    credential = normalizeOAuthCredential(msg.credential);
-                    if (credential === null)
-                        failure = '登录模块返回了无效的授权凭证';
-                }
-                else if (msg.type === 'error') {
-                    failure = typeof msg.message === 'string' ? msg.message : '登录流程异常结束';
-                }
-            }
-            if (credential === null && failure === null) {
-                const timer = this.timer();
-                if (Date.now() > deadline) {
-                    failure = '登录超时（15 分钟）';
-                    break;
-                }
-                if (proc.status !== 'running') {
-                    failure = '登录进程意外退出';
-                    break;
-                }
-                if (timer === undefined) {
-                    failure = 'DSH 计时服务不可用';
-                    break;
-                }
-                try {
-                    await timer.timeout(1000);
-                }
-                catch {
-                    failure = '登录轮询已停止';
-                    break;
-                }
-            }
-        }
-        if (failure !== null) {
-            try {
-                proc.kill();
-            }
-            catch { }
-            await proc.done;
-            const knownFailure = failure === '登录超时（15 分钟）'
-                || failure === '登录进程意外退出'
-                || failure === 'DSH 计时服务不可用'
-                || failure === '登录轮询已停止'
-                || failure === '登录模块返回了无效的授权凭证';
-            const summary = knownFailure ? failure : 'OpenAI 登录请求未完成';
-            const hint = /404|not enabled/i.test(failure)
-                ? ' 请在 ChatGPT 安全设置中启用设备码授权后重试。'
-                : ' 请重试。';
-            notify({ message: summary + '。' + hint });
-            throw new Error('OpenAI authorization failed');
-        }
-        if (credential === null)
-            throw new Error('OpenAI authorization ended without credentials');
-        if (proc.status === 'running')
-            proc.kill();
-        await proc.done;
-        if (control.aborted())
+        if (granted === null || control.aborted())
             return null;
-        const granted = credential;
         await credentials.modifyRecord(KEY, async (current) => {
             if (control.aborted())
                 return undefined;
@@ -430,6 +186,7 @@ class OpenAISubscriptionController extends TypertRemoteService {
                     ...currentPayload,
                     provider: 'openai',
                     loginMethod: 'device_code',
+                    cleanupPending: false,
                     accountId: granted.accountId ?? null,
                     access: granted.access,
                     refresh: granted.refresh ?? '',
@@ -438,26 +195,26 @@ class OpenAISubscriptionController extends TypertRemoteService {
                     managedPiRoute: currentPayload.managedPiRoute === true,
                 },
             };
-        });
+        }).catch((error) => { throw new SubscriptionError(failureCode(error, 'credential-write-failed')); });
         if (control.aborted())
             return null;
         if (!(await this.mirrorToPiAi(granted, undefined, control.signal))) {
             if (control.aborted())
                 return null;
             notify({ message: '授权已完成，但模型凭证保存失败，请重试。' });
-            throw new Error('Provider credential write failed');
+            throw new SubscriptionError('credential-write-failed');
         }
         if (control.aborted())
             return null;
         try {
-            await this.synchronizeModels(control.signal);
-            notify({ kind: 'models-synced', message: '可用模型已同步。' });
+            const sync = await this.synchronizeModels(control.signal);
+            notify({ kind: sync.warningCode ? 'models-sync-failed' : 'models-synced', errorCode: sync.warningCode, message: '可用模型已同步。' });
         }
         catch (error) {
             if (control.aborted())
                 return null;
             console.error('[openai-subscription] initial model sync failed: ' + errorMessage(error));
-            notify({ kind: 'models-sync-failed', message: '授权已保存，模型目录可稍后重试同步。' });
+            notify({ kind: 'models-sync-failed', errorCode: failureCode(error, 'settings-write-failed'), message: '授权已保存，模型目录可稍后重试同步。' });
         }
         return granted;
     }
@@ -465,14 +222,14 @@ class OpenAISubscriptionController extends TypertRemoteService {
         const credentials = this.credentials();
         if (credentials === undefined) {
             notify({ message: 'DSH 凭证服务不可用，请重启后重试。' });
-            throw new Error('DSH credential service unavailable');
+            throw new SubscriptionError('credentials-unavailable');
         }
         const current = await credentials.readRecord(KEY);
         const adapterRecord = await credentials.readRecord(PI_AI_RECORD);
-        if ((current === undefined || current.kind !== 'grant') && (adapterRecord === undefined || adapterRecord.kind !== 'grant')) {
-            notify({ message: '尚未登录 ChatGPT 账号，请先完成设备授权。' });
-            throw new Error('ChatGPT authorization not found');
-        }
+        if (current === undefined || current.kind !== 'grant' || grantPayload(current).cleanupPending === true)
+            throw new SubscriptionError('not-connected');
+        if (!runtimeSupported())
+            throw new SubscriptionError('runtime-unsupported');
         const payload = current?.kind === 'grant' && current.payload && typeof current.payload === 'object'
             ? current.payload
             : {};
@@ -483,17 +240,17 @@ class OpenAISubscriptionController extends TypertRemoteService {
         const secretPayload = typeof adapterPayload.refresh === 'string' && adapterPayload.refresh ? adapterPayload : payload;
         if (typeof secretPayload.refresh !== 'string' || !secretPayload.refresh) {
             notify({ message: '当前授权无法刷新，请退出后重新登录。' });
-            throw new Error('ChatGPT authorization cannot be refreshed');
+            throw new SubscriptionError('not-refreshable');
         }
         const expectedMainRefresh = typeof payload.refresh === 'string' ? payload.refresh : null;
         const expectedAdapterRefresh = secretPayload.refresh;
         const adapterRecordRequired = adapterRecord?.kind === 'grant';
         const modulePath = await this.locateAuthModule();
         const shell = this.shell();
-        if (!modulePath || shell === undefined) {
-            notify({ message: '当前 DSH 环境缺少 OpenAI 登录组件，请更新 DSH 后重试。' });
-            throw new Error('OpenAI login component unavailable');
-        }
+        if (shell === undefined)
+            throw new SubscriptionError('shell-unavailable');
+        if (!modulePath)
+            throw new SubscriptionError('component-unavailable');
         const previous = {};
         if (typeof secretPayload.access === 'string' && secretPayload.access)
             previous.access = secretPayload.access;
@@ -505,7 +262,7 @@ class OpenAISubscriptionController extends TypertRemoteService {
             previous.accountId = secretPayload.accountId;
         notify({ kind: 'refreshing', message: '正在刷新 ChatGPT 订阅授权…' });
         const spec = shell.resolve({
-            command: 'node --input-type=module --eval ' + this.shq(DRIVER_REFRESH) + ' ' + this.shq(modulePath),
+            command: buildNodeCommand(DRIVER_REFRESH, modulePath),
             timeoutMs: 120000,
             stdoutMaxBytes: 65536,
             signal: control.signal,
@@ -515,46 +272,43 @@ class OpenAISubscriptionController extends TypertRemoteService {
         const result = await shell.run(spec);
         if (result.aborted || control.aborted())
             return null;
+        if (result.sandbox?.denied)
+            throw new SubscriptionError('access-denied');
+        if (result.timedOut)
+            throw new SubscriptionError('timeout');
+        if (result.stdout.truncated)
+            throw new SubscriptionError('invalid-response');
+        if (result.exitCode !== 0)
+            throw new SubscriptionError('process-exited');
         let msg = null;
-        if (result.exitCode === 0) {
-            const lines = (result.stdout.text || '').split('\n');
-            for (let i = lines.length - 1; i >= 0; i--) {
-                const line = (lines[i] ?? '').trim();
-                if (!line)
-                    continue;
-                try {
-                    msg = JSON.parse(line);
-                }
-                catch {
-                    continue;
-                }
+        const lines = (result.stdout.text || '').split('\n');
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const candidate = parseDriverMessage(lines[i] ?? '');
+            if (candidate?.type === 'result' || candidate?.type === 'error') {
+                msg = candidate;
                 break;
             }
         }
-        if (!msg || msg.type !== 'result' || !msg.credential || typeof msg.credential !== 'object') {
-            notify({ message: '刷新失败，请检查网络后重试；若问题持续，请退出后重新登录。' });
-            throw new Error('OpenAI authorization refresh failed');
-        }
-        const next = normalizeOAuthCredential(msg.credential, previous);
-        if (next === null) {
-            notify({ message: '刷新失败：登录服务返回了无效响应。' });
-            throw new Error('Invalid authorization response');
-        }
+        if (msg?.type === 'error')
+            throw new SubscriptionError(oauthFailureCode(msg.message));
+        const next = normalizeOAuthCredential(msg?.credential, previous);
+        if (next === null)
+            throw new SubscriptionError('invalid-response');
         if (!(await this.mirrorToPiAi(next, { refresh: expectedAdapterRefresh, requireExisting: adapterRecordRequired }, control.signal))) {
             notify({ message: '刷新期间授权记录已变化，已保留较新的凭证。' });
-            throw new Error('Provider authorization changed during refresh');
+            throw new SubscriptionError('credential-changed');
         }
         await credentials.modifyRecord(KEY, async (latest) => {
             if (control.aborted())
                 return undefined;
-            if (latest !== undefined && latest.kind !== 'grant')
-                throw new Error('Plugin authorization changed during refresh');
+            if (latest === undefined || latest.kind !== 'grant')
+                throw new SubscriptionError('credential-changed');
             const latestPayload = latest?.kind === 'grant' && latest.payload && typeof latest.payload === 'object'
                 ? latest.payload
                 : {};
             const latestRefresh = typeof latestPayload.refresh === 'string' ? latestPayload.refresh : null;
             if (latestRefresh !== expectedMainRefresh)
-                throw new Error('Plugin authorization changed during refresh');
+                throw new SubscriptionError('credential-changed');
             return {
                 kind: 'grant',
                 payload: {
@@ -570,18 +324,18 @@ class OpenAISubscriptionController extends TypertRemoteService {
                     managedPiRoute: latestPayload.managedPiRoute === true,
                 },
             };
-        });
+        }).catch((error) => { throw new SubscriptionError(failureCode(error, 'credential-write-failed')); });
         if (control.aborted())
             return null;
         try {
-            await this.synchronizeModels(control.signal);
-            notify({ kind: 'models-synced', message: '授权与可用模型已更新。' });
+            const sync = await this.synchronizeModels(control.signal);
+            notify({ kind: sync.warningCode ? 'models-sync-failed' : 'models-synced', errorCode: sync.warningCode, message: '授权与可用模型已更新。' });
         }
         catch (error) {
             if (control.aborted())
                 return null;
             console.error('[openai-subscription] model sync after refresh failed: ' + errorMessage(error));
-            notify({ kind: 'models-sync-failed', message: '授权已更新，模型目录可稍后重试同步。' });
+            notify({ kind: 'models-sync-failed', errorCode: failureCode(error, 'settings-write-failed'), message: '授权已更新，模型目录可稍后重试同步。' });
         }
         return next;
     }
@@ -603,12 +357,14 @@ class OpenAISubscriptionController extends TypertRemoteService {
                     return undefined;
                 if (expected !== undefined) {
                     if (expected.requireExisting && (current === undefined || current.kind !== 'grant')) {
-                        throw new Error('Provider authorization was removed during refresh');
+                        throw new SubscriptionError('credential-changed');
                     }
+                    if (current !== undefined && current.kind !== 'grant')
+                        throw new SubscriptionError('credential-changed');
                     if (current !== undefined && current.kind === 'grant') {
                         const currentPayload = current.payload && typeof current.payload === 'object' ? current.payload : {};
                         if (currentPayload.refresh !== expected.refresh)
-                            throw new Error('Provider authorization changed during refresh');
+                            throw new SubscriptionError('credential-changed');
                     }
                 }
                 return { kind: 'grant', payload };
@@ -617,7 +373,7 @@ class OpenAISubscriptionController extends TypertRemoteService {
         }
         catch (error) {
             console.error('[openai-subscription] mirror to llm-pi-ai/openai-codex failed: ' + errorMessage(error));
-            return false;
+            throw new SubscriptionError(failureCode(error, 'credential-write-failed'));
         }
     }
     /** Keep one cancellable model sync in flight so login, refresh, and UI actions cannot race. */
@@ -644,25 +400,50 @@ class OpenAISubscriptionController extends TypertRemoteService {
         });
         return pending;
     }
+    /** Bound this read even if an older adapter ignores AbortSignal. No writes are raced. */
+    async readBuiltinModels(signal) {
+        const llm = this.llm();
+        if (llm === undefined || typeof llm.discoverModels !== 'function')
+            throw new SubscriptionError('models-unavailable');
+        const timeout = new AbortController();
+        const timer = setTimeout(() => timeout.abort(), 30_000);
+        const combined = AbortSignal.any([signal, timeout.signal]);
+        let onAbort = () => { };
+        const aborted = new Promise((_resolve, reject) => {
+            onAbort = () => reject(new SubscriptionError(signal.aborted ? 'cancelled' : 'timeout'));
+            combined.addEventListener('abort', onAbort, { once: true });
+            if (combined.aborted)
+                onAbort();
+        });
+        try {
+            if (combined.aborted)
+                return await aborted;
+            return await Promise.race([aborted, llm.discoverModels('llm-pi-ai', { provider: 'openai-codex' }, combined)]);
+        }
+        finally {
+            clearTimeout(timer);
+            combined.removeEventListener('abort', onAbort);
+        }
+    }
     /** Fetch the account-scoped catalog and replace only this plugin's previous rows. */
     async performModelSync(signal, adoptExistingModels) {
         const credentials = this.credentials();
         if (credentials === undefined)
-            throw new Error('DSH 凭证服务不可用，请重启后重试');
+            throw new SubscriptionError('credentials-unavailable');
         const settings = this.ctx.get('settings');
         if (settings === undefined || typeof settings.mutate !== 'function') {
-            throw new Error('DSH 模型设置服务不可用，请重启后重试');
+            throw new SubscriptionError('settings-unavailable');
         }
         const [ownerRecord, adapterRecord] = await Promise.all([
             credentials.readRecord(KEY),
             credentials.readRecord(PI_AI_RECORD),
         ]);
-        if (recordOf(ownerRecord)?.kind !== 'grant')
-            throw new Error('尚未通过此插件连接 ChatGPT，请先完成登录');
+        if (recordOf(ownerRecord)?.kind !== 'grant' || grantPayload(ownerRecord).cleanupPending === true)
+            throw new SubscriptionError('not-connected');
         const adapter = grantPayload(adapterRecord);
         const access = typeof adapter.access === 'string' ? adapter.access : '';
         if (!access)
-            throw new Error('尚未连接 ChatGPT，请先完成登录');
+            throw new SubscriptionError('not-connected');
         const accountId = typeof adapter.accountId === 'string' && adapter.accountId.length > 0
             ? adapter.accountId
             : undefined;
@@ -673,49 +454,48 @@ class OpenAISubscriptionController extends TypertRemoteService {
         // user/profile allow-list has no prior plugin ownership snapshot.
         const initialDescriptor = settings.describe({ redactSecrets: true }).find((entry) => entry.ns === 'llm-pi-ai');
         if (initialDescriptor === undefined)
-            throw new Error('DSH 模型适配器未启用，请更新 DSH 后重试');
+            throw new SubscriptionError('settings-unavailable');
         const initialPlugin = grantPayload(ownerRecord);
         if (!adoptExistingModels
             && modelIds(initialPlugin.managedModels).length === 0
             && explicitRouteModels(initialDescriptor.user, initialDescriptor.base) !== undefined) {
-            throw new Error('现有模型列表由配置管理，请在 ChatGPT 设置页确认同步');
+            throw new SubscriptionError('models-confirmation-required');
         }
         const remoteModels = await this.modelDiscovery(discoveryCredential, { signal });
-        const llm = this.llm();
-        if (llm === undefined || typeof llm.discoverModels !== 'function') {
-            throw new Error('DSH 模型目录服务不可用，请重启后重试');
-        }
         let builtinModels;
         try {
-            builtinModels = await llm.discoverModels('llm-pi-ai', { provider: 'openai-codex' }, signal);
+            builtinModels = await this.readBuiltinModels(signal);
+            if (!Array.isArray(builtinModels) || builtinModels.some((candidate) => typeof recordOf(candidate)?.id !== 'string')) {
+                throw new SubscriptionError('invalid-response');
+            }
         }
         catch (error) {
             console.error('[openai-subscription] read installed openai-codex catalog failed: ' + errorMessage(error));
-            throw new Error('无法读取 DSH 内置模型目录，现有设置未更改');
+            throw new SubscriptionError(failureCode(error, 'models-unavailable'));
         }
         const discovered = unionModelCatalog(remoteModels, builtinModels);
         for (let attempt = 0; attempt < 3; attempt++) {
             if (signal.aborted)
-                throw new Error('模型同步已取消');
+                throw new SubscriptionError('cancelled');
             const [currentOwner, currentAdapter] = await Promise.all([
                 credentials.readRecord(KEY),
                 credentials.readRecord(PI_AI_RECORD),
             ]);
             if (recordOf(currentOwner)?.kind !== 'grant')
-                throw new Error('ChatGPT 连接已被移除');
+                throw new SubscriptionError('credential-changed');
             const liveAdapter = grantPayload(currentAdapter);
             const liveAccess = typeof liveAdapter.access === 'string' ? liveAdapter.access : '';
             const liveAccountId = typeof liveAdapter.accountId === 'string' ? liveAdapter.accountId : undefined;
             if (!liveAccess || (accountId === undefined ? liveAccess !== access : liveAccountId !== accountId)) {
-                throw new Error('ChatGPT 连接在同步期间发生变化，请重试');
+                throw new SubscriptionError('credential-changed');
             }
             const descriptor = settings.describe({ redactSecrets: true }).find((entry) => entry.ns === 'llm-pi-ai');
             if (descriptor === undefined)
-                throw new Error('DSH 模型适配器未启用，请更新 DSH 后重试');
+                throw new SubscriptionError('settings-unavailable');
             const plugin = grantPayload(currentOwner);
             const explicitModels = explicitRouteModels(descriptor.user, descriptor.base);
             if (!adoptExistingModels && modelIds(plugin.managedModels).length === 0 && explicitModels !== undefined) {
-                throw new Error('现有模型列表由配置管理，请在 ChatGPT 设置页确认同步');
+                throw new SubscriptionError('models-confirmation-required');
             }
             const merged = mergeModelCatalog(explicitModels, plugin.managedModels, discovered, plugin.suppressedModelIds);
             const createdRoute = piRoute(descriptor.value) === null;
@@ -724,23 +504,23 @@ class OpenAISubscriptionController extends TypertRemoteService {
                 : { op: 'set', path: ['providers', 'openai-codex', 'models'], value: merged.models };
             try {
                 if (signal.aborted)
-                    throw new Error('模型同步已取消');
+                    throw new SubscriptionError('cancelled');
                 await settings.mutate('llm-pi-ai', [operation], descriptor.revision);
             }
             catch (error) {
                 if (attempt < 2 && settingsConflict(error))
                     continue;
                 if (settingsConflict(error))
-                    throw new Error('模型设置刚刚发生变化，请重试同步');
-                throw error;
+                    throw new SubscriptionError('settings-conflict');
+                throw new SubscriptionError(failureCode(error, 'settings-write-failed'));
             }
             try {
                 await credentials.modifyRecord(KEY, async (latest) => {
                     if (latest === undefined || latest.kind !== 'grant')
-                        throw new Error('ChatGPT 连接在同步期间被移除');
+                        throw new SubscriptionError('credential-changed');
                     const payload = recordOf(latest.payload) ?? {};
                     if (accountId !== undefined && typeof payload.accountId === 'string' && payload.accountId !== accountId) {
-                        throw new Error('ChatGPT 账号在同步期间发生变化');
+                        throw new SubscriptionError('credential-changed');
                     }
                     return {
                         ...latest,
@@ -758,10 +538,11 @@ class OpenAISubscriptionController extends TypertRemoteService {
                 // Settings already contain the safe complete snapshot. A later sync will
                 // conservatively treat it as local rather than risk overwriting it.
                 console.error('[openai-subscription] remember managed model catalog failed: ' + errorMessage(error));
+                return { synced: true, count: modelIds(merged.models).length, warningCode: 'ownership-save-failed' };
             }
             return { synced: true, count: modelIds(merged.models).length };
         }
-        throw new Error('模型设置刚刚发生变化，请重试同步');
+        throw new SubscriptionError('settings-conflict');
     }
     /** Remove only unchanged dynamic rows, preserving every local model and profile field. */
     async removeManagedPiRoute(managedRoute, managedModels) {
@@ -770,12 +551,12 @@ class OpenAISubscriptionController extends TypertRemoteService {
             return;
         const settings = this.ctx.get('settings');
         if (settings === undefined || typeof settings.mutate !== 'function') {
-            throw new Error('DSH 模型设置服务不可用，尚未断开连接');
+            throw new SubscriptionError('settings-unavailable');
         }
         for (let attempt = 0; attempt < 3; attempt++) {
             const descriptor = settings.describe({ redactSecrets: true }).find((entry) => entry.ns === 'llm-pi-ai');
             if (descriptor === undefined)
-                throw new Error('DSH 模型适配器未启用，尚未断开连接');
+                throw new SubscriptionError('settings-unavailable');
             const route = piRoute(descriptor.user);
             if (route === null)
                 return;
@@ -812,26 +593,33 @@ class OpenAISubscriptionController extends TypertRemoteService {
                 if (attempt < 2 && settingsConflict(error))
                     continue;
                 if (settingsConflict(error))
-                    throw new Error('模型设置持续发生变化，尚未断开连接');
-                throw error;
+                    throw new SubscriptionError('settings-conflict');
+                throw new SubscriptionError(failureCode(error, 'settings-write-failed'));
             }
         }
     }
-    beginLogin(method) {
+    beginLogin(method, observer) {
         this.ensureAuthorizationFlow();
-        if (this.pendingBridge !== null) {
-            if (this.pendingBridge.done)
-                this.pendingBridge = null;
-            else
-                return { started: false, error: '已有一个进行中的授权流程' };
+        if (method !== 'device_code' && method !== 'refresh') {
+            return { started: false, error: '[openai-subscription:invalid-method]', errorCode: 'invalid-method' };
+        }
+        if (this.disconnecting != null || this.syncingModels !== null || (this.pendingBridge !== null && !this.pendingBridge.done)) {
+            return { started: false, error: '[openai-subscription:busy]', errorCode: 'busy' };
         }
+        this.pendingBridge = null;
         const controller = new AbortController();
         const state = { notices: [], done: false, outcome: null, error: null, controller, task: null };
         this.pendingBridge = state;
         const notify = (notice) => {
-            state.notices.push({ kind: notice.kind, message: notice.message, url: notice.url, code: notice.code });
+            state.notices.push({ ...notice });
             if (state.notices.length > 50)
                 state.notices.shift();
+            try {
+                observer?.(notice);
+            }
+            catch (error) {
+                logFailure('notify', error);
+            }
         };
         const control = { signal: controller.signal, aborted: () => controller.signal.aborted };
         const task = (async () => {
@@ -842,24 +630,24 @@ class OpenAISubscriptionController extends TypertRemoteService {
                 else if (method === 'device_code')
                     credential = await this.runDevice(control, notify);
                 else
-                    throw new Error('未知的登录方式：' + method);
-                state.outcome = credential === null ? 'cancelled' : 'authorized';
+                    throw new SubscriptionError('invalid-method');
+                state.outcome = controller.signal.aborted || credential === null ? 'cancelled' : 'authorized';
             }
-            catch {
+            catch (error) {
                 state.outcome = controller.signal.aborted ? 'cancelled' : 'failed';
-                state.error = controller.signal.aborted ? null : '授权失败，请根据提示重试。';
+                if (!controller.signal.aborted) {
+                    state.errorCode = failureCode(error);
+                    state.error = new SubscriptionError(state.errorCode).message;
+                    if (state.errorCode === 'component-unavailable')
+                        this.cachedModule = null;
+                    logFailure('authorize', error);
+                }
             }
             finally {
                 state.done = true;
-                const timer = this.timer();
-                if (timer !== undefined) {
-                    void timer.timeout(30000).then(() => {
-                        if (this.pendingBridge === state)
-                            this.pendingBridge = null;
-                    }).catch(() => {
-                        // Fiber disposal cancels timer promises; the flow is already done.
-                    });
-                }
+                state.completedAt = Date.now();
+                // Device codes are only useful while pending; terminal snapshots keep no code.
+                state.notices = state.notices.filter((notice) => notice.kind !== 'enter-code');
             }
         })();
         state.task = task;
@@ -880,17 +668,25 @@ class OpenAISubscriptionController extends TypertRemoteService {
                     { id: 'refresh', label: '刷新授权' },
                 ],
                 run: async (session) => {
-                    const notify = (notice) => session.notify(notice);
-                    const control = { signal: session.signal, aborted: () => session.signal.aborted };
-                    if (session.method === 'refresh') {
-                        await this.runRefresh(control, notify);
+                    if (session.signal.aborted)
                         return;
+                    const result = this.beginLogin(session.method, (notice) => session.notify(notice));
+                    if (!result.started)
+                        throw new SubscriptionError(result.errorCode);
+                    const state = this.pendingBridge;
+                    const abort = () => state.controller.abort();
+                    session.signal.addEventListener('abort', abort, { once: true });
+                    if (session.signal.aborted)
+                        abort();
+                    // The registered flow and Web settings share the same lock and task.
+                    try {
+                        await state.task;
+                        if (state.outcome === 'failed')
+                            throw new SubscriptionError(state.errorCode ?? 'unknown');
                     }
-                    if (session.method === 'device_code') {
-                        await this.runDevice(control, notify);
-                        return;
+                    finally {
+                        session.signal.removeEventListener('abort', abort);
                     }
-                    throw new Error('未知的登录方式：' + session.method);
                 },
             });
             this.registeredAuthorization = authorization;
@@ -899,24 +695,39 @@ class OpenAISubscriptionController extends TypertRemoteService {
             console.error('[openai-subscription] registerFlow failed: ' + errorMessage(error));
         }
     }
-    shq(value) {
-        return "'" + String(value).replace(/'/g, "'\\''") + "'";
-    }
     async status() {
+        try {
+            return await this.readStatus();
+        }
+        catch (error) {
+            throw new SubscriptionError(failureCode(error, 'credentials-unavailable'));
+        }
+    }
+    async readStatus() {
         this.ensureAuthorizationFlow();
         const modulePath = await this.locateAuthModule();
         const credentials = this.credentials();
+        const unavailableReason = !runtimeSupported() ? 'runtime-unsupported'
+            : credentials === undefined ? 'credentials-unavailable'
+                : this.shell() === undefined ? 'shell-unavailable'
+                    : !modulePath ? 'component-unavailable' : undefined;
+        const base = {
+            configured: false,
+            ready: unavailableReason === undefined,
+            flowPending: this.pendingBridge !== null && !this.pendingBridge.done,
+            ...(unavailableReason ? { unavailableReason } : {}),
+        };
         if (credentials === undefined)
-            return { configured: false, ready: !!modulePath };
+            return base;
         const [record, adapterRecord] = await Promise.all([
             credentials.readRecord(KEY),
             credentials.readRecord(PI_AI_RECORD),
         ]);
         const plugin = grantPayload(record);
         const adapter = grantPayload(adapterRecord);
-        if (recordOf(record)?.kind !== 'grant' || typeof adapter.access !== 'string' || !adapter.access) {
-            return { configured: false, ready: !!modulePath };
-        }
+        base.cleanupAvailable = recordOf(record)?.kind === 'grant';
+        if (!base.cleanupAvailable || plugin.cleanupPending === true || typeof adapter.access !== 'string' || !adapter.access.trim())
+            return base;
         const managedIds = modelIds(plugin.managedModels);
         const suppressed = new Set(Array.isArray(plugin.suppressedModelIds)
             ? plugin.suppressedModelIds.filter((id) => typeof id === 'string')
@@ -933,23 +744,29 @@ class OpenAISubscriptionController extends TypertRemoteService {
         }
         const modelsSynced = managedIds.length > 0 && expectedIds.every((id) => configuredIds.includes(id));
         return {
+            ...base,
             configured: true,
-            ready: !!modulePath,
-            refreshable: typeof adapter.refresh === 'string' && adapter.refresh.length > 0,
+            credentialState: typeof adapter.expires !== 'number' || !Number.isFinite(adapter.expires) || adapter.expires <= 0
+                ? 'unknown' : adapter.expires <= Date.now() ? 'expired' : 'valid',
+            refreshable: typeof adapter.refresh === 'string' && adapter.refresh.trim().length > 0,
             modelsSynced,
             modelCount: modelsSynced ? configuredIds.length : 0,
         };
     }
-    async authorize(method) {
-        return this.beginLogin(typeof method === 'string' ? method : 'device_code');
+    async authorize(method = 'device_code') {
+        return this.beginLogin(typeof method === 'string' ? method : '');
     }
     async poll() {
-        if (this.pendingBridge === null)
-            return { status: 'idle', notices: [] };
         const bridge = this.pendingBridge;
-        const notices = bridge.notices.splice(0);
+        if (bridge?.done && bridge.completedAt !== undefined && Date.now() - bridge.completedAt > 15 * 60 * 1000) {
+            this.pendingBridge = null;
+        }
+        if (this.pendingBridge === null || bridge === null)
+            return { status: 'idle', notices: [] };
+        // Repeatable snapshots let reconnecting pages/tabs recover progress safely.
+        const notices = bridge.notices.map((notice) => ({ ...notice }));
         if (bridge.done)
-            return { status: 'done', notices, outcome: bridge.outcome, error: bridge.error };
+            return { status: 'done', notices, outcome: bridge.outcome, error: bridge.error, ...(bridge.errorCode ? { errorCode: bridge.errorCode } : {}) };
         return { status: 'pending', notices };
     }
     async cancel() {
@@ -964,13 +781,34 @@ class OpenAISubscriptionController extends TypertRemoteService {
         }
         return { ok: true };
     }
-    async syncModels() {
-        // This explicit UI action is the opt-in for treating an existing allow-list
-        // as locally owned additions on top of the live and installed catalogs.
-        return this.synchronizeModels(undefined, true);
+    async syncModels(confirmed = false) {
+        if (this.disconnecting != null || (this.pendingBridge !== null && !this.pendingBridge.done))
+            throw new SubscriptionError('busy');
+        try {
+            return await this.synchronizeModels(undefined, confirmed === true);
+        }
+        catch (error) {
+            throw new SubscriptionError(failureCode(error, 'settings-write-failed'));
+        }
     }
-    /** Cancel active authorization and remove plugin-managed credentials and settings. */
+    /** Serialize disconnect with authorization and sync, including other tabs. */
     async logout() {
+        if (this.disconnecting != null)
+            return this.disconnecting;
+        const pending = this.performLogout().catch((error) => {
+            throw new SubscriptionError(failureCode(error, 'credential-write-failed'));
+        });
+        this.disconnecting = pending;
+        try {
+            return await pending;
+        }
+        finally {
+            if (this.disconnecting === pending)
+                this.disconnecting = null;
+        }
+    }
+    /** Cancel active authorization and remove plugin-managed credentials and settings. */
+    async performLogout() {
         const pending = this.pendingBridge;
         if (pending !== null) {
             pending.controller.abort();
@@ -992,10 +830,10 @@ class OpenAISubscriptionController extends TypertRemoteService {
             await activeSync.catch(() => { });
         const credentials = this.credentials();
         if (credentials === undefined)
-            throw new Error('DSH credential service unavailable');
+            throw new SubscriptionError('credentials-unavailable');
         const record = await credentials.readRecord(KEY);
         if (recordOf(record)?.kind !== 'grant')
-            throw new Error('ChatGPT 连接不属于此插件');
+            throw new SubscriptionError('not-connected');
         const payload = grantPayload(record);
         const managedPiRoute = payload.managedPiRoute === true;
         const managedModels = payload.managedModels;
@@ -1011,16 +849,16 @@ class OpenAISubscriptionController extends TypertRemoteService {
             let staged = false;
             await credentials.modifyRecord(KEY, async (latest) => {
                 if (latest === undefined || latest.kind !== 'grant')
-                    throw new Error('ChatGPT 连接在断开期间发生变化');
+                    throw new SubscriptionError('credential-changed');
                 const latestPayload = grantPayload(latest);
                 if (latestPayload.access !== payload.access || latestPayload.refresh !== payload.refresh) {
-                    throw new Error('ChatGPT 连接在断开期间发生变化');
+                    throw new SubscriptionError('credential-changed');
                 }
                 staged = true;
                 return { kind: 'grant', payload: { provider: 'openai', cleanupPending: true } };
             });
             if (!staged)
-                throw new Error('ChatGPT 连接在断开期间发生变化');
+                throw new SubscriptionError('credential-changed');
         }
         // The adapter credential is the authorization actually used for requests.
         await credentials.deleteRecord(PI_AI_RECORD);