@ai-workbench/remote-agent 0.8.13 → 0.8.15

package/dist/broker-runtime.js

@@ -6,6 +6,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { CloseDiagnostics, closeCode, flushCloseDiagnostics } from "./close-diagnostics.js";
 import { BrokerTransport, brokerCommand, brokerId, legacyBrokerId, sshIo, controlJson } from "./broker.js";
 import { CODEX_AGENT } from "./agents.js";
 import { protectedOneShotLayout } from "./host-layout.js";
@@ -63,15 +64,24 @@ export function brokerFactory(get, _ask, configuration, provided) {
         const contextBoundScope = recoveryKey([...scopeParts, request.contextSha256]);
         // A Codex ACP process can own several immutable native sessions. D18's durable
         // pointer controls their context; the broker still binds every transport identity.
-        const scope = agent.loginProvider === 'codex' ? recoveryKey([...scopeParts, undefined]) : contextBoundScope;
+        const scope = recoveryKey([...scopeParts, undefined]);
+        const previousContextScope = agent.loginProvider === 'claude' && request.previousContextSha256 ? recoveryKey([...scopeParts, request.previousContextSha256]) : contextBoundScope;
         const existing = request.retainProcess ? retained.get(key) : undefined;
         if (existing) {
             if (existing.scope !== scope)
                 throw need('SESSION_CONTEXT_MISMATCH');
             if (existing.runtime.broker?.error)
                 throw existing.runtime.broker.error;
+            if (request.requireFreshSession) {
+                if (existing.runtime.broker?.promptInFlight)
+                    throw need('INPUT_DELIVERY_UNCONFIRMED');
+                await existing.runtime.dispose?.({ layer: 'broker', initiator: 'broker.fresh-session-required', reason: 'PRIVATE_RECOVERY_POINTER_ABSENT', action: 'dispose' });
+                return open(target, project, request);
+            }
             existing.update(request);
             existing.runtime.restartNotice = undefined;
+            existing.runtime.restartInputIds = undefined;
+            existing.runtime.freshSessionConfirmed = undefined;
             existing.runtime.recoveredSession = undefined;
             return existing.runtime;
         }
@@ -83,7 +93,7 @@ export function brokerFactory(get, _ask, configuration, provided) {
             if (!journal)
                 throw need('RECOVERY_STORAGE_REQUIRED');
             let state = await journal.read();
-            const legacyContextScope = !!state && state.scope !== scope && agent.loginProvider === 'codex' && state.scope === contextBoundScope;
+            const legacyContextScope = !!state && state.scope !== scope && state.scope === previousContextScope;
             if (state && state.scope !== scope && !legacyContextScope)
                 throw need(agent.loginProvider === 'codex' ? 'RECOVERY_CONTEXT_POLICY_UNSUPPORTED' : 'SESSION_CONTEXT_MISMATCH');
             if (legacyContextScope && state?.phase !== 'clean')
@@ -106,9 +116,11 @@ export function brokerFactory(get, _ask, configuration, provided) {
             const report = async (code, extra = {}, cleanup = false) => { request.detailChannel?.record({ kind: 'need', severity: 'warning', code, summary: '远端会话恢复状态：' + code, payload: extra }); await request.detailChannel?.flush(); await validate(cleanup); };
             const list = async (cleanup = false) => timing.run('broker-list', async () => { const rows = controlJson(await io.run(command(['list']), cleanup ? undefined : request.signal)); if (!Array.isArray(rows) || rows.some(row => typeof row?.id !== 'string'))
                 throw need('BROKER_PROTOCOL_INVALID'); return rows; });
+            const detailSink = request.detailChannel;
+            const closeDiagnostics = request.closeDiagnostics ?? new CloseDiagnostics(event => detailSink?.record(event));
             let rows = await list();
             const id = brokerId(request.sessionId, employeeScope ? agent.id + '/employee/' + employeeScope : agent.id), oldId = legacyBrokerId(request.sessionId, agent.id);
-            let restarted = false;
+            let restarted = !!request.requireFreshSession;
             const attachArgs = (entry, after) => ['attach', entry.id, '--after', String(after), '--framed', ...(modern(entry) ? ['--leased', '--if-instance', entry.instanceId] : [])];
             const connectWithLease = async (transport, entry, cleanup = false) => {
                 try {
@@ -143,13 +155,13 @@ export function brokerFactory(get, _ask, configuration, provided) {
                 }
             };
             const claim = async (entry, cleanup = false) => {
-                const probe = new BrokerTransport({ discardOutput: true, onNeed: n => request.detailChannel?.record({ kind: 'need', severity: 'warning', code: n.code, summary: '主机会话连接状态', payload: { brokerId: entry.id, instanceId: entry.instanceId ?? null } }), maxFrameBytes: settings.brokerMaxFrameBytes, initialSequence: entry.lastSequence, instanceId: entry.instanceId, leased: modern(entry), controlMaxBytes: entry.controlMaxBytes, attach: after => io.attach(command(attachArgs(entry, after))) });
+                const probe = new BrokerTransport({ observeClose: closeDiagnostics.child().capture(), discardOutput: true, onNeed: n => request.detailChannel?.record({ kind: 'need', severity: 'warning', code: n.code, summary: '主机会话连接状态', payload: { brokerId: entry.id, instanceId: entry.instanceId ?? null } }), maxFrameBytes: settings.brokerMaxFrameBytes, initialSequence: entry.lastSequence, instanceId: entry.instanceId, leased: modern(entry), controlMaxBytes: entry.controlMaxBytes, attach: after => io.attach(command(attachArgs(entry, after))) });
                 try {
                     await connectWithLease(probe, entry, cleanup);
                 }
                 catch (error) {
                     if (!(entry.state === 'exited' && error instanceof NeedError && error.code === 'AGENT_EXITED')) {
-                        probe.close();
+                        probe.close({ layer: 'broker', initiator: 'broker.probe-close', reason: 'BROKER_PROBE_FINISHED', action: 'close' });
                         throw error;
                     }
                 }
@@ -183,7 +195,7 @@ export function brokerFactory(get, _ask, configuration, provided) {
                         throw need('REMOTE_CLEANUP_UNCONFIRMED');
                 }
                 finally {
-                    probe.close();
+                    probe.close({ layer: 'broker', initiator: 'broker.probe-close', reason: 'BROKER_PROBE_FINISHED', action: 'close' });
                 }
             };
             const legacy = employeeScope ? undefined : rows.find(row => row.id === oldId);
@@ -192,13 +204,13 @@ export function brokerFactory(get, _ask, configuration, provided) {
             let entry = rows.find(row => row.id === id);
             if (entry)
                 validEntry(entry);
-            if (legacyContextScope && !entry)
+            if (legacyContextScope && !entry && !request.requireFreshSession)
                 throw need('RECOVERY_CONTEXT_POLICY_UNSUPPORTED');
             if (legacy && !entry)
                 restarted = true;
             let transport;
             let resume;
-            const build = (entry, after, recovery) => new BrokerTransport({ onNeed: n => request.detailChannel?.record({ kind: 'need', severity: 'warning', code: n.code, summary: '主机会话连接状态', payload: { brokerId: entry.id, instanceId: entry.instanceId } }), maxFrameBytes: settings.brokerMaxFrameBytes, maxMessageBytes: request.acpMaxMessageBytes ?? settings.brokerMaxFrameBytes, initialSequence: after, instanceId: entry.instanceId, leased: true, controlMaxBytes: entry.controlMaxBytes, beforeInput: async () => { await validate(); if (state?.phase !== 'dirty' || state.instanceId !== entry.instanceId) {
+            const build = (entry, after, recovery) => new BrokerTransport({ observeClose: closeDiagnostics.capture(), onNeed: n => request.detailChannel?.record({ kind: 'need', severity: 'warning', code: n.code, summary: '主机会话连接状态', payload: { brokerId: entry.id, instanceId: entry.instanceId } }), maxFrameBytes: settings.brokerMaxFrameBytes, maxMessageBytes: request.acpMaxMessageBytes ?? settings.brokerMaxFrameBytes, initialSequence: after, instanceId: entry.instanceId, leased: true, controlMaxBytes: entry.controlMaxBytes, beforeInput: async () => { await validate(); if (state?.phase !== 'dirty' || state.instanceId !== entry.instanceId) {
                     const dirty = { version: 1, scope, brokerId: id, instanceId: entry.instanceId, pid: entry.pid, phase: 'dirty' };
                     await journal.write(dirty);
                     state = dirty;
@@ -225,6 +237,15 @@ export function brokerFactory(get, _ask, configuration, provided) {
             if (entry) {
                 if (!modern(entry))
                     throw need('BROKER_CAPABILITY_REQUIRED');
+                if (request.requireFreshSession) {
+                    if (!state || !['clean', 'ended'].includes(state.phase) || state.instanceId !== entry.instanceId)
+                        throw need('INPUT_DELIVERY_UNCONFIRMED');
+                    await stop(entry, 'PRIVATE_RECOVERY_POINTER_ABSENT');
+                    restarted = true;
+                    entry = undefined;
+                }
+            }
+            if (entry) {
                 const clean = !employeeScope && state?.phase === 'clean' && state.instanceId === entry.instanceId && state.acp?.sessionId === request.resumeSessionId && state.checkpointId === request.recoveryCheckpointId && state.cursor >= entry.firstSequence - 1 && state.cursor <= entry.lastSequence && entry.state === 'running' && (legacyContextScope ? await request.verifyRecovery?.() === true : await request.verifyRecovery?.() !== false);
                 if (legacyContextScope && !clean)
                     throw need('RECOVERY_CONTEXT_POLICY_UNSUPPORTED');
@@ -237,14 +258,14 @@ export function brokerFactory(get, _ask, configuration, provided) {
                         await validate();
                         if (legacyContextScope) {
                             const migrated = { ...state, scope };
-                            await report('CODEX_RECOVERY_SCOPE_MIGRATED', { oldScope: state.scope, newScope: scope, sessionId: state.acp.sessionId, checkpointId: state.checkpointId, instanceId: entry.instanceId, cursor: state.cursor });
+                            await report(agent.loginProvider === 'codex' ? 'CODEX_RECOVERY_SCOPE_MIGRATED' : 'CLAUDE_RECOVERY_SCOPE_MIGRATED', { oldScope: state.scope, newScope: scope, sessionId: state.acp.sessionId, checkpointId: state.checkpointId, instanceId: entry.instanceId, cursor: state.cursor });
                             await journal.write(migrated);
                             state = migrated;
                         }
                         resume = state.acp;
                     }
                     catch (error) {
-                        transport.close();
+                        transport.close({ layer: 'broker', initiator: 'broker.replay-failure', reason: closeCode(error, 'RECOVERY_UNCONFIRMED'), action: 'close' });
                         if (legacyContextScope || error instanceof NeedError && ['ATTACH_BUSY', 'SESSION_IN_USE', 'SESSION_INSTANCE_MISMATCH', 'ABORTED'].includes(error.code))
                             throw error;
                         await report('SESSION_REPLAY_UNRECOVERABLE', { brokerId: id, instanceId: entry.instanceId, reason: error instanceof NeedError ? error.code : 'UNKNOWN_FAILURE', recordedCursor: state?.cursor ?? null, firstSequence: entry.firstSequence, lastSequence: entry.lastSequence });
@@ -274,7 +295,7 @@ export function brokerFactory(get, _ask, configuration, provided) {
                 validEntry(entry);
                 transport = build(entry, 0);
                 const opening = transport;
-                const aborted = () => opening.fail(need('ABORTED'));
+                const aborted = () => opening.fail(need('ABORTED'), { layer: 'broker', initiator: 'broker.open-signal', reason: 'ABORTED', action: 'abort' });
                 request.signal?.addEventListener('abort', aborted, { once: true });
                 try {
                     request.signal?.throwIfAborted();
@@ -284,7 +305,7 @@ export function brokerFactory(get, _ask, configuration, provided) {
                 catch (error) {
                     if (!(error instanceof NeedError && ['ATTACH_BUSY', 'SESSION_IN_USE', 'SESSION_INSTANCE_MISMATCH'].includes(error.code)))
                         await stop(entry, 'SESSION_OPEN_FAILED', opening, true, true);
-                    opening.close();
+                    opening.close({ layer: 'broker', initiator: 'broker.open-failure', reason: closeCode(error), action: 'close' });
                     throw error;
                 }
                 finally {
@@ -294,8 +315,8 @@ export function brokerFactory(get, _ask, configuration, provided) {
             const ownedEntry = entry, ownedTransport = transport;
             let disposed = false;
             let disposal;
-            const runtime = { identity: identity(target), cwd: project.path, broker: ownedTransport, acpTransport: ownedTransport,
-                ...(resume ? { recoveredSession: resume } : {}), ...(restarted ? { restartNotice: '上次会话无法接回，已新建会话；本次从你的这条请求继续。', restartInputIds: request.currentInputIds } : {}),
+            const runtime = { closeDiagnostics, identity: identity(target), cwd: project.path, broker: ownedTransport, acpTransport: ownedTransport,
+                ...(resume ? { recoveredSession: resume } : {}), ...(restarted ? { restartNotice: '上次会话无法接回，已新建会话；本次从你的这条请求继续。', restartInputIds: request.currentInputIds } : {}), ...(request.requireFreshSession ? { freshSessionConfirmed: true } : {}),
                 saveCheckpoint: async (checkpointId, acp) => { await validate(); const saved = await ownedTransport.commitCheckpoint(async (cursor) => { await validate(); const clean = { version: 1, phase: 'clean', scope, brokerId: id, instanceId: ownedEntry.instanceId, pid: ownedEntry.pid, cursor, checkpointId, acp }; try {
                     await journal.write(clean);
                     state = clean;
@@ -305,24 +326,29 @@ export function brokerFactory(get, _ask, configuration, provided) {
                     throw error;
                 } }); if (!saved)
                     await report('SESSION_CHECKPOINT_NOT_CLEAN', { brokerId: id, instanceId: ownedEntry.instanceId }); return saved; },
-                detach: async () => { ownedTransport.close(); active.delete(key); retained.delete(key); },
-                dispose: () => disposal ??= (async () => { if (disposed)
-                    return; try {
+                detach: async (cause = { layer: 'broker', initiator: 'broker.runtime-detach', reason: 'BROKER_DETACH', action: 'detach' }) => { const sink = request.detailChannel; closeDiagnostics.record(cause); ownedTransport.close(cause); active.delete(key); retained.delete(key); await flushCloseDiagnostics(closeDiagnostics, sink ? () => sink.flush() : undefined); },
+                dispose: (cause = { layer: 'broker', initiator: 'broker.runtime-dispose', reason: 'BROKER_DISPOSE', action: 'dispose' }) => { const sink = request.detailChannel; closeDiagnostics.record(cause); return disposal ??= (async () => { if (disposed)
+                    return; let primary; try {
                     await stop(ownedEntry, 'SESSION_ENDED', ownedTransport, true);
                     await journal.write({ version: 1, phase: 'ended', scope, brokerId: id, instanceId: ownedEntry.instanceId, pid: ownedEntry.pid });
                     disposed = true;
                 }
+                catch (error) {
+                    primary = { error };
+                }
                 finally {
-                    ownedTransport.close();
+                    ownedTransport.close({ layer: 'broker', initiator: 'broker.dispose-finally', reason: 'BROKER_DISPOSE_CLEANUP', action: 'close' });
                     active.delete(key);
                     retained.delete(key);
-                } })(), };
+                } await flushCloseDiagnostics(closeDiagnostics, sink ? () => sink.flush() : undefined, primary); })(); },
+            };
             if (employeeScope) {
                 runtime.saveCheckpoint = undefined;
                 runtime.detach = runtime.dispose;
             }
             if (request.retainProcess)
-                retained.set(key, { runtime, scope, update: next => { request = next; timing = next.timing ?? new StageTiming(); } });
+                retained.set(key, { runtime, scope, update: next => { const sink = next.detailChannel; if (sink)
+                        closeDiagnostics.bind(event => sink.record(event)); request = next; timing = next.timing ?? new StageTiming(); } });
             return runtime;
         }
         catch (error) {

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,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { CLAUDE_EMPLOYEE_SCOPE_NOTICE as NOTICE } from "./employee-presentation.js";
+import { CloseDiagnostics, closeCode } from "./close-diagnostics.js";
 import { isDeepStrictEqual } from 'node:util';
 import { openEmployeeLease } from "./employee-endpoint.js";
 import { openEmployeeMcp } from "./employee-mcp.js";
@@ -15,7 +17,6 @@ import { sshIo } from "./broker.js";
 import { NeedError, shellQuote } from "./remote.js";
 import { awaitL } from "./provider.js";
 const failure = (code) => new NeedError(code, '当前本机执行上下文无法确认，本轮已停止；没有改在主机执行。', 'L当前本地绑定、N员工端点与S同代桥');
-const NOTICE = '本轮六类文件与命令工具在你的电脑执行，使用你选择的文件夹；Git也使用本机仓库。子代理和内部直接调用尚不支持本机，可能仍在主机；已识别的此类审批不会执行。PDF等二进制读取、后台命令暂不支持。';
 /** Local source only. Host and legacy-host remain with the original provider. */
 export function createClaudeLocalProvider(options) {
     const entries = new Map();
@@ -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>;