feat(companion): allow platform disconnect code and reason

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(code?, reason?)`)
+  - 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()`)
 - `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.

docs/plans/state.json

@@ -1210,6 +1210,20 @@
       ],
       "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-platform-disconnect-params-parity": {
+      "status": "completed",
+      "date": "2026-02-17",
+      "updated": "2026-02-17",
+      "summary": "Aligned platform wrappers with runtime lifecycle API by extending `disconnect()` to accept optional `code`/`reason` parameters, with unit/integration assertions confirming passthrough and snapshot metadata updates.",
+      "files_modified": [
+        "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",

src/companion/platformClients.integration.test.ts

@@ -338,8 +338,18 @@ describe('platform clients integration', () => {
     expect(client.connected).toBe(false);
     await client.connect();
     expect(client.connected).toBe(true);
-    client.disconnect();
+    client.disconnect(4100, 'manual platform stop');
     expect(client.connected).toBe(false);
+    expect(client.getConnectionSnapshot()).toEqual({
+      connected: false,
+      eventSubscriptionCount: 0,
+      pendingRequestCount: 0,
+      pendingEventWaitCount: 0,
+      hasPendingWork: false,
+      idle: true,
+      lastDisconnectCode: 4100,
+      lastDisconnectReason: 'manual platform stop',
+    });
   });
 
   it('macOS companion wrapper registers and writes status with platform pinning', async () => {

src/companion/platformClients.test.ts

@@ -225,14 +225,14 @@ describe('platform companion clients', () => {
     await client.setLocation({ latitude: 10, longitude: 20, source: 'manual' });
     await client.registerPushToken({ token: 'a'.repeat(64), topic: 'dev.flynn.macos', environment: 'production' });
     await client.listNodes();
-    client.disconnect();
+    client.disconnect(4100, 'manual stop');
 
     expect(mock.connect).toHaveBeenCalledOnce();
     expect(mock.registerNode).toHaveBeenCalledWith(expect.objectContaining({ nodeId: 'mac-node', role: 'companion' }));
     expect(mock.setNodeStatus).toHaveBeenCalledWith(expect.objectContaining({ platform: 'macos' }));
     expect(mock.setNodePushToken).toHaveBeenCalledWith(expect.objectContaining({ provider: 'apns', topic: 'dev.flynn.macos' }));
     expect(mock.listSystemNodes).toHaveBeenCalledWith({ platform: 'macos', role: 'companion' });
-    expect(mock.disconnect).toHaveBeenCalledOnce();
+    expect(mock.disconnect).toHaveBeenCalledWith(4100, 'manual stop');
   });
 
   it('iOS client uses ios platform status and APNs push', async () => {

src/companion/platformClients.ts

@@ -110,8 +110,8 @@ export class MacOSCompanionClient {
     return this.runtime.connected;
   }
 
-  disconnect(): void {
-    this.runtime.disconnect();
+  disconnect(code?: number, reason?: string): void {
+    this.runtime.disconnect(code, reason);
   }
 
   dispose(code?: number, reason?: string): void {
@@ -388,8 +388,8 @@ export class IOSCompanionClient {
     return this.runtime.connected;
   }
 
-  disconnect(): void {
-    this.runtime.disconnect();
+  disconnect(code?: number, reason?: string): void {
+    this.runtime.disconnect(code, reason);
   }
 
   dispose(code?: number, reason?: string): void {
@@ -666,8 +666,8 @@ export class AndroidCompanionClient {
     return this.runtime.connected;
   }
 
-  disconnect(): void {
-    this.runtime.disconnect();
+  disconnect(code?: number, reason?: string): void {
+    this.runtime.disconnect(code, reason);
   }
 
   dispose(code?: number, reason?: string): void {