@ai-workbench/remote-agent 0.8.12 → 0.8.14

package/dist/employee-exec.d.ts

@@ -1,3 +1,4 @@
+import { type CloseCause, type CloseDiagnostics, type CloseObserver } from './close-diagnostics.ts';
 import type { ChildProcessWithoutNullStreams } from 'node:child_process';
 import { NeedError } from './remote.ts';
 export type EmployeeMessage = Record<string, unknown>;
@@ -5,10 +6,11 @@ export interface EmployeeExecutionTransport {
     write(message: EmployeeMessage, signal?: AbortSignal): Promise<void>;
     read(signal?: AbortSignal): Promise<EmployeeMessage | null>;
     /** Closing a carrier never proves that an employee command completed. */
-    close(): void | Promise<void>;
+    close(cause?: CloseCause): void | Promise<void>;
 }
 export interface EmployeeExecutionOptions {
     bindingId: string;
+    closeDiagnostics?: CloseDiagnostics;
     acpMaxMessageBytes: number;
     /** Rechecks the current L CAS/directory/account and N/S five-tuple. No cached permit. */
     validate(signal: AbortSignal): Promise<void>;
@@ -42,12 +44,13 @@ export declare class EmployeeExecution {
     private gate;
     private stop;
     private closeTransport;
-    invalidate(error?: NeedError): void;
+    invalidate(error?: NeedError, cause?: CloseCause): void;
     private cleanup;
-    dispose(): Promise<void>;
+    dispose(cause?: CloseCause): Promise<void>;
     handle(params: unknown, signal?: AbortSignal): Promise<EmployeeExecutionResult>;
+    private handleRequest;
     private open;
     private read;
 }
 /** NDJSON carrier with byte bounds and backpressure derived solely from acpMaxMessageBytes. */
-export declare function createEmployeeProcessTransport(child: ChildProcessWithoutNullStreams, acpMaxMessageBytes: number, stderrCodes?: readonly string[]): EmployeeExecutionTransport;
+export declare function createEmployeeProcessTransport(child: ChildProcessWithoutNullStreams, acpMaxMessageBytes: number, stderrCodes?: readonly string[], observe?: CloseObserver): EmployeeExecutionTransport;

package/dist/employee-exec.js

@@ -1,3 +1,4 @@
+import { closeCode } from "./close-diagnostics.js";
 import { randomUUID } from 'node:crypto';
 import { NeedError } from "./remote.js";
 const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
@@ -80,7 +81,8 @@ export class EmployeeExecution {
     active() { if (this.ended)
         throw this.error ?? need('EMPLOYEE_EXEC_CLOSED'); }
     async gate(signal) { this.active(); cancelled(signal); await waiting(this.options.validate(signal), signal); this.active(); cancelled(signal); }
-    stop(error) {
+    stop(error, cause = { layer: 'executor', initiator: 'executor.stop', reason: closeCode(error, 'EMPLOYEE_EXEC_CLOSED'), action: 'close' }, observe = this.options.closeDiagnostics?.capture()) {
+        observe?.({ ...cause, changes: cause.changes ?? [{ field: 'executor.ended', before: this.ended, after: true }] });
         if (this.ended)
             return;
         this.ended = true;
@@ -89,12 +91,13 @@ export class EmployeeExecution {
         const io = this.io;
         this.io = undefined;
         if (io)
-            this.closeTransport(io);
+            this.closeTransport(io, undefined, observe);
     }
-    closeTransport(io) {
+    closeTransport(io, cause = { layer: 'executor', initiator: 'executor.transport-cleanup', reason: 'EXECUTOR_CLEANUP', action: 'close' }, observe = this.options.closeDiagnostics?.capture()) {
+        observe?.(cause);
         let closing;
         try {
-            closing = Promise.resolve(io.close());
+            closing = Promise.resolve(io.close(cause));
         }
         catch {
             closing = Promise.reject(need('EMPLOYEE_EXEC_UNKNOWN'));
@@ -103,28 +106,32 @@ export class EmployeeExecution {
         // Revocation starts cleanup without a caller waiting yet; retain rejection for close/dispose.
         void this.closing.catch(() => { });
     }
-    invalidate(error = need('EMPLOYEE_CONTEXT_CHANGED')) { this.stop(error); }
+    invalidate(error = need('EMPLOYEE_CONTEXT_CHANGED'), cause) { this.stop(error, cause ?? { layer: 'executor', initiator: 'executor.invalidate', reason: error.code, action: 'invalidate' }); }
     async cleanup() { await this.factoryReceipt; await this.closing; }
-    async dispose() { this.stop(); await this.cleanup(); }
+    async dispose(cause = { layer: 'executor', initiator: 'executor.dispose', reason: 'EXECUTOR_DISPOSE', action: 'dispose' }) { this.stop(undefined, cause); await this.cleanup(); }
     async handle(params, signal) {
-        const request = this.parse(params);
+        const request = this.parse(params), observe = this.options.closeDiagnostics?.capture();
+        const run = () => this.handleRequest(request, signal, observe);
+        return this.options.closeDiagnostics ? this.options.closeDiagnostics.run('employee-exec.' + request.operation, run) : run();
+    }
+    async handleRequest(request, signal, observe) {
         cancelled(signal);
         if (request.operation === 'close') {
-            this.stop();
+            this.stop(undefined, { layer: 'executor', initiator: 'remote.employee-exec.close', reason: 'REMOTE_REASON_UNAVAILABLE', remoteReason: 'unavailable', operation: 'close', action: 'close' }, observe);
             await this.cleanup();
             return { version: 1, closed: true, result: 'UNKNOWN' };
         }
         this.active();
         const current = signal ? AbortSignal.any([signal, this.lifetime.signal]) : this.lifetime.signal;
         if (request.operation === 'open')
-            return this.open(current);
+            return this.open(current, observe);
         if (request.operation === 'read')
-            return this.read(current);
+            return this.read(current, observe);
         const value = encoded(request.message, this.options.acpMaxMessageBytes);
         const size = value.line.byteLength;
         if (this.queuedWriteBytes + size > this.options.acpMaxMessageBytes) {
             const error = need('ACP_MESSAGE_TOO_LARGE');
-            this.stop(error);
+            this.stop(error, { layer: 'executor', initiator: 'executor.write-capacity', reason: error.code, operation: 'write', action: 'failure' }, observe);
             throw error;
         }
         this.queuedWriteBytes += size;
@@ -140,7 +147,7 @@ export class EmployeeExecution {
             }
             catch (error) {
                 const known = this.error ?? failure(error);
-                this.stop(known);
+                this.stop(known, { layer: 'executor', initiator: 'executor.write-failure', reason: known.code, operation: 'write', action: 'failure' }, observe);
                 throw known;
             }
             finally {
@@ -150,7 +157,7 @@ export class EmployeeExecution {
         this.writeTail = operation.catch(() => { });
         return operation;
     }
-    async open(signal) {
+    async open(signal, observe) {
         if (this.opening || this.executionId)
             throw need('EMPLOYEE_EXEC_ALREADY_OPEN');
         this.opening = true;
@@ -158,7 +165,7 @@ export class EmployeeExecution {
             await this.gate(signal);
             // A factory may finish after revoke/abort. Its late executor belongs to this binding and must close.
             const created = Promise.resolve().then(() => { cancelled(signal); return this.options.transport(signal); }).then(async (io) => { if (this.ended || signal.aborted) {
-                this.closeTransport(io);
+                this.closeTransport(io, { layer: 'executor', initiator: 'executor.late-factory', reason: this.error?.code ?? 'ABORTED', operation: 'open', action: 'close' }, observe);
                 await this.closing;
                 throw this.error ?? need('ABORTED');
             } this.io = io; return io; });
@@ -176,14 +183,14 @@ export class EmployeeExecution {
         }
         catch (error) {
             const known = this.error ?? failure(error);
-            this.stop(known);
+            this.stop(known, { layer: 'executor', initiator: 'executor.open-failure', reason: known.code, operation: 'open', action: 'failure' }, observe);
             throw known;
         }
         finally {
             this.opening = false;
         }
     }
-    async read(signal) {
+    async read(signal, observe) {
         if (this.pendingRead)
             throw need('EMPLOYEE_EXEC_READ_BUSY');
         this.pendingRead = true;
@@ -201,7 +208,7 @@ export class EmployeeExecution {
             }
             await this.gate(signal);
             if (message === null) {
-                this.stop();
+                this.stop(undefined, { layer: 'executor', initiator: 'executor.read-eof', reason: 'EXECUTOR_EOF', operation: 'read', action: 'eof' }, observe);
                 return { version: 1, messages: [], closed: true };
             }
             const value = encoded(message, this.options.acpMaxMessageBytes);
@@ -215,7 +222,7 @@ export class EmployeeExecution {
             if (signal.aborted && !this.ended) {
                 if (consumed) {
                     const unknown = need('EMPLOYEE_EXEC_UNKNOWN');
-                    this.stop(unknown);
+                    this.stop(unknown, { layer: 'executor', initiator: 'executor.read-consumed-cancel', reason: unknown.code, operation: 'read', action: 'abort' }, observe);
                     throw unknown;
                 }
                 throw need('ABORTED');
@@ -223,7 +230,7 @@ export class EmployeeExecution {
             if (this.ended && !this.error)
                 return { version: 1, messages: [], closed: true };
             const known = failure(error);
-            this.stop(known);
+            this.stop(known, { layer: 'executor', initiator: 'executor.read-failure', reason: known.code, operation: 'read', action: 'failure' }, observe);
             throw known;
         }
         finally {
@@ -232,7 +239,7 @@ export class EmployeeExecution {
     }
 }
 /** NDJSON carrier with byte bounds and backpressure derived solely from acpMaxMessageBytes. */
-export function createEmployeeProcessTransport(child, acpMaxMessageBytes, stderrCodes = []) {
+export function createEmployeeProcessTransport(child, acpMaxMessageBytes, stderrCodes = [], observe) {
     capacity(acpMaxMessageBytes);
     let partial = Buffer.alloc(0), queuedBytes = 0, writingBytes = 0, closed = false, reason;
     let processClosed = false, terminationRequested = false;
@@ -247,6 +254,7 @@ export function createEmployeeProcessTransport(child, acpMaxMessageBytes, stderr
     const settle = () => { if (!pending)
         return; const reader = pending; pending = undefined; reader.clear(); reason ? reader.reject(reason) : reader.resolve(null); };
     const terminate = () => {
+        observe?.({ layer: 'relay', initiator: 'ssh.terminate', reason: 'TRANSPORT_CLEANUP', action: 'terminate', changes: [{ field: 'transport.termination-requested', before: terminationRequested, after: processClosed || terminationRequested ? terminationRequested : true }] });
         if (processClosed || terminationRequested)
             return;
         terminationRequested = true;
@@ -267,7 +275,8 @@ export function createEmployeeProcessTransport(child, acpMaxMessageBytes, stderr
             receipt.reject(need('EMPLOYEE_EXEC_UNKNOWN'));
         }
     };
-    const finish = (error, kill = false) => {
+    const finish = (error, kill = false, cause = { layer: 'relay', initiator: 'ssh.protocol-failure', reason: closeCode(error, 'TRANSPORT_CLOSED'), action: 'failure' }) => {
+        observe?.({ ...cause, changes: cause.changes ?? [{ field: 'transport.closed', before: closed, after: true }] });
         if (!closed) {
             closed = true;
             reason = error;
@@ -353,9 +362,10 @@ export function createEmployeeProcessTransport(child, acpMaxMessageBytes, stderr
         }
     });
     child.stderr.resume();
-    child.stdin.on('error', () => finish(need(diagnosticCode ?? 'EMPLOYEE_EXEC_UNKNOWN'), true));
-    child.once('error', () => finish(need('EMPLOYEE_EXEC_UNKNOWN'), true));
-    child.once('close', (code, signal) => { processClosed = true; finish(partial.length ? need('EMPLOYEE_EXEC_PROTOCOL_INVALID') : code === 0 && !signal ? undefined : need(diagnosticCode ?? 'EMPLOYEE_EXEC_UNKNOWN')); receipt.resolve(); });
+    child.stdin.on('error', () => finish(need(diagnosticCode ?? 'EMPLOYEE_EXEC_UNKNOWN'), true, { layer: 'relay', initiator: 'ssh.stdin-error', reason: diagnosticCode ?? 'EMPLOYEE_EXEC_UNKNOWN', action: 'failure' }));
+    child.once('error', () => finish(need('EMPLOYEE_EXEC_UNKNOWN'), true, { layer: 'relay', initiator: 'ssh.process-error', reason: 'EMPLOYEE_EXEC_UNKNOWN', action: 'failure' }));
+    child.prependOnceListener('close', (code, signal) => observe?.({ layer: 'relay', initiator: 'ssh.process.close', reason: diagnosticCode ?? (code === 0 && !signal ? 'PROCESS_EXIT' : 'EMPLOYEE_EXEC_UNKNOWN'), action: 'exit', exitCode: code, signal }));
+    child.once('close', (code, signal) => { processClosed = true; finish(partial.length ? need('EMPLOYEE_EXEC_PROTOCOL_INVALID') : code === 0 && !signal ? undefined : need(diagnosticCode ?? 'EMPLOYEE_EXEC_UNKNOWN'), false, { layer: 'relay', initiator: 'ssh.process-close-settle', reason: diagnosticCode ?? (code === 0 && !signal ? 'PROCESS_EXIT' : 'EMPLOYEE_EXEC_UNKNOWN'), action: 'exit', exitCode: code, signal }); receipt.resolve(); });
     return {
         write: async (message, signal) => {
             cancelled(signal);
@@ -364,7 +374,7 @@ export function createEmployeeProcessTransport(child, acpMaxMessageBytes, stderr
             const value = encoded(message, acpMaxMessageBytes);
             if (writingBytes + value.line.byteLength > acpMaxMessageBytes) {
                 const error = need('ACP_MESSAGE_TOO_LARGE');
-                finish(error, true);
+                finish(error, true, { layer: 'relay', initiator: 'ssh.write-capacity', reason: error.code, operation: 'write', action: 'failure' });
                 throw error;
             }
             writingBytes += value.line.byteLength;
@@ -374,19 +384,19 @@ export function createEmployeeProcessTransport(child, acpMaxMessageBytes, stderr
                     return false; done = true; writingBytes -= value.line.byteLength; writes.delete(fail); signal?.removeEventListener('abort', abort); return true; };
                 const fail = (error) => { if (cleanup())
                     reject(error); };
-                const abort = () => { const error = need('EMPLOYEE_EXEC_UNKNOWN'); finish(error, true); fail(error); };
+                const abort = () => { const error = need('EMPLOYEE_EXEC_UNKNOWN'); finish(error, true, { layer: 'relay', initiator: 'ssh.write-abort', reason: error.code, operation: 'write', action: 'abort' }); fail(error); };
                 writes.add(fail);
                 signal?.addEventListener('abort', abort, { once: true });
                 try {
                     child.stdin.write(value.line, error => { if (error) {
-                        finish(need('EMPLOYEE_EXEC_UNKNOWN'), true);
+                        finish(need('EMPLOYEE_EXEC_UNKNOWN'), true, { layer: 'relay', initiator: 'ssh.write-callback', reason: 'EMPLOYEE_EXEC_UNKNOWN', operation: 'write', action: 'failure' });
                         fail(need('EMPLOYEE_EXEC_UNKNOWN'));
                     }
                     else if (cleanup())
                         resolve(); });
                 }
                 catch {
-                    finish(need('EMPLOYEE_EXEC_UNKNOWN'), true);
+                    finish(need('EMPLOYEE_EXEC_UNKNOWN'), true, { layer: 'relay', initiator: 'ssh.write-call', reason: 'EMPLOYEE_EXEC_UNKNOWN', operation: 'write', action: 'failure' });
                     fail(need('EMPLOYEE_EXEC_UNKNOWN'));
                 }
                 if (signal?.aborted)
@@ -418,6 +428,6 @@ export function createEmployeeProcessTransport(child, acpMaxMessageBytes, stderr
                     abort();
             });
         },
-        close: () => { finish(undefined, true); queue.length = 0; queuedBytes = 0; return receipt.promise; }
+        close: (cause = { layer: 'relay', initiator: 'ssh.transport-close', reason: 'TRANSPORT_CLOSE', action: 'close' }) => { finish(undefined, true, cause); queue.length = 0; queuedBytes = 0; return receipt.promise; }
     };
 }

package/dist/employee-mcp.d.ts

@@ -1,3 +1,4 @@
+import { type CloseCause, type CloseDiagnostics, type CloseObserver } from './close-diagnostics.ts';
 import { type Socket } from 'node:net';
 import { type JSONRPCMessage, type Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
@@ -10,6 +11,7 @@ export declare const EMPLOYEE_MCP_TOOLS: Tool[];
 export declare class EmployeeSocketTransport implements Transport {
     private socket;
     private maxBytes;
+    private observeClose?;
     onclose?: () => void;
     onerror?: (error: Error) => void;
     onmessage?: (message: JSONRPCMessage) => void;
@@ -19,13 +21,14 @@ export declare class EmployeeSocketTransport implements Transport {
     get error(): Error | undefined;
     private readonly lifetime;
     readonly signal: AbortSignal;
-    constructor(socket: Socket, maxBytes: number);
+    constructor(socket: Socket, maxBytes: number, observeClose?: CloseObserver | undefined);
     private failed;
     start(): Promise<void>;
     send(message: JSONRPCMessage): Promise<void>;
-    close(): Promise<void>;
+    close(cause?: CloseCause): Promise<void>;
 }
 export interface EmployeeMcpOptions {
+    closeDiagnostics?: CloseDiagnostics;
     lease: EmployeeLease;
     maxBytes: number;
     killGraceMs: number;
@@ -37,6 +40,6 @@ export interface EmployeeMcpOptions {
 export interface EmployeeMcp {
     routing: ReturnType<typeof employeeRouting>;
     signal: AbortSignal;
-    close(): Promise<void>;
+    close(cause?: CloseCause): Promise<void>;
 }
 export declare function openEmployeeMcp(options: EmployeeMcpOptions): Promise<EmployeeMcp>;

package/dist/employee-mcp.js

@@ -1,3 +1,4 @@
+import { closeCode } from "./close-diagnostics.js";
 import { createServer } from 'node:net';
 import { mkdtemp, lstat, rm, access } from 'node:fs/promises';
 import { constants } from 'node:fs';
@@ -20,6 +21,7 @@ export const EMPLOYEE_MCP_TOOLS = [
 export class EmployeeSocketTransport {
     socket;
     maxBytes;
+    observeClose;
     onclose;
     onerror;
     onmessage;
@@ -29,9 +31,10 @@ export class EmployeeSocketTransport {
     get error() { return this.failure; }
     lifetime = new AbortController();
     signal = this.lifetime.signal;
-    constructor(socket, maxBytes) {
+    constructor(socket, maxBytes, observeClose) {
         this.socket = socket;
         this.maxBytes = maxBytes;
+        this.observeClose = observeClose;
     }
     failed(error) { try {
         this.onerror?.(error);
@@ -40,11 +43,11 @@ export class EmployeeSocketTransport {
         this.failure = observation instanceof Error ? observation : new Error('EMPLOYEE_MCP_OBSERVATION_FAILED');
     }
     finally {
-        void this.close();
+        void this.close({ layer: 'relay', initiator: 'mcp.socket-failure', reason: closeCode(error, 'EMPLOYEE_MCP_PROTOCOL_OR_SOCKET_ERROR'), action: 'failure' });
     } }
     async start() {
         this.socket.on('error', error => this.failed(error));
-        this.socket.on('close', () => void this.close());
+        this.socket.on('close', () => void this.close({ layer: 'relay', initiator: 'mcp.socket-peer-close', reason: 'MCP_SOCKET_CLOSED', action: 'close' }));
         this.socket.on('data', (bytes) => {
             try {
                 let cursor = 0;
@@ -71,12 +74,12 @@ export class EmployeeSocketTransport {
             throw new Error('EMPLOYEE_MCP_CLOSED');
         const wire = Buffer.from(JSON.stringify(message) + '\n');
         if (wire.length - 1 > this.maxBytes) {
-            await this.close();
+            await this.close({ layer: 'relay', initiator: 'mcp.send-capacity', reason: 'EMPLOYEE_MCP_MESSAGE_TOO_LARGE', action: 'close' });
             throw new Error('EMPLOYEE_MCP_MESSAGE_TOO_LARGE');
         }
         await new Promise((yes, no) => this.socket.write(wire, error => error ? no(error) : yes()));
     }
-    async close() { if (this.ended)
+    async close(cause = { layer: 'relay', initiator: 'mcp.transport-close', reason: 'MCP_TRANSPORT_CLOSED', action: 'close' }) { this.observeClose?.({ ...cause, changes: cause.changes ?? [{ field: 'mcp.ended', before: this.ended, after: true }] }); if (this.ended)
         return; this.ended = true; this.lifetime.abort(); this.socket.destroy(); this.onclose?.(); }
 }
 export async function openEmployeeMcp(options) {
@@ -85,7 +88,7 @@ export async function openEmployeeMcp(options) {
     if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 1)
         throw new NeedError('SETTINGS_REQUIRED', '本机工具消息容量无效。', 'acpMaxMessageBytes');
     await access('/usr/bin/nc', constants.X_OK);
-    const tools = createEmployeeTools({ cwd: options.lease.target.local.directory.path, shell: options.lease.target.endpoint.endpointShell, uid: options.lease.target.endpoint.remoteUid, maxBytes: options.maxBytes, killGraceMs: options.killGraceMs, detail: observe, runShell: options.runShell, validate: signal => options.lease.validate(signal).then(() => { }) });
+    const tools = createEmployeeTools({ closeDiagnostics: options.closeDiagnostics, cwd: options.lease.target.local.directory.path, shell: options.lease.target.endpoint.endpointShell, uid: options.lease.target.endpoint.remoteUid, maxBytes: options.maxBytes, killGraceMs: options.killGraceMs, detail: observe, runShell: options.runShell, validate: signal => options.lease.validate(signal).then(() => { }) });
     const root = await mkdtemp('/private/tmp/aw-x87-'), socketPath = root + '/mcp';
     try {
         const info = await lstat(root);
@@ -93,19 +96,40 @@ export async function openEmployeeMcp(options) {
             throw new NeedError('EMPLOYEE_MCP_STORAGE_INVALID', '本机工具私有通道不可用。', '当前员工的700私有Unix目录');
     }
     catch (error) {
-        await tools.close();
-        await rm(root, { recursive: true });
+        options.closeDiagnostics?.record({ layer: 'relay', initiator: 'mcp.storage-failure', reason: closeCode(error), action: 'failure' });
+        const failures = [error];
+        try {
+            await tools.close({ layer: 'executor', initiator: 'mcp.storage-cleanup', reason: 'MCP_STORAGE_FAILED', action: 'close' });
+        }
+        catch (cleanup) {
+            failures.push(cleanup);
+        }
+        try {
+            await rm(root, { recursive: true });
+        }
+        catch (cleanup) {
+            failures.push(cleanup);
+        }
+        try {
+            options.closeDiagnostics?.assertRecorded();
+        }
+        catch (reporting) {
+            failures.push(reporting);
+        }
+        if (failures.length > 1)
+            throw new AggregateError(failures, 'EMPLOYEE_MCP_STORAGE_AND_CLEANUP_FAILED');
         throw error;
     }
     const clients = new Set(), transports = new Set();
     let closing, diagnosticFailure;
     const failureLifetime = new AbortController();
     const poison = (error) => {
+        options.closeDiagnostics?.record({ layer: 'relay', initiator: 'mcp.poison', reason: closeCode(error, 'CONVERSATION_DETAILS_FAILED'), action: 'invalidate' });
         diagnosticFailure ??= error;
         failureLifetime.abort(error);
         // Close is memoized synchronously: no fresh connection/call can pass the fence.
-        void options.lease.close().catch(failure => { diagnosticFailure ??= failure; });
-        void close().catch(failure => { diagnosticFailure ??= failure; });
+        void options.lease.close({ layer: 'endpoint', initiator: 'mcp.poison-lease', reason: 'CONVERSATION_DETAILS_FAILED', action: 'close' }).catch(failure => { diagnosticFailure ??= failure; });
+        void close({ layer: 'relay', initiator: 'mcp.poison-close', reason: 'CONVERSATION_DETAILS_FAILED', action: 'close' }).catch(failure => { diagnosticFailure ??= failure; });
     };
     function observeUsing(event, sink) { if (diagnosticFailure)
         throw diagnosticFailure; try {
@@ -118,10 +142,12 @@ export async function openEmployeeMcp(options) {
     function observe(event) { observeUsing(event, options.detail); }
     const server = createServer(socket => {
         if (closing || failureLifetime.signal.aborted || options.lease.signal.aborted) {
+            options.closeDiagnostics?.record({ layer: 'relay', initiator: 'mcp.reject-late-socket', reason: 'MCP_CLOSING', action: 'close' });
             socket.destroy();
             return;
         }
-        const mcp = new Server({ name: 'ai-workbench-employee', version: '0.8.12' }, { capabilities: { tools: {} } }), transport = new EmployeeSocketTransport(socket, options.maxBytes);
+        const observeConnection = options.closeDiagnostics?.child().capture();
+        const mcp = new Server({ name: 'ai-workbench-employee', version: '0.8.14' }, { capabilities: { tools: {} } }), transport = new EmployeeSocketTransport(socket, options.maxBytes, observeConnection);
         clients.add(mcp);
         transports.add(transport);
         mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: EMPLOYEE_MCP_TOOLS }));
@@ -133,40 +159,50 @@ export async function openEmployeeMcp(options) {
             const sink = options.captureDetail?.() ?? options.detail;
             return tools.call(request.params.name, request.params.arguments ?? {}, signal, event => observeUsing(event, sink));
         });
-        mcp.onerror = () => { try {
+        mcp.onerror = () => { observeConnection?.({ layer: 'relay', initiator: 'mcp.server-error', reason: 'EMPLOYEE_MCP_PROTOCOL_OR_TRANSPORT_ERROR', action: 'failure' }); try {
             observe({ kind: 'session', severity: 'warning', code: 'CLAUDE_EMPLOYEE_MCP_UNKNOWN', summary: '本机工具连接出现协议或传输错误；在途结果未知，没有重放' });
         }
         catch (error) {
             poison(error);
         } };
-        mcp.onclose = () => { clients.delete(mcp); transports.delete(transport); };
-        void mcp.connect(transport).catch(() => { socket.destroy(); });
+        mcp.onclose = () => { observeConnection?.({ layer: 'relay', initiator: 'mcp.client-closed', reason: 'MCP_CLIENT_CLOSED', action: 'close' }); clients.delete(mcp); transports.delete(transport); };
+        void mcp.connect(transport).catch(error => { observeConnection?.({ layer: 'relay', initiator: 'mcp.connect-failure', reason: closeCode(error, 'MCP_CONNECT_FAILED'), action: 'close' }); socket.destroy(); });
     });
-    const close = () => closing ??= Promise.resolve().then(async () => {
-        options.lease.signal.removeEventListener('abort', aborted);
-        const errors = [], clean = async (operation) => { try {
-            await operation();
-        }
-        catch (error) {
-            if (!errors.includes(error))
+    const close = (cause = { layer: 'relay', initiator: 'mcp.close', reason: 'MCP_CLOSE_REQUESTED', action: 'close' }) => {
+        options.closeDiagnostics?.record({ ...cause, changes: cause.changes ?? [{ field: 'mcp.closing', before: !!closing, after: true }] });
+        return closing ??= Promise.resolve().then(async () => {
+            options.lease.signal.removeEventListener('abort', aborted);
+            const errors = [], clean = async (operation) => { try {
+                await operation();
+            }
+            catch (error) {
+                if (!errors.includes(error))
+                    errors.push(error);
+            } };
+            for (const transport of transports)
+                await clean(() => transport.close({ layer: 'relay', initiator: 'mcp.cleanup-transport', reason: 'MCP_CLEANUP', action: 'close' }));
+            await Promise.all([...clients].map(client => clean(() => client.close())));
+            await clean(() => tools.close({ layer: 'executor', initiator: 'mcp.cleanup-tools', reason: 'MCP_CLEANUP', action: 'close' }));
+            await clean(() => options.lease.close({ layer: 'endpoint', initiator: 'mcp.cleanup-lease', reason: 'MCP_CLEANUP', action: 'close' }));
+            options.closeDiagnostics?.record({ layer: 'relay', initiator: 'mcp.server-close', reason: 'MCP_CLEANUP', action: 'close' });
+            if (server.listening)
+                await clean(() => new Promise((yes, no) => server.close(error => error ? no(error) : yes())));
+            await clean(() => rm(root, { recursive: true }));
+            if (diagnosticFailure && !errors.includes(diagnosticFailure))
+                errors.unshift(diagnosticFailure);
+            try {
+                options.closeDiagnostics?.assertRecorded();
+            }
+            catch (error) {
                 errors.push(error);
-        } };
-        for (const transport of transports)
-            await clean(() => transport.close());
-        await Promise.all([...clients].map(client => clean(() => client.close())));
-        await clean(() => tools.close());
-        await clean(() => options.lease.close());
-        if (server.listening)
-            await clean(() => new Promise((yes, no) => server.close(error => error ? no(error) : yes())));
-        await clean(() => rm(root, { recursive: true }));
-        if (diagnosticFailure && !errors.includes(diagnosticFailure))
-            errors.unshift(diagnosticFailure);
-        if (errors.length === 1)
-            throw errors[0];
-        if (errors.length)
-            throw new AggregateError(errors, 'EMPLOYEE_MCP_CLEANUP_FAILED');
-    });
-    const aborted = () => { void close().catch(error => { diagnosticFailure ??= error; failureLifetime.abort(error); }); };
+            }
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length)
+                throw new AggregateError(errors, 'EMPLOYEE_MCP_CLEANUP_FAILED');
+        });
+    };
+    const aborted = () => { void close({ layer: 'endpoint', initiator: 'mcp.lease-abort', reason: closeCode(options.lease.signal.reason, 'EMPLOYEE_CONTEXT_CHANGED'), action: 'abort' }).catch(error => { diagnosticFailure ??= error; failureLifetime.abort(error); }); };
     try {
         await new Promise((yes, no) => { server.once('error', no); server.listen(socketPath, () => { server.removeListener('error', no); yes(); }); });
         options.lease.signal.addEventListener('abort', aborted, { once: true });
@@ -175,7 +211,7 @@ export async function openEmployeeMcp(options) {
         return { routing: employeeRouting(options.lease.target, socketPath, options.maxBytes), signal: failureLifetime.signal, close };
     }
     catch (error) {
-        await close();
+        await close({ layer: 'relay', initiator: 'mcp.open-failure', reason: closeCode(error, 'MCP_OPEN_FAILED'), action: 'failure' });
         throw error;
     }
 }