@oh-my-pi/pi-coding-agent 17.2.4 → 17.2.6

package/src/launch/broker.ts

@@ -15,14 +15,17 @@ import {
 	DAEMON_PTY_COLUMNS,
 	DAEMON_PTY_ROWS,
 	DAEMON_RUNTIME_DIR_ENV,
+	type DaemonCompletionNotification,
 	type DaemonOperation,
 	type DaemonReadySpec,
 	type DaemonRpcResult,
 	type DaemonSignal,
 	type DaemonSnapshot,
 	type DaemonSpec,
+	type DaemonWireRequest,
 	parseDaemonSnapshot,
 	parseDaemonSpec,
+	parseDaemonWireMessage,
 	parseDaemonWireRequest,
 } from "./protocol";
 import { resolveDaemonSpawnOptions } from "./spawn-options";
@@ -81,6 +84,9 @@ interface ManagedDaemon {
 	readyPattern?: RegExp;
 	restartTimer?: NodeJS.Timeout;
 	consecutiveFailures: number;
+	completionCapable: boolean;
+	pendingCompletions: DaemonCompletionNotification[];
+	completionSubscriptionId?: string;
 	persistQueue: Promise<void>;
 }
 
@@ -107,6 +113,10 @@ function settledState(state: DaemonSnapshot["state"]): boolean {
 	return terminalState(state) || state === "restarting";
 }
 
+function publishesCompletionOwners(request: DaemonWireRequest): boolean {
+	return request.completionEvents === true && (request.completionAcks?.length ?? 0) === 0;
+}
+
 /**
  * Order daemons for the `list` response: non-terminal (active) daemons first,
  * oldest to newest, so the process the user is acting on is immediately visible
@@ -352,6 +362,9 @@ class DaemonBroker {
 	 */
 	readonly #startingNames = new Set<string>();
 	readonly #clients = new Set<net.Socket>();
+	readonly #ownerSockets = new Map<string, { socket: net.Socket; subscriptionId: string | undefined }>();
+	readonly #completionSubscriptions = new Map<string, string | undefined>();
+	readonly #pendingCompletions = new Map<string, Map<string, DaemonCompletionNotification>>();
 	readonly #finished = Promise.withResolvers<void>();
 	readonly #sockets = new Set<net.Socket>();
 	#server: net.Server | undefined;
@@ -393,6 +406,7 @@ class DaemonBroker {
 			await record.log?.close();
 			await record.persistQueue;
 		}
+		this.#ownerSockets.clear();
 		for (const socket of this.#sockets) socket.destroy();
 		this.#sockets.clear();
 		this.#clients.clear();
@@ -439,6 +453,9 @@ class DaemonBroker {
 			if (!authenticated) return;
 			this.#clients.delete(socket);
 			this.#scheduleIdleShutdown();
+			for (const [owner, registration] of this.#ownerSockets) {
+				if (registration.socket === socket) this.#ownerSockets.delete(owner);
+			}
 		});
 	}
 
@@ -450,6 +467,78 @@ class DaemonBroker {
 			id = request.id;
 			if (request.token !== this.#token) throw new Error("Daemon broker authentication failed");
 			onAuthenticated();
+			for (const owner of request.completionUnsubscribes ?? []) {
+				const subscriptionId = this.#completionSubscriptions.get(owner);
+				if (
+					!this.#completionSubscriptions.has(owner) ||
+					(subscriptionId !== undefined && subscriptionId !== request.completionSubscriptionId)
+				) {
+					continue;
+				}
+				this.#ownerSockets.delete(owner);
+				this.#completionSubscriptions.delete(owner);
+				await this.#setRecordCompletionCapability(owner, false);
+				this.#pendingCompletions.delete(owner);
+			}
+			for (const completionId of request.completionAcks ?? []) {
+				for (const [owner, pending] of this.#pendingCompletions) {
+					const registration = this.#ownerSockets.get(owner);
+					if (
+						!registration ||
+						registration.socket !== socket ||
+						registration.subscriptionId !== request.completionSubscriptionId
+					) {
+						continue;
+					}
+					const completion = pending.get(completionId);
+					if (!completion) continue;
+					pending.delete(completionId);
+					if (pending.size === 0) this.#pendingCompletions.delete(owner);
+					const record = this.#records.get(completion.daemon.name);
+					const index = record?.pendingCompletions.findIndex(item => item.completionId === completionId) ?? -1;
+					if (record && index >= 0) {
+						record.pendingCompletions.splice(index, 1);
+						this.#persist(record);
+						await record.persistQueue;
+					}
+				}
+			}
+			if (publishesCompletionOwners(request)) {
+				const replayOwners = new Set(request.completionReplays ?? []);
+				const activeOwners = new Set(request.owners ?? []);
+				const detachedOwners = new Set(request.detachedOwners ?? []);
+				const advertisedOwners = new Set([...activeOwners, ...detachedOwners]);
+				for (const [owner, subscriptionId] of this.#completionSubscriptions) {
+					if (subscriptionId !== request.completionSubscriptionId || advertisedOwners.has(owner)) continue;
+					this.#ownerSockets.delete(owner);
+					this.#completionSubscriptions.delete(owner);
+					await this.#setRecordCompletionCapability(owner, false);
+					this.#pendingCompletions.delete(owner);
+				}
+				for (const owner of activeOwners) {
+					this.#completionSubscriptions.set(owner, request.completionSubscriptionId);
+					await this.#setRecordCompletionCapability(owner, true);
+					const previous = this.#ownerSockets.get(owner);
+					this.#ownerSockets.set(owner, {
+						socket,
+						subscriptionId: request.completionSubscriptionId,
+					});
+					if (previous?.socket === socket && !replayOwners.has(owner)) continue;
+					for (const completion of this.#pendingCompletions.get(owner)?.values() ?? []) {
+						socket.write(`${JSON.stringify(completion)}\n`);
+					}
+				}
+				for (const owner of detachedOwners) {
+					const subscriptionId = this.#completionSubscriptions.get(owner);
+					if (this.#completionSubscriptions.has(owner) && subscriptionId !== request.completionSubscriptionId) {
+						continue;
+					}
+					this.#completionSubscriptions.set(owner, request.completionSubscriptionId);
+					await this.#setRecordCompletionCapability(owner, true);
+					const registration = this.#ownerSockets.get(owner);
+					if (registration?.subscriptionId === request.completionSubscriptionId) this.#ownerSockets.delete(owner);
+				}
+			}
 			const result = await this.#dispatch(request.operation);
 			socket.write(`${JSON.stringify({ id, ok: true, result })}\n`);
 			if (request.operation.op === "shutdown") setTimeout(() => void this.shutdown(), 10);
@@ -520,6 +609,9 @@ class DaemonBroker {
 			if (existing && !terminalState(existing.snapshot.state)) {
 				throw new Error(`Daemon ${spec.name} is already ${existing.snapshot.state}`);
 			}
+			if (existing && existing.pendingCompletions.length > 0) {
+				throw new Error(`Daemon ${spec.name} has unacknowledged completion notifications`);
+			}
 			if (spec.ready?.log) {
 				try {
 					new RegExp(spec.ready.log, "u");
@@ -556,6 +648,9 @@ class DaemonBroker {
 				readyPattern: spec.ready?.log ? new RegExp(spec.ready.log, "u") : undefined,
 				consecutiveFailures: 0,
 				persistQueue: Promise.resolve(),
+				completionCapable: owner !== undefined && this.#completionSubscriptions.has(owner),
+				completionSubscriptionId: owner === undefined ? undefined : this.#completionSubscriptions.get(owner),
+				pendingCompletions: [],
 			};
 			syncReadyPending(record);
 			this.#records.set(spec.name, record);
@@ -785,6 +880,14 @@ class DaemonBroker {
 		await this.#settle(record, generation);
 	}
 
+	async #monitorRecoveredDetached(record: ManagedDaemon, generation: number): Promise<void> {
+		while (!this.#shuttingDown && generation === record.generation && !settledState(record.snapshot.state)) {
+			await Bun.sleep(100);
+			if (this.#shuttingDown || generation !== record.generation) return;
+			await this.#refreshDetached(record);
+		}
+	}
+
 	async #pollPort(record: ManagedDaemon, generation: number, ready: DaemonReadySpec): Promise<void> {
 		const host = ready.host ?? "127.0.0.1";
 		const port = ready.port;
@@ -812,6 +915,15 @@ class DaemonBroker {
 		return this.#settle(record, generation, result.exitCode, result.timedOut ? "timed out" : undefined);
 	}
 
+	#notifyCompletion(completion: DaemonCompletionNotification): void {
+		const pending = this.#pendingCompletions.get(completion.owner) ?? new Map<string, DaemonCompletionNotification>();
+		pending.set(completion.completionId, completion);
+		this.#pendingCompletions.set(completion.owner, pending);
+		const registration = this.#ownerSockets.get(completion.owner);
+		if (!registration || registration.socket.destroyed) return;
+		registration.socket.write(`${JSON.stringify(completion)}\n`);
+	}
+
 	async #settle(record: ManagedDaemon, generation: number, exitCode?: number, error?: string): Promise<void> {
 		// `restarting` is a settled state (child exited, relaunch timer armed). Any op that
 		// runs #refreshDetached on such a record must not re-settle it: re-entry double-counts
@@ -855,9 +967,29 @@ class DaemonBroker {
 			return;
 		}
 		record.snapshot.state = failed && !record.stopRequested ? "failed" : "exited";
+		const completion =
+			record.snapshot.owner !== undefined &&
+			!record.stopRequested &&
+			this.#completionSubscriptions.has(record.snapshot.owner)
+				? ({
+						event: "daemon-completed",
+						completionId: crypto.randomUUID(),
+						owner: record.snapshot.owner,
+						daemon: { ...record.snapshot },
+					} satisfies DaemonCompletionNotification)
+				: undefined;
+		if (completion) record.pendingCompletions.push(completion);
 		this.#persist(record);
 		await record.log?.close();
 		record.log = undefined;
+		await record.persistQueue;
+		if (
+			completion &&
+			this.#completionSubscriptions.has(completion.owner) &&
+			record.pendingCompletions.some(pending => pending.completionId === completion.completionId)
+		) {
+			this.#notifyCompletion(completion);
+		}
 	}
 
 	async #logs(operation: Extract<DaemonOperation, { op: "logs" }>): Promise<DaemonRpcResult> {
@@ -1027,9 +1159,21 @@ class DaemonBroker {
 	#persist(record: ManagedDaemon): void {
 		const metaPath = path.join(record.dir, META_FILE);
 		const tempPath = `${metaPath}.${process.pid}.tmp`;
+		const metadata = {
+			daemon: { ...record.snapshot },
+			spec: record.spec,
+			completionEvents: record.completionCapable,
+			completionSubscriptionId: record.completionSubscriptionId,
+			completionPending: record.pendingCompletions.length > 0,
+			pendingCompletion: record.pendingCompletions.at(-1)?.daemon,
+			pendingCompletions: record.pendingCompletions.map(completion => ({
+				...completion,
+				daemon: { ...completion.daemon },
+			})),
+		};
 		record.persistQueue = record.persistQueue
 			.then(async () => {
-				await Bun.write(tempPath, JSON.stringify({ daemon: record.snapshot, spec: record.spec }));
+				await Bun.write(tempPath, JSON.stringify(metadata));
 				await fs.rename(tempPath, metaPath);
 			})
 			.catch(error => {
@@ -1040,6 +1184,28 @@ class DaemonBroker {
 			});
 	}
 
+	async #setRecordCompletionCapability(owner: string, capable: boolean): Promise<void> {
+		const subscriptionId = capable ? this.#completionSubscriptions.get(owner) : undefined;
+		const persistence: Promise<void>[] = [];
+		for (const record of this.#records.values()) {
+			const clearPendingCompletions = !capable && record.pendingCompletions.length > 0;
+			if (
+				record.snapshot.owner !== owner ||
+				(record.completionCapable === capable &&
+					record.completionSubscriptionId === subscriptionId &&
+					!clearPendingCompletions)
+			) {
+				continue;
+			}
+			record.completionCapable = capable;
+			record.completionSubscriptionId = subscriptionId;
+			if (!capable) record.pendingCompletions = [];
+			this.#persist(record);
+			persistence.push(record.persistQueue);
+		}
+		await Promise.all(persistence);
+	}
+
 	async #recoverRecords(): Promise<void> {
 		const root = path.join(this.#runtimeDir, "daemons");
 		const entries = await fs.readdir(root, { withFileTypes: true }).catch(error => {
@@ -1057,11 +1223,9 @@ class DaemonBroker {
 				const snapshot = parseDaemonSnapshot(decoded.daemon);
 				const spec = parseDaemonSpec(decoded.spec);
 				const processRef = snapshot.pid === undefined ? null : Process.fromPid(snapshot.pid);
-				const detached =
-					spec.detached &&
-					!terminalState(snapshot.state) &&
-					snapshot.state !== "stopping" &&
-					processRef?.status() === "running";
+				const recoverableExit = !terminalState(snapshot.state) && snapshot.state !== "stopping";
+				const detached = spec.detached && recoverableExit && processRef?.status() === "running";
+				const recoveredDead = recoverableExit && !detached;
 				if (!detached) {
 					// Reap only records that were still alive when the previous broker
 					// exited; already-terminal records keep their real exit time so
@@ -1088,12 +1252,64 @@ class DaemonBroker {
 					readyPattern: spec.ready?.log ? new RegExp(spec.ready.log, "u") : undefined,
 					consecutiveFailures: 0,
 					persistQueue: Promise.resolve(),
+					completionCapable: "completionEvents" in decoded && decoded.completionEvents === true,
+					completionSubscriptionId:
+						"completionSubscriptionId" in decoded && typeof decoded.completionSubscriptionId === "string"
+							? decoded.completionSubscriptionId
+							: undefined,
+					pendingCompletions: (() => {
+						if ("pendingCompletions" in decoded && Array.isArray(decoded.pendingCompletions)) {
+							return decoded.pendingCompletions.map(value => {
+								const message = parseDaemonWireMessage(value);
+								if (!("event" in message)) throw new Error("Pending daemon completion is not an event");
+								return message;
+							});
+						}
+						const pendingSnapshot =
+							"pendingCompletion" in decoded
+								? parseDaemonSnapshot(decoded.pendingCompletion)
+								: "completionPending" in decoded && decoded.completionPending === true
+									? { ...snapshot }
+									: undefined;
+						return pendingSnapshot
+							? [
+									{
+										event: "daemon-completed",
+										completionId: crypto.randomUUID(),
+										owner: pendingSnapshot.owner ?? snapshot.owner ?? "",
+										daemon: pendingSnapshot,
+									},
+								]
+							: [];
+					})(),
 				};
+				if (recoveredDead && record.completionCapable && snapshot.owner && record.pendingCompletions.length === 0) {
+					record.pendingCompletions.push({
+						event: "daemon-completed",
+						completionId: crypto.randomUUID(),
+						owner: snapshot.owner,
+						daemon: { ...snapshot },
+					});
+				}
 				syncReadyPending(record);
 				this.#records.set(snapshot.name, record);
+				if (snapshot.owner && record.completionCapable && (detached || record.pendingCompletions.length > 0)) {
+					this.#completionSubscriptions.set(snapshot.owner, record.completionSubscriptionId);
+				}
+				if (record.completionCapable) {
+					for (const completion of record.pendingCompletions) this.#notifyCompletion(completion);
+				}
 				if (detached && spec.ready?.port !== undefined && snapshot.state !== "ready") {
 					void this.#pollPort(record, record.generation, spec.ready);
 				}
+				if (detached) {
+					void this.#monitorRecoveredDetached(record, record.generation).catch(error => {
+						logger.warn("Failed to monitor recovered detached daemon", {
+							name: record.snapshot.name,
+							error: error instanceof Error ? error.message : String(error),
+						});
+					});
+				}
 				this.#persist(record);
 			} catch (error) {
 				logger.warn("Failed to recover daemon record", {
@@ -1124,7 +1340,7 @@ class DaemonBroker {
 	}
 }
 
-/** Start the detached per-project daemon broker selected by the CLI worker host. */
+/** Start the detached project or global daemon broker selected by the CLI worker host. */
 export async function startDaemonBrokerFromEnvironment(): Promise<void> {
 	const projectDir = process.env[DAEMON_PROJECT_DIR_ENV];
 	const runtimeDir = process.env[DAEMON_RUNTIME_DIR_ENV];

package/src/launch/client.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs/promises";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
-import { isEexist, isEisdir, isEnoent, postmortem } from "@oh-my-pi/pi-utils";
+import { getGlobalDaemonRuntimeDir, isEexist, isEisdir, isEnoent, logger, postmortem } from "@oh-my-pi/pi-utils";
 import { hostHasInheritableConsole } from "../eval/py/spawn-options";
 import { resolveWorkerSpawnCmd, workerEnvFromParent } from "../subprocess/worker-client";
 import { daemonBrokerEndpoint, daemonRuntimeDir } from "./paths";
@@ -11,11 +11,12 @@ import {
 	DAEMON_IDLE_GRACE_ENV,
 	DAEMON_PROJECT_DIR_ENV,
 	DAEMON_RUNTIME_DIR_ENV,
+	type DaemonCompletionNotification,
 	type DaemonOperation,
 	type DaemonRpcResult,
-	type DaemonWireResponse,
+	type DaemonWireMessage,
 	parseDaemonRpcResult,
-	parseDaemonWireResponse,
+	parseDaemonWireMessage,
 } from "./protocol";
 import { resolveDaemonSpawnOptions } from "./spawn-options";
 
@@ -43,13 +44,26 @@ export interface DaemonBrokerClientOptions {
 	idleGraceMs?: number;
 }
 
-/** Persistent per-process connection to one project's daemon broker. */
+export interface DaemonCompletionUnregisterOptions {
+	/** Detach this process without deleting broker-persisted pending notifications. */
+	preservePending?: boolean;
+}
+
+/** Persistent per-process connection to one project or global daemon broker. */
 export interface DaemonBrokerClient {
+	onCompletion(
+		owner: string,
+		sink: (notification: DaemonCompletionNotification) => Promise<void> | void,
+	): (options?: DaemonCompletionUnregisterOptions) => void;
+	/** Canonical project directory or synthetic directory identifying a global scope. */
 	readonly projectDir: string;
 	request(operation: DaemonOperation, signal?: AbortSignal): Promise<DaemonRpcResult>;
 	close(): void;
 }
 
+/** A request reached the broker and the broker rejected the operation. */
+export class DaemonBrokerRejectedError extends Error {}
+
 async function canonicalProjectDir(projectDir: string): Promise<string> {
 	const resolved = path.resolve(projectDir);
 	try {
@@ -133,12 +147,20 @@ class SocketDaemonClient implements DaemonBrokerClient {
 	readonly #runtimeDir: string;
 	readonly #endpoint: string;
 	readonly #token: string;
+	readonly #seenCompletionIds = new Set<string>();
 	readonly #idleGraceMs: number | undefined;
 	readonly #pending = new Map<string, PendingRequest>();
+	readonly #completionSinks = new Map<string, (notification: DaemonCompletionNotification) => Promise<void> | void>();
+	readonly #completionUnsubscribes = new Set<string>();
+	readonly #preservedCompletionOwners = new Set<string>();
+	readonly #completionReplays = new Set<string>();
+	readonly #inFlightCompletionIds = new Set<string>();
+	readonly #completionSubscriptionId = crypto.randomUUID();
 	#socket: net.Socket | undefined;
 	#connectPromise: Promise<void> | undefined;
 	#buffer = "";
 	#closed = false;
+	#completionReconnectTimer: NodeJS.Timeout | undefined;
 
 	constructor(projectDir: string, runtimeDir: string, token: string, options: DaemonBrokerClientOptions) {
 		this.projectDir = projectDir;
@@ -155,6 +177,8 @@ class SocketDaemonClient implements DaemonBrokerClient {
 		const socket = this.#socket;
 		if (!socket || socket.destroyed) throw new Error("Daemon broker socket is unavailable");
 
+		const completionUnsubscribes = [...this.#completionUnsubscribes];
+		const completionReplays = [...this.#completionReplays];
 		const id = crypto.randomUUID();
 		const { promise, resolve, reject } = Promise.withResolvers<DaemonRpcResult>();
 		const timer = setTimeout(() => {
@@ -175,18 +199,88 @@ class SocketDaemonClient implements DaemonBrokerClient {
 			pending.removeAbort = () => signal.removeEventListener("abort", abort);
 		}
 		this.#pending.set(id, pending);
-		socket.write(`${JSON.stringify({ id, token: this.#token, operation })}\n`);
-		return promise;
+		socket.write(
+			`${JSON.stringify({
+				id,
+				token: this.#token,
+				owners: [...this.#completionSinks.keys()],
+				detachedOwners: [...this.#preservedCompletionOwners],
+				completionEvents: true,
+				completionUnsubscribes,
+				completionReplays,
+				completionSubscriptionId: this.#completionSubscriptionId,
+				operation,
+			})}\n`,
+		);
+		const result = await promise;
+		for (const owner of completionUnsubscribes) {
+			if (!this.#completionSinks.has(owner)) this.#completionUnsubscribes.delete(owner);
+		}
+		for (const owner of completionReplays) {
+			if (this.#completionSinks.has(owner)) this.#completionReplays.delete(owner);
+		}
+		return result;
 	}
 
 	close(): void {
 		if (this.#closed) return;
 		this.#closed = true;
+		clearTimeout(this.#completionReconnectTimer);
+		this.#completionReconnectTimer = undefined;
 		this.#socket?.destroy();
+		this.#completionSinks.clear();
+		this.#preservedCompletionOwners.clear();
+		this.#completionReplays.clear();
 		this.#socket = undefined;
 		this.#rejectPending(new Error("Daemon broker client closed"));
 	}
 
+	onCompletion(
+		owner: string,
+		sink: (notification: DaemonCompletionNotification) => Promise<void> | void,
+	): (options?: DaemonCompletionUnregisterOptions) => void {
+		this.#completionUnsubscribes.delete(owner);
+		if (this.#preservedCompletionOwners.delete(owner)) this.#completionReplays.add(owner);
+		this.#completionSinks.set(owner, sink);
+		this.#publishCompletionOwners();
+		return options => {
+			if (this.#completionSinks.get(owner) !== sink) return;
+			this.#completionSinks.delete(owner);
+			if (options?.preservePending) {
+				this.#preservedCompletionOwners.add(owner);
+			} else {
+				this.#preservedCompletionOwners.delete(owner);
+				this.#completionUnsubscribes.add(owner);
+			}
+			if (this.#completionSinks.size === 0 && this.#completionReconnectTimer) {
+				clearTimeout(this.#completionReconnectTimer);
+				this.#completionReconnectTimer = undefined;
+			}
+			this.#publishCompletionOwners();
+		};
+	}
+
+	#publishCompletionOwners(): void {
+		if (this.#closed) return;
+		void this.request({ op: "ping" }).catch(() => this.#scheduleCompletionReconnect());
+	}
+
+	#scheduleCompletionReconnect(): void {
+		if (
+			this.#closed ||
+			this.#completionSinks.size === 0 ||
+			this.#completionReconnectTimer !== undefined ||
+			(this.#socket !== undefined && !this.#socket.destroyed)
+		) {
+			return;
+		}
+		this.#completionReconnectTimer = setTimeout(() => {
+			this.#completionReconnectTimer = undefined;
+			this.#publishCompletionOwners();
+		}, CONNECT_RETRY_MS);
+		this.#completionReconnectTimer.unref();
+	}
+
 	async #connect(): Promise<void> {
 		if (this.#socket && !this.#socket.destroyed) return;
 		if (this.#connectPromise) return this.#connectPromise;
@@ -250,6 +344,7 @@ class SocketDaemonClient implements DaemonBrokerClient {
 		socket.on("close", () => {
 			if (this.#socket === socket) this.#socket = undefined;
 			this.#rejectPending(new Error("Daemon broker connection closed"));
+			this.#scheduleCompletionReconnect();
 		});
 	}
 
@@ -261,21 +356,32 @@ class SocketDaemonClient implements DaemonBrokerClient {
 			const line = this.#buffer.slice(0, newline);
 			this.#buffer = this.#buffer.slice(newline + 1);
 			if (line.length === 0) continue;
-			let response: DaemonWireResponse;
+			let decoded: unknown;
 			try {
-				const decoded: unknown = JSON.parse(line);
-				response = parseDaemonWireResponse(decoded);
+				decoded = JSON.parse(line);
 			} catch (error) {
 				this.#rejectPending(error instanceof Error ? error : new Error(String(error)));
 				continue;
 			}
+			let message: DaemonWireMessage;
+			try {
+				message = parseDaemonWireMessage(decoded);
+			} catch (error) {
+				this.#rejectPending(error instanceof Error ? error : new Error(String(error)));
+				continue;
+			}
+			if ("event" in message) {
+				void this.#deliverCompletion(message);
+				continue;
+			}
+			const response = message;
 			const pending = this.#pending.get(response.id);
 			if (!pending) continue;
 			this.#pending.delete(response.id);
 			clearTimeout(pending.timer);
 			pending.removeAbort?.();
 			if (!response.ok) {
-				pending.reject(new Error(response.error));
+				pending.reject(new DaemonBrokerRejectedError(response.error));
 				continue;
 			}
 			try {
@@ -286,6 +392,53 @@ class SocketDaemonClient implements DaemonBrokerClient {
 		}
 	}
 
+	async #deliverCompletion(message: DaemonCompletionNotification): Promise<void> {
+		if (this.#seenCompletionIds.has(message.completionId)) {
+			this.#ackCompletion(message.completionId);
+			return;
+		}
+		if (this.#inFlightCompletionIds.has(message.completionId)) return;
+		const sink = this.#completionSinks.get(message.owner);
+		if (!sink) return;
+		this.#inFlightCompletionIds.add(message.completionId);
+		try {
+			await sink(message);
+			if (this.#seenCompletionIds.size >= 512) {
+				const oldest = this.#seenCompletionIds.values().next().value;
+				if (oldest !== undefined) this.#seenCompletionIds.delete(oldest);
+			}
+			this.#seenCompletionIds.add(message.completionId);
+			this.#ackCompletion(message.completionId);
+		} catch (error) {
+			logger.warn("Daemon completion sink failed", {
+				owner: message.owner,
+				completionId: message.completionId,
+				error: error instanceof Error ? error.message : String(error),
+			});
+			this.#socket?.destroy();
+		} finally {
+			this.#inFlightCompletionIds.delete(message.completionId);
+		}
+	}
+
+	#ackCompletion(completionId: string): void {
+		const socket = this.#socket;
+		if (!socket || socket.destroyed) return;
+		socket.write(
+			`${JSON.stringify({
+				id: crypto.randomUUID(),
+				token: this.#token,
+				owners: [...this.#completionSinks.keys()],
+				detachedOwners: [...this.#preservedCompletionOwners],
+				completionEvents: true,
+				completionAcks: [completionId],
+				completionUnsubscribes: [...this.#completionUnsubscribes],
+				completionSubscriptionId: this.#completionSubscriptionId,
+				operation: { op: "ping" },
+			})}\n`,
+		);
+	}
+
 	#rejectPending(error: Error): void {
 		for (const pending of this.#pending.values()) {
 			clearTimeout(pending.timer);
@@ -299,7 +452,19 @@ class SocketDaemonClient implements DaemonBrokerClient {
 const sharedClients = new Map<string, Promise<DaemonBrokerClient>>();
 let cancelExitCleanup: (() => void) | undefined;
 
-/** Create an independent socket connection to one project's shared daemon broker. */
+function sharedDaemonClient(key: string, create: () => Promise<DaemonBrokerClient>): Promise<DaemonBrokerClient> {
+	let pending = sharedClients.get(key);
+	if (!pending) {
+		pending = create();
+		sharedClients.set(key, pending);
+		if (!cancelExitCleanup) {
+			cancelExitCleanup = postmortem.register("daemon-broker-clients", () => closeDaemonClients());
+		}
+	}
+	return pending;
+}
+
+/** Create an independent socket connection to one daemon broker scope. */
 export async function createDaemonBrokerClient(
 	projectDir: string,
 	options: DaemonBrokerClientOptions = {},
@@ -313,18 +478,24 @@ export async function createDaemonBrokerClient(
 /** Get the process-shared daemon broker client for one canonical project directory. */
 export async function daemonClientForProject(projectDir: string): Promise<DaemonBrokerClient> {
 	const canonical = await canonicalProjectDir(projectDir);
-	let pending = sharedClients.get(canonical);
-	if (!pending) {
-		pending = createDaemonBrokerClient(canonical);
-		sharedClients.set(canonical, pending);
-		if (!cancelExitCleanup) {
-			cancelExitCleanup = postmortem.register("daemon-broker-clients", () => closeDaemonClients());
-		}
-	}
-	return pending;
+	return sharedDaemonClient(`project:${canonical}`, () => createDaemonBrokerClient(canonical));
+}
+
+/** Get the process-shared client that leases one profile-independent, machine-global daemon broker. */
+export async function daemonClientForGlobal(service: string): Promise<DaemonBrokerClient> {
+	const runtimeDir = getGlobalDaemonRuntimeDir(service);
+	// Canonicalize only after creation so the first caller and later callers
+	// derive the same Windows pipe key even when an ancestor is a symlink.
+	await fs.mkdir(runtimeDir, { recursive: true, mode: 0o700 });
+	const canonical = await fs.realpath(runtimeDir);
+	return sharedDaemonClient(`global:${canonical}`, () =>
+		createDaemonBrokerClient(canonical, {
+			runtimeDir: canonical,
+		}),
+	);
 }
 
-/** Close every project broker connection held by this omp process. */
+/** Close every project and machine-global broker connection held by this omp process. */
 export async function closeDaemonClients(): Promise<void> {
 	const pending = [...sharedClients.values()];
 	sharedClients.clear();