Plan: @gadhs/pi-remote — /remote-control hands the running session to a paired phone (#142)

Transport: one wss://<relay>/ws; text frames are the relay Envelope (hello, box_auth, welcome, err, expect, vouch, unvouch, device_up, device_down); binary frames are Routed on the box side (32-byte device id ‖ 4-byte session id ‖ body). routedEncode/Decode, frameEncode/Decode from the wasm. Frames ≤ 65 535 + 36 bytes.

Handshake: Noise IK, device initiates, box responds (Handshake.responder(me)); message 1’s payload is the raw token when pairing, empty when reconnecting; after read(), remoteStatic() is the device’s Noise static; admit a pairing device iff Token.matches(payload), a known device iff its static is on the trusted list; then write(empty), intoSession(), Session.seal/open.

Control records (session 0, encrypted, JSON tagged t): ToBox introduce | open | close | refresh; ToDevice hello | paired | session_opened | session_ended | refused | waiting | idle (types/ToBox.ts, types/ToDevice.ts).

Session-frame rule: any session id ≠ 0 carries pi’s RPC records verbatim - box→device pi’s events, device→box prompt / abort / extension_ui_response. A broker ask goes as an extension_ui_request record (method, title, message, options, placeholder, timeout only when headless); the answer comes back as extension_ui_response (confirmed | value | cancelled).

Pairing as the box drives it: expect { token_hash, until ≤ now+120 }, print pairingUrl(relay, me, token); device_up (placeholder id = token hash) → responder handshake; introduce { device_id, label } → persist, vouch, paired { box_id }, unvouch placeholder. On every relay connection: box_auth, re-vouch every trusted device, re-expect an open window. forget = drop the record + unvouch.

pivot’s asks of us: send idle on settle(answered-locally | timeout | cancelled); hello.allowed_dirs empty; open/close → refused.

Loading: the package is CommonJS (wasm-bindgen nodejs); from our ESM through createRequire(import.meta.url), which jiti honours (this repo’s packages already use import.meta.url under pi).

pi (installed 0.85.1): pi.sendUserMessage (types.d.ts:980); ctx.abort() (:238); ctx.sessionManager.getSessionName() (session-manager.d.ts:230); events message_start/update/end, tool_execution_start/update/end, agent_start/end, turn_start/end, ui_prompt_start/end, session_shutdown { reason } (:478); global WebSocket is stable in Node ≥ 22.4 (pi ships 22.23.2), so the relay client needs no dependency.

index.ts - the factory: /remote-control [pair|stop|status|devices| forget [<id>]] with argument completion (verbs; device labels for forget, the memory-picker pattern), the event hooks, session_shutdown → session_ended to every device and stop.

config.ts - loadRemoteConfig(agentDir, env) → { relay, boxName } or a problem string; the wss:// rule.

identity.ts - loadOrCreateIdentity(dir, wire) (0600, refuses a file of the wrong length), TrustedDevices load/save/forget.

wire.ts - the createRequire loader and a narrow Wire type over the wasm surface this package uses (so tests inject the real wasm once).

link.ts - the relay connection: SocketFactory injected (default the global WebSocket, binaryType = "arraybuffer"), the envelope state machine (hello → box_auth → welcome → re-vouch → re-expect), Routed demux to peers, reconnect, stop().

peer.ts - one device: responder handshake with the pairing/known decision, Session, control in/out, session-1 in/out, the pending-ask map, the RemoteAnswerer (register on ready, unregister on close).

mirror.ts - pure: extension event → record; RemoteAsk → extension_ui_request; extension_ui_response → RemoteAnswer | undefined; nudge matching.

pairing.ts - token mint, expect, the pane/notify, the window’s expiry.

qr.ts - uqr render to lines.

contract (vectors.test.ts): every deterministic vector in @gadhs/pivot-wire/vectors/vectors.json reproduced through wire.ts (identity from secrets, token hash, relay-nonce signature, frame and routed encodings, pairing URL) and the loopback fixture crossing the rekey boundary - proves our loading of the wasm, not the wasm.

unit (config, identity, mirror, qr): the wss:// rule and the localhost exception; env over file; a missing relay names the file and the env; identity created 0600 and reloaded byte-equal, a wrong-length file refused; devices round-trip and forget removes exactly one; every mirrored event keeps its type and fields (property: for any object with a string type, record(event) is JSON-round-trippable and equal); a RemoteAsk of each kind becomes the documented extension_ui_request (timeout only when set); each extension_ui_response shape maps to its RemoteAnswer, cancelled and an unknown id to undefined; the nudge filter suppresses a broker ask’s own prompt and passes others; the QR renders to non-empty lines of equal width.

wiring (link, peer, pairing, over the fake relay): connect → box_auth with a signature the device side verifies → welcome → re-vouch of every trusted device → re-expect of an open window; a pairing device (real wasm initiator, token in message 1) is admitted, introduce persists it, vouch + paired + unvouch placeholder are sent in that order, the pane closes; a wrong token gets no message 2 and an unvouch; a known device with an untrusted static is refused; after the handshake hello names this session; prompt reaches sendUserMessage, abort reaches ctx.abort, open gets refused; events become session-1 frames the device opens and parses; device_down unregisters that device’s answerer; socket close unregisters all and reconnects with backoff (fake timers); stop() sends session_ended, closes, unregisters; session_shutdown does the same.

wiring, the answerer: a broker ask → one extension_ui_request per device with the ask’s id; the device’s confirmed: true → {kind:"confirm", value:true}; value for select/input; cancelled → decline; a response for an unknown id is dropped; signal abort removes the pending ask; settle of any outcome sends idle to that device; the winning device, never settled, gets none.

concurrency: two devices answering one ask - the broker takes the first, the other is settled and gets idle, exactly one RemoteAnswer reaches the ask; a device that goes down (device_down) with an ask pending - its answerer is unregistered, its signal aborted, the ask declined, the desk dialog untouched; socket loss during a handshake - the half-built peer is dropped, nothing registered, reconnect proceeds; stop() during a pending ask - every pending ask declined before the socket closes.

regression: with /remote-control never invoked, the factory has loaded the wire (the Wire handle exists) but no socket is opened, no timer is pending, nothing is written under the agent dir, and remoteAttached() is false; a factory whose wire fails to load registers only the explanatory command.

timing (fake timers): a pairing window expires at 120 s - the pane says so and a late pair is refused by the box; reconnect backoff doubles from 1 s to a 30 s ceiling; the connection notices fire on the first failure and on recovery only, not on every attempt.

security: the pairing URL appears in the pane’s lines and nowhere in sendMessage, appendEntry or the debug log; the identity file is 0600; no log line contains token bytes or secrets (grep the captured debug log for the hex of both).

live: none here by pivot’s rule 2 - the end-to-end test with the PWA and a real relay is pivot’s #66 against the published package. What this repo cannot prove is stated in remote.adoc.

fail-open: a phone answer reaching an ask it was never offered - the pending map is keyed by the ask id we minted, per device, session 1 only; an unknown id is dropped; the broker validates the value again.

fail-open: an untrusted device admitted - a known device is admitted only when remoteStatic() is on the trusted list; a pairing device only inside an open window with a matching token, once; both refusals send no message 2.

silent (narrowed desk): a dead link leaving answerers registered - unregister on device_down, socket close/error, and stop(); the regression and wiring tests assert remoteAttached() false after each.

hang (fail-closed): an ask offered to a device that dies mid-ask - its answerer is unregistered, which aborts its signal and declines; the desk dialog is still there and nothing is decided until a person acts; headless keeps pi’s timeout.

secret exposure (silent): the token in the transcript or a log - the pane-only rule and the security test; identity 0600.

leak (silent): sockets or timers surviving stop(), so a later session’s phone talks to a stale link - stop() clears the reconnect timer and closes the socket; tests use fake timers and assert none pending.

misattribution (silent): with two phones, which one answered - the broker names remote either way; the device label goes to the debug log only, never to the verdict.

silent (unproven load): the wasm resolving but not loading from the installed flat root under pi’s jiti - decision 11 loads it in the factory, so consumer-sim’s "pi loads every extension" check exercises it on the packed distribution before every tag.