feat(companion): forward dispose close params on platform clients

README.md

@@ -1199,7 +1199,7 @@ Companion runtime helper:
   - shared `publishHeartbeat()` helper for periodic `node.status.set` updates with safe defaults
   - `createHeartbeatLoop()` convenience helper that returns a bound `CompanionHeartbeatLoop`
   - optional `defaultSessionId` for canvas helper calls so `sessionId` can be omitted per call
-  - lifecycle passthroughs for connection state/teardown (`connected`, `dispose()`)
+  - lifecycle passthroughs for connection state/teardown (`connected`, `dispose(code?, reason?)`)
   - stream passthrough helpers (`subscribeEvents`, `subscribeEvent`, `clearEventSubscriptions`, `listKnownEventNames`, `eventSubscriptionCount`, `subscribeAgentStream/Typing/ContextWarning`, `waitForEvent`, `waitForAnyEvent`, `waitForAgentStream/Typing/ContextWarning`)
 - `src/companion/heartbeatLoop.ts` provides `CompanionHeartbeatLoop` for periodic heartbeat scheduling (`publishHeartbeat`) with start/stop safety, optional interval jitter (`jitterRatio`) to spread load, `tickNow()` for manual sends, success/error hooks, failure observability (`failureCount`, `lastFailure`, `getState()`), and optional auto-stop after repeated failures.
 

docs/plans/state.json

@@ -712,6 +712,19 @@
       ],
       "test_status": "pnpm test:run src/companion/platformClients.test.ts src/companion/runtimeClient.test.ts src/companion/heartbeatLoop.test.ts src/companion/platformClients.integration.test.ts + pnpm typecheck passing"
     },
+    "companion-platform-dispose-close-params": {
+      "status": "completed",
+      "date": "2026-02-17",
+      "updated": "2026-02-17",
+      "summary": "Extended platform client `dispose()` to accept optional WebSocket close `code`/`reason` and forward them to runtime disposal for explicit teardown signaling.",
+      "files_modified": [
+        "src/companion/platformClients.ts",
+        "src/companion/platformClients.test.ts",
+        "README.md",
+        "docs/plans/state.json"
+      ],
+      "test_status": "pnpm test:run src/companion/platformClients.test.ts src/companion/runtimeClient.test.ts src/companion/heartbeatLoop.test.ts src/companion/platformClients.integration.test.ts + pnpm typecheck passing"
+    },
     "browser-tools-activation-clarity": {
       "status": "completed",
       "date": "2026-02-17",

src/companion/platformClients.test.ts

@@ -210,6 +210,15 @@ describe('platform companion clients', () => {
     expect(mock.dispose).toHaveBeenCalledOnce();
   });
 
+  it('platform dispose forwards close code and reason', async () => {
+    const mock = createRuntimeMock();
+    const client = new AndroidCompanionClient({ runtime: mock.runtime, nodeId: 'android-node' });
+
+    client.dispose(4000, 'shutdown');
+
+    expect(mock.dispose).toHaveBeenCalledWith(4000, 'shutdown');
+  });
+
   it('platform connected getter forwards to runtime connected state', async () => {
     const mock = createRuntimeMock();
     const client = new MacOSCompanionClient({ runtime: mock.runtime, nodeId: 'mac-node' });

src/companion/platformClients.ts

@@ -109,8 +109,8 @@ export class MacOSCompanionClient {
     this.runtime.disconnect();
   }
 
-  dispose(): void {
-    this.runtime.dispose();
+  dispose(code?: number, reason?: string): void {
+    this.runtime.dispose(code, reason);
   }
 
   register(): Promise<NodeRegisterResult> {
@@ -351,8 +351,8 @@ export class IOSCompanionClient {
     this.runtime.disconnect();
   }
 
-  dispose(): void {
-    this.runtime.dispose();
+  dispose(code?: number, reason?: string): void {
+    this.runtime.dispose(code, reason);
   }
 
   register(): Promise<NodeRegisterResult> {
@@ -593,8 +593,8 @@ export class AndroidCompanionClient {
     this.runtime.disconnect();
   }
 
-  dispose(): void {
-    this.runtime.dispose();
+  dispose(code?: number, reason?: string): void {
+    this.runtime.dispose(code, reason);
   }
 
   register(): Promise<NodeRegisterResult> {