remote-pi 0.4.2 → 0.5.0

package/dist/pairing/qr.js

@@ -1,6 +1,16 @@
 import { randomBytes } from "node:crypto";
 import qrTerminal from "qrcode-terminal";
-const TOKEN_TTL_MS = 60_000;
+/** Default ephemeral-token lifetime (also the QR rotation period). */
+export const TOKEN_TTL_MS = 60_000;
+/** Bounds for a caller-supplied pairing TTL (e.g. `/remote-pi pair --ttl <s>`). */
+export const PAIR_TTL_MIN_MS = 10_000;
+export const PAIR_TTL_MAX_MS = 600_000;
+/** Clamp an arbitrary ttl (ms) into the safe pairing range; NaN → default. */
+export function clampPairTtlMs(ttlMs) {
+    if (!Number.isFinite(ttlMs))
+        return TOKEN_TTL_MS;
+    return Math.min(PAIR_TTL_MAX_MS, Math.max(PAIR_TTL_MIN_MS, Math.floor(ttlMs)));
+}
 /** Encapsulates the single active QR token. One instance per Pi process. */
 export class QRSession {
     active = null;
@@ -12,9 +22,9 @@ export class QRSession {
      * Issues a new active token, invalidating any previous one.
      * Returns the token and its expiry timestamp.
      */
-    issueToken() {
+    issueToken(ttlMs = TOKEN_TTL_MS) {
         const token = this.generateToken();
-        const expiresAt = Date.now() + TOKEN_TTL_MS;
+        const expiresAt = Date.now() + ttlMs;
         this.active = { token, expiresAt, consumed: false };
         return { token, expiresAt };
     }

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/protocol/codec.js

@@ -2,6 +2,7 @@ const SERVER_TYPES = new Set([
     "pair_ok",
     "pair_error",
     "user_input",
+    "queued_message_state",
     "agent_chunk",
     "agent_done",
     "agent_message",

package/dist/protocol/codec.js.map

@@ -1 +1 @@
-{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/protocol/codec.ts"],"names":[],"mappings":"AAEA,MAAM,YAAY,GAAG,IAAI,GAAG,CAAwB;IAClD,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,aAAa;IACb,YAAY;IACZ,eAAe;IACf,cAAc;IACd,aAAa;IACb,OAAO;IACP,WAAW;IACX,MAAM;IACN,KAAK;IACL,iBAAiB;CAClB,CAAC,CAAC;AAEH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAElB;IADlB,YACkB,IAA4C,EAC5D,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAwC;QAI5D,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAC,GAAkB;IAC7C,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,aAAc,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,IACE,CAAC,GAAG;QACJ,OAAO,GAAG,KAAK,QAAQ;QACvB,OAAQ,GAA+B,CAAC,IAAI,KAAK,QAAQ,EACzD,CAAC;QACD,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,CAAC,GAAI,GAA+B,CAAC,IAAc,CAAC;IAC1D,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAA0B,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,GAAoB,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/protocol/codec.ts"],"names":[],"mappings":"AAEA,MAAM,YAAY,GAAG,IAAI,GAAG,CAAwB;IAClD,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,sBAAsB;IACtB,aAAa;IACb,YAAY;IACZ,eAAe;IACf,cAAc;IACd,aAAa;IACb,OAAO;IACP,WAAW;IACX,MAAM;IACN,KAAK;IACL,iBAAiB;CAClB,CAAC,CAAC;AAEH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAElB;IADlB,YACkB,IAA4C,EAC5D,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAwC;QAI5D,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAC,GAAkB;IAC7C,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,aAAc,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,IACE,CAAC,GAAG;QACJ,OAAO,GAAG,KAAK,QAAQ;QACvB,OAAQ,GAA+B,CAAC,IAAI,KAAK,QAAQ,EACzD,CAAC;QACD,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,CAAC,GAAI,GAA+B,CAAC,IAAc,CAAC;IAC1D,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAA0B,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,GAAoB,CAAC;AAC9B,CAAC"}

package/dist/protocol/types.d.ts

@@ -9,6 +9,13 @@ export type ClientMessage = {
     id: string;
     text: string;
     images?: WireImage[];
+} | {
+    type: "queued_message_set";
+    id: string;
+    text: string;
+} | {
+    type: "queued_message_clear";
+    id: string;
 } | {
     type: "approve_tool";
     id: string;
@@ -132,6 +139,10 @@ export type ServerMessage = {
     id: string;
     text: string;
     images?: WireImage[];
+} | {
+    type: "queued_message_state";
+    id?: string;
+    text?: string;
 } | {
     type: "agent_chunk";
     in_reply_to: string;

package/dist/rooms.d.ts

@@ -7,3 +7,23 @@
  * Format: first 12 chars of base64url(sha256(realpath)).
  */
 export declare function roomIdForCwd(cwd: string): string;
+/**
+ * THE single derivation of the App↔Pi `room_id` (plan/41) — keyed by
+ * `(cwd, name)` so several agents in the SAME folder get distinct rooms (the
+ * app then renders one tile per agent instead of merging them into one).
+ *
+ * Default-preserving: when `name` is absent OR equals `defaultAgentName(cwd)`
+ * (an agent with no custom `agent_name`), it returns the LEGACY `roomIdForCwd`
+ * EXACTLY — so a single unnamed agent's existing conversation is NOT re-keyed
+ * on upgrade. A custom or `#N`-suffixed name → a name-scoped id (same formula
+ * the cwd-lock uses).
+ *
+ * Using the ASSIGNED leaf name (the broker's `#N` on collision) disambiguates
+ * even two unnamed agents: the 1st stays `folder` (== default → legacy room),
+ * the 2nd becomes `folder#2` (≠ default → name-scoped room).
+ *
+ * INVARIANT: every callsite that derives the App↔Pi room for the same agent
+ * MUST go through this function — otherwise the app would pair on a room the
+ * Pi never announces.
+ */
+export declare function roomIdFor(cwd: string, name?: string): string;

package/dist/rooms.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
+import { defaultAgentName } from "./session/local_config.js";
 /**
  * Deterministic room id derived from a cwd. Two Pi processes in the same
  * directory produce the same id; different cwds produce different ids
@@ -19,4 +20,38 @@ export function roomIdForCwd(cwd) {
     }
     return createHash("sha256").update(target).digest("base64url").slice(0, 12);
 }
+/**
+ * THE single derivation of the App↔Pi `room_id` (plan/41) — keyed by
+ * `(cwd, name)` so several agents in the SAME folder get distinct rooms (the
+ * app then renders one tile per agent instead of merging them into one).
+ *
+ * Default-preserving: when `name` is absent OR equals `defaultAgentName(cwd)`
+ * (an agent with no custom `agent_name`), it returns the LEGACY `roomIdForCwd`
+ * EXACTLY — so a single unnamed agent's existing conversation is NOT re-keyed
+ * on upgrade. A custom or `#N`-suffixed name → a name-scoped id (same formula
+ * the cwd-lock uses).
+ *
+ * Using the ASSIGNED leaf name (the broker's `#N` on collision) disambiguates
+ * even two unnamed agents: the 1st stays `folder` (== default → legacy room),
+ * the 2nd becomes `folder#2` (≠ default → name-scoped room).
+ *
+ * INVARIANT: every callsite that derives the App↔Pi room for the same agent
+ * MUST go through this function — otherwise the app would pair on a room the
+ * Pi never announces.
+ */
+export function roomIdFor(cwd, name) {
+    if (!name || name === defaultAgentName(cwd))
+        return roomIdForCwd(cwd);
+    let target;
+    try {
+        target = realpathSync(cwd);
+    }
+    catch {
+        target = cwd;
+    }
+    // NUL separator (U+0000): impossible in a POSIX path and stripped from any
+    // sanitized name, so the cwd/name boundary is unambiguous.
+    const sep = String.fromCharCode(0);
+    return createHash("sha256").update(target + sep + name).digest("base64url").slice(0, 12);
+}
 //# sourceMappingURL=rooms.js.map

package/dist/rooms.js.map

@@ -1 +1 @@
-{"version":3,"file":"rooms.js","sourceRoot":"","sources":["../src/rooms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,MAAM,GAAG,GAAG,CAAC;IACf,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"rooms.js","sourceRoot":"","sources":["../src/rooms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,MAAM,GAAG,GAAG,CAAC;IACf,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,IAAa;IAClD,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,gBAAgB,CAAC,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;IACtE,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,GAAG,CAAC;IACf,CAAC;IACD,2EAA2E;IAC3E,2DAA2D;IAC3D,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACnC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3F,CAAC"}

package/dist/session/address.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Mesh addressing for plan/35 (malha direta). An "agent" ≡ a cwd (cwd_lock
+ * guarantees at most one Pi per folder), so the folder *is* the address:
+ *
+ *   - **local**  → an absolute path on this machine. A local peer is reached by
+ *     `POST`ing its inbox socket directly (see `apiSockPath`).
+ *   - **remote** → `<label>:/path`, where `<label>` names a sibling machine
+ *     (resolved to a pubkey via `mesh_versions`/siblings in Wave C) and `/path`
+ *     is the folder on that machine. Routed cross-PC through the relay.
+ *
+ * The address an agent passes is ALWAYS the absolute folder path; the `.sock`
+ * file itself lives OUTSIDE the cwd (decisão fixada — "Transporte local"). The
+ * folder is hashed to the file name, so the mapping is deterministic and both
+ * the inbox (its own socket) and a sender (the peer's socket) land on the same
+ * file without coordinating.
+ *
+ * Wave 0 only *parses* what it is handed — contacts (known routes) live in the
+ * agent's context/CLAUDE.md (decisão Q5), not in an allowlist module. The
+ * `<label>→pubkey` resolution and remote send arrive in Wave C; here we keep
+ * the parser and the local route→socket mapping.
+ */
+export type Address = {
+    kind: "local";
+    path: string;
+} | {
+    kind: "remote";
+    label: string;
+    path: string;
+};
+export declare class AddressError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parses a mesh address. A `:` separates a remote `<label>` from its `/path`;
+ * with no `:` the whole string is a local absolute path (decisão fixada:
+ * "Sem ':' → local"). Both the local path and the remote path must be
+ * absolute — the folder is the canonical route.
+ */
+export declare function parseAddress(raw: string): Address;
+/**
+ * The inbox socket path for a folder. Single source of truth shared by the
+ * inbox server (its own socket) and the send client (a local peer's socket).
+ *
+ * `~/.pi/remote-pi/socks/<roomId>.sock`, where `roomId = roomIdForCwd(folder)`
+ * (`sha256(realpath(folder))[:12]` — the same hash `cwd_lock` uses). The folder
+ * is the address; the hash is only the file name. `realpath` canonicalization
+ * means `/a` and a symlink to `/a` map to the same socket.
+ */
+export declare function apiSockPath(folderPath: string): string;

package/dist/session/address.js

@@ -0,0 +1,58 @@
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { roomIdForCwd } from "../rooms.js";
+export class AddressError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AddressError";
+    }
+}
+/**
+ * Parses a mesh address. A `:` separates a remote `<label>` from its `/path`;
+ * with no `:` the whole string is a local absolute path (decisão fixada:
+ * "Sem ':' → local"). Both the local path and the remote path must be
+ * absolute — the folder is the canonical route.
+ */
+export function parseAddress(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        throw new AddressError("empty address");
+    const colon = trimmed.indexOf(":");
+    if (colon === -1) {
+        if (!isAbsolute(trimmed)) {
+            throw new AddressError(`local address must be an absolute path: ${trimmed}`);
+        }
+        return { kind: "local", path: trimmed };
+    }
+    const label = trimmed.slice(0, colon);
+    const path = trimmed.slice(colon + 1);
+    if (!label)
+        throw new AddressError(`remote address missing label: ${trimmed}`);
+    if (!path)
+        throw new AddressError(`remote address missing path: ${trimmed}`);
+    if (!isAbsolute(path)) {
+        throw new AddressError(`remote address path must be absolute: ${trimmed}`);
+    }
+    return { kind: "remote", label, path };
+}
+/** Directory holding inbox sockets, resolved at call time (not module load) so
+ *  tests can redirect it via `REMOTE_PI_HOME` — the same override `cwd_lock`
+ *  honors. Kept OUT of the cwd: `sun_path` is capped at 104 chars on macOS
+ *  (EINVAL at ≥105), so a socket nested inside a deep cwd would overflow. */
+function socksDir() {
+    const root = process.env["REMOTE_PI_HOME"] || homedir();
+    return join(root, ".pi", "remote-pi", "socks");
+}
+/**
+ * The inbox socket path for a folder. Single source of truth shared by the
+ * inbox server (its own socket) and the send client (a local peer's socket).
+ *
+ * `~/.pi/remote-pi/socks/<roomId>.sock`, where `roomId = roomIdForCwd(folder)`
+ * (`sha256(realpath(folder))[:12]` — the same hash `cwd_lock` uses). The folder
+ * is the address; the hash is only the file name. `realpath` canonicalization
+ * means `/a` and a symlink to `/a` map to the same socket.
+ */
+export function apiSockPath(folderPath) {
+    return join(socksDir(), `${roomIdForCwd(folderPath)}.sock`);
+}
+//# sourceMappingURL=address.js.map

package/dist/session/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../src/session/address.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA4B3C,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,YAAY,CAAC,eAAe,CAAC,CAAC;IAEtD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;QACjB,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,YAAY,CAAC,2CAA2C,OAAO,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,YAAY,CAAC,iCAAiC,OAAO,EAAE,CAAC,CAAC;IAC/E,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,YAAY,CAAC,gCAAgC,OAAO,EAAE,CAAC,CAAC;IAC7E,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,YAAY,CAAC,yCAAyC,OAAO,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzC,CAAC;AAED;;;6EAG6E;AAC7E,SAAS,QAAQ;IACf,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,OAAO,EAAE,CAAC;IACxD,OAAO,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,UAAkB;IAC5C,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAC9D,CAAC"}

package/dist/session/broker.d.ts

@@ -1,5 +1,47 @@
 import type { Server } from "node:net";
 import { type Envelope } from "./envelope.js";
+/**
+ * Structured view of one mesh peer (plan/38). The `address` is the canonical
+ * routing key; the other fields let a client group/label peers WITHOUT parsing
+ * the address string. `pc` is undefined for local peers (filled cross-PC in
+ * Fase 2). Returned by `list_peers` as `peers_detailed`.
+ */
+export interface PeerInfo {
+    /** Cross-PC label; undefined for a local peer. */
+    pc?: string;
+    /** Working directory (realpath). Empty string for a legacy peer (no cwd). */
+    cwd: string;
+    /** Clean leaf name (carries a `#N` only on a same-(cwd,name) collision). */
+    name: string;
+    /** Canonical address — the broker's Map key and the `to`/`from` on the wire. */
+    address: string;
+}
+/**
+ * THE sole encoder of a peer address (plan/38): `[<pc>:]<cwd>@<nome>`.
+ *
+ * - `cwd` present → `<cwd>@<nome>` (the `@` separates name from path so a `/`
+ *   in the path never confuses lookup, which is exact-match anyway).
+ * - `cwd` empty (legacy peer that sent no cwd) → `address == name`, preserving
+ *   pre-plan/38 behavior so a mixed mesh keeps routing.
+ * - `pc` present (cross-PC, Fase 2) → prefixed `<pc>:`.
+ *
+ * Does NOT sanitize — callers sanitize the `name` once (see `sanitizeMeshName`)
+ * before composing, so an already-appended `#N` collision suffix survives.
+ * Everyone else ECHOES `peer.address` verbatim; only the broker composes.
+ */
+export declare function composeAddress(parts: {
+    pc?: string;
+    cwd: string;
+    name: string;
+}): string;
+/**
+ * Sanitize a requested mesh name to a safe leaf while PRESERVING a trailing
+ * `#N` collision suffix (which the cwd-lock or a prior assignment may have
+ * added — `sanitizeSegment` alone would mangle `#`→`-`). The base is run through
+ * `sanitizeSegment` (af66d04); an unusable base (empty / reserved keyword) falls
+ * back to `"agent"`.
+ */
+export declare function sanitizeMeshName(raw: string): string;
 /**
  * Broker hosted by the session leader. Accepts UDS connections, maintains a
  * `name → connection` map, routes envelopes per the `to` field, and appends
@@ -50,9 +92,15 @@ export interface RemoteRouter {
      * 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. */
+    /** Aggregated remote peer addresses (`<pc_label>:<cwd>@<nome>`) for the
+     *  `list_peers` reply's `peers` (string) field. Empty when nothing known. */
     listRemotePeers(): string[];
+    /** Structured remote roster (plan/38 Fase 2): one `PeerInfo` per cross-PC
+     *  peer with `pc` filled (the sibling label), `cwd`/`name` from the sibling's
+     *  inventory, and `address` prefixed `<pc>:<cwd>@<nome>`. Powers the
+     *  `peers_detailed` half of `list_peers` so clients group by `pc`/`cwd`
+     *  without parsing. Empty when nothing known. */
+    listRemotePeerInfos(): PeerInfo[];
 }
 /** Local outcome of a cross-PC envelope injection. broker_remote uses this
  *  to construct the ACK envelope it sends back via the relay. plan/34: `busy`
@@ -90,7 +138,35 @@ export declare class Broker {
     private _onData;
     private _handleLine;
     private _handleRegister;
-    private _uniqueName;
+    /**
+     * Answer a read-only `list_peers` request from an UNREGISTERED connection
+     * (the `remote-pi peers` CLI probe). Returns true when the line was such a
+     * probe — the reply is written and the connection stays unregistered: no
+     * name assigned, no `peer_joined`/`peer_left` broadcast, no sibling push, so
+     * querying the roster from the shell never perturbs the mesh. Returns false
+     * (not a probe) so the caller falls through to the register handshake.
+     */
+    private _tryObserverProbe;
+    /** Local UDS peer names plus cross-PC `<pc>:<peer>` entries from the remote
+     *  router (empty when no bridge). Shared by the registered `list_peers`
+     *  handler and the unregistered observer probe. */
+    private _allPeerNames;
+    /** Structured roster of LOCAL UDS peers (plan/38): one `PeerInfo` each, no
+     *  `pc` (they're on this machine). Public so the cross-PC router
+     *  (`broker_remote`) can read the authoritative local inventory directly to
+     *  push to siblings — no `list_peers` round-trip, no stale cache. */
+    localPeerInfos(): PeerInfo[];
+    /** Structured roster (plan/38): local peers (no `pc`) + cross-PC peers with
+     *  `pc`/`cwd`/`name` filled by the remote router (Fase 2). */
+    private _allPeerInfos;
+    /**
+     * Resolve a free `(name, address)` for a register, keyed by **(cwd, name)**
+     * (plan/38): the collision check is on the composed ADDRESS, so a name only
+     * collides with another peer in the SAME cwd. `#N` is appended to the name
+     * (matching the cwd-lock's suffix scheme) until the address is free; for a
+     * legacy peer (cwd "") the address is the name, preserving global-name `#N`.
+     */
+    private _uniqueIdentity;
     private _onClose;
     private _route;
     private _resolveTargets;

package/dist/session/broker.js

@@ -1,6 +1,36 @@
 import { appendFile, mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { parse, serialize, uuidv7, EnvelopeError } from "./envelope.js";
+import { sanitizeSegment } from "./local_config.js";
+/**
+ * THE sole encoder of a peer address (plan/38): `[<pc>:]<cwd>@<nome>`.
+ *
+ * - `cwd` present → `<cwd>@<nome>` (the `@` separates name from path so a `/`
+ *   in the path never confuses lookup, which is exact-match anyway).
+ * - `cwd` empty (legacy peer that sent no cwd) → `address == name`, preserving
+ *   pre-plan/38 behavior so a mixed mesh keeps routing.
+ * - `pc` present (cross-PC, Fase 2) → prefixed `<pc>:`.
+ *
+ * Does NOT sanitize — callers sanitize the `name` once (see `sanitizeMeshName`)
+ * before composing, so an already-appended `#N` collision suffix survives.
+ * Everyone else ECHOES `peer.address` verbatim; only the broker composes.
+ */
+export function composeAddress(parts) {
+    const base = parts.cwd ? `${parts.cwd}@${parts.name}` : parts.name;
+    return parts.pc ? `${parts.pc}:${base}` : base;
+}
+/**
+ * Sanitize a requested mesh name to a safe leaf while PRESERVING a trailing
+ * `#N` collision suffix (which the cwd-lock or a prior assignment may have
+ * added — `sanitizeSegment` alone would mangle `#`→`-`). The base is run through
+ * `sanitizeSegment` (af66d04); an unusable base (empty / reserved keyword) falls
+ * back to `"agent"`.
+ */
+export function sanitizeMeshName(raw) {
+    const m = /^(.*?)(#\d+)?$/.exec(raw);
+    const base = sanitizeSegment(m?.[1] ?? raw) ?? "agent";
+    return m?.[2] ? base + m[2] : base;
+}
 const BROKER_NAME = "broker";
 export class Broker {
     peers = new Map();
@@ -65,7 +95,7 @@ export class Broker {
     }
     // ── connection lifecycle ──────────────────────────────────────────────────
     _handleConnection(socket) {
-        const conn = { name: "", socket, buf: "" };
+        const conn = { name: "", cwd: "", address: "", socket, buf: "" };
         socket.setEncoding("utf8");
         socket.on("data", (chunk) => this._onData(conn, chunk));
         socket.on("close", () => this._onClose(conn));
@@ -83,8 +113,12 @@ export class Broker {
         }
     }
     async _handleLine(conn, line) {
-        // Unregistered conn must send a `register` control message first.
+        // Unregistered conn: a read-only `list_peers` probe (the `remote-pi peers`
+        // CLI — answered without registering, so it leaves no trace on the mesh) or
+        // the mandatory `register` handshake. Anything else `_handleRegister` drops.
         if (!conn.name) {
+            if (this._tryObserverProbe(conn, line))
+                return;
             this._handleRegister(conn, line);
             return;
         }
@@ -98,8 +132,9 @@ export class Broker {
                 return; // malformed; drop silently
             throw e;
         }
-        // Force `from` to the registered name (security: peer can't spoof).
-        env.from = conn.name;
+        // Force `from` to the registered ADDRESS (security: peer can't spoof; and
+        // replies/ACKs address back by the same canonical key the Map is keyed on).
+        env.from = conn.address;
         await this._route(env);
     }
     _handleRegister(conn, line) {
@@ -119,32 +154,114 @@ export class Broker {
             conn.socket.destroy();
             return;
         }
-        const assigned = this._uniqueName(req.name);
-        conn.name = assigned;
-        this.peers.set(assigned, conn);
-        const ack = { type: "register_ack", name_assigned: assigned };
+        // (cwd, name) identity (plan/38). The cwd is the first-class axis: the
+        // address embeds it, so two same-named agents in DIFFERENT folders get
+        // distinct addresses and never collide — `#N` fires only on the same cwd +
+        // same name. A legacy peer (no cwd) → cwd "" → `address == name`, preserving
+        // the old global-name behavior so a mixed mesh keeps routing.
+        conn.cwd = typeof req.cwd === "string" ? req.cwd : "";
+        const { name, address } = this._uniqueIdentity(conn.cwd, req.name);
+        conn.name = name;
+        conn.address = address;
+        this.peers.set(address, conn);
+        // `name_assigned` doubles as the compat alias: for a legacy peer it equals
+        // `address_assigned` (cwd empty → address == name), so old clients that read
+        // `name_assigned` still get a routable identity.
+        const ack = { type: "register_ack", address_assigned: address, name_assigned: name };
         try {
             conn.socket.write(JSON.stringify(ack) + "\n");
         }
         catch { /* peer hung up */ }
-        // Notify others (peer_joined broadcast).
-        this._broadcastSystem({ type: "peer_joined", name: assigned }, assigned);
+        // Notify others (peer_joined broadcast). The field carries the ADDRESS.
+        this._broadcastSystem({ type: "peer_joined", name: address, address }, address);
     }
-    _uniqueName(requested) {
-        if (!this.peers.has(requested))
-            return requested;
+    /**
+     * Answer a read-only `list_peers` request from an UNREGISTERED connection
+     * (the `remote-pi peers` CLI probe). Returns true when the line was such a
+     * probe — the reply is written and the connection stays unregistered: no
+     * name assigned, no `peer_joined`/`peer_left` broadcast, no sibling push, so
+     * querying the roster from the shell never perturbs the mesh. Returns false
+     * (not a probe) so the caller falls through to the register handshake.
+     */
+    _tryObserverProbe(conn, line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return false; // not JSON → let _handleRegister destroy it
+        }
+        if (!parsed || typeof parsed !== "object" || parsed.type !== "list_peers") {
+            return false;
+        }
+        const reply = {
+            from: BROKER_NAME,
+            to: "observer", // synthetic: the conn has no registered name
+            id: uuidv7(),
+            re: null,
+            body: {
+                type: "list_peers_reply",
+                peers: this._allPeerNames(),
+                peers_detailed: this._allPeerInfos(),
+            },
+        };
+        try {
+            conn.socket.write(serialize(reply));
+        }
+        catch { /* probe hung up */ }
+        return true;
+    }
+    /** Local UDS peer names plus cross-PC `<pc>:<peer>` entries from the remote
+     *  router (empty when no bridge). Shared by the registered `list_peers`
+     *  handler and the unregistered observer probe. */
+    _allPeerNames() {
+        const remote = this.remoteRouter ? this.remoteRouter.listRemotePeers() : [];
+        return [...this.peerNames(), ...remote];
+    }
+    /** Structured roster of LOCAL UDS peers (plan/38): one `PeerInfo` each, no
+     *  `pc` (they're on this machine). Public so the cross-PC router
+     *  (`broker_remote`) can read the authoritative local inventory directly to
+     *  push to siblings — no `list_peers` round-trip, no stale cache. */
+    localPeerInfos() {
+        return [...this.peers.values()].map((p) => ({
+            cwd: p.cwd,
+            name: p.name,
+            address: p.address,
+        }));
+    }
+    /** Structured roster (plan/38): local peers (no `pc`) + cross-PC peers with
+     *  `pc`/`cwd`/`name` filled by the remote router (Fase 2). */
+    _allPeerInfos() {
+        const remote = this.remoteRouter?.listRemotePeerInfos() ?? [];
+        return [...this.localPeerInfos(), ...remote];
+    }
+    /**
+     * Resolve a free `(name, address)` for a register, keyed by **(cwd, name)**
+     * (plan/38): the collision check is on the composed ADDRESS, so a name only
+     * collides with another peer in the SAME cwd. `#N` is appended to the name
+     * (matching the cwd-lock's suffix scheme) until the address is free; for a
+     * legacy peer (cwd "") the address is the name, preserving global-name `#N`.
+     */
+    _uniqueIdentity(cwd, requested) {
+        const sanitized = sanitizeMeshName(requested);
+        let address = composeAddress({ cwd, name: sanitized });
+        if (!this.peers.has(address))
+            return { name: sanitized, address };
+        // Collision: strip any client-provided `#N`, then re-suffix from #2.
+        const base = sanitized.replace(/#\d+$/, "");
         for (let n = 2; n < 1000; n++) {
-            const candidate = `${requested}#${n}`;
-            if (!this.peers.has(candidate))
-                return candidate;
+            const name = `${base}#${n}`;
+            address = composeAddress({ cwd, name });
+            if (!this.peers.has(address))
+                return { name, address };
         }
-        throw new Error(`name space exhausted for ${requested}`);
+        throw new Error(`name space exhausted for ${base} in ${cwd || "(no cwd)"}`);
     }
     _onClose(conn) {
-        if (!conn.name)
+        if (!conn.address)
             return;
-        this.peers.delete(conn.name);
-        this._broadcastSystem({ type: "peer_left", name: conn.name }, conn.name);
+        this.peers.delete(conn.address);
+        this._broadcastSystem({ type: "peer_left", name: conn.address, address: conn.address }, conn.address);
     }
     // ── routing ───────────────────────────────────────────────────────────────
     async _route(env) {
@@ -193,7 +310,15 @@ export class Broker {
     }
     _resolveTargets(env) {
         if (env.to === "broadcast") {
-            return this.peerNames().filter((n) => n !== env.from);
+            // plan/38 decision C: broadcast is scoped to the sender's cwd (folder
+            // colleagues), local-only. A peer in /a/b never hears /a/c. The sender is
+            // keyed by its address (= env.from); legacy peers (cwd "") broadcast among
+            // other cwd-less peers, matching pre-plan/38 behavior.
+            const sender = this.peers.get(env.from);
+            const scope = sender?.cwd ?? "";
+            return [...this.peers.values()]
+                .filter((p) => p.address !== env.from && p.cwd === scope)
+                .map((p) => p.address);
         }
         if (Array.isArray(env.to)) {
             return env.to.filter((n) => n !== env.from);
@@ -234,14 +359,16 @@ export class Broker {
         if (!body || typeof body !== "object")
             return;
         if (body.type === "list_peers") {
-            const remote = this.remoteRouter ? this.remoteRouter.listRemotePeers() : [];
-            const peers = [...this.peerNames(), ...remote];
             const reply = {
                 from: BROKER_NAME,
                 to: env.from,
                 id: uuidv7(),
                 re: env.id,
-                body: { type: "list_peers_reply", peers },
+                body: {
+                    type: "list_peers_reply",
+                    peers: this._allPeerNames(), // addresses — legacy clients route by these
+                    peers_detailed: this._allPeerInfos(), // plan/38 — clients group without parsing
+                },
             };
             const peer = this.peers.get(env.from);
             if (peer) {
@@ -256,13 +383,13 @@ export class Broker {
         // delivery on busy state. The Pi extension still publishes working state
         // as room_meta over the relay (index.ts), independent of the broker.
     }
-    _broadcastSystem(body, excludeName) {
-        for (const [name, peer] of this.peers) {
-            if (name === excludeName)
+    _broadcastSystem(body, excludeAddress) {
+        for (const [address, peer] of this.peers) {
+            if (address === excludeAddress)
                 continue;
             const env = {
                 from: BROKER_NAME,
-                to: name,
+                to: address,
                 id: uuidv7(),
                 re: null,
                 body,