cc-peer 1.3.5 → 1.5.0

package/README.md

@@ -57,6 +57,32 @@ Every release is also mirrored to the GitHub Packages registry as `@exadev/cc-pe
 
 The REST facade (`npx cc-peer`) serves `GET /sessions`, `POST /messages`, `POST /idle-subscriptions`, `GET /events` (SSE), and a self-describing `GET /openapi.json` on loopback with a bearer token.
 
+### Session discovery and reply aliases
+
+`CcPeer.roster()` already lists every live local Claude Code session, not just ones `cc-peer` itself registered — the registry it reads (`~/.claude/sessions/*.json`) is written by every interactive session on startup. A relay/front application that wants to discover every session to attach to needs nothing beyond `roster()`.
+
+Giving a relayed session a name it can reply to natively for each of several correspondents is a different problem: the registry is one file per real OS pid with a single name each, so one process can only ever publish one discoverable name at a time (see [docs/PROTOCOL.md](docs/PROTOCOL.md#session-enumeration-and-reply-aliases-for-a-relayfront-building-on-this-sdk) for the empirical detail). `AliasPool`, exported from `cc-peer/alias-pool`, is the mechanism for this: it lazily forks one lightweight `CcPeer`-backed child process per correspondent name, and relays whatever that alias receives back to the parent.
+
+```ts
+import { AliasPool } from "cc-peer/alias-pool";
+
+const aliases = AliasPool.create();
+
+aliases.on("message", (m) => {
+  // m.alias is the correspondent name the relayed session replied to;
+  // forward m.body to that correspondent's own channel.
+  console.log(`reply for ${m.alias}: ${m.body}`);
+});
+
+// Whenever a new correspondent messages the relayed session for the first
+// time, give it a reply-able name (idempotent; a no-op if already active).
+await aliases.ensure("alice");
+
+// …later, once a correspondent is no longer relevant:
+await aliases.retire("alice");
+await aliases.stopAll();
+```
+
 ## Limitations
 
 - **Same-process constraint**: receipts and idle notices only reach the process that owns the peer's listening socket (the protocol verifies return addresses via kernel peer-pids). Do not split `CcPeer` listening and sending across processes or differently-owned workers.

package/dist/adapters/node/alias-worker.cjs

@@ -0,0 +1,42 @@
+const require_rolldown_runtime = require("../../rolldown-runtime-VH7oDXx4.cjs");
+const require_cc_peer = require("../../cc-peer-ClYIGdRf.cjs");
+const require_alias_ipc = require("../../alias-ipc-Cjs5yivH.cjs");
+let node_process = require("node:process");
+node_process = require_rolldown_runtime.__toESM(node_process, 1);
+//#region src/adapters/node/alias-worker.ts
+/**
+* Entry point for one reply alias's real OS process, forked by ForkedAliasProcess. Excluded from the coverage gate the same way src/bin/** is (see vitest.config.ts): pure process-lifecycle glue, exercised end to end by a real fork in forked-alias-process.integration.test.ts rather than in-process unit coverage.
+*/
+let peer;
+node_process.default.on("message", (raw) => {
+	handleCommand(raw);
+});
+async function handleCommand(raw) {
+	if (!require_alias_ipc.AliasCommandSchema.is(raw)) return;
+	if (raw.type === "stop") {
+		await peer?.stop();
+		node_process.default.exit(0);
+		return;
+	}
+	let created;
+	try {
+		created = await require_cc_peer.CcPeer.create({
+			name: raw.name,
+			...raw.homeDir !== void 0 ? { homeDir: raw.homeDir } : {},
+			...raw.socketDir !== void 0 ? { socketDir: raw.socketDir } : {},
+			...raw.sessionId !== void 0 ? { sessionId: raw.sessionId } : {}
+		});
+	} catch {
+		node_process.default.exit(1);
+		return;
+	}
+	peer = created;
+	peer.on("message", (message) => {
+		node_process.default.send?.({
+			type: "message",
+			...message
+		});
+	});
+	node_process.default.send?.({ type: "started" });
+}
+//#endregion

package/dist/adapters/node/alias-worker.d.cts

@@ -0,0 +1 @@
+export {}

package/dist/adapters/node/alias-worker.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/adapters/node/alias-worker.mjs

@@ -0,0 +1,41 @@
+import { n as CcPeer } from "../../cc-peer-BduoSupO.mjs";
+import { t as AliasCommandSchema } from "../../alias-ipc-DkaozCo7.mjs";
+import process from "node:process";
+//#region src/adapters/node/alias-worker.ts
+/**
+* Entry point for one reply alias's real OS process, forked by ForkedAliasProcess. Excluded from the coverage gate the same way src/bin/** is (see vitest.config.ts): pure process-lifecycle glue, exercised end to end by a real fork in forked-alias-process.integration.test.ts rather than in-process unit coverage.
+*/
+let peer;
+process.on("message", (raw) => {
+	handleCommand(raw);
+});
+async function handleCommand(raw) {
+	if (!AliasCommandSchema.is(raw)) return;
+	if (raw.type === "stop") {
+		await peer?.stop();
+		process.exit(0);
+		return;
+	}
+	let created;
+	try {
+		created = await CcPeer.create({
+			name: raw.name,
+			...raw.homeDir !== void 0 ? { homeDir: raw.homeDir } : {},
+			...raw.socketDir !== void 0 ? { socketDir: raw.socketDir } : {},
+			...raw.sessionId !== void 0 ? { sessionId: raw.sessionId } : {}
+		});
+	} catch {
+		process.exit(1);
+		return;
+	}
+	peer = created;
+	peer.on("message", (message) => {
+		process.send?.({
+			type: "message",
+			...message
+		});
+	});
+	process.send?.({ type: "started" });
+}
+//#endregion
+export {};

package/dist/alias-ipc-Cjs5yivH.cjs

@@ -0,0 +1,48 @@
+const require_errors = require("./errors-Dl_lSq1N.cjs");
+let zod = require("zod");
+//#region src/schemas/alias-ipc.ts
+/**
+* The parent-to-child and child-to-parent IPC contract `AliasPool`'s Node adapter (`adapters/node/forked-alias-process.ts`) and worker (`adapters/node/alias-worker.ts`) exchange over `child_process.fork()`'s built-in channel. This is deliberately independent of the wire protocol schemas in `wire.ts`: it never touches a socket, it only carries commands and events between a pool and the real OS process backing one reply alias.
+*/
+const AliasStartCommandSchema = require_errors.defineSchema(zod.z.object({
+	type: zod.z.literal("start"),
+	name: zod.z.string().min(1),
+	homeDir: zod.z.string().optional(),
+	socketDir: zod.z.string().optional(),
+	sessionId: zod.z.string().optional()
+}));
+const AliasStopCommandSchema = require_errors.defineSchema(zod.z.object({ type: zod.z.literal("stop") }));
+const AliasCommandSchema = require_errors.defineSchema(zod.z.union([AliasStartCommandSchema, AliasStopCommandSchema]));
+/** Sent once the worker's own CcPeer is listening and registered. */
+const AliasStartedEventSchema = require_errors.defineSchema(zod.z.object({ type: zod.z.literal("started") }));
+/** Mirrors CcPeer's own InboundMessage shape, carried over IPC instead of an EventEmitter within one process. */
+const AliasMessageEventSchema = require_errors.defineSchema(zod.z.object({
+	type: zod.z.literal("message"),
+	from: zod.z.string().optional(),
+	fromSession: zod.z.string().optional(),
+	fromName: zod.z.string().optional(),
+	fromMode: zod.z.enum(["bypass", "prompting"]).optional(),
+	hopChain: zod.z.array(zod.z.string()).optional(),
+	body: zod.z.string(),
+	msgId: zod.z.string()
+}));
+require_errors.defineSchema(zod.z.union([AliasStartedEventSchema, AliasMessageEventSchema]));
+//#endregion
+Object.defineProperty(exports, "AliasCommandSchema", {
+	enumerable: true,
+	get: function() {
+		return AliasCommandSchema;
+	}
+});
+Object.defineProperty(exports, "AliasMessageEventSchema", {
+	enumerable: true,
+	get: function() {
+		return AliasMessageEventSchema;
+	}
+});
+Object.defineProperty(exports, "AliasStartedEventSchema", {
+	enumerable: true,
+	get: function() {
+		return AliasStartedEventSchema;
+	}
+});

package/dist/alias-ipc-DkaozCo7.mjs

@@ -0,0 +1,31 @@
+import { o as defineSchema } from "./errors-Dcqq2MIW.mjs";
+import { z } from "zod";
+//#region src/schemas/alias-ipc.ts
+/**
+* The parent-to-child and child-to-parent IPC contract `AliasPool`'s Node adapter (`adapters/node/forked-alias-process.ts`) and worker (`adapters/node/alias-worker.ts`) exchange over `child_process.fork()`'s built-in channel. This is deliberately independent of the wire protocol schemas in `wire.ts`: it never touches a socket, it only carries commands and events between a pool and the real OS process backing one reply alias.
+*/
+const AliasStartCommandSchema = defineSchema(z.object({
+	type: z.literal("start"),
+	name: z.string().min(1),
+	homeDir: z.string().optional(),
+	socketDir: z.string().optional(),
+	sessionId: z.string().optional()
+}));
+const AliasStopCommandSchema = defineSchema(z.object({ type: z.literal("stop") }));
+const AliasCommandSchema = defineSchema(z.union([AliasStartCommandSchema, AliasStopCommandSchema]));
+/** Sent once the worker's own CcPeer is listening and registered. */
+const AliasStartedEventSchema = defineSchema(z.object({ type: z.literal("started") }));
+/** Mirrors CcPeer's own InboundMessage shape, carried over IPC instead of an EventEmitter within one process. */
+const AliasMessageEventSchema = defineSchema(z.object({
+	type: z.literal("message"),
+	from: z.string().optional(),
+	fromSession: z.string().optional(),
+	fromName: z.string().optional(),
+	fromMode: z.enum(["bypass", "prompting"]).optional(),
+	hopChain: z.array(z.string()).optional(),
+	body: z.string(),
+	msgId: z.string()
+}));
+defineSchema(z.union([AliasStartedEventSchema, AliasMessageEventSchema]));
+//#endregion
+export { AliasMessageEventSchema as n, AliasStartedEventSchema as r, AliasCommandSchema as t };

package/dist/alias-pool.cjs

@@ -0,0 +1,162 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("./errors-Dl_lSq1N.cjs");
+const require_alias_ipc = require("./alias-ipc-Cjs5yivH.cjs");
+let node_events = require("node:events");
+let node_child_process = require("node:child_process");
+let node_url = require("node:url");
+//#region src/adapters/node/forked-alias-process.ts
+/**
+* The real, Node-backed {@link AliasProcess}: forks a fresh OS process running `alias-worker.ts`, which registers a standalone CcPeer under the given name and relays every inbound reply back over the fork's own IPC channel.
+*/
+var ForkedAliasProcess = class {
+	events = new node_events.EventEmitter();
+	forkFn;
+	workerPath;
+	child;
+	constructor(deps) {
+		this.forkFn = deps.fork ?? node_child_process.fork;
+		this.workerPath = deps.workerPath;
+	}
+	async start(options) {
+		const child = this.forkFn(this.workerPath, [], {});
+		this.child = child;
+		child.on("message", (raw) => {
+			if (require_alias_ipc.AliasMessageEventSchema.is(raw)) this.events.emit("message", toInboundMessage(raw));
+		});
+		child.on("exit", () => {
+			this.events.emit("exit");
+		});
+		await new Promise((resolve, reject) => {
+			function onExitBeforeStart(code) {
+				child.off("message", onStarted);
+				reject(new require_errors.AliasStartError(`alias worker exited before starting (code ${code === null ? "null" : code.toString()})`));
+			}
+			function onStarted(raw) {
+				if (require_alias_ipc.AliasStartedEventSchema.is(raw)) {
+					child.off("message", onStarted);
+					child.off("exit", onExitBeforeStart);
+					resolve();
+				}
+			}
+			child.on("message", onStarted);
+			child.once("exit", onExitBeforeStart);
+			child.send({
+				type: "start",
+				name: options.name,
+				...options.homeDir !== void 0 ? { homeDir: options.homeDir } : {},
+				...options.socketDir !== void 0 ? { socketDir: options.socketDir } : {},
+				...options.sessionId !== void 0 ? { sessionId: options.sessionId } : {}
+			});
+		});
+	}
+	async stop() {
+		const child = this.child;
+		if (child === void 0) return;
+		if (child.exitCode !== null || child.signalCode !== null) return;
+		await new Promise((resolve) => {
+			child.once("exit", () => {
+				resolve();
+			});
+			child.send({ type: "stop" });
+		});
+	}
+};
+function toInboundMessage(event) {
+	return {
+		...event.from !== void 0 ? { from: event.from } : {},
+		...event.fromSession !== void 0 ? { fromSession: event.fromSession } : {},
+		...event.fromName !== void 0 ? { fromName: event.fromName } : {},
+		...event.fromMode !== void 0 ? { fromMode: event.fromMode } : {},
+		...event.hopChain !== void 0 ? { hopChain: event.hopChain } : {},
+		body: event.body,
+		msgId: event.msgId
+	};
+}
+//#endregion
+//#region src/alias-pool.ts
+/** Default log sink: logs go nowhere unless a logger is provided, matching CcPeer's own default. */
+const sinkLog = () => void 0;
+/**
+* Mirrors this module's own real build extension (tsdown's `fixedExtension: true` always emits `.mjs` or `.cjs`, never a plain `.js`) so a computed sibling path names a file tsdown actually produces. Exported as a pure function, independent of `import.meta.url`, so both branches are directly unit-testable: in this repo's own dev/test tree `import.meta.url` always ends in `.ts`, so a test exercising this module's own `import.meta.url` can only ever observe the `.mjs` branch.
+*/
+function workerExtensionFor(moduleUrl) {
+	return moduleUrl.endsWith(".cjs") ? ".cjs" : ".mjs";
+}
+/**
+* alias-worker.ts's own built location, computed from this file's `import.meta.url` rather than ForkedAliasProcess's own: this file is itself a dedicated tsdown entry (see tsdown.config.ts), so its emitted location is stable and predictable, and alias-worker.ts (also a dedicated entry) is emitted at the same relative position to it as the two source files hold to each other in src/.
+*/
+const DEFAULT_WORKER_PATH = (0, node_url.fileURLToPath)(new URL(`./adapters/node/alias-worker${workerExtensionFor(require("url").pathToFileURL(__filename).href)}`, require("url").pathToFileURL(__filename).href));
+/**
+* Lazily materialises one natively-discoverable Claude Code peer identity per mesh correspondent name, each backed by its own real OS process (see ports/alias-process.ts for why a real process is required). Emits "message" (an {@link AliasMessage}) for every reply an alias receives, and "exit" (an object with an `alias` name field) when an alias's backing process ends, whether from a deliberate retire() or an unexpected crash.
+*/
+var AliasPool = class AliasPool extends node_events.EventEmitter {
+	deps;
+	options;
+	active = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new Map();
+	log;
+	constructor(deps, options = {}) {
+		super();
+		this.deps = deps;
+		this.options = options;
+		this.log = options.logger ?? sinkLog;
+	}
+	static create(options = {}) {
+		return new AliasPool({ spawn: () => new ForkedAliasProcess({ workerPath: DEFAULT_WORKER_PATH }) }, options);
+	}
+	/** Idempotent: a no-op if the alias is already active, and dedup'd if another ensure() for the same name is already in flight. */
+	async ensure(name) {
+		if (this.active.has(name)) return;
+		const inFlight = this.pending.get(name);
+		if (inFlight !== void 0) {
+			await inFlight;
+			return;
+		}
+		const started = this.startAlias(name);
+		this.pending.set(name, started);
+		try {
+			await started;
+		} finally {
+			this.pending.delete(name);
+		}
+	}
+	async startAlias(name) {
+		const proc = this.deps.spawn();
+		proc.events.on("message", (message) => {
+			this.emit("message", {
+				alias: name,
+				...message
+			});
+		});
+		proc.events.on("exit", () => {
+			this.active.delete(name);
+			this.emit("exit", { alias: name });
+		});
+		await proc.start({
+			name,
+			...this.options.homeDir !== void 0 ? { homeDir: this.options.homeDir } : {},
+			...this.options.socketDir !== void 0 ? { socketDir: this.options.socketDir } : {}
+		});
+		this.active.set(name, proc);
+		this.log(`alias ${name} active`);
+	}
+	/** Waits for any in-flight ensure() of the same name to settle first, so a retire() issued while an alias is still starting stops it once (and if) it becomes active. A no-op for a name that is neither active nor pending. */
+	async retire(name) {
+		const inFlight = this.pending.get(name);
+		if (inFlight !== void 0) await inFlight.catch(() => void 0);
+		const proc = this.active.get(name);
+		if (proc === void 0) return;
+		this.active.delete(name);
+		await proc.stop();
+		this.log(`alias ${name} retired`);
+	}
+	async stopAll() {
+		await Promise.all([...this.active.keys()].map(async (name) => this.retire(name)));
+	}
+	activeAliases() {
+		return [...this.active.keys()];
+	}
+};
+//#endregion
+exports.AliasPool = AliasPool;
+exports.workerExtensionFor = workerExtensionFor;

package/dist/alias-pool.d.cts

@@ -0,0 +1,51 @@
+import { a as InboundMessage, l as PathConfig } from "./cc-peer-B3i4ZlKV.cjs";
+import { EventEmitter } from "node:events";
+//#region src/ports/alias-process.d.ts
+interface AliasStartOptions extends PathConfig {
+  name: string;
+  sessionId?: string;
+}
+/**
+ * A synthetic, natively-discoverable Claude Code peer identity backed by a real OS process. A real process is required, not a design choice: the registry is one file per real pid with a single optional name field each (see docs/PROTOCOL.md's "Reply aliases" section), so a single process can only ever publish one discoverable name at a time. `events` emits "message" (an InboundMessage-shaped object) for each reply the alias receives, and "exit" once the backing process has ended, whether from a deliberate stop() or an unexpected crash.
+ */
+interface AliasProcess {
+  readonly events: EventEmitter;
+  start: (options: Readonly<AliasStartOptions>) => Promise<void>;
+  stop: () => Promise<void>;
+}
+//#endregion
+//#region src/alias-pool.d.ts
+export interface AliasPoolOptions extends PathConfig {
+  logger?: (message: string) => void;
+}
+/** An inbound reply relayed from one alias, with the correspondent name it arrived for attached. */
+export interface AliasMessage extends InboundMessage {
+  alias: string;
+}
+/**
+ * Mirrors this module's own real build extension (tsdown's `fixedExtension: true` always emits `.mjs` or `.cjs`, never a plain `.js`) so a computed sibling path names a file tsdown actually produces. Exported as a pure function, independent of `import.meta.url`, so both branches are directly unit-testable: in this repo's own dev/test tree `import.meta.url` always ends in `.ts`, so a test exercising this module's own `import.meta.url` can only ever observe the `.mjs` branch.
+ */
+export declare function workerExtensionFor(moduleUrl: string): ".mjs" | ".cjs";
+interface Deps {
+  spawn: () => AliasProcess;
+}
+/**
+ * Lazily materialises one natively-discoverable Claude Code peer identity per mesh correspondent name, each backed by its own real OS process (see ports/alias-process.ts for why a real process is required). Emits "message" (an {@link AliasMessage}) for every reply an alias receives, and "exit" (an object with an `alias` name field) when an alias's backing process ends, whether from a deliberate retire() or an unexpected crash.
+ */
+export declare class AliasPool extends EventEmitter {
+  private readonly deps;
+  private readonly options;
+  private readonly active;
+  private readonly pending;
+  private readonly log;
+  constructor(deps: Readonly<Deps>, options?: Readonly<AliasPoolOptions>);
+  static create(options?: Readonly<AliasPoolOptions>): AliasPool;
+  /** Idempotent: a no-op if the alias is already active, and dedup'd if another ensure() for the same name is already in flight. */
+  ensure(name: string): Promise<void>;
+  private startAlias;
+  /** Waits for any in-flight ensure() of the same name to settle first, so a retire() issued while an alias is still starting stops it once (and if) it becomes active. A no-op for a name that is neither active nor pending. */
+  retire(name: string): Promise<void>;
+  stopAll(): Promise<void>;
+  activeAliases(): string[];
+}
+//#endregion

package/dist/alias-pool.d.mts

@@ -0,0 +1,51 @@
+import { a as InboundMessage, l as PathConfig } from "./cc-peer-B3i4ZlKV.mjs";
+import { EventEmitter } from "node:events";
+//#region src/ports/alias-process.d.ts
+interface AliasStartOptions extends PathConfig {
+  name: string;
+  sessionId?: string;
+}
+/**
+ * A synthetic, natively-discoverable Claude Code peer identity backed by a real OS process. A real process is required, not a design choice: the registry is one file per real pid with a single optional name field each (see docs/PROTOCOL.md's "Reply aliases" section), so a single process can only ever publish one discoverable name at a time. `events` emits "message" (an InboundMessage-shaped object) for each reply the alias receives, and "exit" once the backing process has ended, whether from a deliberate stop() or an unexpected crash.
+ */
+interface AliasProcess {
+  readonly events: EventEmitter;
+  start: (options: Readonly<AliasStartOptions>) => Promise<void>;
+  stop: () => Promise<void>;
+}
+//#endregion
+//#region src/alias-pool.d.ts
+export interface AliasPoolOptions extends PathConfig {
+  logger?: (message: string) => void;
+}
+/** An inbound reply relayed from one alias, with the correspondent name it arrived for attached. */
+export interface AliasMessage extends InboundMessage {
+  alias: string;
+}
+/**
+ * Mirrors this module's own real build extension (tsdown's `fixedExtension: true` always emits `.mjs` or `.cjs`, never a plain `.js`) so a computed sibling path names a file tsdown actually produces. Exported as a pure function, independent of `import.meta.url`, so both branches are directly unit-testable: in this repo's own dev/test tree `import.meta.url` always ends in `.ts`, so a test exercising this module's own `import.meta.url` can only ever observe the `.mjs` branch.
+ */
+export declare function workerExtensionFor(moduleUrl: string): ".mjs" | ".cjs";
+interface Deps {
+  spawn: () => AliasProcess;
+}
+/**
+ * Lazily materialises one natively-discoverable Claude Code peer identity per mesh correspondent name, each backed by its own real OS process (see ports/alias-process.ts for why a real process is required). Emits "message" (an {@link AliasMessage}) for every reply an alias receives, and "exit" (an object with an `alias` name field) when an alias's backing process ends, whether from a deliberate retire() or an unexpected crash.
+ */
+export declare class AliasPool extends EventEmitter {
+  private readonly deps;
+  private readonly options;
+  private readonly active;
+  private readonly pending;
+  private readonly log;
+  constructor(deps: Readonly<Deps>, options?: Readonly<AliasPoolOptions>);
+  static create(options?: Readonly<AliasPoolOptions>): AliasPool;
+  /** Idempotent: a no-op if the alias is already active, and dedup'd if another ensure() for the same name is already in flight. */
+  ensure(name: string): Promise<void>;
+  private startAlias;
+  /** Waits for any in-flight ensure() of the same name to settle first, so a retire() issued while an alias is still starting stops it once (and if) it becomes active. A no-op for a name that is neither active nor pending. */
+  retire(name: string): Promise<void>;
+  stopAll(): Promise<void>;
+  activeAliases(): string[];
+}
+//#endregion

package/dist/alias-pool.mjs

@@ -0,0 +1,160 @@
+import { t as AliasStartError } from "./errors-Dcqq2MIW.mjs";
+import { n as AliasMessageEventSchema, r as AliasStartedEventSchema } from "./alias-ipc-DkaozCo7.mjs";
+import { EventEmitter } from "node:events";
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+//#region src/adapters/node/forked-alias-process.ts
+/**
+* The real, Node-backed {@link AliasProcess}: forks a fresh OS process running `alias-worker.ts`, which registers a standalone CcPeer under the given name and relays every inbound reply back over the fork's own IPC channel.
+*/
+var ForkedAliasProcess = class {
+	events = new EventEmitter();
+	forkFn;
+	workerPath;
+	child;
+	constructor(deps) {
+		this.forkFn = deps.fork ?? fork;
+		this.workerPath = deps.workerPath;
+	}
+	async start(options) {
+		const child = this.forkFn(this.workerPath, [], {});
+		this.child = child;
+		child.on("message", (raw) => {
+			if (AliasMessageEventSchema.is(raw)) this.events.emit("message", toInboundMessage(raw));
+		});
+		child.on("exit", () => {
+			this.events.emit("exit");
+		});
+		await new Promise((resolve, reject) => {
+			function onExitBeforeStart(code) {
+				child.off("message", onStarted);
+				reject(new AliasStartError(`alias worker exited before starting (code ${code === null ? "null" : code.toString()})`));
+			}
+			function onStarted(raw) {
+				if (AliasStartedEventSchema.is(raw)) {
+					child.off("message", onStarted);
+					child.off("exit", onExitBeforeStart);
+					resolve();
+				}
+			}
+			child.on("message", onStarted);
+			child.once("exit", onExitBeforeStart);
+			child.send({
+				type: "start",
+				name: options.name,
+				...options.homeDir !== void 0 ? { homeDir: options.homeDir } : {},
+				...options.socketDir !== void 0 ? { socketDir: options.socketDir } : {},
+				...options.sessionId !== void 0 ? { sessionId: options.sessionId } : {}
+			});
+		});
+	}
+	async stop() {
+		const child = this.child;
+		if (child === void 0) return;
+		if (child.exitCode !== null || child.signalCode !== null) return;
+		await new Promise((resolve) => {
+			child.once("exit", () => {
+				resolve();
+			});
+			child.send({ type: "stop" });
+		});
+	}
+};
+function toInboundMessage(event) {
+	return {
+		...event.from !== void 0 ? { from: event.from } : {},
+		...event.fromSession !== void 0 ? { fromSession: event.fromSession } : {},
+		...event.fromName !== void 0 ? { fromName: event.fromName } : {},
+		...event.fromMode !== void 0 ? { fromMode: event.fromMode } : {},
+		...event.hopChain !== void 0 ? { hopChain: event.hopChain } : {},
+		body: event.body,
+		msgId: event.msgId
+	};
+}
+//#endregion
+//#region src/alias-pool.ts
+/** Default log sink: logs go nowhere unless a logger is provided, matching CcPeer's own default. */
+const sinkLog = () => void 0;
+/**
+* Mirrors this module's own real build extension (tsdown's `fixedExtension: true` always emits `.mjs` or `.cjs`, never a plain `.js`) so a computed sibling path names a file tsdown actually produces. Exported as a pure function, independent of `import.meta.url`, so both branches are directly unit-testable: in this repo's own dev/test tree `import.meta.url` always ends in `.ts`, so a test exercising this module's own `import.meta.url` can only ever observe the `.mjs` branch.
+*/
+function workerExtensionFor(moduleUrl) {
+	return moduleUrl.endsWith(".cjs") ? ".cjs" : ".mjs";
+}
+/**
+* alias-worker.ts's own built location, computed from this file's `import.meta.url` rather than ForkedAliasProcess's own: this file is itself a dedicated tsdown entry (see tsdown.config.ts), so its emitted location is stable and predictable, and alias-worker.ts (also a dedicated entry) is emitted at the same relative position to it as the two source files hold to each other in src/.
+*/
+const DEFAULT_WORKER_PATH = fileURLToPath(new URL(`./adapters/node/alias-worker${workerExtensionFor(import.meta.url)}`, import.meta.url));
+/**
+* Lazily materialises one natively-discoverable Claude Code peer identity per mesh correspondent name, each backed by its own real OS process (see ports/alias-process.ts for why a real process is required). Emits "message" (an {@link AliasMessage}) for every reply an alias receives, and "exit" (an object with an `alias` name field) when an alias's backing process ends, whether from a deliberate retire() or an unexpected crash.
+*/
+var AliasPool = class AliasPool extends EventEmitter {
+	deps;
+	options;
+	active = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new Map();
+	log;
+	constructor(deps, options = {}) {
+		super();
+		this.deps = deps;
+		this.options = options;
+		this.log = options.logger ?? sinkLog;
+	}
+	static create(options = {}) {
+		return new AliasPool({ spawn: () => new ForkedAliasProcess({ workerPath: DEFAULT_WORKER_PATH }) }, options);
+	}
+	/** Idempotent: a no-op if the alias is already active, and dedup'd if another ensure() for the same name is already in flight. */
+	async ensure(name) {
+		if (this.active.has(name)) return;
+		const inFlight = this.pending.get(name);
+		if (inFlight !== void 0) {
+			await inFlight;
+			return;
+		}
+		const started = this.startAlias(name);
+		this.pending.set(name, started);
+		try {
+			await started;
+		} finally {
+			this.pending.delete(name);
+		}
+	}
+	async startAlias(name) {
+		const proc = this.deps.spawn();
+		proc.events.on("message", (message) => {
+			this.emit("message", {
+				alias: name,
+				...message
+			});
+		});
+		proc.events.on("exit", () => {
+			this.active.delete(name);
+			this.emit("exit", { alias: name });
+		});
+		await proc.start({
+			name,
+			...this.options.homeDir !== void 0 ? { homeDir: this.options.homeDir } : {},
+			...this.options.socketDir !== void 0 ? { socketDir: this.options.socketDir } : {}
+		});
+		this.active.set(name, proc);
+		this.log(`alias ${name} active`);
+	}
+	/** Waits for any in-flight ensure() of the same name to settle first, so a retire() issued while an alias is still starting stops it once (and if) it becomes active. A no-op for a name that is neither active nor pending. */
+	async retire(name) {
+		const inFlight = this.pending.get(name);
+		if (inFlight !== void 0) await inFlight.catch(() => void 0);
+		const proc = this.active.get(name);
+		if (proc === void 0) return;
+		this.active.delete(name);
+		await proc.stop();
+		this.log(`alias ${name} retired`);
+	}
+	async stopAll() {
+		await Promise.all([...this.active.keys()].map(async (name) => this.retire(name)));
+	}
+	activeAliases() {
+		return [...this.active.keys()];
+	}
+};
+//#endregion
+export { AliasPool, workerExtensionFor };