@ai-workbench/remote-agent 0.8.0 → 0.8.2

package/dist/provider.js

@@ -1,3 +1,4 @@
+import { loginDiagnostic, loginReason } from "./login-diagnostic.js";
 import { NeedError } from "./remote.js";
 import { CONNECTION_REQUIRED, TEST_HOST_NOTICE } from "./presentation.js";
 import { CODEX_AGENT } from "./agents.js";
@@ -8,6 +9,8 @@ export function requireLoginCoordinator(api) {
 export function requireLoginState(state) {
     const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
     const need = (v) => object(v) && typeof v.code === 'string' && v.code.length > 0 && ['enrollment', 'network', 'ssh', 'auth', 'integration', 'settings', 'projects'].includes(v.layer) && typeof v.message === 'string' && typeof v.requires === 'string' && ['employee', 'administrator', 'ai-administrator', 'plugin'].includes(v.actor) && object(v.action) && typeof v.action.id === 'string' && typeof v.action.label === 'string' && typeof v.action.available === 'boolean';
+    if (state.queuedProviders !== undefined && (!Array.isArray(state.queuedProviders) || state.queuedProviders.some(p => p !== 'codex' && p !== 'claude') || new Set(state.queuedProviders).size !== state.queuedProviders.length || state.queuedProviders.some(p => state.checkingProviders?.includes(p))))
+        throw new NeedError('CONNECT_API_MISMATCH', '我需要真实的品牌排队与进行中状态', 'L >=0.7.10');
     if (!Array.isArray(state.checkingProviders) || state.checkingProviders.some(p => p !== 'codex' && p !== 'claude') || !object(state.providerNeeds) || Object.entries(state.providerNeeds).some(([p, v]) => !['codex', 'claude'].includes(p) || !need(v)))
         throw new NeedError('CONNECT_API_MISMATCH', '我需要按助手区分的真实登录状态', 'L >=0.6.1');
 }
@@ -32,15 +35,77 @@ function verifiedLogin(api, brand, expected) {
     if (!connection.instanceId || !Number.isSafeInteger(connection.epoch) || connection.epoch < 0 || connection.phase !== 'connected' || expected && (connection.instanceId !== expected.instanceId || connection.epoch !== expected.epoch))
         throw new NeedError('CONNECTION_LOST', 'connection binding changed', 'current employee connection');
     requireLoginState(login);
-    if (login.instanceId !== connection.instanceId || login.checkingProviders.includes(brand) || login.providerNeeds[brand] || login.phase === 'blocked' || login.phase === 'disposed' || login.phase === 'authorizing' && login.provider === brand || typeof login.logins?.[brand] !== 'boolean')
-        throw new NeedError('AUTH_STATUS_INVALID', '无法确认当前品牌的登录状态', 'L核验的本品牌登录状态');
-    if (!login.logins[brand])
-        throw new NeedError('LOGIN_REQUIRED', '需要登录，请到设置 → 远程主机连接 点登录', '本人登录');
+    const reason = loginReason(login, connection, brand);
+    if (reason)
+        throw Object.assign(new NeedError(reason === 'LOGIN_REQUIRED' ? 'LOGIN_REQUIRED' : 'AUTH_STATUS_INVALID', reason === 'LOGIN_REQUIRED' ? '需要登录，请到设置 → 远程主机连接 点登录' : '无法确认当前品牌的登录状态', 'L核验的本品牌登录状态'), { technical: loginDiagnostic('verified-login', reason, brand, connection, login), ...(typeof login.providerNeeds[brand]?.officialReason === 'string' ? { officialReason: login.providerNeeds[brand].officialReason } : {}) });
     return { ...connection };
 }
+/** Wait only for L's explicit in-progress evidence. No timer, polling, refresh or authorization. */
+async function waitForLogin(api, brand, expected, get, signal) {
+    const check = () => {
+        signal?.throwIfAborted();
+        if (get() !== api)
+            throw new NeedError('CONNECTION_LOST', '远程主机连接组件已更换', '当前员工连接');
+        const connection = api.getConnectionState(), state = api.getLoginPromptState();
+        requireLoginState(state);
+        if (connection.phase !== 'connected' || connection.instanceId !== expected.instanceId || connection.epoch !== expected.epoch)
+            return verifiedLogin(api, brand, expected);
+        const pending = state.instanceId === connection.instanceId && state.phase !== 'blocked' && state.phase !== 'disposed' && (state.queuedProviders?.includes(brand) || state.checkingProviders.includes(brand) || state.phase === 'authorizing' && state.provider === brand);
+        return pending ? undefined : verifiedLogin(api, brand, expected);
+    };
+    const ready = check();
+    if (ready)
+        return ready;
+    if (typeof api.onLoginPromptState !== 'function' || typeof api.onConnectionState !== 'function')
+        throw new NeedError('CONNECT_API_MISMATCH', '我需要登录检查状态订阅能力', 'L onLoginPromptState / onConnectionState');
+    return new Promise((resolve, reject) => {
+        let ended = false;
+        const disposers = [];
+        const clear = () => { ended = true; signal?.removeEventListener('abort', abort); for (const off of disposers)
+            off(); };
+        const changed = () => { if (ended)
+            return; try {
+            const value = check();
+            if (value) {
+                clear();
+                resolve(value);
+            }
+        }
+        catch (error) {
+            clear();
+            reject(error);
+        } };
+        const abort = () => { if (ended)
+            return; clear(); reject(new NeedError('ABORTED', 'consumer wait cancelled', 'employee action')); };
+        const register = (off) => { if (ended)
+            off();
+        else
+            disposers.push(off); };
+        signal?.addEventListener('abort', abort, { once: true });
+        try {
+            if (signal?.aborted)
+                abort();
+            if (!ended)
+                register(api.onLoginPromptState(changed));
+            if (!ended)
+                register(api.onConnectionState(changed));
+            changed();
+        }
+        catch (error) {
+            clear();
+            reject(error);
+        }
+    });
+}
+async function ensureReady(api, brand, signal) {
+    const result = await awaitL(() => api.ensureReady(brand), signal);
+    if (!result.ok)
+        throw Object.assign(new NeedError(result.error.code, result.error.message, result.error.requires), { technical: loginDiagnostic('ensure-ready', 'L_ENSURE_READY_FAILED', brand, api.getConnectionState(), api.getLoginPromptState(), result.error.officialReason), ...(typeof result.error.officialReason === 'string' ? { officialReason: result.error.officialReason } : {}) });
+    return result.value;
+}
 export function unwrap(result) {
     if (!result.ok)
-        throw new NeedError(result.error.code, result.error.message, result.error.requires);
+        throw Object.assign(new NeedError(result.error.code, result.error.message, result.error.requires), typeof result.error.officialReason === 'string' ? { officialReason: result.error.officialReason } : {});
     return result.value;
 }
 export function validateTarget(t) {
@@ -76,12 +141,12 @@ export async function offerLogin(connect, request, currentApi, agent = CODEX_AGE
     requireNativeWorkspace(connect);
     request.signal?.throwIfAborted();
     const before = connect.getConnectionState();
-    const target = unwrap(await awaitL(() => connect.ensureReady(agent.loginProvider), request.signal));
+    const target = await ensureReady(connect, agent.loginProvider, request.signal);
     validateTarget(target);
     request.signal?.throwIfAborted();
     if (currentApi && currentApi() !== connect)
         throw new NeedError('CONNECTION_LOST', '远程主机连接组件已更换', '当前员工连接');
-    verifiedLogin(connect, agent.loginProvider, before);
+    await waitForLogin(connect, agent.loginProvider, before, currentApi ?? (() => connect), request.signal);
 }
 export function sameTarget(a, b) {
     return identity(a) === identity(b) && a.projectRoot === b.projectRoot && a.knownHostsFile === b.knownHostsFile && a.proxyCommand === b.proxyCommand && a.session.command === b.session.command && a.session.root === b.session.root && a.session.settingsPath === b.session.settingsPath;
@@ -99,12 +164,12 @@ export function connectProvider(get, options = {}) {
         if (request.mode === 'one-shot' && !agent.oneShot)
             throw new NeedError('MODE_UNSUPPORTED', '此远程模型仅支持会话模式', '使用会话模式');
         const before = api.getConnectionState();
-        const target = unwrap(await awaitL(() => api.ensureReady(agent.loginProvider), request.signal));
+        const target = await ensureReady(api, agent.loginProvider, request.signal);
         validateTarget(target);
         request.signal?.throwIfAborted();
         if (get() !== api)
             throw new NeedError('CONNECTION_LOST', '远程主机连接组件已更换', '当前员工连接');
-        const connection = verifiedLogin(api, agent.loginProvider, before);
+        const connection = await waitForLogin(api, agent.loginProvider, before, get, request.signal);
         if (request.identity && request.identity !== identity(target))
             throw new NeedError('SESSION_CONTEXT_MISMATCH', '员工主机与原会话不一致，请新建会话', '原员工主机');
         admissions.set(request, { api, target, connection });
@@ -115,15 +180,14 @@ export function connectProvider(get, options = {}) {
         const admitted = admissions.get(request);
         admissions.delete(request);
         const { api, target, connection } = admitted;
-        const stable = () => { request.signal?.throwIfAborted(); if (get() !== api)
-            throw new NeedError('CONNECTION_LOST', '远程主机连接组件已更换', '当前员工连接'); verifiedLogin(api, agent.loginProvider, connection); };
-        stable();
+        const stable = () => waitForLogin(api, agent.loginProvider, connection, get, request.signal);
+        await stable();
         if (!request.sessionId)
             throw new NeedError('PROJECT_BINDING_REQUIRED', '我需要当前会话和已选择的工作区，请使用原生工作区入口', 'DSH会话与原生工作区');
         await options.notice?.reconcile(request, api);
-        stable();
+        await stable();
         const resolved = unwrap(await awaitL(() => api.resolveSessionProject(request.sessionId, { provider: agent.loginProvider, purpose: 'user-turn' }), request.signal));
-        stable();
+        await stable();
         if (!resolved || resolved.instanceId !== connection.instanceId || resolved.epoch !== connection.epoch)
             throw new NeedError('CONNECTION_LOST', '工作区解析回复已失效', '当前连接代次');
         validateTarget(resolved.target);
@@ -132,22 +196,28 @@ export function connectProvider(get, options = {}) {
             throw new NeedError('PROJECT_BINDING_INVALID', '工作区绑定与当前会话或可信主机不一致', 'L核验的原生工作区绑定');
         if (request.cwd && request.cwd !== project.path || request.bindingId && request.bindingId !== resolved.bindingId || request.workspaceId && request.workspaceId !== resolved.workspaceId)
             throw new NeedError('SESSION_CONTEXT_MISMATCH', '原会话的工作区绑定已改变，请新建会话', '原工作区绑定');
+        const details = await options.details?.(request, api, connection, target);
+        await stable();
+        let workspaceNotice = undefined;
         if (resolved.notice) {
             if (!options.notice)
                 throw new NeedError('DEPENDENCY_REQUIRED', '我需要官方会话持久记录来确认工作区说明', '官方会话与持久化服务');
-            await options.notice.deliver(resolved.notice, resolved, request, api);
-            stable();
+            workspaceNotice = await options.notice.deliver(resolved.notice, resolved, request, api);
+            await stable();
         }
         if (!options.open)
             throw new NeedError('RUNTIME_REQUIRED', '我需要主机运行适配器', '主机broker适配');
         const runtime = await options.open(resolved.target, project, { ...request, agent });
         try {
-            stable();
+            await stable();
         }
         catch (error) {
             await runtime.dispose?.();
             throw error;
         }
+        // The transport can outlive a turn; presentation belongs only to this invocation.
+        runtime.workspaceNotice = workspaceNotice || undefined;
+        runtime.details = details ?? runtime.details;
         runtime.binding = { bindingId: resolved.bindingId, workspaceId: resolved.workspaceId, revision: resolved.bindingRevision };
         runtime.connection = { ...connection };
         runtime.loginRequired = () => offerLogin(api, request, get, agent);

package/dist/readiness.js

@@ -32,6 +32,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
+import { loginDiagnostic } from "./login-diagnostic.js";
 import { randomUUID } from 'node:crypto';
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { unwrap, awaitL, requireLoginCoordinator, requireLoginState } from "./provider.js";
@@ -56,18 +57,19 @@ function snapshot(api, agent = CODEX_AGENT) {
     if (connection.phase !== 'connected')
         return denied(connection.need?.code ?? (connection.phase === 'disposed' ? 'DISPOSED' : 'CONNECTION_LOST'));
     const state = api.getLoginPromptState();
+    const diagnostic = (reason) => ({ label: '登录检查快照', value: JSON.stringify(loginDiagnostic('readiness', reason, brand, connection, state)) });
     if (!connection.instanceId || state.instanceId !== connection.instanceId)
-        return denied('AUTH_STATUS_INVALID');
+        return denied('AUTH_STATUS_INVALID', [diagnostic('LOGIN_INSTANCE_MISMATCH')]);
     requireLoginState(state);
     const technical = details({ hostContext: state.technicalDetails?.hostContext });
     if (state.phase === 'blocked' || state.phase === 'disposed')
-        return denied(state.technicalDetails?.code ?? 'AUTH_STATUS_INVALID', technical);
-    if (state.checkingProviders.includes(brand) || state.phase === 'authorizing' && state.provider === brand)
+        return denied(state.technicalDetails?.code ?? 'AUTH_STATUS_INVALID', [...technical, diagnostic(state.phase === 'disposed' ? 'LOGIN_PHASE_DISPOSED' : 'LOGIN_PHASE_BLOCKED')]);
+    if (state.queuedProviders?.includes(brand) || state.checkingProviders.includes(brand) || state.phase === 'authorizing' && state.provider === brand)
         return { phase: 'checking', loginStatus: 'unknown', title: `正在检查 ${agent.name.zh} 登录状态`, message: '远程主机连接正在检查登录状态。', technical };
     if (state.providerNeeds[brand])
-        return denied(state.providerNeeds[brand].code, technical);
+        return denied(state.providerNeeds[brand].code, [...technical, diagnostic('LOGIN_PROVIDER_NEED')]);
     if (typeof state.logins?.[brand] !== 'boolean')
-        return denied('AUTH_STATUS_INVALID', technical);
+        return denied('AUTH_STATUS_INVALID', [...technical, diagnostic('LOGIN_VALUE_INVALID')]);
     return state.logins[brand] ? { phase: 'ready', loginStatus: 'logged-in', title: `${agent.name.zh}已登录`, message: '本次远程主机连接和主机登录检查已完成。', technical } : { phase: 'login-required', loginStatus: 'not-logged-in', title: `${agent.name.zh} 尚未登录`, message: '需要登录，请到设置 → 远程主机连接 点登录', technical };
 }
 export function createReadiness(get, agent = CODEX_AGENT) {

package/dist/remote-details.d.ts

@@ -0,0 +1,39 @@
+import { type DetailObservation } from './conversation-details.ts';
+import type { LoginDiagnostic } from './login-diagnostic.ts';
+import type { ConnectApi as LConnectApi, ConnectionState } from '@ai-workbench/connect/api';
+export type { RemoteConversationDetail as RemoteDetail } from '@ai-workbench/connect/api';
+type Connection = Pick<ConnectionState, 'instanceId' | 'epoch' | 'phase'>;
+export type RemoteDetailsApi = Pick<LConnectApi, 'getConnectionState'> & Partial<Pick<LConnectApi, 'getContractInfo' | 'appendRemoteConversationDetail' | 'getRemoteConversationDetailReceipt' | 'listRemoteConversationDetails' | 'appendLoginDiagnostic' | 'getLoginDiagnosticReceipt' | 'listLoginDiagnostics'>>;
+export interface DetailChannel {
+    record(observation: DetailObservation): void;
+    beginTurn(ids: {
+        turn: string | number | null;
+        step: string | number | null;
+    }): void;
+    endTurn(): void;
+    flush(): Promise<void>;
+}
+export interface DetailRequest {
+    sessionId: string;
+    provider: 'claude' | 'codex';
+    identity: string;
+    connection: Connection;
+}
+export declare function createRemoteDetails(options: {
+    profileDir: string;
+    getApi: () => RemoteDetailsApi | undefined;
+}): {
+    recordLoginFailure(request: {
+        sessionId?: string;
+        code: string;
+        diagnostic: LoginDiagnostic;
+        context?: {
+            turn: string | number | null;
+            step: string | number | null;
+        };
+    }): Promise<{
+        eventId: string;
+        recorded: true;
+    }>;
+    open(request: DetailRequest): Promise<DetailChannel>;
+};

package/dist/remote-details.js

@@ -0,0 +1,381 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { mkdir, open, lstat, realpath, readdir } from 'node:fs/promises';
+import { isAbsolute, join, parse } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { sanitizeObservation, isSanitizedRedaction } from "./conversation-details.js";
+import { NeedError } from "./remote.js";
+const failure = (code, message = '技术详情未能持久记录，本轮已停止。') => new NeedError(code, message, '可用的远程主机连接技术详情');
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+function unwrap(result) {
+    if (!object(result))
+        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+    if (result.ok === false && object(result.error) && typeof result.error.code === 'string')
+        throw failure(result.error.code);
+    if (result.ok !== true)
+        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+    return result.value;
+}
+function identifier(value) { return value === null || typeof value === 'string' && value.trim().length > 0 || typeof value === 'number' && Number.isSafeInteger(value) && value >= 0; }
+function kind(observation) {
+    if (/UNKNOWN|UNSUPPORTED|FOREIGN/.test(observation.code))
+        return observation.severity === 'action-required' ? 'action-required' : 'unknown';
+    return { extension: 'extensions', tool: 'tools', need: 'action-required', notice: 'extensions', session: 'extensions' }[observation.kind] ?? observation.kind;
+}
+async function privateDirectory(path) {
+    if (!isAbsolute(path))
+        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+    // Existing parent/profile ownership is the host's responsibility; reject symlinks
+    // along the full path before creating our own private child directories.
+    let part = parse(path).root;
+    for (const member of path.slice(part.length).split('/').filter(Boolean)) {
+        part = join(part, member);
+        try {
+            const info = await lstat(part);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+        }
+        catch (error) {
+            if (error?.code !== 'ENOENT')
+                throw error;
+            try {
+                await mkdir(part, { mode: 0o700 });
+            }
+            catch (creation) {
+                if (creation?.code !== 'EEXIST')
+                    throw creation;
+                const info = await lstat(part);
+                if (!info.isDirectory() || info.isSymbolicLink())
+                    throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+            }
+        }
+    }
+    if (await realpath(path) !== path)
+        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+    const info = await lstat(path);
+    if ((info.mode & 0o077) !== 0 || (process.getuid && info.uid !== process.getuid()))
+        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+}
+async function durableWrite(path, value) {
+    const file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value) + '\n');
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    const parent = await open(join(path, '..'), 'r');
+    try {
+        await parent.sync();
+    }
+    finally {
+        await parent.close();
+    }
+}
+async function readJournal(path) {
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const info = await file.stat();
+        if (!info.isFile() || (info.mode & 0o077) !== 0 || (process.getuid && info.uid !== process.getuid()))
+            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+        return JSON.parse(await file.readFile('utf8'));
+    }
+    finally {
+        await file.close();
+    }
+}
+export function createRemoteDetails(options) {
+    const root = join(options.profileDir, 'ai-workbench-remote-agent', 'diagnostics');
+    const scopes = new Map(), loginScopes = new Map();
+    const initialize = async () => { await privateDirectory(join(options.profileDir, 'ai-workbench-remote-agent')); await privateDirectory(root); };
+    return {
+        async recordLoginFailure(request) {
+            await initialize();
+            const eventId = randomUUID(), diagnostic = request.diagnostic;
+            // The original observed IDs and full approved snapshot are durable before any L call.
+            await durableWrite(join(root, eventId + '.json'), { version: 1, eventId, kind: 'login-check', code: request.code, sessionHash: request.sessionId ? hash(request.sessionId) : null, diagnostic, delivery: 'pending' });
+            if (!request.sessionId)
+                throw failure('REMOTE_DETAIL_SCOPE_INVALID');
+            const sessionId = request.sessionId, provider = diagnostic.provider, api = options.getApi(), connection = diagnostic.connection;
+            const stable = () => { const now = api?.getConnectionState(); if (!api || options.getApi() !== api || now?.phase !== 'connected' || now.instanceId !== connection.instanceId || now.epoch !== connection.epoch)
+                throw failure('CONNECTION_LOST'); };
+            stable();
+            if (api.getContractInfo?.().loginDiagnostics !== 1 || !['appendLoginDiagnostic', 'getLoginDiagnosticReceipt', 'listLoginDiagnostics'].every(key => typeof api[key] === 'function'))
+                throw failure('TECHNICAL_DETAILS_UNAVAILABLE', '技术详情暂不可用，请更新远程主机连接组件。');
+            const parent = join(root, 'login');
+            await privateDirectory(parent);
+            const key = hash(sessionId + '\0' + provider), dir = join(parent, key);
+            await privateDirectory(dir);
+            const scope = loginScopes.get(key) ?? { tail: Promise.resolve(), maximum: 0, loaded: false };
+            loginScopes.set(key, scope);
+            const operation = scope.tail.then(async () => {
+                stable();
+                const generation = connection.instanceId + '\0' + connection.epoch;
+                if (!scope.loaded || scope.generation !== generation) {
+                    const names = await readdir(dir);
+                    for (const name of names) {
+                        const match = /^(\d+)-([0-9a-f-]+)\.json$/.exec(name);
+                        if (!match)
+                            continue;
+                        const sequence = Number(match[1]);
+                        if (!Number.isSafeInteger(sequence))
+                            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                        scope.maximum = Math.max(scope.maximum, sequence);
+                        const saved = await readJournal(join(dir, name));
+                        if (!object(saved) || !object(saved.detail) || saved.detail.sequence !== sequence || saved.detail.eventId !== match[2] || saved.detail.sessionId !== sessionId || saved.detail.provider !== provider)
+                            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                        const settled = 'settled-' + match[2] + '.json';
+                        if (names.includes(settled)) {
+                            const receipt = await readJournal(join(dir, settled));
+                            if (!object(receipt) || receipt.eventId !== match[2] || !['recorded', 'rejected'].includes(receipt.state))
+                                throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                            continue;
+                        }
+                        stable();
+                        const receipt = unwrap(await api.getLoginDiagnosticReceipt({ eventId: match[2], sessionId, provider }));
+                        stable();
+                        if (receipt.eventId !== match[2] || !receipt.recorded)
+                            throw failure('REMOTE_DETAIL_DELIVERY_UNKNOWN');
+                        if (!isDeepStrictEqual(receipt.detail, saved.detail))
+                            throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                        await durableWrite(join(dir, settled), { eventId: match[2], state: 'recorded' });
+                    }
+                    let cursor, previous = -1, count = 0, expected;
+                    const seen = new Set();
+                    do {
+                        stable();
+                        const page = unwrap(await api.listLoginDiagnostics({ sessionId, provider, ...(cursor ? { cursor } : {}) }));
+                        stable();
+                        if (!object(page) || !Array.isArray(page.items) || ![page.total, page.unknownCount, page.actionRequiredCount].every(n => Number.isSafeInteger(n) && n >= 0))
+                            throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                        const counts = { total: page.total, unknownCount: page.unknownCount, actionRequiredCount: page.actionRequiredCount };
+                        if (expected && !isDeepStrictEqual(expected, counts))
+                            throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                        expected = counts;
+                        for (const entry of page.items) {
+                            if (entry.sessionId !== sessionId || entry.provider !== provider || !Number.isSafeInteger(entry.sequence) || entry.sequence < 0 || entry.sequence <= previous)
+                                throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                            previous = entry.sequence;
+                            scope.maximum = Math.max(scope.maximum, entry.sequence);
+                            count++;
+                        }
+                        cursor = page.nextCursor;
+                        if (cursor !== undefined && (typeof cursor !== 'string' || !cursor || seen.has(cursor)))
+                            throw failure('REMOTE_DETAIL_CURSOR_INVALID');
+                        if (cursor)
+                            seen.add(cursor);
+                    } while (cursor);
+                    if (count !== expected?.total)
+                        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                    scope.loaded = true;
+                    scope.generation = generation;
+                }
+                const mismatch = diagnostic.reason === 'LOGIN_INSTANCE_MISMATCH', unsupported = !!diagnostic.officialReasonRejected;
+                const reason = mismatch ? 'LOGIN_INSTANCE_MISMATCH' : unsupported ? 'OFFICIAL_REASON_UNSUPPORTED' : diagnostic.reason;
+                // L 0.7.11: observed evidence never changes the current connection scope.
+                const login = { phase: diagnostic.login.phase, instanceId: diagnostic.login.instanceId, logins: Object.fromEntries(Object.entries(diagnostic.login.logins).filter(([, v]) => typeof v === 'boolean' || v === 'absent')), queuedProviders: diagnostic.login.queuedProviders, checkingProviders: diagnostic.login.checkingProviders };
+                const payload = { reason, connection: { ...connection }, login, ...(mismatch ? { observedLoginInstanceId: diagnostic.login.instanceId } : {}), ...(diagnostic.officialReason ? { officialReason: diagnostic.officialReason } : {}), ...(unsupported && !mismatch ? { officialReasonRejected: diagnostic.officialReasonRejected } : {}) };
+                // The two payload reasons are exclusive in L's contract. Preserve both facts
+                // using the approved fixed summary and full digest, without inventing a field.
+                const rejected = diagnostic.officialReasonRejected;
+                const summary = '登录检查：' + diagnostic.reason + (rejected ? '; OFFICIAL_REASON_UNSUPPORTED; bytes=' + rejected.bytes + '; SHA256=' + rejected.sha256 : '');
+                const context = request.context ?? { turn: null, step: null };
+                if (!identifier(context.turn) || !identifier(context.step))
+                    throw failure('REMOTE_DETAIL_SCOPE_INVALID');
+                const sequence = scope.maximum + 1;
+                if (!Number.isSafeInteger(sequence))
+                    throw failure('REMOTE_DETAIL_SEQUENCE_INVALID');
+                scope.maximum = sequence;
+                const detail = { version: 1, eventId, instanceId: connection.instanceId, epoch: connection.epoch, sessionId, provider, turn: context.turn, step: context.step, sequence, kind: 'login-check', severity: 'action-required', code: request.code, summary, method: diagnostic.source, payload };
+                await durableWrite(join(dir, sequence + '-' + eventId + '.json'), { state: 'pending', detail });
+                stable();
+                let response;
+                try {
+                    response = await api.appendLoginDiagnostic(structuredClone(detail));
+                }
+                catch {
+                    stable();
+                    const receipt = unwrap(await api.getLoginDiagnosticReceipt({ eventId, sessionId, provider }));
+                    stable();
+                    if (receipt.eventId !== eventId)
+                        throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                    if (!receipt.recorded)
+                        throw failure('REMOTE_DETAIL_DELIVERY_UNKNOWN');
+                    if (!isDeepStrictEqual(receipt.detail, detail))
+                        throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                    await durableWrite(join(dir, 'settled-' + eventId + '.json'), { eventId, state: 'recorded' });
+                    return;
+                }
+                stable();
+                if (response?.ok === false)
+                    await durableWrite(join(dir, 'settled-' + eventId + '.json'), { eventId, state: 'rejected', code: response.error.code });
+                const ack = unwrap(response);
+                if (ack.eventId !== eventId || ack.recorded !== true)
+                    throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                await durableWrite(join(dir, 'settled-' + eventId + '.json'), { eventId, state: 'recorded' });
+            });
+            scope.tail = operation.then(() => { }, () => { scope.loaded = false; });
+            await operation;
+            return { eventId, recorded: true };
+        },
+        async open(request) {
+            if (!request.sessionId || !request.identity || !request.connection.instanceId || !Number.isSafeInteger(request.connection.epoch) || request.connection.epoch < 0 || !['claude', 'codex'].includes(request.provider))
+                throw failure('REMOTE_DETAIL_SCOPE_INVALID');
+            try {
+                await initialize();
+            }
+            catch {
+                throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+            }
+            const api = options.getApi();
+            const stable = () => {
+                const now = api?.getConnectionState();
+                if (!api || options.getApi() !== api || now?.phase !== 'connected' || now.instanceId !== request.connection.instanceId || now.epoch !== request.connection.epoch)
+                    throw failure('CONNECTION_LOST');
+            };
+            stable();
+            const capability = api.getContractInfo?.();
+            if (!object(capability) || capability.remoteConversationDetails !== 1 || !['appendRemoteConversationDetail', 'getRemoteConversationDetailReceipt', 'listRemoteConversationDetails'].every(key => typeof api[key] === 'function')) {
+                await durableWrite(join(root, randomUUID() + '.json'), { version: 1, code: 'TECHNICAL_DETAILS_UNAVAILABLE', summary: '技术详情暂不可用', session: hash(request.sessionId), provider: request.provider });
+                throw failure('TECHNICAL_DETAILS_UNAVAILABLE', '技术详情暂不可用，请更新远程主机连接组件。');
+            }
+            const key = hash(request.identity + '\0' + request.sessionId + '\0' + request.provider), dir = join(root, key);
+            await privateDirectory(dir);
+            const scope = scopes.get(key) ?? { tail: Promise.resolve(), maximum: 0, loaded: false };
+            scopes.set(key, scope);
+            // Serialize open and appends in this host-user/session/brand scope.
+            const load = scope.tail.then(async () => {
+                stable();
+                const generation = request.connection.instanceId + '\0' + request.connection.epoch;
+                if (scope.loaded && scope.generation === generation)
+                    return;
+                const names = await readdir(dir);
+                for (const name of names) {
+                    const match = /^(\d+)-([0-9a-f-]+)\.json$/.exec(name);
+                    if (!match)
+                        continue;
+                    const n = Number(match[1]);
+                    if (!Number.isSafeInteger(n))
+                        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                    scope.maximum = Math.max(scope.maximum, n);
+                    const saved = await readJournal(join(dir, name));
+                    if (!object(saved) || !object(saved.detail) || saved.detail.eventId !== match[2] || saved.detail.sequence !== n || saved.detail.sessionId !== request.sessionId || saved.detail.provider !== request.provider)
+                        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                    const settled = 'settled-' + match[2] + '.json';
+                    if (names.includes(settled)) {
+                        const result = await readJournal(join(dir, settled));
+                        if (!object(result) || result.eventId !== match[2] || !['recorded', 'rejected'].includes(result.state))
+                            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                        continue;
+                    }
+                    // An interrupted append is reconciled by pure read, with the original
+                    // event's epoch intact. Missing receipts stay unknown and never trigger append.
+                    stable();
+                    const receipt = unwrap(await api.getRemoteConversationDetailReceipt({ eventId: match[2], sessionId: request.sessionId, provider: request.provider }));
+                    stable();
+                    if (receipt.eventId !== match[2])
+                        throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                    if (!receipt.recorded)
+                        throw failure('REMOTE_DETAIL_DELIVERY_UNKNOWN');
+                    if (!isDeepStrictEqual(receipt.detail, saved.detail))
+                        throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                    await durableWrite(join(dir, settled), { eventId: match[2], state: 'recorded' });
+                }
+                let cursor, previous = -1;
+                const seen = new Set();
+                let expected;
+                let count = 0;
+                do {
+                    stable();
+                    const page = unwrap(await api.listRemoteConversationDetails({ sessionId: request.sessionId, provider: request.provider, ...(cursor ? { cursor } : {}) }));
+                    stable();
+                    if (!object(page) || !Array.isArray(page.items) || ![page.total, page.unknownCount, page.actionRequiredCount].every(n => Number.isSafeInteger(n) && n >= 0))
+                        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                    const counts = { total: page.total, unknownCount: page.unknownCount, actionRequiredCount: page.actionRequiredCount };
+                    if (expected && !isDeepStrictEqual(expected, counts))
+                        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                    expected = counts;
+                    for (const entry of page.items) {
+                        if (entry.sessionId !== request.sessionId || entry.provider !== request.provider || !Number.isSafeInteger(entry.sequence) || entry.sequence <= previous)
+                            throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                        previous = entry.sequence;
+                        scope.maximum = Math.max(scope.maximum, entry.sequence);
+                        count++;
+                    }
+                    cursor = page.nextCursor;
+                    if (cursor !== undefined && (typeof cursor !== 'string' || !cursor || seen.has(cursor)))
+                        throw failure('REMOTE_DETAIL_CURSOR_INVALID');
+                    if (cursor)
+                        seen.add(cursor);
+                } while (cursor);
+                if (count !== expected?.total)
+                    throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                scope.loaded = true;
+                scope.generation = generation;
+            });
+            scope.tail = load.then(() => { }, () => { });
+            await load;
+            let turn = null, step = null;
+            let tail = Promise.resolve(), firstFailure;
+            const enqueue = (operation) => {
+                const task = scope.tail.then(operation);
+                scope.tail = task.then(() => { }, () => { });
+                tail = task.catch(error => { scope.loaded = false; firstFailure ??= { error }; });
+            };
+            return {
+                beginTurn(ids) { if (!identifier(ids.turn) || !identifier(ids.step))
+                    throw failure('REMOTE_DETAIL_SCOPE_INVALID'); turn = ids.turn; step = ids.step; },
+                endTurn() { turn = null; step = null; },
+                record(observation) {
+                    const safe = sanitizeObservation(observation, true);
+                    const wire = (value) => Array.isArray(value) ? value.map(wire) : object(value) ? isSanitizedRedaction(value) ? (typeof value.valueType === 'string' ? { redacted: true, valueType: value.valueType, value: '已脱敏' } : '已脱敏') : Object.fromEntries(Object.entries(value).map(([key, child]) => [key, wire(child)])) : value;
+                    const sequence = scope.maximum + 1;
+                    if (!Number.isSafeInteger(sequence))
+                        throw failure('REMOTE_DETAIL_SEQUENCE_INVALID');
+                    scope.maximum = sequence;
+                    const detail = Object.freeze({ ...safe, payload: wire(safe.payload), version: 1, eventId: randomUUID(), instanceId: request.connection.instanceId, epoch: request.connection.epoch, sessionId: request.sessionId, provider: request.provider, turn, step, sequence, kind: kind(observation) });
+                    enqueue(async () => {
+                        // A private X journal is retained even if L is disconnected or rejects it.
+                        const file = join(dir, sequence + '-' + detail.eventId + '.json');
+                        try {
+                            await durableWrite(file, { state: 'pending', detail });
+                        }
+                        catch {
+                            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                        }
+                        stable();
+                        let response;
+                        try {
+                            response = await api.appendRemoteConversationDetail(structuredClone(detail));
+                        }
+                        catch {
+                            stable();
+                            const receipt = unwrap(await api.getRemoteConversationDetailReceipt({ eventId: detail.eventId, sessionId: detail.sessionId, provider: detail.provider }));
+                            stable();
+                            if (receipt.eventId !== detail.eventId)
+                                throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                            if (!receipt.recorded)
+                                throw failure('REMOTE_DETAIL_DELIVERY_UNKNOWN');
+                            if (!isDeepStrictEqual(receipt.detail, detail))
+                                throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                            await durableWrite(join(dir, 'settled-' + detail.eventId + '.json'), { eventId: detail.eventId, state: 'recorded' });
+                            return;
+                        }
+                        stable();
+                        if (response?.ok === false) {
+                            await durableWrite(join(dir, 'settled-' + detail.eventId + '.json'), { eventId: detail.eventId, state: 'rejected', code: response.error.code });
+                        }
+                        const ack = unwrap(response);
+                        if (ack.eventId !== detail.eventId || ack.recorded !== true)
+                            throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                        await durableWrite(join(dir, 'settled-' + detail.eventId + '.json'), { eventId: detail.eventId, state: 'recorded' });
+                    });
+                },
+                async flush() { await tail; if (firstFailure)
+                    throw firstFailure.error; stable(); },
+            };
+        }
+    };
+}