agent-comms 8.15.9 → 8.15.10

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

@@ -0,0 +1,160 @@
+/**
+ * CcPeerFront — coordinator-only periodic controller for the default cc-peer front (agent-comms#157), attaching and detaching fronted sessions on each poll tick. Mirrors StaleAgentChecker's own "coordinator-only periodic probe" shape (owns its own interval timer exclusively, start/stop, no immediate first tick) since both are the same kind of thing: a background job that only ever runs on this machine's current mesh coordinator.
+ *
+ * Kept free of any real cc-peer/MeshStore construction, exactly like front.ts's pure decision logic this class is built on -- every real I/O (listRoster, probeSlotOwner, attach, detach) is injected, so the attach/detach/yield diffing across ticks is testable with fake timers and no real local Claude Code session. front-runtime.ts supplies the real dependencies.
+ */
+
+import {
+  selectSessionsToFront,
+  matchInboundMessageSession,
+  type CcPeerRosterEntryLike,
+} from "./front.js";
+import type { IdentitySlot } from "../../core/identity-store.js";
+import type { ReplyContext } from "./reply-aliases.js";
+
+/** How often the front re-enumerates the local cc-peer roster and re-probes every currently-fronted session's own slot. */
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+
+/** The minimum shape a fronted-session record must carry so CcPeerFront can track and route to it, regardless of whatever real MeshStore/CommsTool state a concrete implementation (front-runtime.ts) attaches alongside these fields. */
+export interface FrontedSessionRecord {
+  readonly pid: number;
+  readonly cwd: string;
+  readonly messagingSocketPath: string;
+  /** Delivers an inbound cc-peer message addressed to this fronted session into the mesh (the session-to-mesh direction) -- wired by attach() itself, exactly as wireCcPeerBridge's own peer.on("message") handler does for the one-shot bridge command. */
+  readonly handleInbound: (
+    message: Readonly<{ from?: string; fromName?: string; body: string }>,
+  ) => void;
+  /** Routes a reply arriving on one of this session's own reply aliases back into the mesh, sent as this session's own device-id (agent-comms#158) — the session-to-mesh direction for lazy per-correspondent aliases. A dm context sends a mesh DM addressed to the correspondent that alias stands for; a room context instead posts back into the room the aliased message was itself sent in, since a reply to a room message must return to that room rather than becoming a private DM to its sender (agent-comms#289). Only called once handleAliasMessage has already resolved the alias to a known correspondent and context; a stale alias goes to notifyStaleAlias instead. */
+  readonly handleAliasReply: (
+    correspondentId: string,
+    context: Readonly<ReplyContext>,
+    message: Readonly<{ from?: string; fromName?: string; body: string }>,
+  ) => void;
+  /** Delivers a clear error back into this session when a reply arrives on an alias the directory no longer maps to any correspondent -- e.g. after a front restart, since reply aliases are ephemeral by design -- rather than silently dropping the reply. */
+  readonly notifyStaleAlias: (aliasName: string) => void;
+}
+
+/** The narrow slice of ReplyAliasDirectory (reply-aliases.ts) CcPeerFront needs to resolve an inbound alias message's own correspondent -- narrowed rather than importing the class directly so front-controller.ts stays free of any construction concern, matching probeSlotOwner's own injected-function convention. */
+export interface CcPeerFrontAliasDirectory {
+  correspondentFor: (aliasName: string) => string | undefined;
+  /** The reply context (dm vs. a named room) a previously-minted alias name currently carries — reply-aliases.ts's ReplyAliasDirectory.contextFor in production. Always defined whenever correspondentFor is, since both are set together by the directory's own ensure(); treated as a stale alias when either is missing. */
+  contextFor: (aliasName: string) => ReplyContext | undefined;
+}
+
+export interface CcPeerFrontDeps<TRecord extends FrontedSessionRecord> {
+  /** Enumerates the current local cc-peer roster. Rejects propagate to onError rather than throwing out of the poll timer. */
+  listRoster: () => Promise<readonly CcPeerRosterEntryLike[]>;
+  /** Read-only probe of a slot's current lock holder -- identity-store.ts's probeSlotOwner in production. */
+  probeSlotOwner: (slot: Readonly<IdentitySlot>) => number | undefined;
+  /** Builds a fronted-session record for a newly-selected roster entry (mints/loads its identity, wires the mesh store and the inbound relay). Rejects propagate to onError; the entry is retried on the next tick. */
+  attach: (entry: Readonly<CcPeerRosterEntryLike>) => Promise<TRecord>;
+  /** Tears a fronted-session record down (marks its agent offline, shuts its mesh store down). Rejects propagate to onError. */
+  detach: (record: TRecord) => Promise<void>;
+  /** Resolves an inbound alias message's own alias name back to the correspondent it stands for -- reply-aliases.ts's ReplyAliasDirectory in production. */
+  aliasDirectory: CcPeerFrontAliasDirectory;
+  /** Sessions this process already relays by other means and must not also front -- the one-shot `bridge cc-peer` command's own target, which shares this process's single cc-peer peer with the front. A session that becomes excluded while fronted is detached on the next tick, like one that yields to a live bridge. */
+  excludeSession?:
+    ((entry: Readonly<CcPeerRosterEntryLike>) => boolean) | undefined;
+  pollIntervalMs?: number | undefined;
+  onError?: ((error: Error) => void) | undefined;
+}
+
+/** Normalises a caught value for the front's own error channel, which reports Errors. Exported so front-relay.ts reports a failed relay onto that same channel in the same shape, rather than keeping its own copy of this. */
+export function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}
+
+export class CcPeerFront<TRecord extends FrontedSessionRecord> {
+  private readonly fronted = new Map<number, TRecord>();
+  private timer: ReturnType<typeof setInterval> | undefined;
+
+  constructor(private readonly deps: Readonly<CcPeerFrontDeps<TRecord>>) {}
+
+  /** Starts the periodic poll (coordinator-only). No-op if already running. Matches StaleAgentChecker's own convention of no immediate first tick -- the first attach happens on the first elapsed interval, not synchronously on start(). */
+  start(): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.tick();
+    }, this.deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+  }
+
+  /** Stops the periodic poll and detaches every currently-fronted session -- this side is no longer the coordinator, so it has no business still relaying on any session's behalf. */
+  async stop(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    const records = [...this.fronted.values()];
+    this.fronted.clear();
+    for (const record of records) {
+      await this.detachOne(record);
+    }
+  }
+
+  /** Routes an inbound cc-peer message to whichever fronted session it came from, if any -- the shared front-wide CcPeer instance's own "message" listener calls this directly (front-runtime.ts), since only this class knows the current fronted set. A message matching no fronted session (already detached, or genuinely foreign) is silently dropped -- there's nowhere for it to go. */
+  handleInboundMessage(
+    message: Readonly<{ from?: string; fromName?: string; body: string }>,
+  ): void {
+    const record = matchInboundMessageSession(this.fronted.values(), message);
+    record?.handleInbound(message);
+  }
+
+  /** Routes a reply arriving on a shared reply alias to whichever fronted session actually sent it — matched the same way as handleInboundMessage, by the envelope's own socket-path convention. A message matching no fronted session is silently dropped, same as handleInboundMessage: there is nowhere for it to go, and we cannot safely address an error back to a session we do not control. Once the sending session is identified, the alias directory resolves which correspondent this reply is for and the reply context (dm vs. room) it should return to; an alias the directory no longer knows about, or whose context is missing, is reported back into the session as a stale-alias error rather than silently dropped, per agent-comms#158. */
+  handleAliasMessage(
+    message: Readonly<{ alias: string; from?: string; body: string }>,
+  ): void {
+    const record = matchInboundMessageSession(this.fronted.values(), message);
+    if (!record) return;
+    const correspondentId = this.deps.aliasDirectory.correspondentFor(
+      message.alias,
+    );
+    const context = this.deps.aliasDirectory.contextFor(message.alias);
+    if (correspondentId === undefined || context === undefined) {
+      record.notifyStaleAlias(message.alias);
+      return;
+    }
+    record.handleAliasReply(correspondentId, context, message);
+  }
+
+  private async tick(): Promise<void> {
+    let roster: readonly CcPeerRosterEntryLike[];
+    try {
+      roster = await this.deps.listRoster();
+    } catch (err) {
+      this.deps.onError?.(toError(err));
+      return;
+    }
+
+    const selected = selectSessionsToFront(
+      roster,
+      this.deps.probeSlotOwner,
+    ).filter((entry) => this.deps.excludeSession?.(entry) !== true);
+    const selectedPids = new Set(selected.map((entry) => entry.pid));
+    const rosterPids = new Set(roster.map((entry) => entry.pid));
+
+    // Detach anything that either exited (gone from the roster entirely) or yielded (its own slot is now held by a live bridge, so it's no longer in the selected set even though the session process itself is still running).
+    for (const [pid, record] of [...this.fronted]) {
+      if (rosterPids.has(pid) && selectedPids.has(pid)) continue;
+      this.fronted.delete(pid);
+      await this.detachOne(record);
+    }
+
+    for (const entry of selected) {
+      if (this.fronted.has(entry.pid)) continue;
+      try {
+        const record = await this.deps.attach(entry);
+        this.fronted.set(entry.pid, record);
+      } catch (err) {
+        this.deps.onError?.(toError(err));
+      }
+    }
+  }
+
+  private async detachOne(record: TRecord): Promise<void> {
+    try {
+      await this.deps.detach(record);
+    } catch (err) {
+      this.deps.onError?.(toError(err));
+    }
+  }
+}

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

@@ -0,0 +1,191 @@
+/**
+ * Pure, DI-testable wiring for one fronted session's own cc-peer-to-mesh relay (agent-comms#157) -- the "attach"/"detach" half of the default front, building a FrontedSessionRecord (front-controller.ts) from an already-constructed mesh and the front's shared cc-peer peer. Mirrors bridges/cc-peer/bridge.ts's own wireCcPeerBridge split: kept free of any real CcPeer.create()/createBridgeMeshFromIdentity construction so it's testable against fakes, with front-runtime.ts supplying the real ones.
+ *
+ * Reuses CcPeerRef/CcPeerInboundMessage from bridge.ts rather than redeclaring them -- the wire shape a shared front-wide peer speaks is identical to the one-shot bridge command's own peer, just addressed by pid instead of a fixed target.
+ */
+
+import { buildAction } from "../../core/bridge.js";
+import {
+  answerJoinRequest,
+  formatCcPeerDelivery,
+  parseApprovalCommand,
+} from "./approval-commands.js";
+import type { CommsTool } from "../../core/tool.js";
+import type { CommsAction, DeliveryEvent } from "../../core/types.js";
+import { toError, type FrontedSessionRecord } from "./front-controller.js";
+import type { CcPeerRosterEntryLike } from "./front.js";
+import type { CcPeerInboundMessage, CcPeerRef } from "./bridge.js";
+import { replyTargetForEvent, type ReplyContext } from "./reply-aliases.js";
+
+/** The narrow slice of MeshStore a fronted session's own record needs -- onDelivery to wire the mesh-to-session direction, setAgentOffline/shutdown for detachFrontedSession's own teardown. */
+export interface FrontRelayStore {
+  onDelivery:
+    | ((agentId: string, event: DeliveryEvent) => void | Promise<void>)
+    | undefined;
+  setAgentOffline: (id: string) => Promise<void>;
+  shutdown: () => Promise<void>;
+}
+
+/** The narrow slice of the front's shared CcPeer instance this relay needs -- just send(), since the front-wide "message" listener (front-runtime.ts) is what routes an inbound message to this record's own handleInbound in the first place, not this module. */
+export interface FrontRelayPeer {
+  send: (
+    target: Readonly<CcPeerRef>,
+    body: string,
+  ) => Promise<{ msgId: string }>;
+}
+
+/** The narrow slice of AliasPool (cc-peer's own cc-peer/alias-pool subpath) this relay needs: sending from the real OS-backed reply alias a correspondent's name was already minted for by FrontRelayAliasDirectory, which materialises that alias on the way. Narrowed so this module has no compile-time dependency on the cc-peer package itself, leaving front-runtime.ts to supply the real AliasPool. */
+export interface FrontRelayAliasPool {
+  send: (
+    name: string,
+    target: Readonly<CcPeerRef>,
+    body: string,
+  ) => Promise<{ msgId: string }>;
+}
+
+/** The narrow slice of ReplyAliasDirectory (reply-aliases.ts) this relay needs to mint/recall the alias name for one correspondent, and record its current reply context, on the mesh-to-session direction. */
+export interface FrontRelayAliasDirectory {
+  ensure: (correspondentId: string, context: ReplyContext) => string;
+}
+
+export interface FrontedRelayRecord extends FrontedSessionRecord {
+  agentId: string;
+  roomId: string;
+  store: FrontRelayStore;
+}
+
+export interface BuildFrontedSessionRecordDeps {
+  entry: Readonly<CcPeerRosterEntryLike>;
+  /** The name the shared peer is registered under, which a session is told to message to answer a join request. */
+  peerName: string;
+  agentId: string;
+  roomId: string;
+  store: FrontRelayStore;
+  tool: Pick<CommsTool, "handle">;
+  peer: FrontRelayPeer;
+  aliasPool: FrontRelayAliasPool;
+  aliasDirectory: FrontRelayAliasDirectory;
+  /** Where a relay failure this session cannot act on is reported: the front's own error channel (CcPeerFront's onError, ultimately the host bridge's store.onError), so a message that could not be delivered repliably is visible to the operator and not only to the session. */
+  onError?: ((error: Error) => void) | undefined;
+}
+
+/**
+ * Wires both relay directions for one fronted session and returns the record CcPeerFront tracks it under. Mesh-to-session: store.onDelivery sends the formatted event to this session's own pid. An event with a single originating correspondent (a dm or room_message, per replyTargetForEvent) is sent from that correspondent's own reply alias, so the sender the session sees, and therefore replies to, is the correspondent rather than the front (agent-comms#284); every other event, having no one repliable behind it, is sent from the front's shared peer. Session-to-mesh: the returned handleInbound (called by the front's shared "message" listener once it's matched this record by socket path) posts the message into this session's own project room, exactly as wireCcPeerBridge's own peer.on("message") handler does for the one-shot bridge command; handleAliasReply (called once CcPeerFront has resolved an inbound alias message to its correspondent and reply context) sends a mesh DM to that correspondent when the context is a dm, or posts back into the originating room when the context is a room — a reply to a room message no longer always becomes a private DM to its sender (agent-comms#289); notifyStaleAlias delivers a clear error back into the session for a reply on an alias the directory no longer recognises. All three mesh actions report a refusal back into the session rather than discarding it, so a reply the mesh would not carry is visible where it was written.
+ */
+export function buildFrontedSessionRecord(
+  deps: Readonly<BuildFrontedSessionRecordDeps>,
+): FrontedRelayRecord {
+  const {
+    entry,
+    peerName,
+    agentId,
+    roomId,
+    store,
+    tool,
+    peer,
+    aliasPool,
+    aliasDirectory,
+    onError,
+  } = deps;
+
+  const ctx = {
+    agentId,
+    harness: "claude-code",
+    cwd: entry.cwd,
+    pid: process.pid,
+  };
+
+  const sendToSession = async (body: string): Promise<{ msgId: string }> =>
+    peer.send({ pid: entry.pid }, body);
+
+  /** Runs a mesh action as this session's own agent and relays a refusal back into the session. A relayed message the mesh refused is otherwise invisible from the session's side, so a reply that never left looks exactly like one that was delivered. */
+  const runForSession = async (
+    action: Readonly<CommsAction>,
+    what: string,
+  ): Promise<void> => {
+    const outcome = await tool.handle(ctx, action);
+    if (!outcome.isError) return;
+    await sendToSession(`${what}: ${outcome.content}`);
+  };
+
+  store.onDelivery = async (_targetId, event) => {
+    const body = formatCcPeerDelivery(event, peerName);
+    const target = replyTargetForEvent(event);
+    if (target === undefined) {
+      await sendToSession(body);
+      return;
+    }
+    const aliasName = aliasDirectory.ensure(
+      target.correspondentId,
+      target.context,
+    );
+    try {
+      // Sent from the correspondent's own alias, not from the front's shared peer, so the session's native reply-to-sender lands on that alias and handleAliasReply routes it back to this correspondent's dm channel, or back into the room, per the alias's own recorded context. A hint naming the alias is deliberately not appended: the reply target is now the sender the session already replies to, and a model is free to ignore a hint (agent-comms#284).
+      await aliasPool.send(aliasName, { pid: entry.pid }, body);
+    } catch (error) {
+      // Re-sending from the front's shared peer with a plain body would put the session back in exactly the failure this alias delivery exists to remove: its reply would reach the front, be posted into the project room, and never arrive. Deliver the content, say plainly that a reply cannot get back, and report the failure on the front's own error channel.
+      onError?.(toError(error));
+      await sendToSession(
+        `${body}\n(Cannot reply: ${target.correspondentId}'s reply peer could not be started, so a reply to this message goes to this session's project room instead.)`,
+      );
+    }
+  };
+
+  return {
+    pid: entry.pid,
+    cwd: entry.cwd,
+    messagingSocketPath: entry.messagingSocketPath,
+    agentId,
+    roomId,
+    store,
+    handleInbound: (message: Readonly<CcPeerInboundMessage>) => {
+      // A well-formed accept or reject is the session's decision on a waiting join request, not something to post into the project room.
+      const decision = parseApprovalCommand(message.body);
+      if (decision !== undefined) {
+        void answerJoinRequest({ tool, ctx }, decision).then(sendToSession);
+        return;
+      }
+      const sender = message.fromName ?? message.from ?? "unknown";
+      const action = buildAction({
+        action: "send",
+        room: roomId,
+        content: `${sender}: ${message.body}`,
+      });
+      void runForSession(action, `Not posted to ${roomId}`);
+    },
+    handleAliasReply: (
+      correspondentId: string,
+      context: Readonly<ReplyContext>,
+      message: Readonly<{ body: string }>,
+    ) => {
+      if (context.kind === "room") {
+        const action = buildAction({
+          action: "send",
+          room: context.room,
+          content: message.body,
+        });
+        void runForSession(action, `Reply to ${context.room} not delivered`);
+        return;
+      }
+      const action = buildAction({
+        action: "dm",
+        target: correspondentId,
+        content: message.body,
+      });
+      void runForSession(action, `Reply to ${correspondentId} not delivered`);
+    },
+    notifyStaleAlias: (aliasName: string) => {
+      void sendToSession(
+        `Reply not delivered: peer "${aliasName}" is no longer a known correspondent (reply aliases don't survive a front restart). Wait for a new message from them and reply to that instead.`,
+      );
+    },
+  };
+}
+
+/** Tears a fronted session's record down: marks its agent offline (a courtesy to peers watching its presence), then shuts its mesh store down. There is no identity lock to release -- attach() never took one (loadIdentityForFront's whole point), so a real bridge for this slot can already have claimed it by the time this runs. */
+export async function detachFrontedSession(
+  record: Readonly<Pick<FrontedRelayRecord, "agentId" | "store">>,
+): Promise<void> {
+  await record.store.setAgentOffline(record.agentId);
+  await record.store.shutdown();
+}

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

@@ -0,0 +1,167 @@
+/**
+ * Real cc-peer/MeshStore construction for the default coordinator-run front (agent-comms#157) -- the counterpart to bridges/cc-peer/run.ts's own real CcPeer.create()/createBridgeMesh construction for the one-shot `bridge cc-peer` command. Wires front-controller.ts's CcPeerFront (attach/detach diffing across ticks) to front-relay.ts's buildFrontedSessionRecord/detachFrontedSession (one session's own relay) against one shared, front-wide CcPeer instance and a fresh per-session MeshStore built from loadIdentityForFront's lock-free identity.
+ *
+ * Untested directly, exactly like run.ts's own real construction (see cc-peer-bridge.test.ts's header comment): front.ts, front-controller.ts, and front-relay.ts already carry the front's entire decision/diffing/relay logic under direct DI-based unit tests, so this file's only remaining job -- calling the real cc-peer/core APIs in the right order -- is exercised by actually running a bridge as this machine's coordinator.
+ */
+
+import { parseDisplayName } from "../../core/display-name.js";
+import { CcPeer, CC_PEER_VERSION } from "cc-peer";
+import { AliasPool } from "cc-peer/alias-pool";
+import type { AliasMessage } from "cc-peer/alias-pool";
+import {
+  createBridgeMeshFromIdentity,
+  ensureRegistered,
+  ensureProjectRoom,
+} from "../../core/index.js";
+import {
+  loadIdentityForFront,
+  probeSlotOwner,
+} from "../../core/identity-store.js";
+import { CcPeerFront } from "./front-controller.js";
+import { computeFrontSlot } from "./front.js";
+import type { CcPeerRosterEntryLike } from "./front.js";
+import type { CcPeerInboundMessage } from "./bridge.js";
+import {
+  buildFrontedSessionRecord,
+  detachFrontedSession,
+  type FrontedRelayRecord,
+  type FrontRelayPeer,
+} from "./front-relay.js";
+import { ReplyAliasDirectory } from "./reply-aliases.js";
+import { SharedPeer } from "./shared-peer.js";
+
+/** cc-peer's own registered display name for the front's shared peer -- distinct from any individual fronted session's own agent-comms display name (front-relay.ts's ensureRegistered call uses the session's own cc-peer name/pid for that). */
+const FRONT_PEER_NAME = "agent-comms-front";
+
+/** The slice of a cc-peer peer the front uses: reading the local roster, receiving messages, and sending to a fronted session. The real CcPeer satisfies it. */
+export interface FrontCcPeer extends FrontRelayPeer {
+  roster: () => Promise<readonly CcPeerRosterEntryLike[]>;
+  on: (
+    event: "message",
+    listener: (message: Readonly<CcPeerInboundMessage>) => void,
+  ) => unknown;
+  stop: () => Promise<void>;
+}
+
+export interface CreateDefaultCcPeerFrontOptions {
+  coordinatorPort?: number | undefined;
+  hubUrl?: string | undefined;
+  pollIntervalMs?: number | undefined;
+  onError?: ((error: Error) => void) | undefined;
+  /** The cc-peer peer this process already owns, when it has one. cc-peer allows one peer per process, so a process that runs its own (the one-shot `bridge cc-peer` command) must lend it here rather than let the front try to create a second. The front only borrows it: it never stops it, and registers its inbound listener on it once. Without this the front creates and owns its own peer. */
+  peer?: FrontCcPeer | undefined;
+  /** The name the shared peer is registered under, which fronted sessions are told to message to answer a join request. Defaults to the front's own peer name; a host process that lends its own peer names it here. */
+  peerName?: string | undefined;
+  /** Sessions this process already relays by other means, which the front must therefore leave alone. */
+  excludeSession?:
+    ((entry: Readonly<CcPeerRosterEntryLike>) => boolean) | undefined;
+}
+
+/** The session's own cc-peer display name when it is usable as an agent name (parseDisplayName, which registration enforces), otherwise "claude-code-<pid>": ensureRegistered requires a defaultName, and a session that never picked a name, or picked one registration would refuse, is still worth fronting under something stable and identifiable. */
+function defaultSessionName(entry: Readonly<CcPeerRosterEntryLike>): string {
+  const name =
+    entry.name === undefined ? undefined : parseDisplayName(entry.name);
+  return name ?? `claude-code-${String(entry.pid)}`;
+}
+
+/**
+ * Builds the default cc-peer front. start()/stop() are safe to call from bridge-mesh.ts's onCoordinatorRoleChanged hook regardless of whether cc-peer itself is usable on this machine: the shared CcPeer instance is created lazily, on the first poll tick that actually needs it (listRoster), not at start() itself, and any construction or attach failure is reported via onError rather than thrown -- "absent sockets" (no local Claude Code sessions at all) is then a clean no-op front rather than a crash of the coordinator that owns it.
+ */
+export function createDefaultCcPeerFront(
+  options: Readonly<CreateDefaultCcPeerFrontOptions> = {},
+): Pick<CcPeerFront<FrontedRelayRecord>, "start" | "stop"> {
+  const borrowedPeer = options.peer;
+  const peerName = options.peerName ?? FRONT_PEER_NAME;
+  let aliasPool: AliasPool | undefined;
+  const aliasDirectory = new ReplyAliasDirectory();
+
+  const front = new CcPeerFront<FrontedRelayRecord>({
+    listRoster: async () => {
+      const peer = await ensureSharedPeer();
+      return peer.roster();
+    },
+    probeSlotOwner,
+    attach: async (entry) => attachSession(entry, await ensureSharedPeer()),
+    detach: detachFrontedSession,
+    aliasDirectory,
+    excludeSession: options.excludeSession,
+    pollIntervalMs: options.pollIntervalMs,
+    onError: options.onError,
+  });
+
+  const sharedPeer = new SharedPeer<FrontCcPeer>(async () => {
+    if (borrowedPeer !== undefined) return borrowedPeer;
+    const peer = await CcPeer.create({ name: FRONT_PEER_NAME });
+    peer.on("message", (message: Readonly<CcPeerInboundMessage>) => {
+      front.handleInboundMessage(message);
+    });
+    return peer;
+  });
+  // A borrowed peer outlives the front's own start/stop cycles, so its listener is attached once here rather than on every (re)creation, which would relay each inbound message once per restart.
+  borrowedPeer?.on("message", (message: Readonly<CcPeerInboundMessage>) => {
+    front.handleInboundMessage(message);
+  });
+
+  return {
+    start: () => {
+      front.start();
+    },
+    stop: async () => {
+      await front.stop();
+      const peer = await sharedPeer.release();
+      if (borrowedPeer === undefined) await peer?.stop();
+      await aliasPool?.stopAll();
+      aliasPool = undefined;
+    },
+  };
+
+  /** Materialises the front's own shared AliasPool on first use (mirroring ensureSharedPeer's own lazy-construction convention) and wires its "message" event, every reply arriving on any fronted session's own correspondent aliases, straight into the controller's handleAliasMessage, which resolves the sending session and the alias's own correspondent before routing it on. The pool is also what delivers a correspondent's own messages into a fronted session, from that correspondent's alias, so the session's reply comes back on this same "message" event. */
+  function ensureAliasPool(): AliasPool {
+    if (aliasPool) return aliasPool;
+    const pool = AliasPool.create();
+    pool.on("message", (message: Readonly<AliasMessage>) => {
+      front.handleAliasMessage(message);
+    });
+    aliasPool = pool;
+    return pool;
+  }
+
+  async function ensureSharedPeer(): Promise<FrontCcPeer> {
+    return sharedPeer.get();
+  }
+
+  async function attachSession(
+    entry: Readonly<CcPeerRosterEntryLike>,
+    peer: Readonly<FrontCcPeer>,
+  ): Promise<FrontedRelayRecord> {
+    const slot = computeFrontSlot(entry.cwd);
+    const identity = loadIdentityForFront(slot);
+    const { store, tool } = await createBridgeMeshFromIdentity(identity, slot, {
+      coordinatorPort: options.coordinatorPort,
+      hubUrl: options.hubUrl,
+    });
+    store.getCcPeerVersion = () => CC_PEER_VERSION;
+
+    const reg = await ensureRegistered({
+      store,
+      harness: "claude-code",
+      cwd: entry.cwd,
+      defaultName: defaultSessionName(entry),
+      visibility: "visible",
+    });
+    const roomId = await ensureProjectRoom(store, reg.agentId, entry.cwd);
+
+    return buildFrontedSessionRecord({
+      entry,
+      peerName,
+      agentId: reg.agentId,
+      roomId,
+      store,
+      tool,
+      peer,
+      aliasPool: ensureAliasPool(),
+      aliasDirectory,
+      onError: options.onError,
+    });
+  }
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Pure decision logic for the default cc-peer front (agent-comms#157): a machine's coordinator bridge relays every local Claude Code session that doesn't already front itself, using the same (harness, cwd) identity slot that session's own agent-comms bridge would use, so addressing carries over unchanged the moment that session's own bridge appears.
+ *
+ * Kept free of any real cc-peer/MeshStore construction so it's testable without a real local Claude Code session, a real filesystem, or real sockets -- see front-runtime.ts for the stateful controller and the real wiring built on top of these functions.
+ */
+
+import type { IdentitySlot } from "../../core/identity-store.js";
+
+/** The slice of cc-peer's own RegistryEntry this module needs. Narrowed rather than importing cc-peer's type directly so this file has no compile-time dependency on the cc-peer package (only front-runtime.ts, which does the real construction, needs that). */
+export interface CcPeerRosterEntryLike {
+  pid: number;
+  cwd: string;
+  name?: string | undefined;
+  /** cc-peer's own registry entries for library-backed peers (this front itself, the one-shot `bridge cc-peer` command, an alias-pool worker) always carry the literal string "cc-peer" here -- see buildRegistryEntry in cc-peer's own source. A real interactive Claude Code session, which registers itself natively rather than through the cc-peer library, reports its own Claude Code version instead. */
+  version: string;
+  messagingSocketPath: string;
+}
+
+/** True for a roster entry that is itself a cc-peer-library-backed peer (this front's own shared identity, the one-shot bridge command, an alias-pool worker) rather than a real interactive Claude Code session -- see CcPeerRosterEntryLike.version's own doc comment for the mechanism. The front must never try to front one of these: it would compute a spurious claude-code identity slot for a process that isn't a Claude Code session at all, and relay cc-peer traffic into it that nothing there ever reads. */
+export function isCcPeerLibraryPeer(
+  entry: Readonly<CcPeerRosterEntryLike>,
+): boolean {
+  return entry.version === "cc-peer";
+}
+
+/** The identity slot a session's own agent-comms bridge would hold if it started right now -- the same (harness, cwd) pair every real claude-code bridge entry point (bridges/claude-code/channel.ts) already constructs. */
+export function computeFrontSlot(cwd: string): IdentitySlot {
+  return { harness: "claude-code", cwd };
+}
+
+/**
+ * Filters a cc-peer roster down to the real Claude Code sessions this front should attach to right now: excludes other cc-peer-library peers, and excludes any session whose own slot is already held by a live PID (that session already fronts itself, via its own agent-comms bridge). probeSlotOwner is injected rather than imported directly so this stays a pure function over its inputs -- the real probe (identity-store.ts's probeSlotOwner) reads the filesystem, which has no place in a decision function tested purely over data.
+ */
+export function selectSessionsToFront(
+  roster: readonly CcPeerRosterEntryLike[],
+  probeSlotOwner: (slot: Readonly<IdentitySlot>) => number | undefined,
+): CcPeerRosterEntryLike[] {
+  return roster.filter((entry) => {
+    if (isCcPeerLibraryPeer(entry)) return false;
+    const slot = computeFrontSlot(entry.cwd);
+    return probeSlotOwner(slot) === undefined;
+  });
+}
+
+/**
+ * Finds which currently-fronted session an inbound cc-peer message came from, by matching the envelope's own `from` field (always the literal string "uds:" followed by the sender's own listening socket path, per cc-peer's own send() -- see CcPeer.send in cc-peer's source) against each fronted session's messagingSocketPath. Generic over the fronted-session record type so front-runtime.ts's real records (which carry a live MeshStore/CommsTool alongside the roster entry) can be matched directly without this module needing to know their shape.
+ */
+export function matchInboundMessageSession<
+  T extends { readonly messagingSocketPath: string },
+>(
+  fronted: Readonly<Iterable<T>>,
+  message: Readonly<{ from?: string }>,
+): T | undefined {
+  if (message.from === undefined) return undefined;
+  for (const record of fronted) {
+    if (message.from === `uds:${record.messagingSocketPath}`) return record;
+  }
+  return undefined;
+}