agent-comms 8.15.9 → 8.15.11

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();
+    }
+  };
+}

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();
+}