@ai-workbench/remote-agent 0.8.13 → 0.8.15

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();

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>;