@ai-workbench/remote-agent 0.8.13 → 0.8.14

package/dist/broker.d.ts

@@ -1,8 +1,10 @@
+import { type CloseCause, type CloseObserver } from './close-diagnostics.ts';
 import { type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { NeedError, type Need } from './remote.ts';
 import { type ConnectTarget } from './provider.ts';
 export type Attachment = ChildProcessWithoutNullStreams;
 export interface BrokerOptions {
+    observeClose?: CloseObserver;
     maxFrameBytes: number;
     initialSequence?: number;
     instanceId?: string;
@@ -64,8 +66,8 @@ export declare class BrokerTransport {
     onChange(fn: () => void): () => void;
     private changed;
     private notice;
-    fail(error: NeedError): void;
-    close(): void;
+    fail(error: NeedError, cause?: CloseCause): void;
+    close(cause?: CloseCause): void;
     waitOnline(signal?: AbortSignal): Promise<void>;
     connect(): Promise<void>;
     private attach;

package/dist/broker.js

@@ -1,3 +1,4 @@
+import { closeCode } from "./close-diagnostics.js";
 import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { ProtocolBoundary } from "./protocol-boundary.js";
@@ -39,8 +40,8 @@ export class BrokerTransport {
             this.boundary = new ProtocolBoundary(options.maxMessageBytes);
         this.recovering = !!options.recoverySessionId;
         this.lease.abort();
-        this.readable = new ReadableStream({ start: c => { this.output = c; }, pull: () => { this.attachment?.stdout.resume(); }, cancel: () => { this.close(); } });
-        this.writable = new WritableStream({ write: bytes => this.write(bytes), close: () => this.close(), abort: () => this.close() });
+        this.readable = new ReadableStream({ start: c => { this.output = c; }, pull: () => { this.attachment?.stdout.resume(); }, cancel: reason => { this.close({ layer: 'broker', initiator: 'broker.reader-cancel', reason: closeCode(reason, 'BROKER_READER_CANCELLED'), action: 'close' }); } });
+        this.writable = new WritableStream({ write: bytes => this.write(bytes), close: () => this.close({ layer: 'broker', initiator: 'broker.writer-close', reason: 'BROKER_WRITER_CLOSED', action: 'close' }), abort: reason => this.close({ layer: 'broker', initiator: 'broker.writer-abort', reason: closeCode(reason, 'BROKER_WRITER_ABORTED'), action: 'abort' }) });
     }
     get online() { return this.attached && !this.ended; }
     get generation() { return this.epoch; }
@@ -93,7 +94,8 @@ export class BrokerTransport {
     changed() { for (const fn of this.listeners)
         fn(); }
     notice(code, message) { this.options.onNeed?.({ code, message, requires: '恢复原员工主机连接或显式结束本轮' }); }
-    fail(error) {
+    fail(error, cause = { layer: 'broker', initiator: 'broker.fail', reason: error.code, action: 'failure' }) {
+        this.options.observeClose?.({ ...cause, changes: cause.changes ?? [{ field: 'broker.ended', before: this.ended, after: true }] });
         if (this.ended)
             return;
         this.stopHeartbeat();
@@ -109,7 +111,8 @@ export class BrokerTransport {
         }
         catch { /* Reader already cancelled. */ }
     }
-    close() {
+    close(cause = { layer: 'broker', initiator: 'broker.close', reason: 'BROKER_CLOSE_REQUESTED', action: 'close' }) {
+        this.options.observeClose?.({ ...cause, changes: cause.changes ?? [{ field: 'broker.ended', before: this.ended, after: true }] });
         if (this.ended)
             return;
         this.stopHeartbeat();
@@ -158,6 +161,7 @@ export class BrokerTransport {
     async attach() {
         const child = await this.options.attach(this.cursor);
         if (this.ended) {
+            this.options.observeClose?.({ layer: 'broker', initiator: 'broker.late-attachment', reason: 'SESSION_ENDED', action: 'terminate' });
             child.kill('SIGTERM');
             throw new NeedError('SESSION_ENDED', '本轮已结束', '重新连接');
         }
@@ -189,8 +193,10 @@ export class BrokerTransport {
                     if (policy.enabled) {
                         this.stopHeartbeat();
                         this.heartbeat = setInterval(() => { if (this.online && this.attachment === child) {
-                            child.stdin.write('{"type":"heartbeat"}\n', error => { if (error)
-                                child.kill('SIGTERM'); });
+                            child.stdin.write('{"type":"heartbeat"}\n', error => { if (error) {
+                                this.options.observeClose?.({ layer: 'broker', initiator: 'broker.heartbeat-write', reason: 'BROKER_HEARTBEAT_WRITE_FAILED', action: 'terminate' });
+                                child.kill('SIGTERM');
+                            } });
                         } }, policy.heartbeatIntervalMs);
                         this.heartbeat.unref?.();
                     }
@@ -206,6 +212,7 @@ export class BrokerTransport {
                 const code = typeof f.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(f.code) ? f.code : 'BROKER_PROTOCOL_INVALID';
                 const error = new NeedError(code, '主机会话无法续接（' + code + '）；没有重放输入或代答审批', '恢复或显式结束原会话');
                 if (!ready && f.code === 'ATTACH_BUSY') {
+                    this.options.observeClose?.({ layer: 'broker', initiator: 'broker.attach-busy', reason: error.code, action: 'terminate' });
                     attemptClosed = true;
                     connected.reject(error);
                     child.kill('SIGTERM');
@@ -261,7 +268,9 @@ export class BrokerTransport {
                 fatal(error instanceof NeedError ? error : new NeedError('BROKER_PROTOCOL_INVALID', 'broker 输出帧无法解析', '有效的 broker 输出'));
             }
         });
-        const detached = () => {
+        const detached = (cause) => {
+            const effective = !(attemptClosed || generation !== this.epoch || this.ended);
+            this.options.observeClose?.({ ...cause, changes: cause.changes ?? [{ field: 'broker.attached', before: this.attached, after: effective ? false : this.attached }, { field: 'broker.lease-aborted', before: this.lease.signal.aborted, after: effective ? true : this.lease.signal.aborted }] });
             if (attemptClosed || generation !== this.epoch || this.ended)
                 return;
             this.stopHeartbeat();
@@ -281,8 +290,8 @@ export class BrokerTransport {
             this.notice('CONNECTION_LOST', '连接中断，主机可能正在等待你的审批；重连前不发送审批');
             void this.options.onDisconnect?.().catch(error => this.fail(error instanceof NeedError ? error : new NeedError('RECONNECT_FAILED', '续接失败，根因未查明', '恢复原连接')));
         };
-        child.once('error', detached);
-        child.once('close', detached);
+        child.once('error', () => detached({ layer: 'broker', initiator: 'broker.attachment-error', reason: 'BROKER_ATTACHMENT_ERROR', action: 'failure' }));
+        child.once('close', (code, signal) => detached({ layer: 'broker', initiator: 'broker.attachment-close', reason: 'BROKER_ATTACHMENT_CLOSED', action: 'exit', exitCode: code, signal }));
         return connected.promise.finally(off);
     }
     async write(bytes) {

package/dist/claude-local.d.ts

@@ -1,3 +1,4 @@
+import { type CloseCause } from './close-diagnostics.ts';
 import { type EmployeeLease, type EmployeeLeaseOptions, type EmployeeNetworkApi, type EmployeeWorkspace } from './employee-endpoint.ts';
 import { type EmployeeMcpOptions } from './employee-mcp.ts';
 import { createEmployeeShell, type EmployeeShell } from './employee-shell.ts';
@@ -27,7 +28,7 @@ interface Options {
         mcp: (options: EmployeeMcpOptions) => Promise<{
             routing: EmployeeRouting;
             signal?: AbortSignal;
-            close(): Promise<void>;
+            close(cause?: CloseCause): Promise<void>;
         }>;
         shell: (options: Parameters<typeof createEmployeeShell>[0]) => EmployeeShell;
     };

package/dist/claude-local.js

@@ -6,6 +6,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { CloseDiagnostics, closeCode } from "./close-diagnostics.js";
 import { isDeepStrictEqual } from 'node:util';
 import { openEmployeeLease } from "./employee-endpoint.js";
 import { openEmployeeMcp } from "./employee-mcp.js";
@@ -94,6 +95,9 @@ export function createClaudeLocalProvider(options) {
         if (entry && (entry.closing || !isDeepStrictEqual(entry.scope, scope) || entry.lease.signal.aborted))
             throw failure('EMPLOYEE_CONTEXT_CHANGED');
         const details = request.detailChannel;
+        const closeDiagnostics = entry?.runtime.closeDiagnostics ?? new CloseDiagnostics(event => details.record(event));
+        closeDiagnostics.bind(event => details.record(event));
+        request.closeDiagnostics = closeDiagnostics;
         request.timing?.bind(observation => details.record(observation));
         const trusted = async (ignoreCancellation = false) => {
             if (!ignoreCancellation)
@@ -130,60 +134,77 @@ export function createClaudeLocalProvider(options) {
         let privateFailure, privateTail = Promise.resolve();
         try {
             const unscoped = (observation) => { if (privateFailure)
-                throw privateFailure; privateTail = privateTail.then(() => options.recordUnscoped(request, observation)).catch(error => { privateFailure ??= error; void lease?.close().catch(failure => { privateFailure ??= failure; }); }); };
-            lease = await (options.ports?.lease ?? openEmployeeLease)({ getConnect: () => options.getConnect(), getNetwork: options.getNetwork, readWorkspace: () => options.readWorkspace(request.sessionId), host: target, sessionId: request.sessionId, control: async (_target, command, signal) => (await transport()).run(command, signal), detail: unscoped }, request.signal);
-            const shell = (options.ports?.shell ?? createEmployeeShell)({ target: lease.target, maxBytes: maximum, killGraceMs: grace, attach: async (spec) => (await transport()).attach([spec.command, ...spec.args].map(shellQuote).join(' ')) });
-            mcp = await (options.ports?.mcp ?? openEmployeeMcp)({ lease, maxBytes: maximum, killGraceMs: grace, runShell: shell, activeSignal: () => entry?.active?.signal, captureDetail: () => { const sink = entry?.active?.details; if (!sink)
+                throw privateFailure; privateTail = privateTail.then(() => options.recordUnscoped(request, observation)).catch(error => { privateFailure ??= error; closeDiagnostics.record({ layer: 'runtime', initiator: 'claude.private-diagnostic-failure', reason: 'CONVERSATION_DETAILS_FAILED', action: 'failure' }); void lease?.close({ layer: 'endpoint', initiator: 'claude.private-diagnostic-failure', reason: 'CONVERSATION_DETAILS_FAILED', action: 'close' }).catch(failure => { privateFailure ??= failure; }); }); };
+            lease = await (options.ports?.lease ?? openEmployeeLease)({ closeDiagnostics, getConnect: () => options.getConnect(), getNetwork: options.getNetwork, readWorkspace: () => options.readWorkspace(request.sessionId), host: target, sessionId: request.sessionId, control: async (_target, command, signal) => (await transport()).run(command, signal), detail: unscoped }, request.signal);
+            const shell = (options.ports?.shell ?? createEmployeeShell)({ closeDiagnostics, target: lease.target, maxBytes: maximum, killGraceMs: grace, attach: async (spec) => (await transport()).attach([spec.command, ...spec.args].map(shellQuote).join(' ')) });
+            mcp = await (options.ports?.mcp ?? openEmployeeMcp)({ closeDiagnostics, lease, maxBytes: maximum, killGraceMs: grace, runShell: shell, activeSignal: () => entry?.active?.signal, captureDetail: () => { const sink = entry?.active?.details; if (!sink)
                     throw failure('EMPLOYEE_NO_ACTIVE_TURN'); return observation => sink.record(observation); }, detail: unscoped });
             entry = { runtime: undefined, scope, lease, details, request };
             const row = entry;
             base = await options.open(target, { name: workspace.workspaceId, path: target.session.root }, openRequest(row, true));
             const underlying = base, endpoint = mcp;
-            const close = (detach) => row.closing ??= Promise.resolve().then(async () => {
-                row.active = undefined;
-                const errors = [];
-                try {
-                    await endpoint.close();
-                }
-                catch (error) {
-                    errors.push(error);
-                }
-                await privateTail;
-                if (privateFailure)
-                    errors.push(privateFailure);
-                try {
-                    await (detach ? underlying.detach?.() : underlying.dispose?.());
-                }
-                catch (error) {
-                    errors.push(error);
-                }
-                if (errors.length)
-                    throw new AggregateError(errors, 'EMPLOYEE_CLEANUP_UNCONFIRMED');
-                if (entries.get(request.sessionId) === row)
-                    entries.delete(request.sessionId);
-            });
+            const close = (detach, cause = { layer: 'runtime', initiator: detach ? 'claude.runtime-detach' : 'claude.runtime-dispose', reason: detach ? 'RUNTIME_DETACH' : 'RUNTIME_DISPOSE', action: detach ? 'detach' : 'dispose' }) => {
+                closeDiagnostics.record(cause);
+                return row.closing ??= Promise.resolve().then(async () => {
+                    row.active = undefined;
+                    const errors = [];
+                    try {
+                        await endpoint.close({ layer: 'relay', initiator: 'claude.cleanup-mcp', reason: 'RUNTIME_CLEANUP', action: 'close' });
+                    }
+                    catch (error) {
+                        errors.push(error);
+                    }
+                    await privateTail;
+                    if (privateFailure)
+                        errors.push(privateFailure);
+                    try {
+                        await (detach ? underlying.detach?.(cause) : underlying.dispose?.(cause));
+                    }
+                    catch (error) {
+                        errors.push(error);
+                    }
+                    try {
+                        await row.details.flush();
+                    }
+                    catch (error) {
+                        errors.push(error);
+                    }
+                    try {
+                        closeDiagnostics.assertRecorded();
+                    }
+                    catch (error) {
+                        errors.push(error);
+                    }
+                    if (errors.length)
+                        throw new AggregateError(errors, 'EMPLOYEE_CLEANUP_UNCONFIRMED');
+                    if (entries.get(request.sessionId) === row)
+                        entries.delete(request.sessionId);
+                });
+            };
             const executionSignal = AbortSignal.any([lease.signal, ...mcp.signal ? [mcp.signal] : []]);
-            row.runtime = { ...underlying, cwd: workspace.directory.path, details, connection: { ...connection }, binding: { bindingId: item.bindingId, workspaceId: workspace.workspaceId, revision: state.revision }, execution: { hostCwd: target.session.root, routing: mcp.routing, notice: NOTICE, signal: executionSignal, scope: { source: 'local', cwd: workspace.directory.path, hostCwd: target.session.root, uid: lease.target.endpoint.remoteUid, claudeAcpVersion: '0.94.0', sdkVersion: '0.3.303', unsupported: ['subagents', 'internal-direct-calls', 'binary-read', 'background-shell'] }, validate: async (signal) => { executionSignal.throwIfAborted(); await row.lease.validate(signal); }, beginTurn: async (signal) => { executionSignal.throwIfAborted(); if (row.closing || row.active)
-                        throw failure('TURN_BUSY'); await row.lease.validate(signal); executionSignal.throwIfAborted(); row.active = { signal, details: row.details }; }, endTurn: () => { row.active = undefined; } }, dispose: () => close(false), detach: () => close(true) };
+            row.runtime = { ...underlying, closeDiagnostics, cwd: workspace.directory.path, details, connection: { ...connection }, binding: { bindingId: item.bindingId, workspaceId: workspace.workspaceId, revision: state.revision }, execution: { hostCwd: target.session.root, routing: mcp.routing, notice: NOTICE, signal: executionSignal, scope: { source: 'local', cwd: workspace.directory.path, hostCwd: target.session.root, uid: lease.target.endpoint.remoteUid, claudeAcpVersion: '0.94.0', sdkVersion: '0.3.303', unsupported: ['subagents', 'internal-direct-calls', 'binary-read', 'background-shell'] }, validate: async (signal) => { executionSignal.throwIfAborted(); await row.lease.validate(signal); }, beginTurn: async (signal) => { executionSignal.throwIfAborted(); if (row.closing || row.active)
+                        throw failure('TURN_BUSY'); await row.lease.validate(signal); executionSignal.throwIfAborted(); row.active = { signal, details: row.details }; }, endTurn: () => { row.active = undefined; } }, dispose: cause => close(false, cause), detach: cause => close(true, cause) };
             entries.set(request.sessionId, row);
-            lease.signal.addEventListener('abort', () => { void close(false).catch(() => { }); }, { once: true });
+            lease.signal.addEventListener('abort', () => { void close(false, { layer: 'endpoint', initiator: 'claude.lease-abort', reason: closeCode(lease?.signal.reason, 'EMPLOYEE_CONTEXT_CHANGED'), action: 'abort' }).catch(() => { }); }, { once: true });
             if (lease.signal.aborted) {
-                await close(false);
+                await close(false, { layer: 'endpoint', initiator: 'claude.open-aborted', reason: closeCode(lease.signal.reason, 'EMPLOYEE_CONTEXT_CHANGED'), action: 'abort' });
                 throw failure('EMPLOYEE_CONTEXT_CHANGED');
             }
             return row.runtime;
         }
         catch (error) {
+            closeDiagnostics.record({ layer: 'runtime', initiator: 'claude.open-failure', reason: closeCode(error, 'EMPLOYEE_OPEN_FAILED'), action: 'failure' });
+            const cause = { layer: 'runtime', initiator: 'claude.open-cleanup', reason: 'EMPLOYEE_OPEN_FAILED', action: 'close' };
             const cleanup = [];
             try {
-                await mcp?.close();
-                await lease?.close();
+                await mcp?.close(cause);
+                await lease?.close(cause);
             }
             catch (e) {
                 cleanup.push(e);
             }
             try {
-                await base?.dispose?.();
+                await base?.dispose?.(cause);
             }
             catch (e) {
                 cleanup.push(e);
@@ -197,6 +218,12 @@ export function createClaudeLocalProvider(options) {
             catch (e) {
                 cleanup.push(e);
             }
+            try {
+                closeDiagnostics.assertRecorded();
+            }
+            catch (e) {
+                cleanup.push(e);
+            }
             if (cleanup.length)
                 throw new AggregateError([error, ...cleanup], 'EMPLOYEE_OPEN_CLEANUP_UNCONFIRMED');
             throw error;

package/dist/close-diagnostics.d.ts

@@ -0,0 +1,56 @@
+import type { DetailObservation } from './conversation-details.ts';
+import { NeedError } from './remote.ts';
+export interface CloseChange {
+    field: string;
+    before: string | number | boolean | null;
+    after: string | number | boolean | null;
+}
+export interface CloseCause {
+    layer: 'acp' | 'adapter' | 'broker' | 'endpoint' | 'relay' | 'executor' | 'runtime';
+    initiator: string;
+    reason: string;
+    action?: 'close' | 'dispose' | 'detach' | 'invalidate' | 'abort' | 'failure' | 'exit' | 'eof' | 'terminate';
+    operation?: string;
+    exitCode?: number | null;
+    signal?: string | null;
+    remoteReason?: 'unavailable';
+    changedFields?: readonly string[];
+    changes?: readonly CloseChange[];
+}
+export type CloseObserver = (cause: CloseCause) => void;
+/** Only typed codes, never exception messages, causes, stderr or RPC data. */
+export declare function closeCode(error: unknown, fallback?: string): string;
+/** Retain trusted typed codes through wrappers; never traverse error text or invoke getters. */
+export declare function closeErrorCodes(error: unknown, fallback?: string): string[];
+export declare function closeFailure(code: string, message: string, requires: string, codes: readonly string[]): NeedError;
+/** Assign order before abort/kill; persist through the existing asynchronous D19 outbox. */
+export declare class CloseDiagnostics {
+    private sink;
+    readonly parentId?: string | undefined;
+    private state;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    private sequence;
+    private pending;
+    private firstValue?;
+    private readonly started;
+    stage: string;
+    constructor(sink: (detail: DetailObservation) => void, parentId?: string | undefined, state?: {
+        failure?: {
+            error: unknown;
+        };
+    });
+    run<T>(operation: string, work: () => Promise<T>): Promise<T>;
+    get recordingFailureCode(): string | undefined;
+    get first(): Readonly<Record<string, unknown>> | undefined;
+    bind(sink: (detail: DetailObservation) => void): void;
+    /** A delayed resource callback retains its original accepted detail channel. */
+    capture(): CloseObserver;
+    child(sink?: (detail: DetailObservation) => void): CloseDiagnostics;
+    record(cause: CloseCause): void;
+    private recordUsing;
+    assertRecorded(): void;
+}
+/** Run after owned cleanup; expose both the primary error code and persistence failure. */
+export declare function flushCloseDiagnostics(diagnostics: CloseDiagnostics, flush: (() => Promise<void>) | undefined, primary?: {
+    error: unknown;
+}): Promise<void>;

package/dist/close-diagnostics.js

@@ -0,0 +1,104 @@
+import { randomUUID } from 'node:crypto';
+import { NeedError } from "./remote.js";
+/** Only typed codes, never exception messages, causes, stderr or RPC data. */
+export function closeCode(error, fallback = 'CLOSE_REASON_UNKNOWN') {
+    return error instanceof NeedError && /^[A-Z][A-Z0-9_]*$/.test(error.code) ? error.code : fallback;
+}
+/** Retain trusted typed codes through wrappers; never traverse error text or invoke getters. */
+export function closeErrorCodes(error, fallback = 'CLOSE_REASON_UNKNOWN') {
+    const queue = [error], seen = new Set(), codes = new Set();
+    while (queue.length) {
+        const next = queue.pop();
+        if (!(next instanceof NeedError || next instanceof AggregateError) || seen.has(next))
+            continue;
+        seen.add(next);
+        if (next instanceof NeedError) {
+            const code = Object.getOwnPropertyDescriptor(next, 'code');
+            if (code && 'value' in code && typeof code.value === 'string' && /^[A-Z][A-Z0-9_]*$/.test(code.value))
+                codes.add(code.value);
+        }
+        const cause = Object.getOwnPropertyDescriptor(next, 'cause');
+        if (cause && 'value' in cause)
+            queue.push(cause.value);
+        if (next instanceof AggregateError) {
+            const errors = Object.getOwnPropertyDescriptor(next, 'errors');
+            if (errors && 'value' in errors && Array.isArray(errors.value))
+                for (const child of errors.value)
+                    queue.push(child);
+        }
+    }
+    return codes.size ? [...codes] : [fallback];
+}
+export function closeFailure(code, message, requires, codes) {
+    return Object.assign(new NeedError(code, message, requires), { cause: new AggregateError([...new Set(codes)].map(value => new NeedError(value, '关闭收尾代码 ' + value, '按安全代码核对')), 'CLOSE_AND_DIAGNOSTIC_FAILURES') });
+}
+/** Assign order before abort/kill; persist through the existing asynchronous D19 outbox. */
+export class CloseDiagnostics {
+    sink;
+    parentId;
+    state;
+    id = randomUUID();
+    sequence = 0;
+    pending = new Map();
+    firstValue;
+    started = performance.now();
+    stage = 'runtime-admission';
+    constructor(sink, parentId, state = {}) {
+        this.sink = sink;
+        this.parentId = parentId;
+        this.state = state;
+    }
+    async run(operation, work) { this.pending.set(operation, (this.pending.get(operation) ?? 0) + 1); try {
+        return await work();
+    }
+    finally {
+        const count = this.pending.get(operation) - 1;
+        if (count)
+            this.pending.set(operation, count);
+        else
+            this.pending.delete(operation);
+    } }
+    get recordingFailureCode() { return this.state.failure ? closeCode(this.state.failure.error, 'CLOSE_RECORD_FAILED') : undefined; }
+    get first() { return this.firstValue; }
+    bind(sink) { this.sink = sink; }
+    /** A delayed resource callback retains its original accepted detail channel. */
+    capture() { const sink = this.sink; return cause => this.recordUsing(sink, cause); }
+    child(sink = this.sink) { const child = new CloseDiagnostics(sink, this.id, this.state); child.stage = this.stage; return child; }
+    record(cause) { this.recordUsing(this.sink, cause); }
+    recordUsing(sink, cause) {
+        const first = this.sequence === 0;
+        const metadata = { ...cause.changedFields ? { changedFields: Object.freeze([...cause.changedFields]) } : {}, changes: Object.freeze((cause.changes ?? [{ field: 'observer.close-sequence', before: this.sequence, after: this.sequence + 1 }]).map(change => Object.freeze({ field: change.field, before: change.before, after: change.after }))), layer: cause.layer, initiator: cause.initiator, reason: cause.reason, ...cause.action ? { action: cause.action } : {}, ...cause.operation ? { operation: cause.operation } : {}, ...cause.exitCode !== undefined ? { exitCode: cause.exitCode } : {}, ...cause.signal !== undefined ? { signal: cause.signal } : {}, ...cause.remoteReason ? { remoteReason: cause.remoteReason } : {} };
+        const payload = Object.freeze({ ...metadata, pendingOperations: Object.freeze([...this.pending.keys()]), closeId: this.id, ...this.parentId ? { parentCloseId: this.parentId } : {}, closeSequence: ++this.sequence, first, stage: this.stage, clock: 'client-monotonic', elapsedMs: performance.now() - this.started });
+        this.firstValue ??= payload;
+        try {
+            sink({ kind: 'session', severity: 'warning', code: first ? 'REMOTE_CLOSE_FIRST' : 'REMOTE_CLOSE_NEXT', summary: first ? '首次观察到关闭（不等同根因）' : '后续关闭或清理', payload });
+        }
+        catch (error) {
+            this.state.failure ??= { error };
+        }
+    }
+    assertRecorded() { if (this.state.failure)
+        throw new NeedError('CONVERSATION_DETAILS_FAILED', '关闭原因保存未完成；首次观察原因 ' + String(this.firstValue?.reason ?? 'CLOSE_REASON_UNKNOWN') + '。', '关闭诊断保存代码 ' + this.recordingFailureCode + '；不将保存失败当作原始关闭原因'); }
+}
+/** Run after owned cleanup; expose both the primary error code and persistence failure. */
+export async function flushCloseDiagnostics(diagnostics, flush, primary) {
+    const reporting = [];
+    try {
+        await flush?.();
+    }
+    catch (error) {
+        reporting.push(...closeErrorCodes(error, 'CLOSE_FLUSH_FAILED'));
+    }
+    try {
+        diagnostics.assertRecorded();
+    }
+    catch (error) {
+        reporting.push(diagnostics.recordingFailureCode ?? closeCode(error, 'CLOSE_RECORD_FAILED'));
+    }
+    if (reporting.length) {
+        const primaryCodes = primary ? closeErrorCodes(primary.error, 'REMOTE_CLEANUP_UNCONFIRMED') : [];
+        throw closeFailure('CONVERSATION_DETAILS_FAILED', '关闭诊断保存未完成；原关闭与清理结果需核对。', '首次关闭 ' + String(diagnostics.first?.reason ?? 'CLOSE_REASON_UNKNOWN') + '；清理 ' + (primaryCodes.join(',') || 'closed') + '；保存 ' + reporting.join(','), [...primaryCodes, ...reporting]);
+    }
+    if (primary)
+        throw primary.error;
+}

package/dist/conversation-details.js

@@ -283,6 +283,10 @@ function modelConfigurationStructure(value, level = 'root') {
     return Object.fromEntries(Object.entries(value).map(([key, child]) => {
         if (typeof child === 'string' && strings[level].includes(key))
             return [key, child];
+        if (level === 'root' && key === 'resolvedModelSource' && child === 'host-user-catalog')
+            return [key, child];
+        if (level === 'root' && key === 'sessionModelReported' && child === false)
+            return [key, false];
         if (level === 'root' && key === 'status' && child === 'remote-configured')
             return [key, child];
         if (level === 'actual' && typeof child === 'boolean' && ['confirmed', 'effortAvailable'].includes(key))
@@ -331,6 +335,58 @@ function employeeStructure(value) {
         return [key, opaqueStructure(child)];
     }));
 }
+/** Closure metadata has no arbitrary exception or transport payload fields. */
+function closeStructure(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return opaqueStructure(value);
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => {
+        if (key === 'changes' && Array.isArray(child))
+            return [key, child.map(change => {
+                    if (!change || typeof change !== 'object' || Array.isArray(change))
+                        return opaqueStructure(change);
+                    const field = change.field;
+                    const known = typeof field === 'string' && (/^(?:observer.close-sequence|executor.ended|transport.closed|transport.termination-requested|provider.ended|broker.ended|broker.attached|broker.lease-aborted|lease.aborted|lease.closed|mcp.ended|mcp.closing|mcp.poisoned|shell.settled|shell.stop-code|tools.aborted|tools.stop-code|acp.close-requested|adapter.turn-aborted|adapter.detached|adapter.shutting-down|workspace.binding-id|workspace.source|workspace.status|workspace.match-count|network.phase|catalog.api-replaced|catalog.capability|catalog.signature-sha256|connection.instance-id|connection.epoch|connection.phase|connection.need-code)$/.test(field) || /^catalog\.(?:codex|claude)\.(?:ok|error-code|instance-id|epoch|provider|target-sha256|metadata-sha256)$/.test(field));
+                    if (!known)
+                        return opaqueStructure(change);
+                    const scalar = (value) => value === null || typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value) || typeof value === 'string' && /^[a-zA-Z0-9_.:@-]+$/.test(value) ? value : opaqueStructure(value);
+                    return Object.fromEntries(Object.entries(change).map(([name, value]) => [name, name === 'field' ? field : ['before', 'after'].includes(name) ? scalar(value) : opaqueStructure(value)]));
+                })];
+        if (key === 'pendingOperations' && Array.isArray(child))
+            return [key, child.map(field => typeof field === 'string' && /^[a-z][a-z0-9._/-]*$/.test(field) ? field : opaqueStructure(field))];
+        if (key === 'changedFields' && Array.isArray(child))
+            return [key, child.map(field => typeof field === 'string' && /^[a-z][a-z-]*$/.test(field) ? field : opaqueStructure(field))];
+        if (['closeId', 'parentCloseId'].includes(key) && typeof child === 'string' && /^[a-f0-9-]+$/.test(child))
+            return [key, child];
+        if (['layer', 'initiator', 'action', 'operation', 'stage', 'clock'].includes(key) && typeof child === 'string' && /^[a-z][a-z0-9._/-]*$/.test(child))
+            return [key, child];
+        if (key === 'reason' && typeof child === 'string' && /^[A-Z][A-Z0-9_]*$/.test(child))
+            return [key, child];
+        if (key === 'remoteReason' && child === 'unavailable' || key === 'first' && typeof child === 'boolean')
+            return [key, child];
+        if (['closeSequence', 'elapsedMs'].includes(key) && typeof child === 'number' && Number.isFinite(child) && child >= 0)
+            return [key, child];
+        if (key === 'exitCode' && (child === null || typeof child === 'number' && Number.isSafeInteger(child)))
+            return [key, child];
+        if (key === 'signal' && (child === null || typeof child === 'string' && /^SIG[A-Z]+$/.test(child)))
+            return [key, child];
+        return [key, opaqueStructure(child)];
+    }));
+}
+function catalogScopeStructure(value, nested = false) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value) || isSanitizedRedaction(value))
+        return opaqueStructure(value);
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => {
+        if (!nested && key === 'reason' && child === 'CATALOG_PRESENTATION_CHANGED')
+            return [key, child];
+        if (!nested && ['before', 'after'].includes(key))
+            return [key, catalogScopeStructure(child, true)];
+        if (nested && key === 'presentationSha256' && (child === null || typeof child === 'string' && /^[a-f0-9]{64}$/.test(child)))
+            return [key, child];
+        if (nested && key === 'needCode' && (child === null || typeof child === 'string' && /^[A-Z][A-Z0-9_]*$/.test(child)))
+            return [key, child];
+        return [key, opaqueStructure(child)];
+    }));
+}
 export function sanitizeObservation(observation, protectModelMaterial = false) {
     const payload = snapshotPayload(observation.payload, new Set(), protectModelMaterial && observation.kind !== 'commands');
     return freezeDeep({
@@ -338,15 +394,17 @@ export function sanitizeObservation(observation, protectModelMaterial = false) {
         code: sanitizeDisplayLabel(observation.code), summary: sanitizeDisplayLabel(observation.summary),
         ...(observation.method === undefined ? {} : { method: sanitizeDisplayLabel(observation.method) }),
         payload: !protectModelMaterial ? payload
-            : observation.kind === 'session' && observation.code === 'CODEX_CONTEXT_SESSION_REPLACED' ? contextTransitionStructure(payload)
-                : observation.kind === 'session' && ['MODEL_CONFIGURATION_CONFIRMED', 'MODEL_CONFIGURATION_FAILED'].includes(observation.code) ? modelConfigurationStructure(payload)
-                    : observation.kind === 'commands' ? catalogStructure(payload)
-                        : observation.kind === 'usage' ? usageStructure(payload)
-                            : observation.kind === 'session' && observation.code === 'REMOTE_STAGE_TIMING' ? timingStructure(payload)
-                                : observation.kind === 'session' && ['CLAUDE_EMPLOYEE_OPERATION', 'CLAUDE_EMPLOYEE_PROCESS', 'CLAUDE_EMPLOYEE_REVOKED', 'CLAUDE_EMPLOYEE_SCOPE'].includes(observation.code) ? employeeStructure(payload)
-                                    : observation.kind === 'need' ? payload
-                                        : observation.kind === 'tool' || ['SDK_ITEM', 'SDK_TOOL', 'ACP_SESSION_UPDATE', 'ACP_IDLE_UPDATE'].includes(observation.code) ? toolStructure(payload)
-                                            : opaqueStructure(payload),
+            : observation.kind === 'session' && observation.code === 'CATALOG_SCOPE_INFORMATION' ? catalogScopeStructure(payload)
+                : observation.kind === 'session' && observation.code === 'CODEX_CONTEXT_SESSION_REPLACED' ? contextTransitionStructure(payload)
+                    : observation.kind === 'session' && ['MODEL_CONFIGURATION_CONFIRMED', 'MODEL_CONFIGURATION_FAILED', 'MODEL_CONFIGURATION_INFORMATION', 'MODEL_CONFIGURATION_CHANGED_DURING_TURN', 'TURN_GATE_INFORMATION'].includes(observation.code) ? modelConfigurationStructure(payload)
+                        : observation.kind === 'session' && ['REMOTE_CLOSE_FIRST', 'REMOTE_CLOSE_NEXT'].includes(observation.code) ? closeStructure(payload)
+                            : observation.kind === 'commands' ? catalogStructure(payload)
+                                : observation.kind === 'usage' ? usageStructure(payload)
+                                    : observation.kind === 'session' && observation.code === 'REMOTE_STAGE_TIMING' ? timingStructure(payload)
+                                        : observation.kind === 'session' && ['CLAUDE_EMPLOYEE_OPERATION', 'CLAUDE_EMPLOYEE_PROCESS', 'CLAUDE_EMPLOYEE_REVOKED', 'CLAUDE_EMPLOYEE_SCOPE'].includes(observation.code) ? employeeStructure(payload)
+                                            : observation.kind === 'need' ? payload
+                                                : observation.kind === 'tool' || ['SDK_ITEM', 'SDK_TOOL', 'ACP_SESSION_UPDATE', 'ACP_IDLE_UPDATE'].includes(observation.code) ? toolStructure(payload)
+                                                    : opaqueStructure(payload),
     });
 }
 function validatedScope(scope) {

package/dist/employee-endpoint.d.ts

@@ -1,3 +1,4 @@
+import { type CloseCause, type CloseDiagnostics } from './close-diagnostics.ts';
 import type { ConnectApi as LApi, LocalWorkspaceContextRequest } from '@ai-workbench/connect/api';
 import type { ConnectTarget } from './provider.ts';
 import type { DetailObservation } from './conversation-details.ts';
@@ -66,6 +67,7 @@ export interface EmployeeWorkspace {
     };
 }
 export interface EmployeeLeaseOptions {
+    closeDiagnostics?: CloseDiagnostics;
     getConnect: () => EmployeeConnectApi | undefined;
     getNetwork: () => EmployeeNetworkApi | undefined;
     readWorkspace: () => Promise<EmployeeWorkspace>;
@@ -86,6 +88,6 @@ export interface EmployeeLease {
     request: Readonly<LocalWorkspaceContextRequest>;
     signal: AbortSignal;
     validate(callerSignal?: AbortSignal): Promise<EmployeeEndpointTarget>;
-    close(): Promise<void>;
+    close(cause?: CloseCause): Promise<void>;
 }
 export declare function openEmployeeLease(options: EmployeeLeaseOptions, initialSignal?: AbortSignal): Promise<EmployeeLease>;

package/dist/employee-endpoint.js

@@ -1,3 +1,4 @@
+import { closeCode } from "./close-diagnostics.js";
 import { lstat, realpath } from 'node:fs/promises';
 import { isDeepStrictEqual } from 'node:util';
 import { sameTarget, unwrap } from "./provider.js";
@@ -41,7 +42,7 @@ export async function openEmployeeLease(options, initialSignal) {
         throw fail();
     const request = { instanceId: connection.instanceId, epoch: connection.epoch, workspaceId: workspace.workspaceId, expectedBindingId: items[0].bindingId };
     let target, closed = false, diagnosticFailure;
-    const invalidate = (code) => { if (lifetime.signal.aborted)
+    const invalidate = (code, initiator = 'lease.validate') => { options.closeDiagnostics?.record({ layer: 'endpoint', initiator, reason: code, action: 'invalidate', changes: [{ field: 'lease.aborted', before: lifetime.signal.aborted, after: true }] }); if (lifetime.signal.aborted)
         return; try {
         options.detail({ kind: 'session', severity: 'warning', code: 'CLAUDE_EMPLOYEE_REVOKED', summary: '本机旧绑定已停止派发，在途结果按实际确认；不会重放', payload: { reason: code, workspaceId: request.workspaceId, bindingId: request.expectedBindingId } });
     }
@@ -59,14 +60,14 @@ export async function openEmployeeLease(options, initialSignal) {
             throw fail();
         lifetime.signal.throwIfAborted();
     };
-    const changed = () => { try {
+    const changed = (initiator) => { try {
         current();
     }
     catch {
-        invalidate('EMPLOYEE_CONTEXT_CHANGED');
+        invalidate('EMPLOYEE_CONTEXT_CHANGED', initiator);
     } };
-    offs.push(api.onConnectionState(changed), api.onWorkspaceLocationState(changed), network.onState(event => { if (event?.kind === 'lost' || network.getState().phase !== 'online')
-        invalidate('EMPLOYEE_ENDPOINT_UNAVAILABLE'); }));
+    offs.push(api.onConnectionState(() => changed('lease.connection-change')), api.onWorkspaceLocationState(() => changed('lease.workspace-change')), network.onState(event => { if (event?.kind === 'lost' || network.getState().phase !== 'online')
+        invalidate('EMPLOYEE_ENDPOINT_UNAVAILABLE', 'lease.network-loss'); }));
     async function validate(callerSignal) {
         if (diagnosticFailure)
             throw diagnosticFailure;
@@ -124,7 +125,7 @@ export async function openEmployeeLease(options, initialSignal) {
     }
     try {
         await validate(initialSignal);
-        return { target: structuredClone(target), request: Object.freeze({ ...request }), signal: lifetime.signal, validate, close: async () => { if (!closed) {
+        return { target: structuredClone(target), request: Object.freeze({ ...request }), signal: lifetime.signal, validate, close: async (cause = { layer: 'endpoint', initiator: 'lease.close', reason: 'EMPLOYEE_EXECUTOR_CLOSED', action: 'close' }) => { options.closeDiagnostics?.record({ ...cause, changes: cause.changes ?? [{ field: 'lease.closed', before: closed, after: true }] }); if (!closed) {
                 closed = true;
                 lifetime.abort(fail('EMPLOYEE_EXECUTOR_CLOSED'));
                 for (const off of offs)
@@ -133,6 +134,7 @@ export async function openEmployeeLease(options, initialSignal) {
                 throw diagnosticFailure; } };
     }
     catch (error) {
+        options.closeDiagnostics?.record({ layer: 'endpoint', initiator: 'lease.open-failure', reason: closeCode(error), action: 'failure' });
         for (const off of offs)
             off();
         lifetime.abort();