@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-intercom/package.json

@@ -1,16 +1,26 @@
 {
   "name": "pi-intercom",
-  "version": "0.13.0",
+  "version": "0.16.1",
   "license": "MIT",
   "type": "module",
   "main": "index.ts",
+  "bin": {
+    "pi-intercom": "cli.mjs"
+  },
   "files": [
+    "cli.mjs",
+    "cli.ts",
+    "cross-machine-discovery.ts",
+    "cross-machine-envelope.ts",
+    "cross-machine-transport.ts",
     "index.ts",
     "types.ts",
     "config.ts",
     "cwd.ts",
     "extension-api.ts",
     "format-context.ts",
+    "handover.ts",
+    "herdr-location.ts",
     "project-agent.ts",
     "reply-tracker.ts",
     "broker/**/*.ts",
@@ -18,7 +28,7 @@
     "skills/**/*"
   ],
   "scripts": {
-    "test": "tsx --test broker/client.test.ts broker/client-liveness.test.ts broker/extension.test.ts broker/framing.test.ts broker/mailbox-persistence.test.ts broker/paths.test.ts broker/runtime-claim.test.ts broker/spawn.test.ts config.test.ts cwd.test.ts format-context.test.ts project-agent.test.ts reply-tracker.test.ts intercom.integration.test.ts test/inline-message.test.ts test/overlay-width.test.ts"
+    "test": "tsx --test handover.test.ts herdr-location.test.ts cross-machine-envelope.test.ts cross-machine-discovery.test.ts cross-machine-transport.test.ts cross-machine-integration.test.ts cli.test.ts broker/cross-machine-provenance.test.ts broker/client.test.ts broker/client-liveness.test.ts broker/mailbox-persistence.test.ts broker/extension.test.ts broker/framing.test.ts broker/paths.test.ts broker/runtime-claim.test.ts broker/spawn.test.ts config.test.ts cwd.test.ts format-context.test.ts project-agent.test.ts reply-tracker.test.ts intercom.integration.test.ts human-priority.pi.test.ts test/inline-message.test.ts test/overlay-width.test.ts test/handover-picker.test.ts"
   },
   "keywords": [
     "pi-package"

package/dist/extensions/pi-intercom/project-agent.ts

@@ -65,7 +65,7 @@ function normalizeCode(raw: unknown): HerdrErrorCode {
   return "VALIDATION_ERROR";
 }
 
-function createHerdrClient(options: { bin?: string; spawn?: SpawnHerdr } = {}): HerdrClient {
+export function createHerdrClient(options: { bin?: string; spawn?: SpawnHerdr } = {}): HerdrClient {
   const bin = options.bin ?? process.env.HERDR_BIN ?? "herdr";
   const spawnImpl = options.spawn ?? spawn;
   return {

package/dist/extensions/pi-intercom/skills/pi-intercom/SKILL.md

@@ -71,7 +71,8 @@ Before sending, verify who's connected:
 
 ```typescript
 intercom({ action: "list" })
-// → Shows all connected sessions with names, cwd, models, and live status (`idle`, `thinking`, `tool:<name>`)
+// → Shows all connected sessions with names, cwd, models, live status, and
+//   current Herdr workspace/tab/pane (or explicit not-hosted/unavailable state)
 ```
 
 ### Pattern 3: Reply Naturally
@@ -159,6 +160,25 @@ intercom({
 If a live session already exists in that `cwd`, intercom reuses it. If multiple
 sessions are active there, pass `to` to select one by name or session ID.
 
+### Pattern 6b: Hand Over Your Session
+
+When the user moves work to another session, `handover` summarizes this
+session (next task, decisions, files, current state, open questions) with the
+current model and sends it. The receiver acts on it like any inbound message.
+Pass the next task as `message`; targeting works exactly like `send`.
+
+```typescript
+intercom({
+  action: "handover",
+  cwd: "/path/to/other-repo",
+  openProjectPaneIfMissing: true,
+  message: "Port the schema fix here and run the adapter tests"
+})
+```
+
+Humans can run `/handover <target> [next task]` to review the summary in an
+editor before it is sent. `/handover` alone opens a picker for the target.
+
 ### Pattern 7: Handle Subagent Escalations (Orchestrator Side)
 
 When `pi-subagents` spawns a delegated child and supplies child bridge metadata,
@@ -235,7 +255,7 @@ new visible project panes should go through the supervisor.
 | `ask` | Blocks until reply (10 min default, configurable with `PI_INTERCOM_ASK_TIMEOUT_MS`) | You need an answer to continue |
 | `reply` | Responds to the active or pending inbound ask | You were asked something and need to answer naturally |
 | `pending` | Lists unresolved inbound asks | You need to see who is waiting before replying |
-| `list` | Returns all sessions with live status | You need to discover targets or choose an idle peer |
+| `list` | Returns all sessions with live status and freshly resolved Herdr location | You need to discover targets or choose an idle peer |
 | `status` | Returns your connection state | Troubleshooting |
 
 ## Visible Peer Sessions
@@ -274,6 +294,10 @@ if (result.isError && result.content[0].text.includes("Already waiting")) {
 
 ## Best Practices
 
+### Use list location instead of guessing
+
+For a Herdr-hosted session, `list` displays readable workspace and tab labels plus stable opaque IDs and a diagnostic pane ID. The workspace/tab values come from a fresh bounded Herdr snapshot for that list request, joined by the Pi session identity that remains stable when Herdr changes the workspace-qualified pane ID, so use them instead of inferring location from cwd or session name. `not under Herdr` means the session did not register a Herdr pane. `Herdr location unavailable` means it did register one, but the current snapshot failed or no longer contained that pane. Use `herdrLocation.paneId`, not the launch-time `herdrPaneId`, when current diagnostic pane metadata is needed. Do not use pane IDs as intercom addressing handles; target the session name or intercom session ID. If no connected session is Herdr-hosted, `list` does not call Herdr or add location lines.
+
 ### Use `ask` for blocking workflows
 
 When the worker needs information to proceed:

package/dist/extensions/pi-intercom/test/handover-picker.test.ts

@@ -0,0 +1,134 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { HandoverPicker, type HandoverPickerResult, type RemoteSessionLister } from "../ui/handover-picker.ts";
+import { SessionListOverlay, type SessionListSelection } from "../ui/session-list.ts";
+import type { SessionInfo } from "../types.ts";
+
+const theme = { fg: (_name: string, text: string) => text, bold: (text: string) => text };
+const KEYS: Record<string, string> = {
+  "tui.select.up": "\x1b[A",
+  "tui.select.down": "\x1b[B",
+  "tui.select.confirm": "\r",
+  "tui.select.cancel": "\x1b",
+  "tui.input.tab": "\t",
+  "tui.editor.deleteCharBackward": "\x7f",
+};
+const keybindings = {
+  matches: (data: string, id: string) => KEYS[id] === data,
+  getKeys: (id: string) => [id.split(".").pop()!],
+};
+
+function session(id: string, name: string, extra: Partial<SessionInfo> = {}): SessionInfo {
+  return { id, name, cwd: `/work/${name}`, model: "model", pid: 1, startedAt: 0, lastActivity: 0, ...extra };
+}
+
+const self = session("self-0000", "planner");
+const roster = [
+  self,
+  session("subagent-worker-run-1", "worker: You are the writer for lane x"),
+  session("unnamed-00", "subagent-chat-unnamed", { runtimeFallbackAlias: true, lastActivity: 1 }),
+  session("adapter-00", "adapter", { lastActivity: 2 }),
+];
+const noRemote: RemoteSessionLister = {
+  listMachines: async () => assert.fail("remote listing must not run on open"),
+  listAgents: async () => [],
+};
+
+function open(options: { lister?: RemoteSessionLister; preselectSessionId?: string } = {}) {
+  const results: Array<HandoverPickerResult | undefined> = [];
+  const picker = new HandoverPicker(
+    { requestRender() {} } as any,
+    theme as any,
+    keybindings as any,
+    { currentSession: self, sessions: roster, lister: options.lister ?? noRemote, preselectSessionId: options.preselectSessionId },
+    (result) => results.push(result),
+  );
+  const press = (...keys: string[]) => keys.forEach((key) => picker.handleInput(KEYS[key] ?? key));
+  return { picker, results, press, text: () => picker.render(88).join("\n") };
+}
+
+test("handover picker lists local peers without self or subagent children", () => {
+  const { text, press, results } = open();
+  assert.doesNotMatch(text(), /planner|You are the writer/);
+  assert.match(text(), /adapter \(adapter-\)[\s\S]*subagent-chat-unnamed/);
+  press("tui.select.confirm");
+  assert.equal(results[0]?.target.kind === "local" && results[0].target.session.id, "adapter-00");
+});
+
+test("handover picker returns the next task typed in the task field", () => {
+  const { press, results } = open({ preselectSessionId: "unnamed-00" });
+  press("port", " the fix", "tui.select.confirm");
+  assert.deepEqual(results, [{ target: { kind: "local", session: roster[2] }, goal: "port the fix" }]);
+});
+
+test("handover picker accepts pasted and Kitty-encoded next-task text", () => {
+  const { press, results } = open();
+  press("tui.input.tab", "\x1b[200~port the fix\x1b[201~", "\x1b[32u", "\x1b[97u", "tui.select.confirm");
+  assert.equal(results[0]?.goal, "port the fix a");
+});
+
+test("session list starts a handover on plain or Kitty-encoded h and messages on Enter", () => {
+  for (const [key, action] of [["h", "handover"], ["\x1b[104u", "handover"], ["\r", "message"]] as const) {
+    const selections: Array<SessionListSelection | undefined> = [];
+    new SessionListOverlay(theme as any, keybindings as any, self, [roster[3]!], (selection) => selections.push(selection)).handleInput(key);
+    assert.deepEqual(selections, [{ session: roster[3], action }], key);
+  }
+});
+
+test("handover picker fetches other machines on demand and targets a remote session by id", async () => {
+  const sessionId = "00000000-0000-4000-8000-000000000001";
+  const lister: RemoteSessionLister = {
+    listMachines: async () => [
+      { label: "workmac", target: "10.0.0.1", enabled: true },
+      { label: "macmini", target: "10.0.0.2", enabled: true },
+      { label: "off", target: "10.0.0.3", enabled: false },
+    ],
+    listAgents: async (machine) => {
+      if (machine.label === "macmini") throw new Error(`Saved Herdr machine "macmini" is unreachable: ${"slow ".repeat(20)}end-of-error.`);
+      return [{ name: sessionId, sessionId, cwd: "/work/remote", status: "idle" }];
+    },
+  };
+  const { press, results, text } = open({ lister });
+  press("tui.select.down", "tui.select.down", "tui.select.down", "tui.select.confirm");
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.match(text(), /00000000@workmac · idle/);
+  assert.match(text(), /Saved Herdr machine "macmini" is unreachable/);
+  assert.match(text(), /end-of-error\./, "long machine errors wrap instead of being cut off");
+  assert.doesNotMatch(text(), /off/);
+  press("tui.select.down", "tui.select.confirm");
+  assert.deepEqual(results, [{ target: { kind: "remote", target: `${sessionId}@workmac` }, goal: undefined }]);
+});
+
+test("handover picker keeps the highlighted remote session when an earlier machine answers later", async () => {
+  let answerSlow: (agents: Array<{ name: string }>) => void = () => {};
+  const lister: RemoteSessionLister = {
+    listMachines: async () => [
+      { label: "slow", target: "10.0.0.1", enabled: true },
+      { label: "fast", target: "10.0.0.2", enabled: true },
+    ],
+    listAgents: (machine) => machine.label === "fast"
+      ? Promise.resolve([{ name: "fast-agent" }])
+      : new Promise((resolve) => { answerSlow = resolve; }),
+  };
+  const { press, results } = open({ lister });
+  press("tui.select.down", "tui.select.down", "tui.select.down", "tui.select.confirm");
+  await new Promise((resolve) => setImmediate(resolve));
+  press("tui.select.down");
+  answerSlow([{ name: "slow-agent" }]);
+  await new Promise((resolve) => setImmediate(resolve));
+  press("tui.select.confirm");
+  assert.deepEqual(results, [{ target: { kind: "remote", target: "fast-agent@fast" }, goal: undefined }]);
+});
+
+test("handover picker renders lines at the declared overlay width", () => {
+  const { picker, press } = open();
+  for (const focus of ["list", "task"]) {
+    for (const width of [1, 2, 20, 50, 88, 120]) {
+      for (const line of picker.render(width)) assert.equal(visibleWidth(line), Math.min(width, 88), `${focus} ${width}`);
+    }
+    press("tui.input.tab", "a long next task that does not fit in a narrow overlay");
+  }
+});

package/dist/extensions/pi-intercom/test/inline-message.test.ts

@@ -51,6 +51,49 @@ test("expanded inline intercom messages show the full body without collapse cont
   assert.doesNotMatch(rendered, /Ctrl\+O/);
 });
 
+test("cross-machine messages label the asserted identity as unverified", () => {
+  const component = new InlineMessageComponent(from, {
+    ...message,
+    crossMachine: {
+      type: "ssh-relay",
+      version: 1,
+      origin: { name: "worker", sessionId: "00000000-0000-4000-8000-000000000001", machine: "laptop" },
+      trust: "ssh-asserted",
+    },
+  }, theme as any, 'intercom({ action: "send", to: "worker@laptop", message: "..." })');
+
+  const rendered = component.render(120).join("\n");
+  assert.match(rendered, /worker@laptop · unverified cross-machine/);
+  assert.match(rendered, /To send a new message to worker@laptop: intercom/);
+  assert.doesNotMatch(rendered, /To reply/);
+});
+
+test("collapsed cross-machine messages keep the unverified identity and new-message affordance explicit", () => {
+  const component = new InlineMessageComponent(from, {
+    ...message,
+    crossMachine: {
+      type: "ssh-relay",
+      version: 1,
+      origin: { name: "worker", sessionId: "00000000-0000-4000-8000-000000000001", machine: "laptop" },
+      trust: "ssh-asserted",
+    },
+  }, theme as any, 'intercom({ action: "send", to: "worker@laptop", message: "..." })', undefined, true);
+
+  const rendered = component.render(160).join("\n");
+  assert.match(rendered, /From: worker@laptop · unverified cross-machine/);
+  assert.match(rendered, /To send a new message to worker@laptop: intercom/);
+  assert.doesNotMatch(rendered, /To reply/);
+});
+
+test("local message header and reply affordance remain unchanged", () => {
+  const component = new InlineMessageComponent(from, message, theme as any, "intercom reply");
+
+  const rendered = component.render(100).join("\n");
+  assert.match(rendered, /From: sender \(\/tmp\/project\)/);
+  assert.match(rendered, /To reply: intercom reply/);
+  assert.doesNotMatch(rendered, /unverified cross-machine|To send a new message to/);
+});
+
 test("collapsed inline intercom messages keep preview, reply hint, and expand key visible", () => {
   const component = new InlineMessageComponent(
     from,

package/dist/extensions/pi-intercom/types.d.ts

@@ -0,0 +1,247 @@
+export declare const EXTENSION_BUS_FEATURE = "extension-bus-v1";
+export declare const EXACT_SEND_FEATURE = "exact-send-v1";
+export type DeliveryState = "socket_delivered" | "queued" | "failed" | "unknown";
+export interface DeliveryDetails {
+    delivery: DeliveryState;
+    code?: string;
+    retryable: boolean;
+    outcomeKnown: boolean;
+}
+export type HerdrLocation = {
+    status: "current";
+    workspace: {
+        id: string;
+        label: string;
+    };
+    tab: {
+        id: string;
+        label: string;
+    };
+    paneId: string;
+    /** Time when the broker requested the live Herdr snapshot. */
+    refreshedAt: number;
+} | {
+    status: "not_hosted";
+} | {
+    status: "unavailable";
+    paneId: string;
+    reason: "herdr_unavailable" | "unsupported" | "command_failed" | "pane_missing" | "invalid_response";
+    detail?: string;
+};
+export interface SessionInfo {
+    id: string;
+    /** Broker-owned lifetime of this live endpoint. */
+    endpointEpoch?: string;
+    name?: string;
+    /** True only when the extension synthesized name for an unnamed runtime. */
+    runtimeFallbackAlias?: boolean;
+    cwd: string;
+    model: string;
+    pid: number;
+    startedAt: number;
+    lastActivity: number;
+    status?: string;
+    peerUid?: number;
+    trustedLocal?: boolean;
+    /** Live context-window usage, pushed via presence from the source session's
+     *  getContextUsage(). contextPct is 0..100 (rounded); contextTokens /
+     *  contextWindow are raw token counts. All optional: unknown right after a
+     *  compaction (before the next assistant response), when no model is selected,
+     *  or on older clients that never report it. */
+    contextPct?: number;
+    contextTokens?: number;
+    contextWindow?: number;
+    /** tmux pane id (e.g. "%212") of the session's terminal, read from
+     *  $TMUX_PANE at registration. Present only when the session runs inside a
+     *  tmux pane; absent for cloud, headless, IDE-embedded, or Herdr sessions.
+     *  The pane id is immutable for the process lifetime — unlike the window
+     *  name, which is mutable — so a peer can live-resolve the current window
+     *  from it via tmux when it needs to introspect or drive that pane. */
+    tmuxPane?: string;
+    /** Launch-time Herdr pane alias. It may differ from the current pane id after a move. */
+    herdrPaneId?: string;
+    /** Present on list responses. `current` is freshly resolved for that request;
+     *  other states explicitly distinguish non-Herdr sessions from failures. */
+    herdrLocation?: HerdrLocation;
+}
+export interface CrossMachineOrigin {
+    name: string;
+    sessionId: string;
+    machine: string;
+}
+export interface CrossMachineProvenance {
+    type: "ssh-relay";
+    version: 1;
+    origin: CrossMachineOrigin;
+    trust: "ssh-asserted";
+}
+export interface Message {
+    id: string;
+    timestamp: number;
+    senderSequence?: number;
+    brokerReceivedAt?: number;
+    brokerDeliveredAt?: number;
+    receiverReceivedAt?: number;
+    injectedAt?: number;
+    supersedes?: string;
+    retryOf?: string;
+    replyTo?: string;
+    expectsReply?: boolean;
+    provenance?: MessageProvenance;
+    crossMachine?: CrossMachineProvenance;
+    content: {
+        text: string;
+        attachments?: Attachment[];
+    };
+}
+export interface MessageProvenance {
+    type: "extension_outbox";
+    extensionId: string;
+    extensionName: string;
+    requestId: string;
+}
+export interface Attachment {
+    type: "file" | "snippet" | "context";
+    name: string;
+    content: string;
+    language?: string;
+}
+export type MessageReceiptStatus = "receiver_received" | "queued" | "injected" | "acknowledged" | "expired" | "cancelled" | "superseded" | "cancellation_requested";
+export interface MessageReceipt {
+    messageId: string;
+    status: MessageReceiptStatus;
+    timestamp: number;
+    detail?: string;
+}
+export type MessageControlAction = "cancel" | "supersede";
+export interface MessageControl {
+    messageId: string;
+    action: MessageControlAction;
+    timestamp: number;
+    supersededBy?: string;
+    detail?: string;
+}
+export interface ExtensionCapability {
+    namespace: string;
+    ownerEligible: boolean;
+}
+export type SessionRegistration = Omit<SessionInfo, "id" | "endpointEpoch" | "peerUid" | "trustedLocal" | "herdrLocation"> & {
+    extensions?: ExtensionCapability[];
+    /** Broker-only join hint; never returned in the public roster. */
+    herdrSessionPath?: string;
+};
+export type ClientMessage = {
+    type: "register";
+    session: SessionRegistration;
+    sessionId?: string;
+    stateId?: string;
+    scopeId?: string;
+} | {
+    type: "unregister";
+} | {
+    type: "extension_capabilities_update";
+    extensions: ExtensionCapability[];
+} | {
+    type: "list";
+    requestId: string;
+} | {
+    type: "send";
+    to: string;
+    message: Message;
+    targetId?: string;
+    targetEpoch?: string;
+} | {
+    type: "message_receipt";
+    receipt: MessageReceipt;
+} | {
+    type: "cancel_message";
+    messageId: string;
+} | {
+    type: "cancel_ask";
+    messageId: string;
+} | {
+    type: "presence";
+    name?: string;
+    runtimeFallbackAlias?: boolean;
+    status?: string;
+    model?: string;
+    contextPct?: number | null;
+    contextTokens?: number | null;
+    contextWindow?: number | null;
+} | {
+    type: "extension_publish";
+    namespace: string;
+    audience: "owner" | "capable";
+    ownerEpoch?: string;
+    ownerOnly?: boolean;
+    payload: unknown;
+} | {
+    type: "extension_state_commit";
+    namespace: string;
+    ownerEpoch: string;
+    expectedRevision: number;
+    payload: unknown;
+};
+export type BrokerMessage = {
+    type: "registered";
+    sessionId: string;
+    features?: string[];
+} | {
+    type: "sessions";
+    requestId: string;
+    sessions: SessionInfo[];
+} | {
+    type: "message";
+    from: SessionInfo;
+    message: Message;
+} | {
+    type: "presence_update";
+    session: SessionInfo;
+} | {
+    type: "session_joined";
+    session: SessionInfo;
+} | {
+    type: "session_left";
+    sessionId: string;
+} | {
+    type: "error";
+    error: string;
+} | ({
+    type: "delivered";
+    messageId: string;
+} & DeliveryDetails) | ({
+    type: "delivery_failed";
+    messageId: string;
+    reason: string;
+} & DeliveryDetails) | {
+    type: "message_receipt";
+    from: SessionInfo;
+    receipt: MessageReceipt;
+} | {
+    type: "message_control";
+    from: SessionInfo;
+    control: MessageControl;
+} | {
+    type: "extension_owner";
+    namespace: string;
+    ownerId?: string;
+    ownerEpoch?: string;
+} | {
+    type: "extension_message";
+    namespace: string;
+    fromSessionId: string;
+    ownerId?: string;
+    ownerEpoch?: string;
+    payload: unknown;
+} | {
+    type: "extension_state";
+    namespace: string;
+    revision: number;
+    payload: unknown;
+} | {
+    type: "extension_state_result";
+    namespace: string;
+    committed: boolean;
+    revision: number;
+    reason?: string;
+};

package/dist/extensions/pi-intercom/types.js

@@ -0,0 +1,2 @@
+export const EXTENSION_BUS_FEATURE = "extension-bus-v1";
+export const EXACT_SEND_FEATURE = "exact-send-v1";

package/dist/extensions/pi-intercom/types.ts

@@ -10,6 +10,23 @@ export interface DeliveryDetails {
   outcomeKnown: boolean;
 }
 
+export type HerdrLocation =
+  | {
+      status: "current";
+      workspace: { id: string; label: string };
+      tab: { id: string; label: string };
+      paneId: string;
+      /** Time when the broker requested the live Herdr snapshot. */
+      refreshedAt: number;
+    }
+  | { status: "not_hosted" }
+  | {
+      status: "unavailable";
+      paneId: string;
+      reason: "herdr_unavailable" | "unsupported" | "command_failed" | "pane_missing" | "invalid_response";
+      detail?: string;
+    };
+
 export interface SessionInfo {
   id: string;
   /** Broker-owned lifetime of this live endpoint. */
@@ -40,6 +57,24 @@ export interface SessionInfo {
    *  name, which is mutable — so a peer can live-resolve the current window
    *  from it via tmux when it needs to introspect or drive that pane. */
   tmuxPane?: string;
+  /** Launch-time Herdr pane alias. It may differ from the current pane id after a move. */
+  herdrPaneId?: string;
+  /** Present on list responses. `current` is freshly resolved for that request;
+   *  other states explicitly distinguish non-Herdr sessions from failures. */
+  herdrLocation?: HerdrLocation;
+}
+
+export interface CrossMachineOrigin {
+  name: string;
+  sessionId: string;
+  machine: string;
+}
+
+export interface CrossMachineProvenance {
+  type: "ssh-relay";
+  version: 1;
+  origin: CrossMachineOrigin;
+  trust: "ssh-asserted";
 }
 
 export interface Message {
@@ -55,6 +90,7 @@ export interface Message {
   replyTo?: string;
   expectsReply?: boolean;
   provenance?: MessageProvenance;
+  crossMachine?: CrossMachineProvenance;
   content: {
     text: string;
     attachments?: Attachment[];
@@ -99,8 +135,10 @@ export interface ExtensionCapability {
   ownerEligible: boolean;
 }
 
-export type SessionRegistration = Omit<SessionInfo, "id" | "endpointEpoch" | "peerUid" | "trustedLocal"> & {
+export type SessionRegistration = Omit<SessionInfo, "id" | "endpointEpoch" | "peerUid" | "trustedLocal" | "herdrLocation"> & {
   extensions?: ExtensionCapability[];
+  /** Broker-only join hint; never returned in the public roster. */
+  herdrSessionPath?: string;
 };
 
 export type ClientMessage =