Add macOS iOS Android companion platform client wrappers

docs/api/PROTOCOL.md

@@ -1291,3 +1291,4 @@ For more implementation details, see:
 - Handlers: `src/gateway/handlers/`
 - Gateway server: `src/gateway/server.ts`
 - Companion runtime client helper: `src/companion/runtimeClient.ts`
+- Platform companion wrappers: `src/companion/platformClients.ts`

docs/plans/2026-02-16-companion-platform-clients-foundation-checklist.md

@@ -0,0 +1,37 @@
+# Companion Platform Clients Foundation Checklist (2026-02-16)
+
+## Scope
+
+- Build platform-focused companion wrappers on top of `CompanionRuntimeClient` so app runtimes can use stable, platform-specific methods without manual RPC payload shaping.
+- Cover macOS, iOS, and Android runtime surfaces.
+
+## Implementation
+
+- Added `src/companion/platformClients.ts` with:
+  - `MacOSCompanionClient`
+  - `IOSCompanionClient`
+  - `AndroidCompanionClient`
+- Standardized shared operations for each platform client:
+  - `connect()` / `disconnect()`
+  - `register()`
+  - `getCapabilities()`
+  - `setStatus()` (platform pinned per client)
+  - `setLocation()` / `getLocation()`
+  - `getSystemCapabilities()`
+  - `listNodes()` (platform + role filtered)
+- Platform push registration semantics:
+  - macOS/iOS -> APNs (`node.push_token.set` provider `apns`)
+  - Android -> FCM (`node.push_token.set` provider `fcm`)
+
+## Tests
+
+- Added `src/companion/platformClients.test.ts`.
+- Verified wrapper behavior with runtime mock coverage for:
+  - platform-specific `node.status.set` payloads
+  - APNs vs FCM push provider enforcement by wrapper
+  - platform-filtered `system.nodes` queries
+
+## Docs Updated
+
+- `README.md` companion section now references `platformClients.ts` wrappers.
+- `docs/api/PROTOCOL.md` implementation references now include platform wrappers.

docs/plans/state.json

@@ -726,6 +726,24 @@
       ],
       "test_status": "pnpm test:run src/companion/runtimeClient.test.ts + pnpm typecheck + pnpm build passing"
     },
+    "companion-platform-clients-foundation": {
+      "file": "2026-02-16-companion-platform-clients-foundation-checklist.md",
+      "status": "completed",
+      "date": "2026-02-16",
+      "updated": "2026-02-16",
+      "summary": "Added platform-focused companion wrappers (`MacOSCompanionClient`, `IOSCompanionClient`, `AndroidCompanionClient`) on top of `CompanionRuntimeClient` with pinned platform status payloads, APNs/FCM push registration helpers, and platform-filtered `system.nodes` queries.",
+      "files_created": [
+        "docs/plans/2026-02-16-companion-platform-clients-foundation-checklist.md",
+        "src/companion/platformClients.ts",
+        "src/companion/platformClients.test.ts"
+      ],
+      "files_modified": [
+        "src/companion/index.ts",
+        "README.md",
+        "docs/api/PROTOCOL.md"
+      ],
+      "test_status": "pnpm test:run src/companion/platformClients.test.ts src/companion/runtimeClient.test.ts + pnpm typecheck + pnpm build passing"
+    },
     "qmd-backend": {
       "file": "2026-02-16-qmd-backend-checklist.md",
       "status": "completed",
@@ -3287,7 +3305,7 @@
     }
   },
   "overall_progress": {
-    "total_test_count": 1817,
+    "total_test_count": 1820,
     "all_tests_passing": true,
     "p0_completion": "3/3 (100%)",
     "p1_completion": "4/4 (100%)",
@@ -3307,7 +3325,7 @@
     "gmail_auth_cli": "flynn gmail-auth command implemented with OAuth2 flow, doctor check, config routed to Telegram",
     "native_audio_support": "completed — smart routing for native audio (Gemini/OpenAI/GitHub) vs Whisper transcription fallback",
     "remaining_phases_completion": "Phase 1: 3/3 (100%) — context levels, command registry, memory structure. Phase 2: 3/3 (100%) — component registry, confidence routing, history index. Phase 3: 2/2 (100%) — adaptive memory/compaction, truthfulness/autonomy hardening",
-    "next_up": "OpenClaw gap: implement macOS/iOS/Android companion runtime clients on top of `src/companion/runtimeClient.ts`"
+    "next_up": "OpenClaw gap: integrate companion platform clients into concrete app runtimes and add end-to-end gateway fixture coverage"
   },
   "soul_md_and_cron_create": {
     "date": "2026-02-11",