[ProjectZero02]

Phase 5 of the recovery layer plan: everything an assistant needs, over MCP, with a guide and a hardware checklist.

MCP tools on the hub

list_machines, get_events, propose_reset, propose_force_off, get_recovery and withdraw_recovery. Each runs the same code as its REST route (propose, findRecovery, decline and machinesFor were pulled out of the handlers), so the rules are the same. There's no tool to confirm. A refusal is a tool error with the REST reply's fields (retryAt). They're listed, and the initialize instructions describe them, only on a helper with a KVM linked. Every 2.5 helper has a hub object, so gating on that would have listed them on every PC.

Fix: proposerKey reached other keys

The recovery routes hid it, but GET /v2/machines (a machine's recovery), the event stream's snapshot, and its recovery events sent it to every watcher. All of them, and get_events, now go through viewMachine/viewEvent. Webhooks never carry it.

powerdeck-helper webhook add|list|test|rm

Found while writing the guide: a webhook could only be added through the API from an owner device.

Docs

• docs/integrating-an-assistant.md: keys, MCP, REST with a pinned certificate (openssl and stdlib Python), the event stream and webhooks, a recovery step by step, what to do with each result and refusal, rules for an assistant, and running your own copy.
• docs/hardware-test.md: the owner's checklist for a real NanoKVM and computer, covering the power light, sleep, wake by KVM and by Wake-on-LAN, a memory test in a VM, a real freeze, a reset lead pulled out, and the agent path.
• README, protocol.md, SECURITY.md and the CHANGELOG are updated. The app's Full guide on GitHub link opens the guide.

Tests

• TestMCPHub covers each hub tool, created vs open proposals, withdraw_recovery by another key (refused), and get_events with after and with an ID that's gone (missed). It also checks the refusals bad_request, scope, device, agents_off, owner_only, not_found and too_soon with retryAt, and that no confirm tool exists.
• TestMCPNoHub: without a KVM linked, only the 5 device tools are listed.
• TestRecoveryEvents and the webhook test: another key's stream, and webhooks, never carry proposerKey. GET /v2/machines is checked in TestMCPHub.
• TestAssistantGuide runs the guide's 9 marked examples, in order, against a test hub whose watch really sees the machine freeze: unknown, then hung after 3 minutes, the hub's own proposal, confirm, then back and recovered. Changing a state, a step, a status or a proposer in the guide fails it (all four tried).
• Checked by hand:
  • The guide's Python ran against a TLS server with a self-signed certificate: the openssl pin matched, a wrong pin was refused, SSE parsing and Last-Event-ID replay worked.
  • webhook add|list|test|rm ran against a real helper process, isolated in a network namespace. The receiver verified the delivery with protocol.md's verify().

Go tests pass, go vet is clean on Linux and Windows, and gofmt is clean.

🤖 Generated with Claude Code