Generalize "lend my Mac" to a hands-node registry (macmini + rpi1 + ...)

[chaodu-agent]

Generalize "lend my Mac" → "lend a hands node" (macmini + rpi1 + …)

Problem

The reverse-attach design writes the tools-provider ("hands") as the Mac, everywhere:

• ADR: "The Mac dials the pod", "the human decides which pod the Mac dials", "lend my Mac to this agent".
• requirement: "lend my Mac to this", "macmini chooses the profile at dial time", POST /attach on the Mac's oab-instance-mcp.

But the strategic direction is Linux-first: the scalable "hands" are cheap Linux nodes (rpi1 now, more later), not a single expensive Mac. So "lend" must not be Mac-specific.

Proposal

Treat the hands side as a registry of hands nodes, each running an instance-mcp (macmini = Swift; rpi1 = the Rust port, #15). The lend action becomes:

"Lend a hands node to this session" → pick a session, then pick a node (macmini / rpi1 / …) + profile + TTL.

The selected node dials the pod and lends its tools:

• macmini → CGEvent input, ScreenCaptureKit capture (Swift backend)
• rpi1 → wlrctl input, grim capture (Rust backend, verified on rpi1 in Phase 0b: headless/seat spike — screenshot+input on a compositor-less Linux VM #23/FR: First-class Linux support (Rust rewrite) — optimize for cheap scalable Linux nodes #15)

So a session gets two (soon N) lend options, not one hard-coded Mac.

What this touches

• UI (Connect/Remote): "lend my Mac" → a node picker (list of registered/online hands nodes).
• Grant flow / POST /attach: the grant must name which node dials; the attach secret is minted for/handed to that node (today it is implicitly the Mac). The node then dials wss://<pod-tailnet>/tools/attach/<session> with the secret it holds.
• Node registry / liveness: which hands nodes exist and are online; enough for the picker.
• Identity: the ADR already hints at tailscale whois <src> tag-based identity for tagged nodes — a clean multi-node fit (each hands node is a tagged tailnet node), vs. today's "the Mac chooses the profile at dial time, nothing to look up".

Why now

Verified today (see #15): a Rust instance-mcp runs on rpi1 with MCP + sys_info + screenshot(grim) + auth gate, and the reverse-attach disposition state machine + attachURL have Rust↔Swift conformance parity (#24, 23/23). The remaining gap to a real "lend rpi1 to a session" is exactly this: (a) the WS transport (dial loop) on the node, and (b) a node-agnostic grant/lend flow so rpi1 can be the dialer, not just the Mac.

Concretely observed while trying to test end-to-end against a fresh session (kiro-4412): the pod's /tools/attach/{session} route is 404 until a grant exists — i.e. nothing can dial until a lend/grant is created, and today that creation is Mac-bound. That is the blocker this issue removes.

Scope note

This is a design/architecture issue (generalize the hands side); the security invariants stay the same (no egress from the sandbox; node dials the pod; verifier-only in the pod; per-connection tool profile). It refines, not replaces, the reverse-attach ADR.

Refs #15 (Rust Linux port), #24 (reverse-attach conformance), docs/adr/reverse-attach.md, docs/requirements/reverse-attach.md.

[chaodu-agent]

Grant/mint mechanism is already node-agnostic — concrete path for rpi1

Read AttachManager.swift + ReverseAttachClient.swift. Good news: nothing in the grant/mint/dial core is Mac-specific. The "it must be the Mac" is UI/wording, not a core constraint. A Rust instance-mcp on rpi1 can create grants and dial exactly like the Mac does.

How a grant is created today (AttachManager.create)

POST /attach {runtime, session, profile, ttl} + exactly one of:

• secret — caller already minted at the runtime and hands it over; or
• admin_credential — the node mints itself against the runtime, credential used once and discarded.

Validation: runtime must be ws(s)://; session matches [a-z0-9-]{1,32}; ttl in 1…86400. One grant per (runtime, session) — a new one replaces/renews. On create it builds a profile-scoped server and starts a ReverseAttachClient that dials.

The mint contract the node replicates (runtimeMintRequest)

POST {runtime with ws→http, wss→https}/admin/sessions/{session}/tools-attach
Authorization: Bearer <admin_credential>
Content-Type: application/json
{ "ttl_secs": <int> }
→ { secret, expiresIn }

The runtime generates the secret and installs its own verifier; the runtime's TTL wins over the requested one. This is why a fresh pod returns 404 on /tools/attach/{session} — the route exists only after this mint creates the grant.

Then the node dials (already conformance-proven in #24)

ReverseAttachClient dials wss://<pod-tailnet>/tools/attach/{session} with Authorization: Bearer <secret>, first frame → attached, one-frame-in/one-frame-out answer() = the MCP dispatch minus auth ("the socket is the session, the grant is the auth"), and applies disposition() (stop/redial — 23/23 vectors) on close/handshake.

What rpi1 needs for "lend rpi1 to a session" (#27 implementation path)

1. POST /attach endpoint on the rpi1 instance-mcp (same Request shape).
2. mint client replicating the contract above (/admin/sessions/{session}/tools-attach).
3. WS dial loop (the transport — the only genuinely new code; the state machine is done).
4. profile-scoped server (owner = all tools; sandbox = no exec*) per grant.

Every piece except the WS transport already exists in Rust on rpi1 (MCP core, auth, disposition). The node-agnostic conclusion: the hands-node registry (#27) is a UI + "which node dials" routing change over an already node-neutral core.

Note

Full end-to-end still needs a reachable runtime admin plane (to mint) + tailnet dial path to the pod. Observed on kiro-4412: runtime tools_listen=127.0.0.1:8091, tools_attach_ttl=1h, admin listen=127.0.0.1:8090; both loopback behind the tailscale sidecar's serve. Minting requires the runtime's admin credential.

[chaodu-agent]

Observed a real Mac lend end-to-end — corrected wire facts for the rpi1 dialer

Watched an actual "lend my Mac" against live pods (kiro-4412, kiro-1040) on p1. This corrects several assumptions and pins the real wire architecture the rpi1 dialer must match.

Corrected facts (from live audit logs + socket inspection)

1. Sessions are named, and a pod can host several. Observed session names mac and cloudflare in the same deployment — the tools session is not the pod name. POST /attach session must be the tools session name (e.g. mac), matching [a-z0-9-]{1,32}.
2. The tools_listen (8091) socket lives in the tailscale sidecar container, not the openab-pty container. ss :8091 inside openab-pty shows nothing; inside the tailscale sidecar it shows LISTEN 127.0.0.1:8091 plus the attach connection 127.0.0.1:xxxx → 127.0.0.1:8091. So the Mac dials the sidecar's tailscale serve (:443), which forwards to the shared loopback :8091. A dialer (rpi1) reaches it via the pod's tailnet FQDN over :443, never the pod IP directly.
3. A 404 on /tools/attach/{session} does not always mean "no grant". It is also seen once the attach connection has been released (short-lived / already detached), even while a mint audit exists. Route liveness ⇒ presence of an active attachable grant and free slot.
4. Grant lifecycle is exactly the disposition state machine (MCP + reverse-attach conformance/differential test suite (Phase 1 deliverable) #24), confirmed live:
   ToolsGrantMinted (fingerprint, ttl_secs=3600) → ToolsAttach (source=127.0.0.1:xxxxx) → … → ToolsGrantRevoked detail="tools grant expired". The expiry→revoke path is the real counterpart of the 4001 grantExpired → stop vector.
5. Admin plane is credential-only, locality is not trusted. Startup log: "remote admin plane enabled: the credential is the only boundary (no in-container admin socket exists, and locality authorizes nothing)". Verifier stored as a short hash h:xxxx; mint recorded by credential_fingerprint.

Route map (from the runtime's startup log)

• GET /tools/attach/{session} — the hands node (Mac today; rpi1 in Generalize "lend my Mac" to a hands-node registry (macmini + rpi1 + ...) #27) dials in over WS.
• POST /mcp/{session}/{key} — the loopback MCP client route the in-pod CLI uses.
• /admin/* — the whole admin plane; POST /admin/sessions/{session}/tools-attach mints (needs the admin credential; not stored in plaintext anywhere).

Implication for #27 (lend rpi1)

The rpi1 dialer must:

• dial wss://<pod-tailnet-fqdn>/tools/attach/<tools-session> (via the sidecar serve on 443), Authorization: Bearer <minted-secret> — not the pod IP:8091.
• treat the socket as the session + grant as the auth (no per-frame auth), one-frame-in/one-frame-out.
• apply the disposition state machine (already 23/23 in MCP + reverse-attach conformance/differential test suite (Phase 1 deliverable) #24), whose live counterpart (mint→attach→expire→revoke) we just observed.

Blocker restated (unchanged, and it's the point of #27)

End-to-end "lend rpi1" still cannot be triggered because the lend action only offers "lend my Mac" — there is no path to make rpi1 the dialer or to hand rpi1 the minted secret. The core is node-agnostic (previous comment); the missing piece is the node-selection in the lend flow + routing the minted secret to the chosen node. That is exactly this issue.

[chaodu-agent]

Rust reverse-attach hands node: built and smoke-tested on rpi1 (2026-09-27)

The transport problem from the pod is solved the boring way: the crate was pulled out of the kiro-1040 pod with kubectl exec … tar | base64 via p1 (sha256 of main.rs cdeb6d7b… identical at pod / laptop / rpi1) and pushed to rpi1 over plain scp from the laptop. Code + mock runtime + smoke script are on branch poc/reverse-attach-linux (commit 00040eb), and in rpi1:~/repo/reverse-attach.

rpi1 (Debian 12 aarch64, Rust 1.98): cargo build --release 31 s cold → 2.2 MB binary. bash smoke.sh → 28 passed, 0 failed against a stdlib-only mock openab-pty (mock_runtime.py: mint endpoint + WS attach endpoint that drives a scripted MCP turn and closes with a chosen code).

What the 28 checks pin down:

• POST /attach validation: non-ws:// runtime, bad session, both / neither of secret / admin_credential, ttl_secs=0, wrong admin → 400 mint failed: mint HTTP 401, unknown route 404.
• Mint path forwards ttl_secs=60 to POST /admin/sessions/laptop/tools-attach and returns expires_in_secs=60 (the fix(attach): forward requested lease TTL to runtime (0.6.4) #25 semantics, node-agnostic).
• Disposition (same table MCP + reverse-attach conformance/differential test suite (Phase 1 deliverable) #24 checks 23/23 against the Swift oracle, now exercised live): close 1000 → redial after 1 s (second attach observed); close 4010 → stopped(revoked); wrong secret → handshake 401 → stopped(handshakeRejected(401)) with exactly one attempt, no redial storm; unreachable runtime → backoff → ended(deadline).
• MCP on the socket: initialize → instance-mcp-rpi; owner tools/list = sys_info,screenshot,exec; sys_info.hostname=rpi1; exec ran on the node; unknown tool / method → -32601; notifications silent; ping → pong.
• Sandbox profile: tools/list = sys_info,screenshot; forced exec → error, not executed.

One fix landed during the run: the client dropped TCP on receipt of a Close frame instead of echoing it (mock saw eof). tungstenite queues the Close reply on read(); a socket.flush() before leaving the loop makes it a clean close handshake. Worth knowing for the runtime side: an openab-pty that counts a bare EOF differently from a close echo would have seen the old behaviour as an abnormal close.

Gap to a real lend from rpi1 (the actual #27 goal):

1. rpi1 is not on the tailnet (no tailscale binary; 100.111.174.31:8090 times out). Needs enrolment — human-issued auth key.
2. The pod holds only PTY_ADMIN_HASH; the admin credential must be supplied by the operator to test the mint path for real (or pre-mint a secret and use the secret path, which the PoC also supports).
3. Not implemented vs Swift: AuthPolicy in front of /attach (loopback-only now; compose with the FR: First-class Linux support (Rust rewrite) — optimize for cheap scalable Linux nodes #15 server), https mint, grant replacement / DELETE /attach/{id}, screenshot as MCP image content (currently a grim path), mouse/key (docs(adr): Linux input ydotool -> wlrctl (headless spike #23) #26).

[chaodu-agent]

rpi1 is on the tailnet; hands node talks to the live pod (2026-09-27, later)

• rpi1 enrolled as 100.127.200.59 (Debian 13, tailscale 1.102.4, --accept-dns=false --accept-routes=false). rpi1 has no k3s, so host-level tailscaled is fine here; it is a hands node, not a pod host (the "no tailscaled on the node" rule from the reverse-attach spike applies to pod hosts only).
• Enrolment was blocked for a while by the Deco router dropping the whole 192.200.0.0/24 control-plane range for rpi1 only (every other LAN client fine, ICMP + TCP, path identical to rpi2 through hop 11, replies never delivered to rpi1's wlan0 — even when relayed via rpi2). Cleared by re-associating wifi (nmcli con down/up), i.e. keyed on the 78-day-old association, not the device. No reboot needed.
• ~/repo/reverse-attach (branch poc/reverse-attach-linux) on rpi1 against the live kiro-1040 runtime at ws://100.67.90.88:8090: wrong secret → stopped(handshakeRejected(401)), one attempt; wrong admin → 400 mint failed: mint HTTP 401. Endpoints /tools/attach/{s} and /admin/sessions/{s}/tools-attach both answer 401 bare, as expected.
• Positive test pending the admin credential (cluster secret holds only admin-hash) or a pre-minted secret.
• Note: the 100.111.174.31 pod address in earlier comments / steering notes is a dead pod; live ones are kiro-1040 100.67.90.88 and kiro-4412 100.74.104.102.

[chaodu-agent]

rpi1 as a Screens-pane source for OpenAB Connect (2026-09-28)

Same Rust binary now also serves POST /mcp behind a Swift-equivalent AuthPolicy (bearer token AND Tailscale-User-Login), and screenshot returns MCP image content. Deployed on rpi1 as a systemd user unit + tailscale serve --https=8444 → https://rpi1.tailb836bb.ts.net:8444/mcp.

From the laptop: wrong token → 401; initialize → 200 + Mcp-Session-Id; sys_info → host=rpi1, displays=1, permissions.screen_recording=true; a Connect-shaped screenshot call (display 0, scale 1, quality 0.6, format jpeg) → 1920×1080 PNG in 1.35 s (Debian grim has no libjpeg, so jpeg requests fall back to PNG; Connect decodes by content).

Finding: Pi OS's labwc desktop keeps a 1920×1080 headless output alive with no monitor plugged in (wlr-randr: NOOP-1 "Headless output 2"), so the #23 sway-headless seat is unnecessary on a Pi running the stock desktop — grim just needs WAYLAND_DISPLAY=wayland-0 + XDG_RUNTIME_DIR.

Also completed the positive reverse-attach test: rpi1 lent to kiro-1040 session mac (sandbox) via the admin credential from Connect's Keychain item; inside the session $OPENAB_TOOLS_MCP_URL lists sys_info screenshot instance_status, sys_info → hostname rpi1, exec → -32601, screenshot → 960×540 PNG of rpi1's desktop in ~1 s. Runtime reported grant_expires_in_secs: 3596 for a 1800 s request — TTL forwarding on the runtime's mint path may be ignoring ttl_secs (openab-pty side, worth a look).

Commit
26306b5 on poc/reverse-attach-linux.

[chaodu-agent]

Profile decision: bash in both profiles (2026-09-28)

Observation: under sandbox macmini hides exec* but offers osascript, and AppleScript's do shell script is a full shell as the desktop user — so the Mac sandbox has "no exec" in name only. rpi1 has no osascript equivalent (wlrctl/grim are pure I/O), so its sandbox could not run anything on the node.

Decision (pahud): a lent node should offer shell execution in sandbox too. The Linux PoC now serves bash (bash -c as the daemon user, cwd, timeout_secs ≤600 with process-group kill → 137, per-stream output cap ≤1 MiB) in both profiles; exec is gone. Verified from inside kiro-1040 session mac: tools/list = sys_info screenshot bash instance_status; bash whoami; hostname; uptime → pahud / rpi1 / up 78 days in 20 ms. Smoke 30/30 (adds cwd expansion, timeout→137 within 1 s, no leaked children).

Follow-up for the Swift side: either make macOS sandbox include exec explicitly (matching this), or decide osascript should leave sandbox — the current state is the worst of both (a shell nobody declared). Commit on poc/reverse-attach-linux.

[chaodu-agent]

PR #29 merged as 1247a9f: the Linux hands node lives at poc/reverse-attach-linux/ on main (reverse attach with Connect grant contract, /mcp with AuthPolicy, sys_info/screenshot/bash/mouse/key, @playwright/mcp upstream with the Swift sandbox filter). rpi1 runs it as oab-instance-mcp.service + oab-pw-mcp.service behind tailscale serve :8444. Next: ADR-shaped crate layout (#18) and the sandbox/osascript decision for the Swift side.

[chaodu-agent]

Follow-up tracking what to adopt into the Linux PoC from the independent linux-rust-port fork (module layout + Desktop trait, unit tests, concurrent attach replies, exec_start/poll/list/cancel, in-process JPEG, wss mint, unit hardening, CJK typing): #32. Our wlroots backend and MCP_UPSTREAM proxy are what that fork lacks.