Add macOS companion node status and system.nodes APIs

docs/api/PROTOCOL.md

@@ -647,6 +647,26 @@ Requires `server.nodes.enabled: true` and `server.nodes.location.enabled: true`.
 
 Return the stored last-known location for the currently registered node connection.
 
+#### `node.status.set`
+
+Publish companion/node runtime status metadata (for example macOS menu-bar heartbeat state).
+
+**Request:**
+```json
+{
+  "id": 12,
+  "method": "node.status.set",
+  "params": {
+    "platform": "macos",
+    "appVersion": "0.3.1",
+    "deviceName": "MacBook Pro",
+    "statusText": "Idle",
+    "batteryPct": 64,
+    "powerSource": "battery"
+  }
+}
+```
+
 #### `system.capabilities`
 
 Return gateway protocol version, node policy status, and feature-gate snapshot.
@@ -684,6 +704,10 @@ Return gateway protocol version, node policy status, and feature-gate snapshot.
 
 Return the operator-facing snapshot of registered node locations.
 
+#### `system.nodes`
+
+Return the operator-facing snapshot of registered node connections (identity, role, capabilities, location/status).
+
 ### Canvas Methods
 
 #### `canvas.put`

docs/plans/2026-02-16-macos-menu-bar-companion-foundation-checklist.md

@@ -0,0 +1,49 @@
+# macOS Menu Bar Companion Foundation Checklist
+
+**Date:** 2026-02-16  
+**Scope:** Close the OpenClaw "macOS menu bar app" gap with a gateway-side companion status foundation.
+
+## Goal
+
+Add a practical companion-node status surface so a macOS menu bar app can report heartbeat/platform metadata and operators can inspect active companion state.
+
+## Implemented
+
+- Added node status protocol parser:
+  - `parseNodeStatusSetParams()`
+- Added node status RPC:
+  - `node.status.set`
+- Extended node connection state:
+  - `status` payload (`platform`, `appVersion`, `deviceName`, `statusText`, `batteryPct`, `powerSource`, `reportedAt`)
+- Added operator node snapshot endpoint:
+  - `system.nodes`
+- Wired gateway runtime callbacks for node snapshot listing and status persistence.
+- Updated node method authorization scopes:
+  - `companion` role can call `node.status.set`
+  - observer/automation remain read-only for node scoped methods.
+
+## Docs Updated
+
+- `README.md` — node method list now includes `node.status.set` and `system.nodes`.
+- `docs/api/PROTOCOL.md` — added request docs for `node.status.set` and `system.nodes`.
+
+## Tests
+
+- `src/gateway/protocol.test.ts`
+  - status parser valid/invalid coverage.
+- `src/gateway/handlers/node.test.ts`
+  - status update persistence behavior.
+- `src/gateway/handlers/handlers.test.ts`
+  - `system.nodes` empty + filtered responses.
+- `src/gateway/server.test.ts`
+  - end-to-end `node.status.set` + `system.nodes` flow.
+- `src/gateway/auth.test.ts`
+  - role-scope denial for `node.status.set` where not permitted.
+
+## Validation Run
+
+```bash
+pnpm test:run src/gateway/protocol.test.ts src/gateway/auth.test.ts src/gateway/handlers/node.test.ts src/gateway/handlers/handlers.test.ts src/gateway/server.test.ts
+pnpm typecheck
+pnpm build
+```

docs/plans/state.json

@@ -517,6 +517,31 @@
       ],
       "test_status": "pnpm test:run src/gateway/canvas-store.test.ts src/gateway/handlers/handlers.test.ts src/gateway/server.test.ts + pnpm typecheck + pnpm build passing"
     },
+    "macos-menu-bar-companion-foundation": {
+      "file": "2026-02-16-macos-menu-bar-companion-foundation-checklist.md",
+      "status": "completed",
+      "date": "2026-02-16",
+      "updated": "2026-02-16",
+      "summary": "Implemented macOS companion foundation on gateway node RPC: added `node.status.set` for companion heartbeat/status metadata and `system.nodes` for operator visibility of registered node snapshots (role/capabilities/identity/location/status), with role-scope auth enforcement and tests/docs.",
+      "files_created": [
+        "docs/plans/2026-02-16-macos-menu-bar-companion-foundation-checklist.md"
+      ],
+      "files_modified": [
+        "src/gateway/protocol.ts",
+        "src/gateway/protocol.test.ts",
+        "src/gateway/handlers/node.ts",
+        "src/gateway/handlers/node.test.ts",
+        "src/gateway/handlers/system.ts",
+        "src/gateway/handlers/handlers.test.ts",
+        "src/gateway/handlers/index.ts",
+        "src/gateway/server.ts",
+        "src/gateway/server.test.ts",
+        "src/gateway/auth.test.ts",
+        "README.md",
+        "docs/api/PROTOCOL.md"
+      ],
+      "test_status": "pnpm test:run src/gateway/protocol.test.ts src/gateway/auth.test.ts src/gateway/handlers/node.test.ts src/gateway/handlers/handlers.test.ts src/gateway/server.test.ts + pnpm typecheck + pnpm build passing"
+    },
     "qmd-backend": {
       "file": "2026-02-16-qmd-backend-checklist.md",
       "status": "completed",
@@ -3078,7 +3103,7 @@
     }
   },
   "overall_progress": {
-    "total_test_count": 1780,
+    "total_test_count": 1786,
     "all_tests_passing": true,
     "p0_completion": "3/3 (100%)",
     "p1_completion": "4/4 (100%)",
@@ -3093,12 +3118,12 @@
     "tier2_completion": "4/4 (100%) — inbound webhooks, vector memory search, Dockerfile, heartbeat monitor",
     "tier3_completion": "5/5 (100%) — lane queue, credential redaction, web UI token dashboard, xAI (Grok) provider, Voyage AI embeddings",
     "tier4_completion": "4/4 (100%) — gateway lock, shell completion, Tailscale Serve/Funnel, DM pairing codes",
-    "feature_gap_scorecard": "120/128 match (94%), 0 partial (0%), 8 missing (6%)",
+    "feature_gap_scorecard": "121/128 match (95%), 0 partial (0%), 7 missing (5%)",
     "operator_dx_milestone": "Phase 3 (Live Ops Dashboard): 2/2 plans complete — milestone done",
     "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: macOS menu bar companion app (open next scoped implementation checklist)"
+    "next_up": "OpenClaw gap: iOS node (open next scoped implementation checklist)"
   },
   "soul_md_and_cron_create": {
     "date": "2026-02-11",