feat(companion): add direct disconnect metadata getters

README.md

@@ -1190,7 +1190,7 @@ Methods:
 - `system.capabilities` returns gateway protocol and node policy snapshot.
 
 Companion runtime helper:
-- `src/companion/runtimeClient.ts` provides a typed Node/WebSocket client for companion runtimes (macOS/iOS/Android workers) with wrappers for `node.register`, `node.capabilities.get`, `node.location.set/get`, `node.status.set`, `node.push_token.set`, `system.capabilities`, `system.nodes`, and canvas artifact RPCs (`canvas.put/get/list/delete/clear`), plus convenience helpers (`bootstrapNode`, optional `autoConnect`, `dispose()`, `waitForIdle()` for pending-work drain synchronization) and event helpers (`subscribeEvents()`, `subscribeEvent()`, `subscribeAgentStream()`, `subscribeAgentTyping()`, `subscribeContextWarning()`, `waitForEvent()` with timeout/predicate/abort support plus event-name/timeout validation and deterministic teardown cancellation including socket-close rejection, `waitForAnyEvent()` with event-list/timeout validation, `waitForAgentStream()`, `waitForAgentTyping()`, `waitForContextWarning()`, `clearEventSubscriptions()` returning cleared-subscription/cancelled-wait counts, `cancelPendingEventWaits()` returning cancelled waiter count, `listKnownEventNames()`, `eventSubscriptionCount`) plus in-flight observability via `pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, `getPendingWorkSnapshot()`, `getEventSurfaceSnapshot()`, and `getConnectionSnapshot()` (including `lastDisconnectCode`/`lastDisconnectReason`).
+- `src/companion/runtimeClient.ts` provides a typed Node/WebSocket client for companion runtimes (macOS/iOS/Android workers) with wrappers for `node.register`, `node.capabilities.get`, `node.location.set/get`, `node.status.set`, `node.push_token.set`, `system.capabilities`, `system.nodes`, and canvas artifact RPCs (`canvas.put/get/list/delete/clear`), plus convenience helpers (`bootstrapNode`, optional `autoConnect`, `dispose()`, `waitForIdle()` for pending-work drain synchronization) and event helpers (`subscribeEvents()`, `subscribeEvent()`, `subscribeAgentStream()`, `subscribeAgentTyping()`, `subscribeContextWarning()`, `waitForEvent()` with timeout/predicate/abort support plus event-name/timeout validation and deterministic teardown cancellation including socket-close rejection, `waitForAnyEvent()` with event-list/timeout validation, `waitForAgentStream()`, `waitForAgentTyping()`, `waitForContextWarning()`, `clearEventSubscriptions()` returning cleared-subscription/cancelled-wait counts, `cancelPendingEventWaits()` returning cancelled waiter count, `listKnownEventNames()`, `eventSubscriptionCount`) plus in-flight observability via `pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, `lastDisconnectCode`, `lastDisconnectReason`, `getPendingWorkSnapshot()`, `getEventSurfaceSnapshot()`, and `getConnectionSnapshot()` (including disconnect metadata).
 - `src/companion/platformClients.ts` provides platform-focused wrappers:
   - `MacOSCompanionClient` (`platform: "macos"`, APNs push registration)
   - `IOSCompanionClient` (`platform: "ios"`, APNs push registration)
@@ -1201,7 +1201,7 @@ Companion runtime helper:
   - optional `defaultSessionId` for canvas helper calls so `sessionId` can be omitted per call
   - lifecycle passthroughs for connection state/teardown (`connected`, `disconnect(code?, reason?)`, `dispose(code?, reason?)`)
   - stream passthrough helpers (`subscribeEvents`, `subscribeEvent`, `clearEventSubscriptions`, `cancelPendingEventWaits`, `listKnownEventNames`, `eventSubscriptionCount`, `subscribeAgentStream/Typing/ContextWarning`, `waitForEvent`, `waitForAnyEvent`, `waitForAgentStream/Typing/ContextWarning`)
-  - runtime observability/control passthroughs (`pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, `getPendingWorkSnapshot()`, `getEventSurfaceSnapshot()`, `getConnectionSnapshot()`, `connected`, `waitForIdle()`)
+  - runtime observability/control passthroughs (`pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, `lastDisconnectCode`, `lastDisconnectReason`, `getPendingWorkSnapshot()`, `getEventSurfaceSnapshot()`, `getConnectionSnapshot()`, `connected`, `waitForIdle()`)
 - `src/companion/heartbeatLoop.ts` provides `CompanionHeartbeatLoop` for periodic heartbeat scheduling (`publishHeartbeat`) with start/stop safety, optional interval jitter (`jitterRatio`) to spread load (with safe normalization for invalid random samples), `tickNow()` for manual sends, success/error hooks, loop observability (`successCount`, `lastSuccessAt`, `failureCount`, `lastFailure`, `getState()`), and optional auto-stop after repeated failures.
 
 ## Canvas / A2UI Foundation

docs/plans/state.json

@@ -1236,6 +1236,22 @@
       ],
       "test_status": "pnpm test:run src/companion/runtimeClient.test.ts src/companion/platformClients.test.ts src/companion/platformClients.integration.test.ts src/companion/heartbeatLoop.test.ts + pnpm typecheck passing"
     },
+    "companion-runtime-disconnect-metadata-direct-getters": {
+      "status": "completed",
+      "date": "2026-02-17",
+      "updated": "2026-02-17",
+      "summary": "Added direct runtime/platform observability getters for disconnect metadata (`lastDisconnectCode`, `lastDisconnectReason`) so companion callers can read lifecycle teardown details without building full connection snapshots.",
+      "files_modified": [
+        "src/companion/runtimeClient.ts",
+        "src/companion/runtimeClient.test.ts",
+        "src/companion/platformClients.ts",
+        "src/companion/platformClients.test.ts",
+        "src/companion/platformClients.integration.test.ts",
+        "README.md",
+        "docs/plans/state.json"
+      ],
+      "test_status": "pnpm test:run src/companion/runtimeClient.test.ts src/companion/platformClients.test.ts src/companion/platformClients.integration.test.ts src/companion/heartbeatLoop.test.ts + pnpm typecheck passing"
+    },
     "browser-tools-activation-clarity": {
       "status": "completed",
       "date": "2026-02-17",
@@ -5034,7 +5050,7 @@
     }
   },
   "overall_progress": {
-    "total_test_count": 1879,
+    "total_test_count": 1881,
     "all_tests_passing": true,
     "p0_completion": "3/3 (100%)",
     "p1_completion": "4/4 (100%)",

src/companion/platformClients.integration.test.ts

@@ -340,6 +340,8 @@ describe('platform clients integration', () => {
     expect(client.connected).toBe(true);
     client.disconnect(4100, 'manual platform stop');
     expect(client.connected).toBe(false);
+    expect(client.lastDisconnectCode).toBe(4100);
+    expect(client.lastDisconnectReason).toBe('manual platform stop');
     expect(client.getConnectionSnapshot()).toEqual({
       connected: false,
       eventSubscriptionCount: 0,

src/companion/platformClients.test.ts

@@ -47,6 +47,8 @@ function createRuntimeMock(): {
   pendingEventWaitCount: number;
   hasPendingWork: boolean;
   idle: boolean;
+  lastDisconnectCode: number | undefined;
+  lastDisconnectReason: string | undefined;
   connected: boolean;
 } {
   const connect = vi.fn(async () => undefined);
@@ -112,6 +114,8 @@ function createRuntimeMock(): {
   const pendingEventWaitCount = 1;
   const hasPendingWork = true;
   const idle = false;
+  const lastDisconnectCode = 1000;
+  const lastDisconnectReason = 'normal closure';
   const connected = true;
 
   const runtime = {
@@ -164,6 +168,12 @@ function createRuntimeMock(): {
     get idle() {
       return idle;
     },
+    get lastDisconnectCode() {
+      return lastDisconnectCode;
+    },
+    get lastDisconnectReason() {
+      return lastDisconnectReason;
+    },
     get connected() {
       return connected;
     },
@@ -210,6 +220,8 @@ function createRuntimeMock(): {
     pendingEventWaitCount,
     hasPendingWork,
     idle,
+    lastDisconnectCode,
+    lastDisconnectReason,
     connected,
   };
 }
@@ -394,6 +406,14 @@ describe('platform companion clients', () => {
     expect(client.idle).toBe(mock.idle);
   });
 
+  it('platform disconnect metadata getters forward runtime values', async () => {
+    const mock = createRuntimeMock();
+    const client = new IOSCompanionClient({ runtime: mock.runtime, nodeId: 'ios-node' });
+
+    expect(client.lastDisconnectCode).toBe(mock.lastDisconnectCode);
+    expect(client.lastDisconnectReason).toBe(mock.lastDisconnectReason);
+  });
+
   it('platform waitForIdle forwards options to runtime client', async () => {
     const mock = createRuntimeMock();
     const client = new IOSCompanionClient({ runtime: mock.runtime, nodeId: 'ios-node' });

src/companion/platformClients.ts

@@ -300,6 +300,14 @@ export class MacOSCompanionClient {
     return this.runtime.idle;
   }
 
+  get lastDisconnectCode(): number | undefined {
+    return this.runtime.lastDisconnectCode;
+  }
+
+  get lastDisconnectReason(): string | undefined {
+    return this.runtime.lastDisconnectReason;
+  }
+
   getPendingWorkSnapshot(): PendingWorkSnapshot {
     return this.runtime.getPendingWorkSnapshot();
   }
@@ -578,6 +586,14 @@ export class IOSCompanionClient {
     return this.runtime.idle;
   }
 
+  get lastDisconnectCode(): number | undefined {
+    return this.runtime.lastDisconnectCode;
+  }
+
+  get lastDisconnectReason(): string | undefined {
+    return this.runtime.lastDisconnectReason;
+  }
+
   getPendingWorkSnapshot(): PendingWorkSnapshot {
     return this.runtime.getPendingWorkSnapshot();
   }
@@ -854,6 +870,14 @@ export class AndroidCompanionClient {
     return this.runtime.idle;
   }
 
+  get lastDisconnectCode(): number | undefined {
+    return this.runtime.lastDisconnectCode;
+  }
+
+  get lastDisconnectReason(): string | undefined {
+    return this.runtime.lastDisconnectReason;
+  }
+
   getPendingWorkSnapshot(): PendingWorkSnapshot {
     return this.runtime.getPendingWorkSnapshot();
   }

src/companion/runtimeClient.test.ts

@@ -797,6 +797,8 @@ describe('CompanionRuntimeClient', () => {
       lastDisconnectCode: 4100,
       lastDisconnectReason: 'manual stop',
     });
+    expect(client.lastDisconnectCode).toBe(4100);
+    expect(client.lastDisconnectReason).toBe('manual stop');
   });
 
   it('connection snapshot tracks transport close code and reason', async () => {

src/companion/runtimeClient.ts

@@ -315,8 +315,8 @@ export class CompanionRuntimeClient {
   private pending = new Map<number, PendingRequest>();
   private readonly eventHandlers = new Set<CompanionEventHandler>();
   private readonly pendingEventWaits = new Set<(error: Error) => void>();
-  private lastDisconnectCode: number | undefined;
+  private _lastDisconnectCode: number | undefined;
-  private lastDisconnectReason: string | undefined;
+  private _lastDisconnectReason: string | undefined;
 
   constructor(options: CompanionRuntimeClientOptions) {
     const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
@@ -354,6 +354,14 @@ export class CompanionRuntimeClient {
     return !this.hasPendingWork;
   }
 
+  get lastDisconnectCode(): number | undefined {
+    return this._lastDisconnectCode;
+  }
+
+  get lastDisconnectReason(): string | undefined {
+    return this._lastDisconnectReason;
+  }
+
   getPendingWorkSnapshot(): PendingWorkSnapshot {
     return {
       pendingRequestCount: this.pendingRequestCount,
@@ -378,8 +386,8 @@ export class CompanionRuntimeClient {
       pendingEventWaitCount: this.pendingEventWaitCount,
       hasPendingWork: this.hasPendingWork,
       idle: this.idle,
-      lastDisconnectCode: this.lastDisconnectCode,
+      lastDisconnectCode: this._lastDisconnectCode,
-      lastDisconnectReason: this.lastDisconnectReason,
+      lastDisconnectReason: this._lastDisconnectReason,
     };
   }
 
@@ -413,9 +421,9 @@ export class CompanionRuntimeClient {
         this.ws.on('message', (raw) => this.handleMessage(raw.toString()));
         this.ws.on('close', (code, reason) => {
           if (this.ws === ws) {
-            this.lastDisconnectCode = code;
+            this._lastDisconnectCode = code;
             const reasonText = reason?.toString().trim();
-            this.lastDisconnectReason = reasonText ? reasonText : undefined;
+            this._lastDisconnectReason = reasonText ? reasonText : undefined;
             this.ws = null;
             this.rejectAllPending(new Error('WebSocket closed'));
             this.rejectEventWaits(new Error('WebSocket closed'));
@@ -454,8 +462,8 @@ export class CompanionRuntimeClient {
   }
 
   disconnect(code?: number, reason?: string): void {
-    this.lastDisconnectCode = code;
+    this._lastDisconnectCode = code;
-    this.lastDisconnectReason = reason;
+    this._lastDisconnectReason = reason;
     if (!this.ws) {
       this.rejectEventWaits(new Error('Disconnected'));
       return;