cc-peer 1.0.0 → 1.1.0

package/dist/cc-peer-BpNw-MoF.mjs

@@ -0,0 +1,945 @@
+import { EventEmitter } from "node:events";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { connect, createServer } from "node:net";
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+//#region src/adapters/node/uds-transport.ts
+/** macOS linger before close, matching the reference client's ~150ms. */
+const DEFAULT_LINGER_MS = 150;
+const CONNECT_TIMEOUT_MS = 5e3;
+const PROBE_TIMEOUT_MS = 2e3;
+var NodeInboundConnection = class {
+	socket;
+	buffer = "";
+	lines = [];
+	waiters = [];
+	ended = false;
+	/** macOS local-peer pid, captured from the first data chunk's control info. */
+	cachedPid;
+	constructor(socket) {
+		this.socket = socket;
+		socket.on("data", (chunk) => {
+			this.cachedPid ??= void 0;
+			this.buffer += chunk.toString("utf8");
+			let index = this.buffer.indexOf("\n");
+			while (index >= 0) {
+				const line = this.buffer.slice(0, index);
+				this.buffer = this.buffer.slice(index + 1);
+				const waiter = this.waiters.shift();
+				if (waiter === void 0) this.lines.push(line);
+				else waiter(line);
+				index = this.buffer.indexOf("\n");
+			}
+		});
+		socket.on("close", () => {
+			this.ended = true;
+			for (const waiter of this.waiters.splice(0)) waiter(void 0);
+		});
+		socket.on("error", () => {
+			this.ended = true;
+			for (const waiter of this.waiters.splice(0)) waiter(void 0);
+		});
+	}
+	peerPid() {
+		return this.cachedPid;
+	}
+	async *readLines() {
+		const waitForLine = async () => new Promise((resolve) => {
+			this.waiters.push(resolve);
+		});
+		for (;;) {
+			const next = this.lines.shift() ?? await waitForLine();
+			if (next === void 0) return;
+			yield next;
+		}
+	}
+	close() {
+		this.socket.destroy();
+	}
+};
+var UdsTransport = class {
+	async connectWrite(socketPath, lines, lingerMs = DEFAULT_LINGER_MS) {
+		const payload = Buffer.from(lines.join("\n") + "\n", "utf8");
+		await new Promise((resolve, reject) => {
+			const socket = connect(socketPath);
+			const fail = (error) => {
+				socket.destroy();
+				reject(error);
+			};
+			socket.setTimeout(CONNECT_TIMEOUT_MS, () => {
+				fail(/* @__PURE__ */ new Error(`timeout connecting ${socketPath}`));
+			});
+			socket.once("error", fail);
+			socket.once("connect", () => {
+				socket.setTimeout(0);
+				socket.write(payload, (error) => {
+					if (error !== null && error !== void 0) fail(error);
+				});
+				setTimeout(() => {
+					socket.end();
+				}, lingerMs).unref();
+			});
+			socket.once("close", () => {
+				resolve();
+			});
+			socket.once("finish", () => {
+				resolve();
+			});
+		});
+	}
+	async probe(socketPath) {
+		return new Promise((resolve) => {
+			const socket = connect(socketPath);
+			const done = (value) => {
+				socket.destroy();
+				resolve(value);
+			};
+			socket.setTimeout(PROBE_TIMEOUT_MS, () => {
+				done(false);
+			});
+			socket.once("error", (error) => {
+				done(error.code === "EBUSY");
+			});
+			socket.once("connect", () => {
+				done(true);
+			});
+		});
+	}
+	async listen(socketPath, onConnection) {
+		const accepted = [];
+		const server = createServer((socket) => {
+			accepted.push(socket);
+			socket.once("close", () => {
+				const index = accepted.indexOf(socket);
+				if (index >= 0) accepted.splice(index, 1);
+			});
+			onConnection(new NodeInboundConnection(socket));
+		});
+		await new Promise((resolve, reject) => {
+			server.once("error", reject);
+			server.listen(socketPath, () => {
+				resolve();
+			});
+		});
+		return {
+			socketPath,
+			close: async () => {
+				await new Promise((resolve) => {
+					server.close(() => {
+						resolve();
+					});
+				});
+				for (const socket of accepted) socket.destroy();
+			}
+		};
+	}
+};
+var SystemClock = class {
+	nowMs() {
+		return Date.now();
+	}
+};
+//#endregion
+//#region src/schemas/define-schema.ts
+/**
+* Attach an `.is()` type guard to a Zod schema so schema, inferred type, and runtime guard derive from one definition (single source of truth). `Schema.parse()` at JSON boundaries; `Schema.is()` for narrowing.
+*/
+function defineSchema(schema) {
+	return Object.assign(schema, { is(value) {
+		return schema.safeParse(value).success;
+	} });
+}
+const hex = (bytes) => bytes * 2;
+const PEER_TOKEN_HEX_LENGTH = hex(16);
+const HOP_ID_HEX_LENGTH = hex(12);
+/**
+* Lint-clean string form of a numeric limit for regex interpolation;
+* `restrict-template-expressions` rejects numbers inside template literals.
+*/
+const count = (n) => String(n);
+//#endregion
+//#region src/schemas/keyfile.ts
+/** The auth key a session publishes next to its socket. */
+const PeerKeyFileSchema = defineSchema(z.object({
+	peerToken: z.string().regex(new RegExp(`^[0-9a-f]{${count(PEER_TOKEN_HEX_LENGTH)}}$`)),
+	procStart: z.string().min(1),
+	pidDomain: z.string().min(1)
+}));
+//#endregion
+//#region src/adapters/node/paths.ts
+/** Candidate socket directories, in the order the reference client accepts them. */
+function socketDirCandidates(config = {}) {
+	if (config.socketDir !== void 0) return [config.socketDir];
+	const runtimeDir = process.env.XDG_RUNTIME_DIR;
+	return [
+		"/tmp/cc-socks",
+		"/private/tmp/cc-socks",
+		...runtimeDir !== void 0 ? [`${runtimeDir}/cc-socks`] : []
+	];
+}
+function sessionsDir(config = {}) {
+	return join(config.homeDir ?? homedir(), ".claude", "sessions");
+}
+function socketPathForPid(pid, config = {}) {
+	return `${socketDirCandidates(config)[0] ?? "/tmp/cc-socks"}/${pid.toString()}.sock`;
+}
+function registryFilePath(pid, config = {}) {
+	return join(sessionsDir(config), `${pid.toString()}.json`);
+}
+/** Key files are named pid.sha256-of-canonical-socket-path with a .key suffix. */
+function keyFilePath(socketPath, config = {}) {
+	const hash = createHash("sha256").update(socketPath).digest("hex");
+	return join(sessionsDir(config), `${pidFromSocketPath(socketPath).toString()}.${hash}.key`);
+}
+function pidFromSocketPath(socketPath) {
+	const base = socketPath.split("/").at(-1) ?? "";
+	const pid = Number.parseInt(base.replace(/\.sock$/, ""), 10);
+	return Number.isNaN(pid) ? 0 : pid;
+}
+/** Temporary-suffix helper keeping pid interpolations string-typed for lint. */
+const tmpSuffix = () => `tmp-${process.pid.toString()}`;
+//#endregion
+//#region src/adapters/node/fs-key-store.ts
+var FsKeyStore = class {
+	config;
+	constructor(config = {}) {
+		this.config = config;
+	}
+	async readForSocket(socketPath) {
+		let raw;
+		try {
+			raw = await readFile(keyFilePath(socketPath, this.config), "utf8");
+		} catch {
+			return;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			return;
+		}
+		const result = PeerKeyFileSchema.safeParse(parsed);
+		return result.success ? result.data : void 0;
+	}
+	async writeForSocket(socketPath, keyFile) {
+		const path = keyFilePath(socketPath, this.config);
+		await mkdir(dirname(path), {
+			recursive: true,
+			mode: 448
+		});
+		const tmp = `${path}.${tmpSuffix()}`;
+		await writeFile(tmp, `${JSON.stringify(keyFile)}\n`, { mode: 384 });
+		await rename(tmp, path);
+	}
+	async removeForSocket(socketPath) {
+		await unlink(keyFilePath(socketPath, this.config)).catch(() => void 0);
+	}
+};
+//#endregion
+//#region src/schemas/registry.ts
+/** Whitelist the receiver applies on read; other values parse to undefined. */
+const NameSourceSchema = defineSchema(z.enum([
+	"user",
+	"peer",
+	"derived",
+	"collision",
+	"auto",
+	"hook"
+]));
+const PeerStatusSchema = defineSchema(z.enum([
+	"busy",
+	"shell",
+	"idle",
+	"waiting"
+]));
+const SessionKindSchema = defineSchema(z.enum([
+	"interactive",
+	"bg",
+	"daemon",
+	"daemon-worker"
+]));
+const PeerFeatureSchema = defineSchema(z.enum([
+	"notify_idle",
+	"reply_across_default_dirs",
+	"artifact_yield"
+]));
+/** One entry of the ~/.claude/sessions/<pid>.json registry. */
+const RegistryEntrySchema = defineSchema(z.object({
+	pid: z.number().int().positive(),
+	sessionId: z.string().min(1),
+	cwd: z.string(),
+	startedAt: z.number().int().nonnegative(),
+	procStart: z.string().min(1),
+	version: z.string().min(1),
+	peerProtocol: z.number().int(),
+	peerFeatures: z.array(PeerFeatureSchema),
+	kind: SessionKindSchema,
+	entrypoint: z.string(),
+	pidDomain: z.string().min(1),
+	messagingSocketPath: z.string().min(1),
+	name: z.string().optional(),
+	nameSource: NameSourceSchema.optional(),
+	nameSince: z.number().int().nonnegative().optional(),
+	updatedAt: z.number().int().nonnegative(),
+	status: PeerStatusSchema.optional(),
+	statusUpdatedAt: z.number().int().nonnegative().optional(),
+	bridgeSessionId: z.string().optional()
+}));
+//#endregion
+//#region src/adapters/node/fs-registry-store.ts
+var FsRegistryStore = class {
+	config;
+	constructor(config = {}) {
+		this.config = config;
+	}
+	async list() {
+		const dir = sessionsDir(this.config);
+		let names;
+		try {
+			names = await readdir(dir);
+		} catch {
+			return [];
+		}
+		const entries = [];
+		for (const name of names) {
+			if (!/^\d+\.json$/.test(name)) continue;
+			const entry = await this.read(Number.parseInt(name, 10));
+			if (entry !== void 0) entries.push(entry);
+		}
+		return entries;
+	}
+	async read(pid) {
+		let raw;
+		try {
+			raw = await readFile(registryFilePath(pid, this.config), "utf8");
+		} catch {
+			return;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			return;
+		}
+		const result = RegistryEntrySchema.safeParse(parsed);
+		return result.success ? result.data : void 0;
+	}
+	async write(entry) {
+		const path = registryFilePath(entry.pid, this.config);
+		await mkdir(dirname(path), {
+			recursive: true,
+			mode: 448
+		});
+		const tmp = `${path}.${tmpSuffix()}`;
+		await writeFile(tmp, `${JSON.stringify(entry)}\n`, { mode: 420 });
+		await rename(tmp, path);
+	}
+	async touch(pid) {
+		const entry = await this.read(pid);
+		if (entry === void 0) return;
+		const now = Date.now();
+		await this.write({
+			...entry,
+			updatedAt: now,
+			...entry.status !== void 0 ? { statusUpdatedAt: now } : {}
+		});
+	}
+	async remove(pid) {
+		await unlink(registryFilePath(pid, this.config)).catch(() => void 0);
+	}
+};
+//#endregion
+//#region src/adapters/node/ps-proc-info.ts
+var PsProcInfo = class PsProcInfo {
+	async alive(pid) {
+		const errno = (error) => {
+			if (error instanceof Error && "code" in error && typeof error.code === "string") return error.code;
+			return "";
+		};
+		return new Promise((resolve) => {
+			try {
+				process.kill(pid, 0);
+				resolve(true);
+			} catch (error) {
+				resolve(errno(error) === "EPERM");
+			}
+		});
+	}
+	/**
+	* `ps -o lstart=` under forced C locale and UTC, returning the trimmed output byte-exact. The registry's liveness check string-compares this value, so the forced environment is load-bearing: bare `ps` follows the user's locale (day-before-month order under en_GB) and local time.
+	*/
+	async lstart(pid) {
+		return (await this.runPs(pid))?.trim();
+	}
+	psCache = /* @__PURE__ */ new Map();
+	static CACHE_MS = 6e4;
+	inFlight = /* @__PURE__ */ new Map();
+	async runPs(pid) {
+		const cached = this.psCache.get(pid);
+		if (cached !== void 0 && Date.now() - cached.at < PsProcInfo.CACHE_MS) return Promise.resolve(cached.value);
+		const existing = this.inFlight.get(pid);
+		if (existing !== void 0) return existing;
+		const promise = new Promise((resolve) => {
+			let child;
+			try {
+				child = spawn("ps", [
+					"-o",
+					"lstart=",
+					"-p",
+					String(pid)
+				], {
+					env: {
+						...process.env,
+						LC_ALL: "C",
+						TZ: "UTC"
+					},
+					stdio: [
+						"ignore",
+						"pipe",
+						"ignore"
+					]
+				});
+			} catch {
+				resolve(void 0);
+				return;
+			}
+			let out = "";
+			child.stdout?.on("data", (chunk) => {
+				out += chunk.toString("utf8");
+			});
+			child.on("error", () => {
+				resolve(void 0);
+			});
+			child.on("close", (code) => {
+				this.psCache.set(pid, {
+					at: Date.now(),
+					value: out
+				});
+				resolve(code === 0 && out.trim().length > 0 ? out : void 0);
+			});
+		}).finally(() => {
+			this.inFlight.delete(pid);
+		});
+		this.inFlight.set(pid, promise);
+		return promise;
+	}
+};
+//#endregion
+//#region src/schemas/envelope.ts
+/**
+* Grammar of the <cross-session-message> envelope attributes, mirroring the receiver's own parser. The serialized attribute ORDER is canonical (from, from-session, hop-chain, from-name, from-mode): the receiver's regex matches that sequence only, so any other order parses as nothing.
+*/
+const EnvelopeAddressSchema = defineSchema(z.string().regex(new RegExp(`^[A-Za-z0-9%:_/.\\\\-]{1,${count(300)}}$`)));
+const FromModeSchema = defineSchema(z.enum(["bypass", "prompting"]));
+const HopIdSchema = z.string().regex(new RegExp(`^[0-9a-f]{${count(HOP_ID_HEX_LENGTH)}}$`));
+const EnvelopeAttributesSchema = defineSchema(z.object({
+	from: EnvelopeAddressSchema,
+	fromSession: z.string().regex(new RegExp(`^[A-Za-z0-9_-]{1,${count(80)}}$`)).optional(),
+	/** Parsed hop chain: at most 32 ids at the grammar level. */
+	hopChain: z.array(HopIdSchema).max(32).optional(),
+	fromName: z.string().min(1).max(80).optional(),
+	fromMode: FromModeSchema.optional()
+}));
+//#endregion
+//#region src/domain/envelope.ts
+const TAG = "cross-session-message";
+/**
+* The receiver's own parse shape: attributes in canonical order, each value constrained to its grammar, body between newlines. Mirrors `HB` in the reference client, including the round-trip check (rebuild-and-compare). The body is captured verbatim: escaping is applied on build only and is idempotent, so parsed bodies stay in escaped form exactly as sent.
+*/
+const ENVELOPE_RE = new RegExp(`^<${TAG}(?: from="([A-Za-z0-9%:_/.\\\\-]{1,${count(300)}})")?(?: from-session="([A-Za-z0-9_-]{1,${count(80)}})")?(?: hop-chain="([0-9a-f]{${count(HOP_ID_HEX_LENGTH)}}(?:,[0-9a-f]{${count(HOP_ID_HEX_LENGTH)}}){0,${count(31)}})")?(?: from-name="([^"<>\\n\\r]{1,${count(80)}})")?(?: from-mode="(bypass|prompting)")?>\\n([\\s\\S]*)\\n</${TAG}>$`);
+/** Occurrences of the closing tag inside a body are escaped to a literal `<\`. Idempotent. */
+function escapeBody(body) {
+	return body.replaceAll(`</${TAG}`, "<\\");
+}
+/** Serialize attributes in the canonical order the receiver's regex requires. */
+function serializeAttributes(attrs) {
+	const parts = [];
+	parts.push(` from="${attrs.from}"`);
+	if (attrs.fromSession !== void 0) parts.push(` from-session="${attrs.fromSession}"`);
+	if (attrs.hopChain !== void 0 && attrs.hopChain.length > 0) parts.push(` hop-chain="${attrs.hopChain.join(",")}"`);
+	if (attrs.fromName !== void 0) parts.push(` from-name="${attrs.fromName.replaceAll("\"", "")}"`);
+	if (attrs.fromMode !== void 0) parts.push(` from-mode="${attrs.fromMode}"`);
+	return parts.join("");
+}
+function buildEnvelope(attrs, body) {
+	const validated = EnvelopeAttributesSchema.parse(attrs);
+	return `<${TAG}${serializeAttributes(validated)}>\n${escapeBody(body)}\n</${TAG}>`;
+}
+function parseEnvelope(content) {
+	const match = ENVELOPE_RE.exec(content);
+	if (match === null) return void 0;
+	const parsed = { body: match[6] ?? "" };
+	if (match[1] !== void 0) parsed.from = match[1];
+	if (match[2] !== void 0) parsed.fromSession = match[2];
+	if (match[3] !== void 0) parsed.hopChain = match[3].split(",");
+	if (match[4] !== void 0) parsed.fromName = match[4];
+	if (match[5] === "bypass" || match[5] === "prompting") parsed.fromMode = match[5];
+	return parsed;
+}
+const DEFAULT_REFILL_PER_SECOND = .5;
+const MS_PER_SECOND = 1e3;
+/**
+* Outbound token bucket mirroring the receiver's admission rate limit (30 tokens, 0.5/s refill): sending faster than the target accepts gets messages dropped with reason "rate-limited". reserve() blocks until a token is available; a negative wait means tokens are already full.
+*/
+var Pacer = class {
+	clock;
+	capacity;
+	refillPerSecond;
+	tokens;
+	lastRefillMs;
+	constructor(clock, capacity = 30, refillPerSecond = DEFAULT_REFILL_PER_SECOND) {
+		this.clock = clock;
+		this.capacity = capacity;
+		this.refillPerSecond = refillPerSecond;
+		this.tokens = capacity;
+		this.lastRefillMs = clock.nowMs();
+	}
+	/** Milliseconds to wait before one token is available (0 = now). */
+	msUntilNextToken() {
+		this.refill();
+		if (this.tokens >= 1) return 0;
+		const deficit = 1 - this.tokens;
+		return Math.ceil(deficit / this.refillPerSecond * MS_PER_SECOND);
+	}
+	/** Consume one token if available. */
+	tryReserve() {
+		this.refill();
+		if (this.tokens < 1) return false;
+		this.tokens -= 1;
+		return true;
+	}
+	refill() {
+		const now = this.clock.nowMs();
+		const elapsedSeconds = (now - this.lastRefillMs) / MS_PER_SECOND;
+		if (elapsedSeconds <= 0) return;
+		this.tokens = Math.min(this.capacity, this.tokens + elapsedSeconds * this.refillPerSecond);
+		this.lastRefillMs = now;
+	}
+};
+//#endregion
+//#region src/domain/ids.ts
+/** Message ids are UUID v4, matching the reference client's `qM()`. */
+function newMsgId() {
+	return randomUUID();
+}
+//#endregion
+//#region src/domain/roster.ts
+/**
+* The receiver's own admission rules, verified live: an entry is listed when it has a socket, is not the caller's own, is not spare/parked, its socket accepts a live connect probe, and its pid is alive with a procStart that byte-matches the ps output. Mismatches classify as recycled and are silently skipped by the reference roster builder.
+*/
+async function filterRoster(entries, probes) {
+	const verdicts = [];
+	for (const entry of entries) {
+		const verdict = await checkEntry(entry, probes);
+		verdicts.push(verdict);
+	}
+	return verdicts.filter((v) => v.admitted).map((v) => v.entry);
+}
+async function checkEntry(entry, probes) {
+	if (entry.messagingSocketPath.length === 0) return {
+		entry,
+		admitted: false,
+		reason: "no-socket"
+	};
+	if (probes.ownSocketPath !== void 0 && entry.messagingSocketPath === probes.ownSocketPath) return {
+		entry,
+		admitted: false,
+		reason: "own-socket"
+	};
+	if (!await probes.procInfo.alive(entry.pid)) return {
+		entry,
+		admitted: false,
+		reason: "pid-dead"
+	};
+	const lstart = await probes.procInfo.lstart(entry.pid);
+	if (lstart === void 0 || lstart !== entry.procStart) return {
+		entry,
+		admitted: false,
+		reason: "proc-start-mismatch"
+	};
+	if (!await probes.transport.probe(entry.messagingSocketPath)) return {
+		entry,
+		admitted: false,
+		reason: "socket-dead"
+	};
+	return {
+		entry,
+		admitted: true
+	};
+}
+//#endregion
+//#region src/schemas/wire.ts
+/** Line 1 of every connection: the receiver's own peerToken (peer class) or childToken (self-sent class). */
+const AuthLineSchema = defineSchema(z.object({
+	type: z.literal("auth"),
+	token: z.string().regex(new RegExp(`^[0-9a-f]{${count(PEER_TOKEN_HEX_LENGTH)}}$`))
+}));
+const PrioritySchema = defineSchema(z.enum(["next", "later"]));
+const FileAttachmentSchema = defineSchema(z.object({
+	path: z.string().min(1),
+	file_name: z.string().min(1),
+	file_size: z.number().int().nonnegative(),
+	sha256: z.string().regex(new RegExp(`^[0-9a-f]{${count(64)}}$`)),
+	media_type: z.string().optional()
+}));
+/** A user-turn message. `"type": "user"` is load-bearing: any other value is silently dropped. */
+const UserFrameSchema = defineSchema(z.object({
+	msgV: z.number().int(),
+	msg_id: z.string().min(1),
+	type: z.literal("user"),
+	message: z.object({
+		role: z.literal("user"),
+		content: z.string()
+	}),
+	priority: PrioritySchema,
+	from: z.string().regex(new RegExp(`^[A-Za-z0-9%:_/.\\\\-]{1,${count(300)}}$`)),
+	/** When present, must match the receiver's sessionId or the frame is silently dropped. */
+	session_id: z.string().optional(),
+	file_attachments: z.array(FileAttachmentSchema).max(16).optional()
+}));
+const DropReasonSchema = defineSchema(z.enum([
+	"rate-limited",
+	"duplicate",
+	"hop-loop",
+	"hop-runaway",
+	"queue-full"
+]));
+const PeerMessageStatusSchema = defineSchema(z.object({
+	type: z.literal("control"),
+	action: z.literal("peer_message_status"),
+	status: z.enum([
+		"held",
+		"delivered",
+		"denied",
+		"expired",
+		"dropped"
+	]),
+	reason: z.string(),
+	from: z.string().regex(new RegExp(`^[A-Za-z0-9%:_/.\\\\-]{1,${count(300)}}$`)),
+	orig_msg_id: z.string().min(1),
+	status_detail: z.string().optional(),
+	drop_reason: DropReasonSchema.optional(),
+	dropped_msg_ids: z.array(z.string()).optional(),
+	msgV: z.number().int(),
+	msg_id: z.string().min(1)
+}));
+const NotifyWhenIdleSchema = defineSchema(z.object({
+	type: z.literal("control"),
+	action: z.literal("notify_when_idle"),
+	from: z.string().regex(new RegExp(`^[A-Za-z0-9%:_/.\\\\-]{1,${count(300)}}$`)),
+	from_mode: z.enum(["bypass", "prompting"]).optional(),
+	msgV: z.number().int(),
+	msg_id: z.string().min(1)
+}));
+const PeerIdleNoticeSchema = defineSchema(z.object({
+	type: z.literal("control"),
+	action: z.literal("peer_idle_notice"),
+	orig_msg_id: z.string().min(1),
+	state: z.enum(["idle", "exited"]),
+	finished_at: z.number(),
+	detail: z.string().optional(),
+	from: z.string().regex(new RegExp(`^[A-Za-z0-9%:_/.\\\\-]{1,${count(300)}}$`)),
+	from_mode: z.enum(["bypass", "prompting"]).optional(),
+	msgV: z.number().int(),
+	msg_id: z.string().min(1)
+}));
+const YieldArtifactRepliesSchema = defineSchema(z.object({
+	type: z.literal("control"),
+	action: z.literal("yield_artifact_replies"),
+	from: z.string().max(512),
+	msg_id: z.string().min(1).max(128),
+	session_id: z.string().max(512),
+	slugs: z.array(z.string().max(128)).max(16),
+	reason: z.enum(["resume", "claim"]).catch("claim"),
+	sent_at: z.number(),
+	claimed_at: z.number().optional(),
+	requester: z.object({
+		cwd: z.string().optional(),
+		tmux: z.string().optional()
+	}).optional(),
+	msgV: z.number().int()
+}));
+const ArtifactRepliesYieldedSchema = defineSchema(z.object({
+	type: z.literal("control"),
+	action: z.literal("artifact_replies_yielded"),
+	orig_msg_id: z.string().max(128),
+	yielded: z.string().optional(),
+	not_held: z.string().optional(),
+	refused: z.string().optional(),
+	msgV: z.number().int(),
+	msg_id: z.string().min(1),
+	from: z.string().optional()
+}));
+const UnyieldArtifactRepliesSchema = defineSchema(z.object({
+	type: z.literal("control"),
+	action: z.literal("unyield_artifact_replies"),
+	orig_msg_id: z.string().max(128),
+	slugs: z.array(z.string().max(128)).max(16),
+	stopped: z.boolean().optional(),
+	msgV: z.number().int(),
+	msg_id: z.string().min(1),
+	from: z.string().optional()
+}));
+const ControlFrameSchema = z.union([
+	PeerMessageStatusSchema,
+	NotifyWhenIdleSchema,
+	PeerIdleNoticeSchema,
+	YieldArtifactRepliesSchema,
+	ArtifactRepliesYieldedSchema,
+	UnyieldArtifactRepliesSchema
+]);
+const WireFrameSchema = z.union([UserFrameSchema, ControlFrameSchema]);
+//#endregion
+//#region src/errors.ts
+/** Base error for every cc-peer failure; `code` is machine-readable. */
+var CcPeerError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "CcPeerError";
+	}
+};
+var NoLiveInboxError = class extends CcPeerError {
+	constructor(message) {
+		super("NO_LIVE_INBOX", message);
+		this.name = "NoLiveInboxError";
+	}
+};
+var UnknownPeerError = class extends CcPeerError {
+	constructor(message) {
+		super("UNKNOWN_PEER", message);
+		this.name = "UnknownPeerError";
+	}
+};
+var MessageTooLargeError = class extends CcPeerError {
+	constructor(message) {
+		super("MESSAGE_TOO_LARGE", message);
+		this.name = "MessageTooLargeError";
+	}
+};
+var NotStartedError = class extends CcPeerError {
+	constructor(message) {
+		super("NOT_STARTED", message);
+		this.name = "NotStartedError";
+	}
+};
+//#endregion
+//#region src/cc-peer.ts
+/** Package version placeholder until semantic-release owns it. */
+const CC_PEER_VERSION = "0.0.0";
+/** Default log sink: logs go nowhere unless a logger is provided. */
+const sinkLog = () => void 0;
+/** Peer tokens are 16 random bytes in hex, matching the reference key files. */
+const PEER_TOKEN_BYTES = 16;
+/** Byte cap on the serialized frame line, mirroring the receiver's line guard. */
+const MAX_FRAME_CHARS = 12e4;
+const DEFAULT_HEARTBEAT_MS = 15e3;
+/**
+* A registered peer on Claude Code's cross-session mesh. Receipts and idle notices only reach the process that owns the listening socket (the protocol verifies return addresses via kernel peer pids), so do not split sending and listening across differently-owned processes.
+*/
+var CcPeer = class CcPeer extends EventEmitter {
+	options;
+	deps;
+	listening;
+	heartbeatTimer;
+	ownKey;
+	pacer;
+	log;
+	stopped = false;
+	constructor(options, deps) {
+		super();
+		this.options = options;
+		this.deps = deps;
+		this.pacer = new Pacer(deps.clock);
+		this.log = options.logger ?? sinkLog;
+	}
+	static async create(options = {}) {
+		const peer = new CcPeer(options, {
+			transport: new UdsTransport(),
+			registry: new FsRegistryStore(options),
+			keys: new FsKeyStore(options),
+			procInfo: new PsProcInfo(),
+			clock: new SystemClock()
+		});
+		await peer.start();
+		return peer;
+	}
+	async start() {
+		const socketPath = socketPathForPid(process.pid, this.options);
+		this.ownKey = {
+			peerToken: randomBytes(PEER_TOKEN_BYTES).toString("hex"),
+			procStart: await this.deps.procInfo.lstart(process.pid) ?? "",
+			pidDomain: "darwin"
+		};
+		if (this.ownKey.procStart === "") throw new NotStartedError("could not read own procStart via ps");
+		await this.deps.keys.writeForSocket(socketPath, this.ownKey);
+		await mkdir(dirname(socketPath), {
+			recursive: true,
+			mode: 448
+		});
+		const entry = this.buildRegistryEntry();
+		await this.deps.registry.write(entry);
+		this.listening = await this.deps.transport.listen(socketPath, (conn) => {
+			this.handleConnection(conn);
+		});
+		this.heartbeatTimer = setInterval(() => {
+			this.deps.registry.touch(process.pid).catch(() => void 0);
+		}, this.options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
+		this.heartbeatTimer.unref();
+		this.log(`listening as ${this.options.name ?? "unnamed"} at ${socketPath}`);
+	}
+	buildRegistryEntry() {
+		const now = this.deps.clock.nowMs();
+		return {
+			pid: process.pid,
+			sessionId: this.options.sessionId ?? newMsgId(),
+			cwd: process.cwd(),
+			startedAt: now,
+			procStart: this.ownKey?.procStart ?? "",
+			version: "cc-peer",
+			peerProtocol: 1,
+			peerFeatures: ["notify_idle", "reply_across_default_dirs"],
+			kind: "interactive",
+			entrypoint: "cli",
+			pidDomain: "darwin",
+			messagingSocketPath: socketPathForPid(process.pid, this.options),
+			...this.options.name !== void 0 ? {
+				name: this.options.name,
+				nameSource: "user",
+				nameSince: now
+			} : {},
+			updatedAt: now,
+			status: "idle",
+			statusUpdatedAt: now
+		};
+	}
+	async roster() {
+		return filterRoster(await this.deps.registry.list(), {
+			transport: this.deps.transport,
+			procInfo: this.deps.procInfo,
+			...this.listening !== void 0 ? { ownSocketPath: this.listening.socketPath } : {}
+		});
+	}
+	async send(target, body, options = {}) {
+		if (this.stopped || this.listening === void 0 || this.ownKey === void 0) throw new NotStartedError("peer is not running");
+		const socketPath = await this.resolveTarget(target);
+		const key = await this.deps.keys.readForSocket(socketPath);
+		const msgId = newMsgId();
+		const from = `uds:${this.listening.socketPath}`;
+		const frame = {
+			msgV: 1,
+			msg_id: msgId,
+			type: "user",
+			message: {
+				role: "user",
+				content: buildEnvelope({
+					from,
+					...(options.sessionId ?? this.options.sessionId) !== void 0 ? { fromSession: options.sessionId ?? this.options.sessionId } : {},
+					...this.options.name !== void 0 ? { fromName: this.options.name } : {},
+					...options.fromMode !== false && options.fromMode !== void 0 ? { fromMode: options.fromMode } : {},
+					...options.fromMode === void 0 ? { fromMode: "bypass" } : {}
+				}, body)
+			},
+			priority: options.priority ?? "next",
+			from
+		};
+		if (key === void 0) throw new NoLiveInboxError(`no auth key published for ${socketPath}`);
+		const auth = AuthLineSchema.parse({
+			type: "auth",
+			token: key.peerToken
+		});
+		const line = JSON.stringify(frame);
+		if (line.length > MAX_FRAME_CHARS) throw new MessageTooLargeError(`serialized frame is ${line.length.toString()} chars, cap ${MAX_FRAME_CHARS.toString()}`);
+		await this.pacedSend(socketPath, [JSON.stringify(auth), line]);
+		return { msgId };
+	}
+	async pacedSend(socketPath, lines) {
+		const waitMs = this.pacer.msUntilNextToken();
+		if (waitMs > 0) await new Promise((resolve) => {
+			setTimeout(() => {
+				resolve();
+			}, waitMs).unref();
+		});
+		if (!this.pacer.tryReserve()) {
+			await this.pacedSend(socketPath, lines);
+			return;
+		}
+		await this.deps.transport.connectWrite(socketPath, lines);
+	}
+	async subscribeIdle(target) {
+		if (this.stopped || this.listening === void 0 || this.ownKey === void 0) throw new NotStartedError("peer is not running");
+		const socketPath = await this.resolveTarget(target);
+		const key = await this.deps.keys.readForSocket(socketPath);
+		if (key === void 0) throw new NoLiveInboxError(`no auth key published for ${socketPath}`);
+		const msgId = newMsgId();
+		const frame = {
+			msgV: 1,
+			msg_id: msgId,
+			type: "control",
+			action: "notify_when_idle",
+			from: `uds:${this.listening.socketPath}`,
+			from_mode: "bypass"
+		};
+		const auth = AuthLineSchema.parse({
+			type: "auth",
+			token: key.peerToken
+		});
+		await this.deps.transport.connectWrite(socketPath, [JSON.stringify(auth), JSON.stringify(frame)]);
+		return { msgId };
+	}
+	async resolveTarget(target) {
+		if ("pid" in target) return socketPathForPid(target.pid, this.options);
+		if ("address" in target) return target.address.replace(/^uds:/, "");
+		const match = (await this.roster()).find((entry) => entry.name === target.name);
+		if (match === void 0) throw new UnknownPeerError(`no roster entry named ${target.name}`);
+		return match.messagingSocketPath;
+	}
+	async handleConnection(conn) {
+		const lines = conn.readLines();
+		const first = await lines[Symbol.asyncIterator]().next();
+		if (first.done === true) return;
+		if (this.ownKey !== void 0) {
+			const parsed = JSON.parse(first.value);
+			if (AuthLineSchema.is(parsed) && parsed.token !== this.ownKey.peerToken) this.log("inbound auth token mismatch (foreign token tolerated)");
+		}
+		for await (const line of lines) {
+			let frame;
+			try {
+				frame = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			if (!WireFrameSchema.safeParse(frame).success) continue;
+			if (UserFrameSchema.is(frame)) {
+				const envelope = parseEnvelope(frame.message.content);
+				this.emit("message", {
+					...envelope?.from !== void 0 ? { from: envelope.from } : {},
+					...envelope?.fromSession !== void 0 ? { fromSession: envelope.fromSession } : {},
+					...envelope?.fromName !== void 0 ? { fromName: envelope.fromName } : {},
+					...envelope?.fromMode !== void 0 ? { fromMode: envelope.fromMode } : {},
+					...envelope?.hopChain !== void 0 ? { hopChain: envelope.hopChain } : {},
+					body: envelope?.body ?? frame.message.content,
+					msgId: frame.msg_id
+				});
+			} else if (PeerMessageStatusSchema.is(frame)) this.emit("receipt", frame);
+			else if (PeerIdleNoticeSchema.is(frame)) this.emit("idle", frame);
+		}
+	}
+	async stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		if (this.heartbeatTimer !== void 0) clearInterval(this.heartbeatTimer);
+		if (this.listening !== void 0) {
+			const socketPath = this.listening.socketPath;
+			await this.listening.close();
+			await this.deps.keys.removeForSocket(socketPath);
+			await this.deps.registry.remove(process.pid);
+		}
+	}
+};
+//#endregion
+export { defineSchema as a, RegistryEntrySchema as i, CcPeer as n, PrioritySchema as r, CC_PEER_VERSION as t };