@ai-workbench/connect 0.7.7 → 0.7.11

package/lib/login.d.ts

@@ -6,11 +6,14 @@ export interface ProxyLease {
     closed?: Promise<void>;
     release(): Promise<void>;
 }
-export interface LoginBoot {
-    provider: Provider;
+export type LoginBoot = {
+    provider: 'claude';
     url: string;
-    proxy: Pick<ProxyLease, 'url' | 'username' | 'password'>;
-}
+} | {
+    provider: 'codex';
+    url: string;
+    deviceCode: string;
+};
 export interface RemoteLogin {
     ownership?: Promise<{
         pid: number;
@@ -18,6 +21,7 @@ export interface RemoteLogin {
         provider: string;
     }>;
     url: Promise<Result<string>>;
+    deviceCode?: Promise<Result<string>>;
     completion: Promise<Result<void>>;
     writeCode(code: string): Promise<void>;
     close(): Promise<void>;

package/lib/login.js

@@ -1,11 +1,11 @@
 import { createRequire } from 'node:module';
 const { isClaudeAuthorizeUrl, validateClaudePaste } = createRequire(import.meta.url)('../helper/claude-callback.cjs');
-import { fail, NeedError, need } from "./needs.js";
+import { fail, NeedError } from "./needs.js";
 export function extractLoginUrl(provider, text) {
-    for (const match of text.matchAll(/https:\/\/[^\s<>"']+/g)) {
+    for (const match of text.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').matchAll(/https:\/\/[^\s<>"']+/g)) {
         try {
             const u = new URL(match[0]);
-            if (!u.username && !u.password && u.protocol === 'https:' && ((provider === 'codex' && u.origin === 'https://auth.openai.com' && u.pathname === '/oauth/authorize') || (provider === 'claude' && isClaudeAuthorizeUrl(u))))
+            if (!u.username && !u.password && u.protocol === 'https:' && ((provider === 'codex' && u.href === 'https://auth.openai.com/codex/device') || (provider === 'claude' && isClaudeAuthorizeUrl(u))))
                 return u.href;
         }
         catch { /* not a complete URL yet */ }
@@ -18,8 +18,8 @@ export async function runLogin(t, p, ports, parentSignal) {
     parentSignal.addEventListener('abort', parentAbort, { once: true });
     if (parentSignal.aborted)
         controller.abort();
-    let remote, lease, window, remove = () => { };
-    let result = fail('LOGIN_FAILED'), leaseLost = false, releasing = false;
+    let remote, window, remove = () => { };
+    let result = fail('LOGIN_FAILED');
     try {
         if (signal.aborted)
             return result;
@@ -30,17 +30,19 @@ export async function runLogin(t, p, ports, parentSignal) {
             return url;
         if (typeof url.value !== 'string' || extractLoginUrl(p, url.value) !== url.value)
             return result;
-        lease = await ports.acquireProxy(t, signal);
-        const lost = () => { if (!releasing) {
-            leaseLost = true;
-            controller.abort();
-        } };
-        void lease.closed?.then(lost, lost);
-        if (signal.aborted)
-            throw new NeedError(need(leaseLost ? 'CONNECTION_LOST' : 'LOGIN_FAILED'));
+        let deviceCode;
+        if (p === 'codex') {
+            if (!remote.deviceCode)
+                return result;
+            const device = await Promise.race([remote.deviceCode, cancelled]);
+            if (!device.ok || typeof device.value !== 'string' || !device.value || /[\x00-\x1f\x7f]/.test(device.value))
+                return result;
+            deviceCode = device.value;
+        }
         let codeSent = false, codeError = () => { };
         const failedCode = new Promise(r => codeError = r);
-        window = await ports.open({ provider: p, url: url.value, proxy: { url: lease.url, username: lease.username, password: lease.password } }, async (code) => {
+        const boot = p === 'claude' ? { provider: p, url: url.value } : { provider: p, url: url.value, deviceCode: deviceCode };
+        window = await ports.open(boot, async (code) => {
             if (p !== 'claude' || codeSent || signal.aborted || !validateClaudePaste(url.value, code)) {
                 codeError(fail('LOGIN_FAILED'));
                 return;
@@ -65,17 +67,6 @@ export async function runLogin(t, p, ports, parentSignal) {
         const cleanup = await Promise.allSettled([window?.close(), remote?.close()]);
         if (cleanup.some(r => r.status === 'rejected'))
             result = fail('LOGIN_FAILED');
-        releasing = true;
-        if (lease) {
-            try {
-                await lease.release();
-            }
-            catch (error) {
-                result = error instanceof NeedError ? { ok: false, error: error.need } : fail('LOGIN_FAILED');
-            }
-        }
-        if (leaseLost)
-            result = fail('CONNECTION_LOST');
     }
     return result;
 }

package/lib/needs.js

@@ -1,4 +1,12 @@
 const entries = {
+    REMOTE_DETAIL_INVALID: { layer: 'integration', message: '诊断内容格式无效或含未脱敏认证材料，已拒绝保存。', requires: '有效且已脱敏的诊断与可信连接', actor: 'plugin', action: { id: 'inspect-remote-details', label: '查看技术详情', available: false } },
+    REMOTE_DETAIL_SCOPE_INVALID: { layer: 'integration', message: '诊断内容与当前连接、原生会话或已核验品牌关联不符，已拒绝保存。', requires: '有效且已脱敏的诊断与可信连接', actor: 'plugin', action: { id: 'inspect-remote-details', label: '查看技术详情', available: false } },
+    REMOTE_DETAIL_STORAGE_FAILED: { layer: 'integration', message: '诊断记录无法持久保存或读取，结果无法确认，请联系管理员。', requires: '有效且已脱敏的诊断与可信连接', actor: 'plugin', action: { id: 'inspect-remote-details', label: '查看技术详情', available: false } },
+    REMOTE_DETAIL_TOO_LARGE: { layer: 'integration', message: '诊断事件超过 conversationDetails.maxEventBytes，已拒绝保存，未裁剪。', requires: '有效且已脱敏的诊断与可信连接', actor: 'plugin', action: { id: 'inspect-remote-details', label: '查看技术详情', available: false } },
+    REMOTE_DETAIL_SEQUENCE_INVALID: { layer: 'integration', message: '诊断事件序号没有严格递增，已拒绝保存。', requires: '有效且已脱敏的诊断与可信连接', actor: 'plugin', action: { id: 'inspect-remote-details', label: '查看技术详情', available: false } },
+    REMOTE_DETAIL_CONFLICT: { layer: 'integration', message: '此诊断事件编号已有不同内容，已拒绝保存。', requires: '有效且已脱敏的诊断与可信连接', actor: 'plugin', action: { id: 'inspect-remote-details', label: '查看技术详情', available: false } },
+    REMOTE_DETAIL_CURSOR_INVALID: { layer: 'integration', message: '详情分页位置与当前主机用户、会话、品牌或快照不符，请刷新详情。', requires: '有效且已脱敏的诊断与可信连接', actor: 'plugin', action: { id: 'inspect-remote-details', label: '查看技术详情', available: false } },
+    MODEL_CATALOG_CONTEXT_INVALID: { layer: 'integration', message: '模型目录查询的品牌无效。', requires: '有效且已脱敏的诊断与可信连接', actor: 'plugin', action: { id: 'inspect-remote-details', label: '查看技术详情', available: false } },
     ACTIVATION_CONFLICT: { layer: 'network', message: '已有另一项开通正在进行，已停止重复开通，请联系管理员。', requires: '唯一的开通请求', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
     ACTIVATION_CANCELLED: { layer: 'network', message: '本次网络开通已取消。', requires: '完成明确的开通操作', actor: 'plugin', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
     ENROLLMENT_CLEANUP_UNBOUND: { layer: 'network', message: '连接资料与已保存的入网身份不匹配，已停止清理，请联系管理员。', requires: '匹配的入网身份与原始连接资料', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },

package/lib/processes.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { StringDecoder } from 'node:string_decoder';
 import { extractLoginUrl } from "./login.js";
 import { fail, ok } from "./needs.js";
+import { AuthDiagnosticError, exceptionSummary, outputSummary } from "./auth-diagnostics.js";
 function limit(n) { if (!Number.isSafeInteger(n) || n < 1)
     throw new Error('OUTPUT_SETTING_REQUIRED'); }
 function start(command, args, signal) {
@@ -18,15 +19,15 @@ export function createRunner(maxBytes) {
     limit(maxBytes);
     return { run: async (command, args, signal, input) => {
             const child = start(command, args, signal);
-            let stdout = '', stderr = '', size = 0, failed = false;
-            child.stdin.on('error', () => { failed = true; child.kill('SIGTERM'); });
+            let stdout = '', stderr = '', size = 0, failure;
+            child.stdin.on('error', error => { failure ??= { stage: 'process-stdin', reason: 'STDIN_FAILED', ...exceptionSummary(error) }; child.kill('SIGTERM'); });
             child.stdin.end(input);
             const finished = new Promise((resolve, reject) => {
-                child.once('error', () => { failed = true; });
+                child.once('error', error => { failure = { stage: 'process-spawn', reason: 'SPAWN_FAILED', ...exceptionSummary(error) }; });
                 for (const [stream, channel] of [[child.stdout, 'out'], [child.stderr, 'err']]) {
                     const decoder = new StringDecoder('utf8');
                     stream.on('data', (chunk) => { size += chunk.length; if (size > maxBytes) {
-                        failed = true;
+                        failure ??= { stage: 'process-output', reason: 'OUTPUT_LIMIT_EXCEEDED', maxOutputBytes: maxBytes, observedBytes: size };
                         child.kill('SIGTERM');
                         return;
                     } if (channel === 'out')
@@ -34,7 +35,7 @@ export function createRunner(maxBytes) {
                     else
                         stderr += decoder.write(chunk); });
                 }
-                child.once('close', code => failed || signal.aborted ? reject(new Error('COMMAND_FAILED')) : resolve({ exitCode: code, stdout, stderr }));
+                child.once('close', (code, processSignal) => failure || signal.aborted || processSignal !== null ? reject(new AuthDiagnosticError(failure ?? { stage: 'process-runner', reason: signal.aborted ? 'CANCELLED' : 'PROCESS_SIGNAL', exitCode: code, signal: ['SIGTERM', 'SIGKILL', 'SIGABRT', 'SIGHUP', 'SIGINT', 'SIGSEGV'].includes(processSignal ?? '') ? processSignal : 'OTHER', stderr: outputSummary(stderr) }, 'COMMAND_FAILED')) : resolve({ exitCode: code, stdout, stderr }));
             });
             const abort = () => child.kill('SIGTERM');
             signal.addEventListener('abort', abort, { once: true });
@@ -58,6 +59,29 @@ export async function createRemoteLogin(command, args, provider, maxBytes, signa
     void ownership.catch(() => { });
     let found = () => { };
     const url = new Promise(r => found = r);
+    let foundCode = () => { }, deviceUrlSeen = false, awaitingCode = false, deviceSent = false;
+    const deviceCode = new Promise(r => foundCode = r);
+    const observeDevice = (line, stdout) => {
+        if (provider !== 'codex' || !stdout || deviceSent)
+            return;
+        const text = line.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').trim();
+        if (!deviceUrlSeen) {
+            if (extractLoginUrl('codex', text) === text)
+                deviceUrlSeen = true;
+            return;
+        }
+        if (text === '2. Enter this one-time code (expires in 15 minutes)') {
+            awaitingCode = true;
+            return;
+        }
+        if (awaitingCode && text) {
+            awaitingCode = false;
+            if (!/[\x00-\x1f\x7f]/.test(text) && !text.startsWith('AW_LOGIN_')) {
+                deviceSent = true;
+                foundCode(ok(text));
+            }
+        }
+    };
     const pending = new Map();
     for (const stream of [child.stdout, child.stderr]) {
         const record = { decoder: new StringDecoder('utf8'), line: '' };
@@ -73,6 +97,7 @@ export async function createRemoteLogin(command, args, provider, maxBytes, signa
             const lines = record.line.split(/\r?\n/);
             record.line = lines.pop();
             for (const line of lines) {
+                observeDevice(line, stream === child.stdout);
                 if (protocol && line.startsWith('AW_LOGIN_PROCESS ')) {
                     try {
                         const v = JSON.parse(line.slice(17));
@@ -123,6 +148,8 @@ export async function createRemoteLogin(command, args, provider, maxBytes, signa
         ownReject();
         if (!urlSent)
             found(fail('LOGIN_FAILED'));
+        if (!deviceSent)
+            foundCode(fail('LOGIN_FAILED'));
         signal.removeEventListener('abort', abort);
         resolve(!invalid && !signal.aborted && code === 0 && (!protocol || (owned && terminal?.exitCode === 0 && !terminal.stopping)) ? ok(undefined) : fail('LOGIN_FAILED'));
     }));
@@ -131,9 +158,9 @@ export async function createRemoteLogin(command, args, provider, maxBytes, signa
     if (signal.aborted)
         abort();
     child.stdin.on('error', () => { invalid = true; });
-    return { url, completion, ...(protocol ? { ownership } : {}),
+    return { url, completion, ...(provider === 'codex' ? { deviceCode } : {}), ...(protocol ? { ownership } : {}),
         writeCode: async (code) => {
-            if (signal.aborted || child.exitCode !== null || child.signalCode !== null || child.stdin.writableEnded || /[\x00-\x20\x7f]/.test(code) || !code)
+            if (provider !== 'claude' || signal.aborted || child.exitCode !== null || child.signalCode !== null || child.stdin.writableEnded || /[\x00-\x20\x7f]/.test(code) || !code)
                 throw new Error('LOGIN_CODE_REJECTED');
             await new Promise((yes, no) => { const failed = () => no(new Error('LOGIN_STDIN_FAILED')); child.stdin.once('error', failed); const done = () => { child.stdin.removeListener('error', failed); yes(); }; if (protocol)
                 child.stdin.write(JSON.stringify({ type: 'code', value: code }) + '\n', done);

package/lib/profile-runtime.js

@@ -3,7 +3,11 @@ import { createProfileEnrollment } from "./profile-enrollment.js";
 import { createWorkspaceBindings } from "./workspace-bindings.js";
 import { NeedError, need, fail } from "./needs.js";
 import { createNativeImportPicker } from "./native-import-picker.js";
-import { L_DEFAULTS } from "./defaults.js";
+import { createHash } from 'node:crypto';
+import { readPrivate } from "./private-files.js";
+import { createConversationDetails } from "./conversation-details.js";
+import { createLoginDiagnostics } from "./login-diagnostics.js";
+import { CONVERSATION_DETAIL_DEFAULTS, L_DEFAULTS } from "./defaults.js";
 import { createProfileActivation } from "./profile-activation.js";
 // Composition only: consume official services; never provide replacements or alter default entries.
 export function attachProfileRuntime(ctx, api, ports, config, network) {
@@ -26,17 +30,53 @@ export function attachProfileRuntime(ctx, api, ports, config, network) {
     ctx.provide('aiWorkbenchWorkspaceDiagnostics', { getLatest: () => lastWorkspaceError });
     ctx.inject(['workspaceRegistry', 'sessions', 'sessionPersistence'], native => {
         const registry = native.get('workspaceRegistry');
+        const readHeader = async (id) => {
+            const live = native.get('sessions');
+            const session = live?.get(id);
+            if (session)
+                return session.header;
+            const persistence = native.get('sessionPersistence');
+            if (!persistence)
+                throw new NeedError(need('DEPENDENCY_REQUIRED'));
+            return (await persistence.list()).find(s => s.header.id === id)?.header;
+        };
         const bindings = createWorkspaceBindings({ profileDir: profile.dir, metadataMaxBytes: config.enrollmentMetadataMaxBytes ?? L_DEFAULTS.enrollmentMetadataMaxBytes, api, registry,
-            readHeader: async (id) => {
-                const live = native.get('sessions');
-                const session = live?.get(id);
-                if (session)
-                    return session.header;
-                const persistence = native.get('sessionPersistence');
-                if (!persistence)
-                    throw new NeedError(need('DEPENDENCY_REQUIRED'));
-                return (await persistence.list()).find(s => s.header.id === id)?.header;
-            }, nextRevision: () => ++workspaceRevision, onState: state => ctx.emit('ai-workbench/workspace-binding-state', state), diagnostic: error => { lastWorkspaceError = error; ctx.emit('ai-workbench/workspace-diagnostic', error); } });
+            readHeader, nextRevision: () => ++workspaceRevision, onState: state => ctx.emit('ai-workbench/workspace-binding-state', state), diagnostic: error => { lastWorkspaceError = error; ctx.emit('ai-workbench/workspace-diagnostic', error); } });
+        const settings = ctx.get('aiWorkbenchConversationDetailSettings');
+        const context = async () => { const current = api.getModelCatalogTarget('codex'); if (!current.ok)
+            return current; const t = current.value.target; try {
+            const trust = await readPrivate(t.knownHostsFile, config.enrollmentMetadataMaxBytes ?? L_DEFAULTS.enrollmentMetadataMaxBytes);
+            return { ok: true, value: { identity: createHash('sha256').update(JSON.stringify([t.host, t.username, t.port, trust])).digest('hex') } };
+        }
+        catch {
+            return fail('REMOTE_DETAIL_SCOPE_INVALID');
+        } };
+        const details = createConversationDetails({ profileDir: profile.dir, get maxEventBytes() { return settings ? settings.values()?.maxEventBytes ?? 0 : config.conversationDetails?.maxEventBytes ?? CONVERSATION_DETAIL_DEFAULTS.maxEventBytes; }, get pageSize() { return settings ? settings.values()?.pageSize ?? 0 : config.conversationDetails?.pageSize ?? CONVERSATION_DETAIL_DEFAULTS.pageSize; }, getConnectionState: api.getConnectionState,
+            context,
+            scope: async (sessionId, provider) => { const current = api.getModelCatalogTarget(provider); if (!current.ok)
+                return current; return bindings.verifyRemoteConversationScope(sessionId, provider, current.value.target); },
+            onState: state => ctx.emit('ai-workbench/remote-conversation-detail-state', state) });
+        api.appendRemoteConversationDetail = details.appendRemoteConversationDetail;
+        api.getRemoteConversationDetailReceipt = details.getRemoteConversationDetailReceipt;
+        api.getRemoteConversationDetailState = details.getRemoteConversationDetailState;
+        api.onRemoteConversationDetailState = details.onRemoteConversationDetailState;
+        api.listRemoteConversationDetails = details.listRemoteConversationDetails;
+        const loginDiagnostics = createLoginDiagnostics({ profileDir: profile.dir, get maxEventBytes() { return settings ? settings.values()?.maxEventBytes ?? 0 : config.conversationDetails?.maxEventBytes ?? CONVERSATION_DETAIL_DEFAULTS.maxEventBytes; }, get pageSize() { return settings ? settings.values()?.pageSize ?? 0 : config.conversationDetails?.pageSize ?? CONVERSATION_DETAIL_DEFAULTS.pageSize; }, getConnectionState: api.getConnectionState, context,
+            scope: async (sessionId, provider) => { const current = api.getModelCatalogTarget(provider); if (!current.ok)
+                return current; const header = await readHeader(sessionId); if (!header || header.id !== sessionId)
+                return fail('REMOTE_DETAIL_SCOPE_INVALID'); return context(); },
+            onState: state => ctx.emit('ai-workbench/login-diagnostic-state', state) });
+        api.appendLoginDiagnostic = loginDiagnostics.appendLoginDiagnostic;
+        api.getLoginDiagnosticReceipt = loginDiagnostics.getLoginDiagnosticReceipt;
+        api.listLoginDiagnostics = loginDiagnostics.listLoginDiagnostics;
+        api.getLoginDiagnosticState = loginDiagnostics.getLoginDiagnosticState;
+        api.onLoginDiagnosticState = loginDiagnostics.onLoginDiagnosticState;
+        const previousContractInfo = api.getContractInfo, detailContractInfo = () => ({ ...previousContractInfo(), remoteConversationDetails: 1, loginDiagnostics: 1 });
+        api.getContractInfo = detailContractInfo;
+        native.effect(() => { details.observeConnection(api.getConnectionState()); return api.onConnectionState(details.observeConnection); });
+        native.effect(() => { loginDiagnostics.observeConnection(api.getConnectionState()); return api.onConnectionState(loginDiagnostics.observeConnection); });
+        native.effect(() => () => { if (api.getContractInfo === detailContractInfo)
+            api.getContractInfo = previousContractInfo; return Promise.all([details.dispose(), loginDiagnostics.dispose()]); });
         native.effect(() => api.onConnectionState(bindings.observeConnection));
         api.getWorkspaceBindingState = bindings.getWorkspaceBindingState;
         api.onWorkspaceBindingState = bindings.onWorkspaceBindingState;

package/lib/profile-settings.js

@@ -1,13 +1,13 @@
 import { isAbsolute, join } from 'node:path';
 import { COMPONENT_SOURCES, preset } from "./component-source.js";
-import { L_DEFAULTS, ELECTRON_PIN } from "./defaults.js";
+import { L_DEFAULTS, ELECTRON_PIN, CONVERSATION_DETAIL_DEFAULTS } from "./defaults.js";
 // Owner approved technical values, 2026-10-20 settings decision, part two.
-// 组件直接来自自己的官方地址；OAuth网页仍通过N主机出口。
+// 组件直接下载；Claude网页遵循员工系统网络，Codex暂保留N主机代理。
 export function profileSettings(config, profileDir, platform = process.platform, arch = process.arch) {
     if (typeof profileDir !== 'string' || !isAbsolute(profileDir))
         return config;
     const runtime = platform === 'darwin' && arch === 'arm64' ? { ...ELECTRON_PIN, source: COMPONENT_SOURCES.npmmirror.source } : {};
     const chosen = config.helper?.componentDownloadSource;
     const selected = chosen === undefined ? {} : { source: preset(chosen) ? COMPONENT_SOURCES[chosen].source : '' };
-    return { ...config, commandOutputMaxBytes: config.commandOutputMaxBytes === undefined ? L_DEFAULTS.commandOutputMaxBytes : config.commandOutputMaxBytes, helper: { ...runtime, componentDownloadMaxRedirects: L_DEFAULTS.componentDownloadMaxRedirects, componentObservationIntervalMs: L_DEFAULTS.componentObservationIntervalMs, maxDownloadBytes: L_DEFAULTS.maxDownloadBytes, maxExtractedBytes: L_DEFAULTS.maxExtractedBytes, loginOutputMaxBytes: L_DEFAULTS.loginOutputMaxBytes, ipcMaxBytes: L_DEFAULTS.ipcMaxBytes, remoteKillGraceMs: L_DEFAULTS.remoteKillGraceMs, ...config.helper, ...selected, cacheDir: config.helper?.cacheDir === undefined ? join(profileDir, 'ai-workbench-connect', 'login-component-cache') : config.helper.cacheDir } };
+    return { ...config, conversationDetails: { ...CONVERSATION_DETAIL_DEFAULTS, ...config.conversationDetails }, commandOutputMaxBytes: config.commandOutputMaxBytes === undefined ? L_DEFAULTS.commandOutputMaxBytes : config.commandOutputMaxBytes, helper: { ...runtime, componentDownloadMaxRedirects: L_DEFAULTS.componentDownloadMaxRedirects, componentObservationIntervalMs: L_DEFAULTS.componentObservationIntervalMs, maxDownloadBytes: L_DEFAULTS.maxDownloadBytes, maxExtractedBytes: L_DEFAULTS.maxExtractedBytes, loginOutputMaxBytes: L_DEFAULTS.loginOutputMaxBytes, ipcMaxBytes: L_DEFAULTS.ipcMaxBytes, remoteKillGraceMs: L_DEFAULTS.remoteKillGraceMs, ...config.helper, ...selected, cacheDir: config.helper?.cacheDir === undefined ? join(profileDir, 'ai-workbench-connect', 'login-component-cache') : config.helper.cacheDir } };
 }

package/lib/ssh.js

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { fail, ok } from "./needs.js";
+import { AuthDiagnosticError, authFailure, outputSummary } from "./auth-diagnostics.js";
 export function shellQuote(s) {
     if (/[\x00-\x1f\x7f%]/.test(s))
         throw new Error('INVALID_PROXY_PATH');
@@ -18,28 +19,46 @@ export async function runRemote(runner, t, command, signal, input) {
     const nonce = randomUUID(), source = await readFile(new URL('../helper/remote-command.cjs', import.meta.url), 'utf8');
     const remote = 'node -e ' + "'" + source.replaceAll("'", "'\\''") + "'";
     const raw = await runner.run('ssh', [...sshArgs(t), remote], signal, JSON.stringify({ protocolVersion: 1, nonce, command, ...input === undefined ? {} : { input } }));
-    if (signal.aborted || raw.exitCode !== 0 || raw.stderr !== '')
-        throw Error('REMOTE_RESULT_INVALID');
+    const bad = (stage, reason, details = {}) => { throw new AuthDiagnosticError({ stage, reason, ...details }); };
+    if (signal.aborted)
+        bad('ssh-result', 'CANCELLED');
+    if (raw.exitCode !== 0 || raw.stderr !== '')
+        bad('ssh-result', raw.exitCode !== 0 ? 'SSH_EXIT_NONZERO' : 'SSH_STDERR_NONEMPTY', { exitCode: raw.exitCode, stderr: outputSummary(raw.stderr) });
     const lines = raw.stdout.split('\n');
     if (lines.pop() !== '')
-        throw Error('REMOTE_RESULT_INVALID');
+        bad('remote-frame', 'FRAME_TRUNCATED');
     let started = false, ended = false, exitCode = null;
     const out = [], err = [];
-    for (const line of lines) {
-        const v = JSON.parse(line);
-        if (!v || typeof v !== 'object' || v.protocolVersion !== 1 || v.nonce !== nonce || ended)
-            throw Error('REMOTE_RESULT_INVALID');
+    for (const [index, line] of lines.entries()) {
+        let v;
+        try {
+            v = JSON.parse(line);
+        }
+        catch {
+            bad('remote-frame', 'FRAME_JSON_INVALID', { index, errorName: 'SyntaxError', output: outputSummary(line) });
+        }
+        if (!v || typeof v !== 'object' || Array.isArray(v))
+            bad('remote-frame', 'FRAME_OBJECT_INVALID', { index });
+        if (v.protocolVersion !== 1)
+            bad('remote-frame', 'FRAME_VERSION_INVALID', { index });
+        if (v.nonce !== nonce)
+            bad('remote-frame', 'FRAME_NONCE_INVALID', { index });
+        if (ended)
+            bad('remote-frame', 'FRAME_AFTER_END', { index });
         const keys = Object.keys(v).sort().join(',');
         if (v.type === 'start' && !started && keys === 'nonce,protocolVersion,type') {
             started = true;
             continue;
         }
+        const expected = v.type === 'start' ? 'nonce,protocolVersion,type' : v.type === 'end' ? 'exitCode,nonce,protocolVersion,signal,type' : v.type === 'stdout' || v.type === 'stderr' ? 'data,nonce,protocolVersion,type' : undefined;
+        if (expected && keys !== expected)
+            bad('remote-frame', 'FRAME_KEYS_INVALID', { index, missing: expected.split(',').filter(key => !Object.hasOwn(v, key)), unexpectedCount: Object.keys(v).filter(key => !expected.split(',').includes(key)).length });
         if (!started)
-            throw Error('REMOTE_RESULT_INVALID');
+            bad('remote-frame', 'FRAME_START_MISSING', { index });
         if ((v.type === 'stdout' || v.type === 'stderr') && keys === 'data,nonce,protocolVersion,type' && typeof v.data === 'string') {
             const bytes = Buffer.from(v.data, 'base64');
             if (bytes.toString('base64') !== v.data)
-                throw Error('REMOTE_RESULT_INVALID');
+                bad('remote-frame', 'FRAME_BASE64_INVALID', { index });
             (v.type === 'stdout' ? out : err).push(bytes);
             continue;
         }
@@ -48,10 +67,14 @@ export async function runRemote(runner, t, command, signal, input) {
             exitCode = v.exitCode;
             continue;
         }
-        throw Error('REMOTE_RESULT_INVALID');
+        if (v.type === 'end' && v.signal !== null)
+            bad('remote-frame', 'REMOTE_COMMAND_SIGNAL', { index, signal: ['SIGTERM', 'SIGKILL', 'SIGABRT', 'SIGHUP', 'SIGINT', 'SIGSEGV'].includes(v.signal) ? v.signal : 'OTHER' });
+        if (v.type === 'end')
+            bad('remote-frame', 'FRAME_END_EXIT_INVALID', { index, exitCodeType: typeof v.exitCode, ...(typeof v.exitCode === 'number' && Number.isFinite(v.exitCode) && Number.isInteger(v.exitCode) ? { exitCode: v.exitCode } : {}) });
+        bad('remote-frame', 'FRAME_SEQUENCE_OR_VALUE_INVALID', { index });
     }
     if (!ended || exitCode === null)
-        throw Error('REMOTE_RESULT_INVALID');
+        bad('remote-frame', 'FRAME_END_MISSING');
     return { exitCode, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8') };
 }
 export function createSsh(runner, maxOutputBytes) {
@@ -66,12 +89,12 @@ export function createSsh(runner, maxOutputBytes) {
         status: async (t, p, signal) => {
             try {
                 if (!['codex', 'claude'].includes(p) || !Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1)
-                    return fail('AUTH_STATUS_INVALID');
+                    return authFailure('ssh-status', 'STATUS_ARGUMENT_INVALID');
                 const source = await readFile(new URL('../helper/auth-status.cjs', import.meta.url), 'utf8');
                 return ok(await runRemote(runner, t, 'node -e ' + "'" + source.replaceAll("'", "'\\''") + "' -- " + p + ' ' + maxOutputBytes, signal));
             }
-            catch {
-                return fail('AUTH_STATUS_INVALID');
+            catch (error) {
+                return authFailure('ssh-status', 'STATUS_EXECUTION_FAILED', {}, error);
             }
         },
     };

package/lib/startup.d.ts

@@ -1,10 +1,31 @@
-import type { ConnectApi, ConnectionState, LoginPromptState, LoginPromptResult, Provider, NeedCode, Result } from './api.ts';
+import type { ConnectApi, ConnectionState, LoginPromptState, LoginPromptResult, LoginState, Provider, NeedCode, Result } from './api.ts';
 export type StartupState = LoginPromptState;
 export declare function employeeMessage(code?: NeedCode): string;
 type Operations = Pick<ConnectApi, 'connect' | 'checkLogin' | 'login' | 'getState'>;
 export declare function createStartup(api: Operations, providers: Provider[], emit?: (s: LoginPromptState) => void, result?: (r: LoginPromptResult) => void, instanceId?: string): {
     getState: () => LoginPromptState;
     check: () => Promise<void>;
+    beginCheck: (provider: Provider) => {
+        provider: Provider;
+        generation: number;
+        serial: number;
+    };
+    finishCheck: (ticket: ReturnType<(provider: Provider) => {
+        provider: Provider;
+        generation: number;
+        serial: number;
+    }>, status: Result<LoginState>) => boolean;
+    currentTicket: (ticket: ReturnType<(provider: Provider) => {
+        provider: Provider;
+        generation: number;
+        serial: number;
+    }>) => boolean;
+    captureCheck: (provider: Provider) => {
+        provider: Provider;
+        generation: number;
+        serial: number;
+    };
+    inheritCheck(source: Result<LoginState>, derived: Result<LoginState>): void;
     subscribe(listener: (s: LoginPromptState) => void): () => void;
     request(provider: Provider, intent: "automatic" | "user"): Promise<Result<LoginPromptState>>;
     respond: (requestId: string, action: "authorize" | "defer") => Promise<Result<LoginPromptState>>;