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

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

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