agent-comms 8.15.8 → 8.15.10

package/src/account-cli.ts

@@ -0,0 +1,195 @@
+/**
+ * `agent-comms account <export|import|invite|join>` (agent-comms#344): the deliberate, consented ways the account key that lets one user principal span machines leaves or reaches a machine. Export and import carry the key as a passphrase-sealed bundle (account-bundle.ts), written to a new owner-only file and never printed; the passphrase comes from AGENT_COMMS_ACCOUNT_PASSPHRASE when set, else from a prompt that does not echo. Invite and join carry it over the mesh (account-join-cli.ts). All four are commands a person runs, never agent_comms tool actions, so nothing an agent is told can move the account and no key or invite lands in an agent's transcript.
+ */
+
+import * as fs from "node:fs";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import {
+  inviteToAccount,
+  joinAccount,
+  type AccountCliStore,
+} from "./account-join-cli.js";
+import { openAccountBundle, sealAccountBundle } from "./core/account-bundle.js";
+import {
+  importAccountKey,
+  loadOrCreateUserIdentity,
+  readAccountContents,
+  type UserIdentityOptions,
+} from "./core/user-identity.js";
+
+/** Where a script supplies the passphrase instead of typing it. */
+export const ACCOUNT_PASSPHRASE_ENV = "AGENT_COMMS_ACCOUNT_PASSPHRASE";
+
+/** A bundle holds the account key, so its file is readable by its owner alone. */
+const BUNDLE_FILE_MODE = 0o600;
+
+export const ACCOUNT_USAGE = [
+  "Usage: agent-comms account export <file>",
+  "       agent-comms account import <file>",
+  "       agent-comms account invite [--ttl-minutes <n>] [--sign-key <file>]",
+  "       agent-comms account join [--public-key <file>] [--fingerprint <hex>] [--label <name>]",
+].join("\n");
+
+export interface AccountCliIo {
+  /** Reads a secret (a passphrase, an invite) without echoing it. */
+  readSecret: (prompt: string) => Promise<string>;
+  log: (line: string) => void;
+  env: Readonly<Record<string, string | undefined>>;
+  /** Starts a store on this machine's mesh for invite and join, which need one to reach the other machine. */
+  openStore: () => Promise<AccountCliStore>;
+}
+
+async function passphrase(
+  io: Readonly<AccountCliIo>,
+  confirm: boolean,
+): Promise<string> {
+  const fromEnv = io.env[ACCOUNT_PASSPHRASE_ENV];
+  if (fromEnv !== undefined) return fromEnv;
+  const first = await io.readSecret("Account bundle passphrase: ");
+  if (!confirm) return first;
+  const second = await io.readSecret("Repeat the passphrase: ");
+  if (first !== second) throw new Error("The passphrases do not match");
+  return first;
+}
+
+function principalOf(identity: Readonly<{ deviceId: Uint8Array }>): string {
+  return deviceIdToHex(Uint8Array.from(identity.deviceId));
+}
+
+/** Runs one `account` subcommand. Throws with a message fit to show the person on any failure: an unknown subcommand or option, a file that already exists (an export never overwrites), a weak or wrong passphrase, a file that is not a bundle, or an invite that is malformed or refused. */
+export async function runAccountCommand(
+  args: readonly string[],
+  io: Readonly<AccountCliIo>,
+  userIdentityOptions: Readonly<UserIdentityOptions> = {},
+): Promise<void> {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "invite") {
+    await inviteToAccount(rest, io);
+    return;
+  }
+  if (subcommand === "join") {
+    await joinAccount(rest, io);
+    return;
+  }
+  const [file, ...extra] = rest;
+  if (file === undefined || extra.length > 0) throw new Error(ACCOUNT_USAGE);
+  if (subcommand === "export") {
+    const identity = loadOrCreateUserIdentity(userIdentityOptions);
+    const bundle = sealAccountBundle(
+      readAccountContents(userIdentityOptions),
+      await passphrase(io, true),
+    );
+    fs.writeFileSync(file, `${bundle}\n`, {
+      encoding: "utf-8",
+      mode: BUNDLE_FILE_MODE,
+      flag: "wx",
+    });
+    io.log(
+      `Exported account ${principalOf(identity)} to ${file}. Anyone with this file and its passphrase holds the account; import it on your other machine with \`agent-comms account import ${file}\`, then delete it.`,
+    );
+    return;
+  }
+  if (subcommand === "import") {
+    const contents = openAccountBundle(
+      fs.readFileSync(file, "utf-8"),
+      await passphrase(io, false),
+    );
+    const { identity, replacedFile } = importAccountKey(
+      userIdentityOptions,
+      contents,
+    );
+    io.log(`This machine now holds account ${principalOf(identity)}.`);
+    if (replacedFile !== undefined) {
+      io.log(
+        `The account it held before was moved to ${replacedFile}; it is still the only key that can revoke what that account issued.`,
+      );
+    }
+    io.log("Restart running agent-comms bridges so they use it.");
+    return;
+  }
+  throw new Error(ACCOUNT_USAGE);
+}
+
+/** What one keypress does to a hidden line being typed. */
+export type HiddenLineStep =
+  | { kind: "typing"; value: string }
+  | { kind: "done"; value: string }
+  | { kind: "failed"; message: string };
+
+const END_OF_TEXT = "\u0003";
+const END_OF_TRANSMISSION = "\u0004";
+const BACKSPACE = "\b";
+const DELETE = "\u007f";
+/** Every character ordered before this one is a C0 control character, none of which a passphrase can hold. */
+const FIRST_PRINTABLE = " ";
+
+/** Applies one character typed at a hidden prompt to the line so far. Enter, or Ctrl-D on a line with something on it, ends the line; Ctrl-C, and Ctrl-D on an empty line, cancel it. Backspace and Delete remove the last character. An escape sequence (an arrow or function key) or any other control character is refused rather than kept, since it would end up in the value invisibly and could never be typed the same way again. */
+export function hiddenLineStep(
+  value: string,
+  character: string,
+): HiddenLineStep {
+  if (character === "\r" || character === "\n") return { kind: "done", value };
+  if (character === END_OF_TEXT)
+    return { kind: "failed", message: "Cancelled" };
+  if (character === END_OF_TRANSMISSION) {
+    return value === ""
+      ? { kind: "failed", message: "Cancelled: no input before end of input" }
+      : { kind: "done", value };
+  }
+  if (character === BACKSPACE || character === DELETE) {
+    // A terminal's backspace removes one visible character, which may be several code points.
+    const graphemes = Array.from(
+      new Intl.Segmenter().segment(value),
+      ({ segment }) => segment,
+    );
+    return { kind: "typing", value: graphemes.slice(0, -1).join("") };
+  }
+  // Escape, which starts every arrow and function key's sequence, is one of these.
+  if (character < FIRST_PRINTABLE) {
+    return {
+      kind: "failed",
+      message:
+        "Arrow keys, Escape and other control keys cannot be used at this prompt, since they would be kept in it invisibly; start again and type it plainly",
+    };
+  }
+  return { kind: "typing", value: value + character };
+}
+
+/** Reads one line from a terminal with echo off, keystroke by keystroke as hiddenLineStep describes. Throws when stdin is not a terminal, since there is nowhere to prompt; a bundle passphrase can then come from ACCOUNT_PASSPHRASE_ENV instead. */
+export async function readHiddenLine(prompt: string): Promise<string> {
+  const { stdin, stderr } = process;
+  if (!stdin.isTTY) {
+    throw new Error(
+      `No terminal to ask on (${prompt.trim()}); a bundle passphrase can be set in ${ACCOUNT_PASSPHRASE_ENV} instead`,
+    );
+  }
+  stderr.write(prompt);
+  stdin.setRawMode(true);
+  stdin.setEncoding("utf-8");
+  stdin.resume();
+  return new Promise((resolve, reject) => {
+    let value = "";
+    // Replaced once the listener exists, so the listener can detach itself.
+    let finish = (): void => undefined;
+    const onData = (chunk: string): void => {
+      for (const character of chunk) {
+        const step = hiddenLineStep(value, character);
+        if (step.kind === "typing") {
+          value = step.value;
+          continue;
+        }
+        finish();
+        if (step.kind === "done") resolve(step.value);
+        else reject(new Error(step.message));
+        return;
+      }
+    };
+    finish = (): void => {
+      stdin.off("data", onData);
+      stdin.setRawMode(false);
+      stdin.pause();
+      stderr.write("\n");
+    };
+    stdin.on("data", onData);
+  });
+}

package/src/account-join-cli.ts

@@ -0,0 +1,191 @@
+/**
+ * `agent-comms account invite` and `agent-comms account join` (agent-comms#344): joining a new machine to the account over the mesh (see core/account-join.ts for the flow). Each runs a store of its own for as long as the command runs. An invite is printed to this terminal only, and the command keeps its store up until the invite is redeemed or expires, since invites live only in the issuing store's memory. A join reads the invite at a prompt that does not echo, so it never sits in shell history.
+ */
+
+import * as fs from "node:fs";
+import type { AccountJoin } from "./core/account-join.js";
+import { createBridgeMesh } from "./core/bridge-mesh.js";
+import { createMeshErrorReporter } from "./core/error-reporting.js";
+import {
+  releaseIdentityLock,
+  type IdentitySlot,
+} from "./core/identity-store.js";
+import type { GenerateConnectionCodeOptions } from "./core/connection-code.js";
+import type { RedeemConnectionCodeOptions } from "./core/connection-code.js";
+import { ConnectionCodeSchema, type ConnectionCode } from "./core/types.js";
+import { ACCOUNT_USAGE, type AccountCliIo } from "./account-cli.js";
+
+/** A store started for one invite or join, and its shutdown. */
+export interface AccountCliStore {
+  account: Pick<AccountJoin, "invite" | "join">;
+  close: () => Promise<void>;
+}
+
+/** The identity slot harness these commands' own store runs under, apart from every bridge's. */
+const ACCOUNT_CLI_HARNESS = "account";
+
+/** Starts a store on this machine's mesh, holding the machine's account, with one hidden agent: that is what gives it a hub session once it trusts the other machine, and a hidden agent is reachable by device id without being listed. */
+export async function openMachineAccountStore(): Promise<AccountCliStore> {
+  const slot: IdentitySlot = {
+    harness: ACCOUNT_CLI_HARNESS,
+    cwd: process.cwd(),
+  };
+  const { store } = await createBridgeMesh(slot);
+  store.onError = createMeshErrorReporter();
+  await store.init();
+  const agent = await store.registerAgent({
+    name: ACCOUNT_CLI_HARNESS,
+    harness: ACCOUNT_CLI_HARNESS,
+    cwd: slot.cwd,
+    pid: process.pid,
+    visibility: "hidden",
+    tags: [],
+  });
+  return {
+    account: store.account,
+    close: async () => {
+      await store.setAgentOffline(agent.id);
+      await store.shutdown();
+      releaseIdentityLock(slot);
+    },
+  };
+}
+
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_MINUTE = SECONDS_PER_MINUTE * MS_PER_SECOND;
+
+/** Parses `--name value` pairs, allowing only `allowed` names, each at most once. */
+function parseOptions(
+  args: readonly string[],
+  allowed: readonly string[],
+): Map<string, string> {
+  const options = new Map<string, string>();
+  for (let i = 0; i < args.length; i += 2) {
+    const name = args[i];
+    const value = args[i + 1];
+    if (
+      name === undefined ||
+      !name.startsWith("--") ||
+      !allowed.includes(name.slice(2)) ||
+      options.has(name.slice(2)) ||
+      value === undefined
+    ) {
+      throw new Error(ACCOUNT_USAGE);
+    }
+    options.set(name.slice(2), value);
+  }
+  return options;
+}
+
+function ttlMsFrom(minutes: string | undefined): number | undefined {
+  if (minutes === undefined) return undefined;
+  const parsed = Number(minutes);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(
+      `--ttl-minutes must be a whole number of minutes above zero, not ${minutes}`,
+    );
+  }
+  return parsed * MS_PER_MINUTE;
+}
+
+async function signingOptions(
+  keyFile: string | undefined,
+  io: Readonly<AccountCliIo>,
+): Promise<
+  Pick<GenerateConnectionCodeOptions, "privateKeyArmored" | "passphrase">
+> {
+  if (keyFile === undefined) return {};
+  const privateKeyArmored = fs.readFileSync(keyFile, "utf-8");
+  const passphrase = await io.readSecret(
+    "PGP key passphrase (press Enter if it has none): ",
+  );
+  return passphrase === ""
+    ? { privateKeyArmored }
+    : { privateKeyArmored, passphrase };
+}
+
+/** Issues an invite, prints it, and returns once it has been redeemed or has expired. */
+export async function inviteToAccount(
+  args: readonly string[],
+  io: Readonly<AccountCliIo>,
+): Promise<void> {
+  const options = parseOptions(args, ["ttl-minutes", "sign-key"]);
+  const ttlMs = ttlMsFrom(options.get("ttl-minutes"));
+  const signing = await signingOptions(options.get("sign-key"), io);
+  const store = await io.openStore();
+  try {
+    const { code, settled } = await store.account.invite({
+      ...(ttlMs !== undefined && { ttlMs }),
+      ...signing,
+    });
+    io.log(
+      `Account invite, valid until ${code.expiresAt} and for one use. Whoever redeems it takes a full copy of this account, so give it only to your own new machine, out of band, and run \`agent-comms account join\` there. Keep this command running until then.`,
+    );
+    io.log(JSON.stringify(code));
+    const outcome = await settled;
+    io.log(
+      outcome === "redeemed"
+        ? "The invite was redeemed: the new machine now holds this account."
+        : "The invite expired unused.",
+    );
+  } finally {
+    await store.close();
+  }
+}
+
+const NOT_AN_INVITE =
+  "That is not an account invite: paste the whole line `agent-comms account invite` printed";
+
+function parseInvite(raw: string): ConnectionCode {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(NOT_AN_INVITE);
+  }
+  if (!ConnectionCodeSchema.is(parsed)) {
+    throw new Error(NOT_AN_INVITE);
+  }
+  return parsed;
+}
+
+function verifyingOptions(
+  options: ReadonlyMap<string, string>,
+): RedeemConnectionCodeOptions {
+  const keyFile = options.get("public-key");
+  const fingerprint = options.get("fingerprint");
+  return {
+    ...(keyFile !== undefined && {
+      publicKeyArmored: fs.readFileSync(keyFile, "utf-8"),
+    }),
+    ...(fingerprint !== undefined && { expectedFingerprint: fingerprint }),
+  };
+}
+
+/** Reads an invite at a prompt and makes this machine hold the account it came from. With --label, the issuing machine keeps the label as its own name for this one. */
+export async function joinAccount(
+  args: readonly string[],
+  io: Readonly<AccountCliIo>,
+): Promise<void> {
+  const options = parseOptions(args, ["public-key", "fingerprint", "label"]);
+  const label = options.get("label");
+  const joinOptions = {
+    ...verifyingOptions(options),
+    ...(label !== undefined && { label }),
+  };
+  const invite = parseInvite(await io.readSecret("Account invite: "));
+  const store = await io.openStore();
+  try {
+    const result = await store.account.join(invite, joinOptions);
+    io.log(`This machine now holds account ${result.principal}.`);
+    if (result.replacedFile !== undefined) {
+      io.log(
+        `The account it held before was moved to ${result.replacedFile}; it is still the only key that can revoke what that account issued.`,
+      );
+    }
+    io.log("Restart running agent-comms bridges so they use it.");
+  } finally {
+    await store.close();
+  }
+}

package/src/bridges/cc-peer/approval-commands.ts

@@ -0,0 +1,82 @@
+/**
+ * Lets a cc-peer session answer a room join or first-contact DM request. A session reached only through cc-peer (no agent-comms tool of its own) cannot call room_accept or room_reject, so the relayed request tells it exactly what to message back, and the relay runs the same tool action when that message arrives. The person at the session decides: only a message from that session's own socket ever reaches its relay.
+ */
+
+import { buildAction, formatDeliveryEvent } from "../../core/bridge.js";
+import type { CommsContext, CommsTool } from "../../core/tool.js";
+import type { DeliveryEvent } from "../../core/types.js";
+
+/** A device-id is a 64-character lowercase hex SHA-256 digest. */
+const DEVICE_ID_HEX = "[0-9a-f]{64}";
+
+/** `accept <room> <requester>` or `reject <room> <requester> [reason]`, the whole message and nothing else, so an ordinary message that merely mentions the word is never mistaken for a decision. */
+const APPROVAL_COMMAND = new RegExp(
+  `^\\s*(accept|reject)\\s+(\\S+)\\s+(${DEVICE_ID_HEX})(?:\\s+(\\S[\\s\\S]*?))?\\s*$`,
+  "i",
+);
+
+export type ApprovalCommand =
+  | { kind: "accept"; room: string; requesterId: string }
+  | { kind: "reject"; room: string; requesterId: string; reason?: string };
+
+/** The command a message body is, or undefined when it is not a well-formed one. */
+export function parseApprovalCommand(
+  body: string,
+): ApprovalCommand | undefined {
+  const match = APPROVAL_COMMAND.exec(body);
+  if (match === null) return undefined;
+  const [, verb, room, requesterId, reason] = match;
+  if (verb === undefined || room === undefined || requesterId === undefined) {
+    return undefined;
+  }
+  if (verb.toLowerCase() === "accept") {
+    return { kind: "accept", room, requesterId: requesterId.toLowerCase() };
+  }
+  return {
+    kind: "reject",
+    room,
+    requesterId: requesterId.toLowerCase(),
+    ...(reason !== undefined ? { reason } : {}),
+  };
+}
+
+/** Renders a delivery event for a cc-peer session. A join request carries the instructions for answering it through `peerName`, the peer the session should message; every other event renders as the shared formatter does. */
+export function formatCcPeerDelivery(
+  event: DeliveryEvent,
+  peerName: string,
+): string {
+  if (event.type !== "room_join_request") return formatDeliveryEvent(event);
+  return [
+    `${event.requesterId} is asking to join ${event.room}.`,
+    `To answer, send the peer "${peerName}" one of these messages:`,
+    `accept ${event.room} ${event.requesterId}`,
+    `reject ${event.room} ${event.requesterId} <optional reason>`,
+  ].join("\n");
+}
+
+export interface AnswerJoinRequestDeps {
+  tool: Pick<CommsTool, "handle">;
+  ctx: Readonly<CommsContext>;
+}
+
+/** Runs the room_accept or room_reject the command asks for as this session's own agent, and returns the tool's own text so the session learns what happened, including why a decision failed. */
+export async function answerJoinRequest(
+  deps: Readonly<AnswerJoinRequestDeps>,
+  command: Readonly<ApprovalCommand>,
+): Promise<string> {
+  const action =
+    command.kind === "accept"
+      ? buildAction({
+          action: "room_accept",
+          room: command.room,
+          requesterId: command.requesterId,
+        })
+      : buildAction({
+          action: "room_reject",
+          room: command.room,
+          requesterId: command.requesterId,
+          ...(command.reason !== undefined ? { reason: command.reason } : {}),
+        });
+  const result = await deps.tool.handle(deps.ctx, action);
+  return result.content;
+}

package/src/bridges/cc-peer/bridge.ts

@@ -0,0 +1,138 @@
+/**
+ * cc-peer bridge — relays between one local Claude Code peer (reached via cc-peer's own native cross-session protocol) and this side's agent-comms mesh, giving that local session cross-machine reach through the mesh's own transport (agent-comms#87).
+ *
+ * One bridge process relays for exactly one target local Claude Code peer, matching the "one bridge process is one agent is one device" model every other bridge in this codebase already follows -- not a many-to-one fan-out. Inbound cc-peer messages from that target are posted into this agent's own project room (the same auto-created room ensureRegistered/ensureProjectRoom already gives every bridge); mesh deliveries for this agent are relayed back to that same target via CcPeer.send().
+ *
+ * The wiring itself (wireCcPeerBridge) is dependency-injected and deliberately separate from the real CcPeer/MeshStore construction in run.ts, so it can be tested against a fake CcPeer without a real local Claude Code session.
+ */
+
+import type { CommsTool } from "../../core/tool.js";
+import { buildAction } from "../../core/bridge.js";
+import {
+  answerJoinRequest,
+  formatCcPeerDelivery,
+  parseApprovalCommand,
+} from "./approval-commands.js";
+import type { DeliveryEvent } from "../../core/types.js";
+
+/** How cc-peer addresses a target peer -- mirrors cc-peer's own PeerRef type without importing it, so this file has no direct dependency on the cc-peer package (only run.ts, which does the real construction, needs that). */
+export type CcPeerRef =
+  { pid: number } | { name: string } | { address: string };
+
+/** The one inbound-message shape this bridge reads from CcPeer's own "message" event -- narrowed to the fields it actually uses. */
+export interface CcPeerInboundMessage {
+  from?: string;
+  fromName?: string;
+  body: string;
+}
+
+/** The narrow slice of CcPeer's own real API this bridge needs -- satisfied by the real class in run.ts, and by a fake in tests. */
+export interface CcPeerLike {
+  on: (
+    event: "message",
+    listener: (m: Readonly<CcPeerInboundMessage>) => void,
+  ) => void;
+  send: (
+    target: Readonly<CcPeerRef>,
+    body: string,
+  ) => Promise<{ msgId: string }>;
+}
+
+/** The narrow slice of MeshStore this bridge needs -- onDelivery is MeshStore-only (not part of the generic CommsStore interface every bridge otherwise depends on), since only a mesh-backed store can push. */
+export interface CcPeerBridgeStore {
+  onDelivery:
+    | ((agentId: string, event: DeliveryEvent) => void | Promise<void>)
+    | undefined;
+  /** Where a failure relaying an inbound message is reported, since the relay is fire-and-forget from the cc-peer event's own point of view. */
+  onError: ((error: Error) => void) | undefined;
+}
+
+/** The slice of a cc-peer roster entry needed to tell whether it is a given target. */
+export interface CcPeerTargetEntry {
+  pid: number;
+  name?: string | undefined;
+  messagingSocketPath: string;
+}
+
+/** Whether a roster entry is the session a target ref addresses. An address target names the session's own `uds:<socket path>` address. */
+export function targetMatchesEntry(
+  target: Readonly<CcPeerRef>,
+  entry: Readonly<CcPeerTargetEntry>,
+): boolean {
+  if ("pid" in target) return entry.pid === target.pid;
+  if ("name" in target) return entry.name === target.name;
+  return target.address === `uds:${entry.messagingSocketPath}`;
+}
+
+/** Builds the predicate that says whether an inbound message was sent by the target session. The sender is identified by its `uds:<socket path>` address, resolved against a fresh roster read for every message so a target addressed by name is still recognised after that session restarts under a new pid. */
+export function createTargetSenderMatcher(
+  target: Readonly<CcPeerRef>,
+  listRoster: () => Promise<readonly CcPeerTargetEntry[]>,
+): (message: Readonly<CcPeerInboundMessage>) => Promise<boolean> {
+  return async (message) => {
+    if (message.from === undefined) return false;
+    if ("address" in target) return message.from === target.address;
+    const roster = await listRoster();
+    const sender = roster.find(
+      (entry) => `uds:${entry.messagingSocketPath}` === message.from,
+    );
+    return sender !== undefined && targetMatchesEntry(target, sender);
+  };
+}
+
+export interface CcPeerBridgeDeps {
+  store: CcPeerBridgeStore;
+  tool: Pick<CommsTool, "handle">;
+  peer: CcPeerLike;
+  agentId: string;
+  roomId: string;
+  target: Readonly<CcPeerRef>;
+  cwd: string;
+  /** The name this bridge's peer is registered under, which the target is told to message to answer a join request. */
+  peerName: string;
+  /** Whether an inbound message was sent by the target session. Only those are posted into the project room: the peer may be shared with the default front, whose fronted sessions message it as well, and those belong to the front's own relay. */
+  isFromTarget: (message: Readonly<CcPeerInboundMessage>) => Promise<boolean>;
+}
+
+/** Wires the two directions of the relay. Never awaited by the caller -- both directions are genuinely fire-and-forget from this function's own point of view (a send failure surfaces through cc-peer's own receipt events / agent-comms' own delivery-status events, not a thrown error here). */
+export function wireCcPeerBridge(deps: Readonly<CcPeerBridgeDeps>): void {
+  deps.peer.on("message", (m) => {
+    void (async () => {
+      if (!(await deps.isFromTarget(m))) return;
+      const ctx = {
+        agentId: deps.agentId,
+        harness: "cc-peer",
+        cwd: deps.cwd,
+        pid: process.pid,
+      };
+      // A well-formed accept or reject is the target's decision on a waiting join request, not something to post into the project room.
+      const decision = parseApprovalCommand(m.body);
+      if (decision !== undefined) {
+        const text = await answerJoinRequest(
+          { tool: deps.tool, ctx },
+          decision,
+        );
+        await deps.peer.send(deps.target, text);
+        return;
+      }
+      const sender = m.fromName ?? m.from ?? "unknown";
+      const action = buildAction({
+        action: "send",
+        room: deps.roomId,
+        content: `${sender}: ${m.body}`,
+      });
+      await deps.tool.handle(ctx, action);
+    })().catch((error: unknown) => {
+      deps.store.onError?.(
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    });
+  });
+
+  deps.store.onDelivery = (_targetId, event) => {
+    void deps.peer.send(
+      deps.target,
+      formatCcPeerDelivery(event, deps.peerName),
+    );
+  };
+}

package/src/bridges/cc-peer/default-front.ts

@@ -0,0 +1,58 @@
+/**
+ * Wires the default cc-peer front (agent-comms#157) onto a real bridge's own store, right after construction -- the piece that actually makes "a machine's coordinator bridge fronts local Claude Code sessions by default" true, rather than a capability every bridge builds but nothing ever switches on. Every real bridge entry point (pi, claude-code, mcp, codex, opencode, user, cc-peer's own one-shot command) calls this once, immediately after createBridgeMesh/createBridgeMeshSync.
+ *
+ * Deliberately the only file outside bridges/cc-peer/ that ever needs to know cc-peer exists: core/mesh-store.ts's onCoordinatorRoleChanged hook is generic (a bare boolean callback), and core/bridge-mesh.ts's factories return a plain MeshStore with no cc-peer awareness at all -- keeping this Node/filesystem/cc-peer-specific capability out of the transport-agnostic core, per this repo's own portable-runtime-boundary convention. A bridge that never becomes this machine's coordinator never starts a front at all; one that does gets it started and stopped automatically as that role comes and goes.
+ */
+
+import type { MeshStore } from "../../core/mesh-store.js";
+import {
+  createDefaultCcPeerFront,
+  type CreateDefaultCcPeerFrontOptions,
+} from "./front-runtime.js";
+import type { CcPeerFront } from "./front-controller.js";
+import type { FrontedSessionRecord } from "./front-controller.js";
+
+export interface WireDefaultCcPeerFrontOptions {
+  coordinatorPort?: number | undefined;
+  hubUrl?: string | undefined;
+  /** The cc-peer peer this process already owns, lent to the front instead of it creating a second one -- see CreateDefaultCcPeerFrontOptions.peer. */
+  peer?: CreateDefaultCcPeerFrontOptions["peer"];
+  /** The name the lent peer is registered under -- see CreateDefaultCcPeerFrontOptions.peerName. */
+  peerName?: CreateDefaultCcPeerFrontOptions["peerName"];
+  /** Sessions this process already relays by other means -- see CreateDefaultCcPeerFrontOptions.excludeSession. */
+  excludeSession?: CreateDefaultCcPeerFrontOptions["excludeSession"];
+  /** Builds the front itself -- defaults to the real createDefaultCcPeerFront. Overridable so this function's own start/stop wiring against store.onCoordinatorRoleChanged is testable without a real CcPeer/local Claude Code session. */
+  createFront?:
+    | ((
+        options: Readonly<CreateDefaultCcPeerFrontOptions>,
+      ) => Pick<CcPeerFront<FrontedSessionRecord>, "start" | "stop">)
+    | undefined;
+}
+
+/**
+ * Builds the store.onCoordinatorRoleChanged callback for a real bridge's own store. Returns the callback rather than assigning it directly, so the caller does the actual store.onCoordinatorRoleChanged = ... assignment itself -- this keeps the store parameter here read-only, matching every other pure-construction function in this file's neighbourhood, instead of this function reaching into the store to mutate it.
+ */
+export function wireDefaultCcPeerFront(
+  store: Readonly<Pick<MeshStore, "onError">>,
+  options: Readonly<WireDefaultCcPeerFrontOptions> = {},
+): (isCoordinator: boolean) => Promise<void> {
+  const createFront = options.createFront ?? createDefaultCcPeerFront;
+  const front = createFront({
+    coordinatorPort: options.coordinatorPort,
+    hubUrl: options.hubUrl,
+    peer: options.peer,
+    peerName: options.peerName,
+    excludeSession: options.excludeSession,
+    onError: (error) => {
+      store.onError?.(error);
+    },
+  });
+
+  return async (isCoordinator: boolean) => {
+    if (isCoordinator) {
+      front.start();
+    } else {
+      await front.stop();
+    }
+  };
+}