remote-pi 0.1.2 → 0.2.0

package/dist/pairing/qr.js

@@ -46,6 +46,11 @@ sessionName,
 roomId) {
     // `r` (relay URL) removed in plano 14 — relay now comes from app config /
     // pi-ext env|config|default chain. Keeps QR ~30-50 chars shorter.
+    // `n` (session name) is kept: the app uses it for the pre-pair_ok preview
+    // screen (showing the agent name immediately after scan, before the
+    // handshake completes). Dropping it briefly shrank the QR but the QR
+    // size no longer matters now that the copy-paste URI is rendered via
+    // `pi.sendMessage` into the chat panel (not the QR overflow area).
     const epkB64 = Buffer.from(longtermEdPk).toString("base64url");
     const params = new URLSearchParams({
         t: token,
@@ -57,16 +62,30 @@ roomId) {
     return `remotepi://pair?${params.toString()}`;
 }
 /**
- * Renders the QR + URI in the Pi TUI's output pane via stderr. `ctx.ui.notify`
- * collapses multi-line content into a single toast, so for ASCII art we need
- * the raw stderr capture that the Pi TUI exposes as scrollable log. Post
- * plano 14 the QR carries only `t/epk/n`, fits comfortably in the panel
- * without needing a separate Terminal window.
+ * Returns the QR ASCII as a string (pure Unicode block characters —
+ * `█ ▀ ▄` and space, NO ANSI escapes — qrcode-terminal v0.12 small mode
+ * is escape-free, see lib/main.js:48-53).
+ *
+ * The caller can either write the string to stderr (legacy path, breaks
+ * the Pi TUI layout) or inject it via `pi.sendMessage` (renders inside
+ * the chat panel as proper content).
+ */
+export function renderQRAscii(uri) {
+    let out = "";
+    qrTerminal.generate(uri, { small: true }, (qrcode) => { out = qrcode; });
+    return out;
+}
+/**
+ * Legacy stderr writer — kept for the standalone CLI mode
+ * (`pi-extension/src/index.ts` bottom block, which runs outside a Pi TUI).
+ * Inside the Pi TUI extension flow, use `renderQRAscii` + `pi.sendMessage`
+ * instead — direct stderr writes from inside an extension break the TUI's
+ * scrollable output widget (the QR overflows the panel and other writes
+ * collide with the prompt area).
  */
 export function displayQR(uri) {
-    qrTerminal.generate(uri, { small: true }, (qrcode) => {
-        process.stderr.write(`\n📱 Scan to pair:\n\n${qrcode}\n${uri}\n`);
-    });
+    const qrcode = renderQRAscii(uri);
+    process.stderr.write(`\n📱 Scan to pair:\n\n${qrcode}\n`);
 }
 /**
  * Starts a rotating QR session: generates a new QR every 60s, printing it

package/dist/pairing/qr.js.map

@@ -1 +1 @@
-{"version":3,"file":"qr.js","sourceRoot":"","sources":["../../src/pairing/qr.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"qr.js","sourceRoot":"","sources":["../../src/pairing/qr.ts"],"names":[],"mappings":"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"}

package/dist/pairing/storage.d.ts

@@ -1,4 +1,32 @@
 import { type Ed25519Keypair } from "./crypto.js";
+/**
+ * Minimal backend interface for credential reads/writes. Swappable so
+ * tests can inject a controlled in-memory store without touching the OS
+ * keyring (which is shared with the developer's own credentials).
+ *
+ * Errors thrown by `read`/`write`/`delete` signal "backend unavailable on
+ * this platform" — callers fall back to the file store on first failure.
+ * Returning `undefined` from `read` means "no such entry" (a normal,
+ * non-error condition).
+ */
+export interface KeyStoreBackend {
+    read(service: string, account: string): Promise<string | undefined>;
+    write(service: string, account: string, value: string): Promise<void>;
+    delete(service: string, account: string): Promise<boolean>;
+}
+/** Test-only: swap (or clear with `null`) the keyring backend. */
+export declare function _setKeyStoreBackendForTest(backend: KeyStoreBackend | null): void;
+/**
+ * Returns the Pi-secret Ed25519 keypair, generating + persisting one on
+ * first call. Resolution order:
+ *   1. New keyring service `dev.remotepi.pi`
+ *   2. Old keyring service `dev.remotepi.mac` (migrate → step 1, delete old)
+ *   3. File `~/.pi/remote/identity.json` (headless-Linux fallback)
+ *   4. Generate a fresh keypair + persist to the first available backend
+ *
+ * Idempotent: subsequent calls return the same identity. The migration
+ * runs at most once per machine (the old entry is deleted after copy).
+ */
 export declare function getOrCreateEd25519Keypair(): Promise<Ed25519Keypair>;
 export interface PeerRecord {
     name: string;
@@ -7,4 +35,17 @@ export interface PeerRecord {
 }
 export declare function listPeers(): Promise<PeerRecord[]>;
 export declare function addPeer(record: PeerRecord): Promise<void>;
+/**
+ * Returns the set of distinct `remote_epk` values in peers.json.
+ *
+ * In the current pairing model (plan/23 + plan/24), each `remote_epk` is the
+ * Owner's Ed25519 pubkey — and we treat each as a distinct Owner the Pi has
+ * been paired with. Used by the mesh self-revoke poller (plan/24 Wave 3) to
+ * know which Owners' mesh blobs to fetch.
+ */
+export declare function listOwnerPubkeys(): Promise<string[]>;
 export declare function removePeer(remoteEpk: string): Promise<boolean>;
+/** Test-only: expose the identity-file path so tests can clean it. */
+export declare const _IDENTITY_FILE_FOR_TEST: string;
+/** Test-only: expose unlink for cleanup. */
+export declare const _unlinkIdentityFileForTest: () => Promise<void>;

package/dist/pairing/storage.js

@@ -1,35 +1,147 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile, chmod, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import keytar from "keytar";
+import { AsyncEntry } from "@napi-rs/keyring";
 import { generateEd25519Keypair } from "./crypto.js";
-const KEYCHAIN_SERVICE = "dev.remotepi.mac";
-const PEERS_PATH = join(homedir(), ".pi", "remote", "peers.json");
-// ── Keychain ──────────────────────────────────────────────────────────────────
-async function loadKeypairFromKeychain(account) {
-    const stored = await keytar.getPassword(KEYCHAIN_SERVICE, account);
-    if (!stored)
-        return null;
+/**
+ * Pi-secret storage (plan/27 Wave E1).
+ *
+ * The Ed25519 long-term identity of this Pi lives in the platform keyring
+ * via `@napi-rs/keyring` (Keychain on macOS, libsecret on Linux desktop,
+ * Credential Manager on Windows — DPAPI-backed). When the keyring is
+ * unavailable (headless Linux without a D-Bus session, Docker containers,
+ * VPS without GNOME Keyring/KWallet running) we fall back to a
+ * file-backed store at `~/.pi/remote/identity.json` with `0o600`
+ * permissions and the parent dir at `0o700`.
+ *
+ * **Migration**: previous builds used `keytar` against service
+ * `dev.remotepi.mac`. This module reads from the old service if the new
+ * service is empty, copies the entry to the new service `dev.remotepi.pi`,
+ * and deletes the old one. Both keytar and `@napi-rs/keyring` address the
+ * same OS-level credential store on every supported platform, so the read
+ * succeeds without keeping the deprecated `keytar` dependency.
+ */
+const NEW_SERVICE = "dev.remotepi.pi"; // platform-neutral
+const OLD_SERVICE = "dev.remotepi.mac"; // legacy keytar service (pre-2026-05-25)
+const ACCOUNT = "longterm-ed25519";
+const PI_DIR = join(homedir(), ".pi", "remote");
+const IDENTITY_FILE = join(PI_DIR, "identity.json");
+const PEERS_PATH = join(PI_DIR, "peers.json");
+class NapiKeyringBackend {
+    async read(service, account) {
+        const entry = new AsyncEntry(service, account);
+        return entry.getPassword(); // returns undefined on no-entry
+    }
+    async write(service, account, value) {
+        const entry = new AsyncEntry(service, account);
+        await entry.setPassword(value);
+    }
+    async delete(service, account) {
+        const entry = new AsyncEntry(service, account);
+        try {
+            return await entry.deleteCredential();
+        }
+        catch {
+            return false;
+        }
+    }
+}
+let _backend = null;
+function _getBackend() {
+    if (!_backend)
+        _backend = new NapiKeyringBackend();
+    return _backend;
+}
+/** Test-only: swap (or clear with `null`) the keyring backend. */
+export function _setKeyStoreBackendForTest(backend) {
+    _backend = backend;
+}
+function _serialize(kp) {
+    const payload = {
+        pk: Buffer.from(kp.publicKey).toString("base64"),
+        sk: Buffer.from(kp.secretKey).toString("base64"),
+    };
+    return JSON.stringify(payload);
+}
+function _deserialize(stored) {
     const parsed = JSON.parse(stored);
     return {
         publicKey: Buffer.from(parsed.pk, "base64"),
         secretKey: Buffer.from(parsed.sk, "base64"),
     };
 }
-async function saveKeypairToKeychain(account, kp) {
-    const data = JSON.stringify({
-        pk: Buffer.from(kp.publicKey).toString("base64"),
-        sk: Buffer.from(kp.secretKey).toString("base64"),
-    });
-    await keytar.setPassword(KEYCHAIN_SERVICE, account, data);
+// ── File fallback (headless Linux) ──────────────────────────────────────────
+async function _readKeypairFromFile() {
+    try {
+        const raw = await readFile(IDENTITY_FILE, "utf8");
+        return _deserialize(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function _writeKeypairToFile(kp) {
+    await mkdir(PI_DIR, { recursive: true, mode: 0o700 });
+    // Best-effort tighten of the dir in case it pre-existed with looser
+    // permissions (mkdir's mode is only applied to NEW dirs).
+    try {
+        await chmod(PI_DIR, 0o700);
+    }
+    catch { /* not fatal */ }
+    await writeFile(IDENTITY_FILE, _serialize(kp), { mode: 0o600 });
+    try {
+        await chmod(IDENTITY_FILE, 0o600);
+    }
+    catch { /* not fatal */ }
 }
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Returns the Pi-secret Ed25519 keypair, generating + persisting one on
+ * first call. Resolution order:
+ *   1. New keyring service `dev.remotepi.pi`
+ *   2. Old keyring service `dev.remotepi.mac` (migrate → step 1, delete old)
+ *   3. File `~/.pi/remote/identity.json` (headless-Linux fallback)
+ *   4. Generate a fresh keypair + persist to the first available backend
+ *
+ * Idempotent: subsequent calls return the same identity. The migration
+ * runs at most once per machine (the old entry is deleted after copy).
+ */
 export async function getOrCreateEd25519Keypair() {
-    const existing = await loadKeypairFromKeychain("longterm-ed25519");
-    if (existing)
-        return existing;
-    const kp = generateEd25519Keypair();
-    await saveKeypairToKeychain("longterm-ed25519", kp);
-    return kp;
+    const backend = _getBackend();
+    // ── Path A: keyring ────────────────────────────────────────────────────
+    try {
+        const existing = await backend.read(NEW_SERVICE, ACCOUNT);
+        if (existing)
+            return _deserialize(existing);
+        const legacy = await backend.read(OLD_SERVICE, ACCOUNT);
+        if (legacy) {
+            const kp = _deserialize(legacy);
+            await backend.write(NEW_SERVICE, ACCOUNT, legacy);
+            const deleted = await backend.delete(OLD_SERVICE, ACCOUNT);
+            console.info(`[remote-pi] Migrated Pi-secret from "${OLD_SERVICE}" to "${NEW_SERVICE}" ` +
+                `(old entry deleted: ${deleted})`);
+            return kp;
+        }
+        // Neither entry exists — generate and save to new service.
+        const fresh = generateEd25519Keypair();
+        await backend.write(NEW_SERVICE, ACCOUNT, _serialize(fresh));
+        console.info(`[remote-pi] Generated new Pi-secret in keyring "${NEW_SERVICE}"`);
+        return fresh;
+    }
+    catch (err) {
+        // ── Path B: file fallback (typically headless Linux) ───────────────
+        console.warn("[remote-pi] WARNING: keyring unavailable, falling back to file-based " +
+            "storage at " + IDENTITY_FILE + " (mode 0600). Set up GNOME Keyring/" +
+            "KWallet for better security. " +
+            `Set PI_KEY_INSECURE_FALLBACK=true to suppress this warning. ` +
+            `Cause: ${String(err)}`);
+        const fromFile = await _readKeypairFromFile();
+        if (fromFile)
+            return fromFile;
+        const fresh = generateEd25519Keypair();
+        await _writeKeypairToFile(fresh);
+        return fresh;
+    }
 }
 export async function listPeers() {
     try {
@@ -53,6 +165,21 @@ export async function addPeer(record) {
     await mkdir(dirname(PEERS_PATH), { recursive: true });
     await writeFile(PEERS_PATH, JSON.stringify({ peers }, null, 2));
 }
+/**
+ * Returns the set of distinct `remote_epk` values in peers.json.
+ *
+ * In the current pairing model (plan/23 + plan/24), each `remote_epk` is the
+ * Owner's Ed25519 pubkey — and we treat each as a distinct Owner the Pi has
+ * been paired with. Used by the mesh self-revoke poller (plan/24 Wave 3) to
+ * know which Owners' mesh blobs to fetch.
+ */
+export async function listOwnerPubkeys() {
+    const peers = await listPeers();
+    const seen = new Set();
+    for (const p of peers)
+        seen.add(p.remote_epk);
+    return [...seen];
+}
 export async function removePeer(remoteEpk) {
     const peers = await listPeers();
     const filtered = peers.filter((p) => p.remote_epk !== remoteEpk);
@@ -62,4 +189,14 @@ export async function removePeer(remoteEpk) {
     await writeFile(PEERS_PATH, JSON.stringify({ peers: filtered }, null, 2));
     return true;
 }
+// ── Test-only helpers ────────────────────────────────────────────────────────
+/** Test-only: expose the identity-file path so tests can clean it. */
+export const _IDENTITY_FILE_FOR_TEST = IDENTITY_FILE;
+/** Test-only: expose unlink for cleanup. */
+export const _unlinkIdentityFileForTest = async () => {
+    try {
+        await unlink(IDENTITY_FILE);
+    }
+    catch { /* fine if missing */ }
+};
 //# sourceMappingURL=storage.js.map

package/dist/pairing/storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/pairing/storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAuB,MAAM,aAAa,CAAC;AAE1E,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AAC5C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;AAElE,iFAAiF;AAEjF,KAAK,UAAU,uBAAuB,CACpC,OAAe;IAEf,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IACnE,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAA+B,CAAC;IAChE,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC;QAC3C,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC;KAC5C,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,qBAAqB,CAClC,OAAe,EACf,EAAoD;IAEpD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAChD,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;KACjD,CAAC,CAAC;IACH,MAAM,MAAM,CAAC,WAAW,CAAC,gBAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB;IAC7C,MAAM,QAAQ,GAAG,MAAM,uBAAuB,CAAC,kBAAkB,CAAC,CAAC;IACnE,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,EAAE,GAAG,sBAAsB,EAAE,CAAC;IACpC,MAAM,qBAAqB,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;IACpD,OAAO,EAAE,CAAC;AACZ,CAAC;AAUD,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;QAC1D,OAAO,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAAkB;IAC9C,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAC;IAChC,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,MAAM,CAAC,UAAU,CAAC,CAAC;IACvE,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,qBAAqB;IAC5C,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC;IACD,MAAM,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,SAAiB;IAChD,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC;IACjE,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACnD,MAAM,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1E,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/pairing/storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAuB,MAAM,aAAa,CAAC;AAE1E;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,GAAG,iBAAiB,CAAC,CAAE,mBAAmB;AAC3D,MAAM,WAAW,GAAG,kBAAkB,CAAC,CAAC,yCAAyC;AACjF,MAAM,OAAO,GAAG,kBAAkB,CAAC;AAEnC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAChD,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AACpD,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAoB9C,MAAM,kBAAkB;IACtB,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,OAAe;QACzC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC/C,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,CAAE,gCAAgC;IAC/D,CAAC;IACD,KAAK,CAAC,KAAK,CAAC,OAAe,EAAE,OAAe,EAAE,KAAa;QACzD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC/C,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,OAAe,EAAE,OAAe;QAC3C,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC/C,IAAI,CAAC;YACH,OAAO,MAAM,KAAK,CAAC,gBAAgB,EAAE,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF;AAED,IAAI,QAAQ,GAA2B,IAAI,CAAC;AAE5C,SAAS,WAAW;IAClB,IAAI,CAAC,QAAQ;QAAE,QAAQ,GAAG,IAAI,kBAAkB,EAAE,CAAC;IACnD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,0BAA0B,CAAC,OAA+B;IACxE,QAAQ,GAAG,OAAO,CAAC;AACrB,CAAC;AASD,SAAS,UAAU,CAAC,EAAkB;IACpC,MAAM,OAAO,GAAsB;QACjC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAChD,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;KACjD,CAAC;IACF,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAsB,CAAC;IACvD,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC;QAC3C,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC;KAC5C,CAAC;AACJ,CAAC;AAED,+EAA+E;AAE/E,KAAK,UAAU,oBAAoB;IACjC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;QAClD,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,mBAAmB,CAAC,EAAkB;IACnD,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACtD,oEAAoE;IACpE,0DAA0D;IAC1D,IAAI,CAAC;QAAC,MAAM,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC;IAC7D,MAAM,SAAS,CAAC,aAAa,EAAE,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAChE,IAAI,CAAC;QAAC,MAAM,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC;AACtE,CAAC;AAED,+EAA+E;AAE/E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB;IAC7C,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;IAE9B,0EAA0E;IAC1E,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAC1D,IAAI,QAAQ;YAAE,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;QAE5C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACxD,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;YAChC,MAAM,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YAClD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YAC3D,OAAO,CAAC,IAAI,CACV,wCAAwC,WAAW,SAAS,WAAW,IAAI;gBAC3E,uBAAuB,OAAO,GAAG,CAClC,CAAC;YACF,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,2DAA2D;QAC3D,MAAM,KAAK,GAAG,sBAAsB,EAAE,CAAC;QACvC,MAAM,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7D,OAAO,CAAC,IAAI,CAAC,mDAAmD,WAAW,GAAG,CAAC,CAAC;QAChF,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,sEAAsE;QACtE,OAAO,CAAC,IAAI,CACV,uEAAuE;YACvE,aAAa,GAAG,aAAa,GAAG,qCAAqC;YACrE,+BAA+B;YAC/B,8DAA8D;YAC9D,UAAU,MAAM,CAAC,GAAG,CAAC,EAAE,CACxB,CAAC;QACF,MAAM,QAAQ,GAAG,MAAM,oBAAoB,EAAE,CAAC;QAC9C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,KAAK,GAAG,sBAAsB,EAAE,CAAC;QACvC,MAAM,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACjC,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAUD,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;QAC1D,OAAO,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAAkB;IAC9C,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAC;IAChC,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,MAAM,CAAC,UAAU,CAAC,CAAC;IACvE,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,qBAAqB;IAC5C,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC;IACD,MAAM,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAC9C,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,SAAiB;IAChD,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC;IACjE,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACnD,MAAM,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1E,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAEhF,sEAAsE;AACtE,MAAM,CAAC,MAAM,uBAAuB,GAAG,aAAa,CAAC;AACrD,4CAA4C;AAC5C,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,IAAmB,EAAE;IAClE,IAAI,CAAC;QAAC,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;AACtE,CAAC,CAAC"}

package/dist/protocol/types.d.ts

@@ -61,6 +61,25 @@ export type ServerMessage = {
     session_name: string;
     session_started_at: number;
     room_id: string;
+    /**
+     * Plan/27 Wave A: identifies the host coding agent driving this
+     * pi-extension instance. `name` is hardcoded to "Pi coding agent"
+     * today; future Pi forks (Claude Code, OpenCode) populate their own
+     * here. `version` is the pi-extension `package.json` version.
+     * Optional in the wire schema so app-side parsing tolerates older
+     * Pi builds that predate this field — every new pairing emits both.
+     */
+    harness?: {
+        name: string;
+        version: string;
+    };
+    /**
+     * Plan/27 Wave A: `os.hostname()` of the machine the Pi runs on.
+     * App displays it in the device list so the user can distinguish
+     * two paired PCs that happen to share a nickname or sit in the
+     * same project folder.
+     */
+    hostname?: string;
 } | {
     type: "pair_error";
     in_reply_to: string;
@@ -70,6 +89,10 @@ export type ServerMessage = {
     type: "user_input";
     id: string;
     text: string;
+} | {
+    type: "user_message";
+    id: string;
+    text: string;
 } | {
     type: "agent_chunk";
     in_reply_to: string;

package/dist/session/broker.d.ts

@@ -7,6 +7,27 @@ import { type Envelope } from "./envelope.js";
  *
  * Auto-suffix on name collision: when a peer registers a name already taken,
  * the broker assigns `<name>#N` and returns it in the register ack.
+ *
+ * ## ACK protocol (plan/25 Wave 0)
+ *
+ * For **unicast non-broker** envelopes the broker synchronously emits an ACK
+ * envelope back to the sender after deciding delivery:
+ *
+ *   - target idle  → mark target busy, deliver envelope, ACK `received`
+ *   - target busy  → drop envelope, ACK `busy`
+ *
+ * "Busy" tracking is driven by control envelopes `{type:"turn_state", busy}`
+ * the peer wrappers send on `turn_start`/`turn_end`. The broker also flips a
+ * peer to busy at the moment it delivers an envelope to it — this is the
+ * "received = commitment" rule: delivery itself is the promise the peer will
+ * handle the message in its upcoming turn. The wrapper's own turn_end clears
+ * it again. Atomicity between busy-check and busy-set is guaranteed by Node's
+ * single-threaded event loop — the block in `_route` does no `await` between
+ * the two.
+ *
+ * Broadcast/multicast/broker-addressed envelopes are not ACKed (no single
+ * authoritative recipient or no semantic match). The audit log carries the
+ * ACK status (`received | busy | dropped | none`) per envelope.
  */
 export interface BrokerOptions {
     server: Server;
@@ -14,12 +35,58 @@ export interface BrokerOptions {
     /** Optional callback invoked after each successful route (testing/observability). */
     onRouted?: (env: Envelope, deliveredTo: string[]) => void;
 }
+/**
+ * Hook the broker calls before doing local routing, so cross-PC prefixes
+ * (`<pc_label>:<peer_name>`) can be handed off to a remote forwarder
+ * without baking transport knowledge into the broker. Wave C (plan/25)
+ * wires `broker_remote.ts` here.
+ */
+export interface RemoteRouter {
+    /**
+     * Try to claim responsibility for routing this envelope cross-PC.
+     * Returns true if claimed (broker MUST NOT also deliver locally). Returns
+     * false if the envelope should fall through to local routing — e.g., the
+     * prefix matches the local `pc_label`, the prefix is not a known remote
+     * label (backward-compat for local names containing `:`), or there's no
+     * prefix at all.
+     */
+    tryRouteOutbound(env: Envelope): boolean;
+    /** Aggregated remote peer names (`<pc_label>:<peer_name>`) for the
+     *  `list_peers` reply. Returns empty when nothing is known yet. */
+    listRemotePeers(): string[];
+}
+/** Local outcome of a cross-PC envelope injection. broker_remote uses this
+ *  to construct the ACK envelope it sends back via the relay. */
+export type RemoteInjectStatus = "received" | "busy" | "denied";
 export declare class Broker {
     private readonly peers;
+    /** Peers whose wrapper has signaled they are mid-turn, or to whom the
+     *  broker has just delivered an envelope (received = commitment). */
+    private readonly busyPeers;
     private readonly auditPath?;
     private readonly onRouted?;
     private readonly server;
+    /** Plan/25 Wave C: optional handoff for cross-PC routing. Null = local only. */
+    private remoteRouter;
     constructor(opts: BrokerOptions);
+    /** Attach (or detach with null) a cross-PC router. Idempotent. */
+    setRemoteRouter(router: RemoteRouter | null): void;
+    /**
+     * Plan/25 Wave C entry point: deliver an envelope that arrived from a
+     * remote PC (via relay forward) into the local UDS mesh. Skips the
+     * `force from = conn.name` rule (that defense is anti-spoof for local
+     * peers; cross-PC has its own defense via the relay's verified `from_pc`).
+     *
+     * Returns the ACK status so the caller (broker_remote) can pack and
+     * forward an ACK envelope back across the relay:
+     *   - `received` — target was idle (or `env.re != null`, see Wave 0
+     *     bypass rule), envelope delivered, broker marked target busy if
+     *     this is new work
+     *   - `busy` — target mid-turn, envelope dropped
+     *   - `denied` — no such local peer (or write failed) — caller maps to
+     *     transport_error or denied ACK as it sees fit
+     */
+    injectFromRemote(env: Envelope): RemoteInjectStatus;
     /** Peers currently registered. Snapshot, safe to read. */
     peerNames(): string[];
     close(): Promise<void>;
@@ -31,6 +98,13 @@ export declare class Broker {
     private _onClose;
     private _route;
     private _resolveTargets;
+    /**
+     * Writes an ACK envelope to the original sender's socket. Synchronous —
+     * the caller is inside `_route` and must keep busy-check/busy-set atomic.
+     * Broker → sender: `from="broker"`, `to=env.from`, `re=env.id`,
+     * `body={type:"ack", status, target}`.
+     */
+    private _sendAckToSender;
     private _handleBrokerMessage;
     private _broadcastSystem;
     private _appendAudit;