jeopi-cli 16.6.14 → 16.6.17

package/src/messenger/discord.ts

@@ -6,9 +6,10 @@ import type { MessengerAdapter, MessengerMessage, MessengerPlatformConfig, Messe
 // Protocol: https://docs.discord.com/developers/events/gateway
 // Close codes: https://docs.discord.com/developers/topics/opcodes-and-status-codes
 // REST messages: https://docs.discord.com/developers/resources/message#create-message
-const API = "https://discord.com/api/v10";
-const INTENTS = (1 << 9) | (1 << 12) | (1 << 15);
+export const DISCORD_API = "https://discord.com/api/v10";
+export const DISCORD_GATEWAY_INTENTS = (1 << 9) | (1 << 12) | (1 << 15);
 const PERMANENT_CLOSE_CODES = new Set([4004, 4010, 4011, 4012, 4013, 4014]);
+const MAX_CLASSIFICATION_PENDING = 100;
 
 // Discord strips boundary whitespace. Invisible guards preserve it in message content;
 // they are part of the delivered text, and consume one UTF-16 unit each.
@@ -82,7 +83,7 @@ interface DiscordSession {
 	sequence: number | null;
 }
 
-function gatewayUrl(value: unknown): string {
+export function discordGatewayUrl(value: unknown): string {
 	let url: URL;
 	try {
 		if (typeof value !== "string") throw new Error();
@@ -158,7 +159,7 @@ function connectGateway(
 	token: string,
 	accountId: string,
 	session: DiscordSession,
-	onMessage: (message: MessengerMessage) => Promise<void>,
+	onMessage: (message: MessengerMessage, raw: unknown) => Promise<void>,
 	signal: AbortSignal,
 	WebSocketImpl: typeof WebSocket,
 	clock: DiscordClock,
@@ -267,7 +268,7 @@ function connectGateway(
 			} else {
 				send(2, {
 					token,
-					intents: INTENTS,
+					intents: DISCORD_GATEWAY_INTENTS,
 					properties: { os: process.platform, browser: "jeopi", device: "jeopi" },
 				});
 			}
@@ -287,7 +288,7 @@ function connectGateway(
 					return;
 				}
 				try {
-					session.url = gatewayUrl(packet.d.resume_gateway_url);
+					session.url = discordGatewayUrl(packet.d.resume_gateway_url);
 				} catch {
 					finish(new DiscordConfigurationError("Discord returned an untrusted resume Gateway URL"));
 					return;
@@ -304,7 +305,7 @@ function connectGateway(
 					// The gateway owns authorization, deduplication and its bounded work queue.
 					void Promise.resolve()
 						.then(() => {
-							if (!signal.aborted) return onMessage(message);
+							if (!signal.aborted) return onMessage(message, packet.d);
 						})
 						.catch(() => logger.warn("Discord message handler failed"));
 				}
@@ -328,6 +329,9 @@ export function createDiscordAdapter(
 	const token = env[config.tokenEnv]?.trim();
 	const clock = deps.clock ?? defaultClock;
 	const createdThreads = new Map<string, { parentChannelId: string; senderId: string }>();
+	const classificationTails = new Map<string, Promise<void>>();
+	const messageClassifications = new Map<string, Promise<void>>();
+	const pendingClassifications = new Set<string>();
 	const rememberThread = (threadId: string, parentChannelId: string, senderId: string): void => {
 		createdThreads.set(threadId, { parentChannelId, senderId });
 		if (createdThreads.size > 10_000) {
@@ -351,7 +355,12 @@ export function createDiscordAdapter(
 				let retryDelay = delay;
 				try {
 					if (!accountId) {
-						const user = await messengerFetchJson(`${API}/users/@me`, { headers: headers() }, signal, deps.fetch);
+						const user = await messengerFetchJson(
+							`${DISCORD_API}/users/@me`,
+							{ headers: headers() },
+							signal,
+							deps.fetch,
+						);
 						if (signal.aborted) return;
 						if (!isRecord(user) || typeof user.id !== "string" || !user.id || user.bot !== true) {
 							throw new DiscordConfigurationError("Discord credentials must identify a bot account");
@@ -360,7 +369,7 @@ export function createDiscordAdapter(
 					}
 					if (!initialUrl) {
 						const gateway = await messengerFetchJson(
-							`${API}/gateway/bot`,
+							`${DISCORD_API}/gateway/bot`,
 							{ headers: headers() },
 							signal,
 							deps.fetch,
@@ -370,49 +379,159 @@ export function createDiscordAdapter(
 						if (isRecord(gateway.session_start_limit) && gateway.session_start_limit.remaining === 0) {
 							throw new DiscordConfigurationError("Discord Gateway session start limit is exhausted");
 						}
-						initialUrl = gatewayUrl(gateway.url);
+						initialUrl = discordGatewayUrl(gateway.url);
 					}
-					const deliver = async (message: MessengerMessage): Promise<void> => {
-						const thread = createdThreads.get(message.channelId);
-						if (thread && thread.senderId === message.senderId) {
-							await onMessage({
-								...message,
-								threadId: message.channelId,
-								parentChannelId: thread.parentChannelId,
-							});
-						} else if (
-							!message.direct &&
-							message.mentioned &&
-							config.allowedUserIds.includes(message.senderId) &&
-							config.allowedChannelIds &&
-							!config.allowedChannelIds.includes(message.channelId)
-						) {
+					const lookup = async (url: string): Promise<unknown> => {
+						for (let attempt = 0; ; attempt++) {
 							try {
-								const channel = await messengerFetchJson(
-									`${API}/channels/${encodeURIComponent(message.channelId)}`,
-									{ headers: headers() },
-									signal,
-									deps.fetch,
-								);
+								return await messengerFetchJson(url, { headers: headers() }, signal, deps.fetch);
+							} catch (error) {
 								if (
-									isRecord(channel) &&
-									typeof channel.type === "number" &&
-									[10, 11, 12].includes(channel.type) &&
-									typeof channel.parent_id === "string" &&
-									channel.parent_id
+									!(error instanceof MessengerHttpError) ||
+									error.status !== 429 ||
+									attempt >= 3 ||
+									signal.aborted
 								) {
-									await onMessage({
-										...message,
-										threadId: message.channelId,
-										parentChannelId: channel.parent_id,
-									});
+									throw error;
 								}
+								await waitForReconnect(error.retryAfterMs ?? 1_000, signal, clock);
+								if (signal.aborted) throw error;
+							}
+						}
+					};
+					const isBotReply = async (value: unknown, channelId: string): Promise<boolean> => {
+						if (!isRecord(value) || value.type !== 19 || !isRecord(value.message_reference)) return false;
+						const reference = value.message_reference;
+						if (
+							typeof reference.message_id !== "string" ||
+							(reference.channel_id && reference.channel_id !== channelId)
+						)
+							return false;
+						let original = value.referenced_message;
+						if (original === undefined) {
+							try {
+								original = await lookup(
+									`${DISCORD_API}/channels/${encodeURIComponent(channelId)}/messages/${encodeURIComponent(reference.message_id)}`,
+								);
 							} catch {
-								if (!signal.aborted) logger.warn("Discord thread parent lookup failed");
+								if (!signal.aborted) logger.warn("Discord reply lookup failed");
+								return false;
 							}
-						} else {
-							await onMessage(message);
 						}
+						return (
+							isRecord(original) &&
+							original.id === reference.message_id &&
+							isRecord(original.author) &&
+							original.author.id === accountId
+						);
+					};
+					const forward = (message: MessengerMessage): void => {
+						if (signal.aborted) return;
+						try {
+							void onMessage(message).catch(() => logger.warn("Discord message handler failed"));
+						} catch {
+							logger.warn("Discord message handler failed");
+						}
+					};
+					const classify = async (message: MessengerMessage, raw: unknown): Promise<void> => {
+						if (message.direct || !config.allowedUserIds.includes(message.senderId)) {
+							forward(message);
+							return;
+						}
+						if (!message.mentioned && (await isBotReply(raw, message.channelId))) {
+							message = { ...message, mentioned: true };
+						}
+						const thread = createdThreads.get(message.channelId);
+						if (thread && thread.senderId === message.senderId) {
+							forward({ ...message, threadId: message.channelId, parentChannelId: thread.parentChannelId });
+							return;
+						}
+						try {
+							const channel = await lookup(`${DISCORD_API}/channels/${encodeURIComponent(message.channelId)}`);
+							if (
+								!isRecord(channel) ||
+								typeof channel.type !== "number" ||
+								![10, 11, 12].includes(channel.type) ||
+								typeof channel.parent_id !== "string" ||
+								!channel.parent_id ||
+								(config.allowedChannelIds &&
+									!config.allowedChannelIds.includes(message.channelId) &&
+									!config.allowedChannelIds.includes(channel.parent_id))
+							) {
+								forward(message);
+								return;
+							}
+							if (!message.mentioned && channel.owner_id !== accountId) {
+								let before = message.messageId;
+								for (;;) {
+									const history = await lookup(
+										`${DISCORD_API}/channels/${encodeURIComponent(message.channelId)}/messages?limit=100&before=${encodeURIComponent(before)}`,
+									);
+									if (!Array.isArray(history)) return;
+									let invoked = false;
+									for (const entry of history) {
+										if (
+											!isRecord(entry) ||
+											!isRecord(entry.author) ||
+											entry.author.bot ||
+											entry.webhook_id ||
+											typeof entry.author.id !== "string" ||
+											!config.allowedUserIds.includes(entry.author.id)
+										)
+											continue;
+										if (
+											(Array.isArray(entry.mentions) &&
+												entry.mentions.some(user => isRecord(user) && user.id === accountId)) ||
+											(await isBotReply(entry, message.channelId))
+										) {
+											invoked = true;
+											break;
+										}
+									}
+									if (invoked) break;
+									if (history.length < 100) {
+										forward(message);
+										return;
+									}
+									const last = history[history.length - 1];
+									if (!isRecord(last) || typeof last.id !== "string" || !last.id || last.id === before) return;
+									before = last.id;
+								}
+							}
+							forward({ ...message, threadId: message.channelId, parentChannelId: channel.parent_id });
+						} catch {
+							if (!signal.aborted) logger.warn("Discord thread lookup failed");
+						}
+						return;
+					};
+					const deliver = (message: MessengerMessage, raw: unknown): Promise<void> => {
+						if (signal.aborted) return Promise.resolve();
+						if (message.direct || !config.allowedUserIds.includes(message.senderId)) {
+							forward(message);
+							return Promise.resolve();
+						}
+						const key = `${message.channelId}:${message.messageId}`;
+						if (pendingClassifications.has(key) || pendingClassifications.size >= MAX_CLASSIFICATION_PENDING) {
+							return Promise.resolve();
+						}
+						pendingClassifications.add(key);
+						const previous = Promise.all([
+							classificationTails.get(message.channelId),
+							messageClassifications.get(message.channelId),
+						]);
+						const current = previous
+							.then(() => (signal.aborted ? undefined : classify(message, raw)))
+							.catch(() => logger.warn("Discord classification failed"));
+						classificationTails.set(message.channelId, current);
+						messageClassifications.set(message.messageId, current);
+						void current.then(() => {
+							pendingClassifications.delete(key);
+							if (messageClassifications.get(message.messageId) === current)
+								messageClassifications.delete(message.messageId);
+							if (classificationTails.get(message.channelId) === current)
+								classificationTails.delete(message.channelId);
+						});
+						return current;
 					};
 					await connectGateway(
 						session.url ?? initialUrl,
@@ -459,7 +578,7 @@ export function createDiscordAdapter(
 				return message;
 			}
 			const channel = await messengerFetchJson(
-				`${API}/channels/${encodeURIComponent(message.channelId)}`,
+				`${DISCORD_API}/channels/${encodeURIComponent(message.channelId)}`,
 				{ headers: headers() },
 				signal,
 				deps.fetch,
@@ -474,7 +593,7 @@ export function createDiscordAdapter(
 			}
 			if (channel.type !== 0 && channel.type !== 5) throw new Error("Discord channel cannot host a reply thread");
 			const thread = await messengerFetchJson(
-				`${API}/channels/${encodeURIComponent(message.channelId)}/messages/${encodeURIComponent(message.messageId)}/threads`,
+				`${DISCORD_API}/channels/${encodeURIComponent(message.channelId)}/messages/${encodeURIComponent(message.messageId)}/threads`,
 				{ method: "POST", headers: headers(), body: JSON.stringify({ name: `Request ${message.messageId}` }) },
 				signal,
 				deps.fetch,
@@ -485,7 +604,7 @@ export function createDiscordAdapter(
 			return { ...message, threadId: thread.id };
 		},
 		async status(message, state, signal) {
-			const base = `${API}/channels/${encodeURIComponent(message.channelId)}/messages/${encodeURIComponent(message.messageId)}/reactions`;
+			const base = `${DISCORD_API}/channels/${encodeURIComponent(message.channelId)}/messages/${encodeURIComponent(message.messageId)}/reactions`;
 			const processing = encodeURIComponent("⏳");
 			if (state !== "processing") {
 				try {
@@ -500,17 +619,44 @@ export function createDiscordAdapter(
 				}
 			}
 			const emoji = state === "processing" ? "⏳" : state === "success" ? "✅" : "❌";
+			try {
+				await messengerFetchJson(
+					`${base}/${encodeURIComponent(emoji)}/@me`,
+					{ method: "PUT", headers: headers() },
+					signal,
+					deps.fetch,
+				);
+			} finally {
+				if (state === "processing" && signal?.aborted) {
+					try {
+						await messengerFetchJson(
+							`${base}/${processing}/@me`,
+							{ method: "DELETE", headers: headers() },
+							AbortSignal.timeout(3_000),
+							deps.fetch,
+						);
+					} catch {
+						logger.warn("Discord late processing reaction removal failed");
+					}
+				}
+			}
+		},
+		async clearStatus(message, signal) {
+			const base = `${DISCORD_API}/channels/${encodeURIComponent(message.channelId)}/messages/${encodeURIComponent(message.messageId)}/reactions`;
 			await messengerFetchJson(
-				`${base}/${encodeURIComponent(emoji)}/@me`,
-				{ method: "PUT", headers: headers() },
+				`${base}/${encodeURIComponent("⏳")}/@me`,
+				{ method: "DELETE", headers: headers() },
 				signal,
 				deps.fetch,
 			);
 		},
+		releaseActivity(message) {
+			activityMessages.delete(JSON.stringify([message.threadId ?? message.channelId, message.messageId]));
+		},
 		async activity(message, text, signal) {
 			const channelId = message.threadId ?? message.channelId;
 			const key = JSON.stringify([channelId, message.messageId]);
-			const messages = `${API}/channels/${encodeURIComponent(channelId)}/messages`;
+			const messages = `${DISCORD_API}/channels/${encodeURIComponent(channelId)}/messages`;
 			const statusId = activityMessages.get(key);
 			if (text === undefined) {
 				if (!statusId) return;
@@ -560,6 +706,19 @@ export function createDiscordAdapter(
 			);
 			if (!isRecord(created) || typeof created.id !== "string" || !created.id)
 				throw new Error("Discord activity message returned no ID");
+			if (signal?.aborted) {
+				try {
+					await messengerFetchJson(
+						`${messages}/${encodeURIComponent(created.id)}`,
+						{ method: "DELETE", headers: headers() },
+						AbortSignal.timeout(3_000),
+						deps.fetch,
+					);
+				} catch {
+					logger.warn("Discord late activity removal failed");
+				}
+				return;
+			}
 			activityMessages.set(key, created.id);
 		},
 		async send(message, text, signal) {
@@ -571,7 +730,7 @@ export function createDiscordAdapter(
 					files = result.files;
 				} catch {
 					await messengerFetchJson(
-						`${API}/channels/${encodeURIComponent(message.threadId ?? message.channelId)}/messages`,
+						`${DISCORD_API}/channels/${encodeURIComponent(message.threadId ?? message.channelId)}/messages`,
 						{
 							method: "POST",
 							headers: headers(),
@@ -614,7 +773,7 @@ export function createDiscordAdapter(
 							});
 						}
 						await messengerFetchJson(
-							`${API}/channels/${encodeURIComponent(message.threadId ?? message.channelId)}/messages`,
+							`${DISCORD_API}/channels/${encodeURIComponent(message.threadId ?? message.channelId)}/messages`,
 							{
 								method: "POST",
 								headers: requestHeaders,
@@ -655,7 +814,7 @@ export function createDiscordAdapter(
 				for (let attempt = 0; ; attempt++) {
 					try {
 						await messengerFetchJson(
-							`${API}/channels/${encodeURIComponent(message.threadId ?? message.channelId)}/messages`,
+							`${DISCORD_API}/channels/${encodeURIComponent(message.threadId ?? message.channelId)}/messages`,
 							{ method: "POST", headers: requestHeaders, body: form },
 							signal,
 							deps.fetch,
@@ -668,7 +827,7 @@ export function createDiscordAdapter(
 						}
 						if (!signal?.aborted) {
 							await messengerFetchJson(
-								`${API}/channels/${encodeURIComponent(message.threadId ?? message.channelId)}/messages`,
+								`${DISCORD_API}/channels/${encodeURIComponent(message.threadId ?? message.channelId)}/messages`,
 								{
 									method: "POST",
 									headers: headers(),

package/src/messenger/gateway.ts

@@ -141,24 +141,27 @@ function createActivityReporter(
 			closing ??= (async () => {
 				closed = true;
 				wake?.();
-				await pump;
-				if (!shown) return;
-				for (let attempt = 0; ; attempt++) {
-					try {
-						await update(undefined);
-						return;
-					} catch (error) {
-						const wait =
-							error instanceof MessengerHttpError && error.status === 429
-								? (error.retryAfterMs ?? 1_000)
-								: 1_000;
-						// One bounded retry: removal holds the request queue.
-						if (attempt > 0 || wait > ACTIVITY_TIMEOUT_MS) {
-							logger.warn("Messenger activity removal failed", { platform: destination.platform });
+				try {
+					await pump;
+					if (!shown) return;
+					for (let attempt = 0; ; attempt++) {
+						try {
+							await update(undefined);
 							return;
+						} catch (error) {
+							const wait =
+								error instanceof MessengerHttpError && error.status === 429
+									? (error.retryAfterMs ?? 1_000)
+									: 1_000;
+							if (attempt > 0 || wait > ACTIVITY_TIMEOUT_MS) {
+								logger.warn("Messenger activity removal failed", { platform: destination.platform });
+								return;
+							}
+							await Bun.sleep(wait);
 						}
-						await Bun.sleep(wait);
 					}
+				} finally {
+					adapter.releaseActivity?.(destination);
 				}
 			})();
 			return closing;
@@ -183,14 +186,18 @@ export function messengerSessionRoute(cwd: string, message: MessengerMessage): s
 }
 
 /**
- * Scheduling heuristic, refined after `prepare`: a top-level server message on a prepare-capable adapter
- * (Discord) starts its own reply thread, so it is never held behind queued work; every other message waits for
- * earlier requests in its conversation. A follow-up arriving in that new thread is ordered behind the request
- * that created it by the prepared-conversation lock in `processRequest`.
+ * Discord creates a thread with the original message's ID. Reserve that conversation key before
+ * preparing it so follow-ups cannot overtake the request while thread creation is in flight.
  */
 function schedulingKey(message: MessengerMessage, adapter: MessengerAdapter): string {
-	if (adapter.prepare && !message.direct && !message.threadId && !message.parentChannelId) {
-		return JSON.stringify([message.platform, message.accountId, message.channelId, message.messageId]);
+	if (
+		message.platform === "discord" &&
+		adapter.prepare &&
+		!message.direct &&
+		!message.threadId &&
+		!message.parentChannelId
+	) {
+		return messengerConversationKey({ ...message, threadId: message.messageId });
 	}
 	return messengerConversationKey(message);
 }
@@ -271,6 +278,7 @@ export function createMessengerGateway(
 		let tail: Promise<void> | undefined;
 		let conversation = "";
 		let statusChain = Promise.resolve();
+		let processingStarted = false;
 		const status = (state: "processing" | "success" | "failure"): void => {
 			if (!adapter.status) return;
 			statusChain = statusChain.then(async () => {
@@ -281,7 +289,10 @@ export function createMessengerGateway(
 				const onAbort = (): void => stopped.resolve();
 				statusSignal.addEventListener("abort", onAbort, { once: true });
 				statusInFlight++;
-				const operation = Promise.resolve().then(() => adapter.status!(message, state, statusSignal));
+				const operation = Promise.resolve().then(() => {
+					if (state === "processing") processingStarted = true;
+					return adapter.status!(message, state, statusSignal);
+				});
 				void operation.then(
 					() => {
 						statusInFlight--;
@@ -345,6 +356,21 @@ export function createMessengerGateway(
 			}
 		} finally {
 			await activity.close();
+			if (signal.aborted && processingStarted && adapter.clearStatus && statusInFlight < MAX_STATUS_IN_FLIGHT) {
+				statusInFlight++;
+				const operation = Promise.resolve().then(() =>
+					adapter.clearStatus!(message, AbortSignal.timeout(STATUS_TIMEOUT_MS)),
+				);
+				void operation.then(
+					() => statusInFlight--,
+					() => statusInFlight--,
+				);
+				try {
+					await Promise.race([operation, Bun.sleep(STATUS_TIMEOUT_MS)]);
+				} catch {
+					logger.warn("Messenger cancelled status removal failed", { platform: message.platform });
+				}
+			}
 			release();
 			if (tail && conversationTails.get(conversation) === tail) conversationTails.delete(conversation);
 			resolve();

package/src/messenger/service.ts

@@ -0,0 +1,122 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { $ } from "bun";
+
+/** A per-user background service that keeps one messenger profile's gateway running. */
+export interface MessengerServicePlan {
+	/** Stable service name derived from the profile directory. */
+	label: string;
+	/** Profile directory: working directory and home of the run script and log. */
+	directory: string;
+	runScript: string;
+	logFile: string;
+}
+
+export function messengerServicePlan(directory: string, runScript: string): MessengerServicePlan {
+	const slug =
+		path
+			.basename(directory)
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, "-")
+			.replace(/^-+|-+$/g, "") || "default";
+	return {
+		label: `dev.jeopi.messenger.${slug}`,
+		directory,
+		runScript,
+		logFile: path.join(directory, "gateway.log"),
+	};
+}
+
+function xml(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+/** launchd job: starts at login, restarts after a crash (throttled), logs to the profile directory. */
+export function launchdPlist(plan: MessengerServicePlan): string {
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Label</key><string>${xml(plan.label)}</string>
+	<key>ProgramArguments</key>
+	<array><string>/bin/sh</string><string>${xml(plan.runScript)}</string></array>
+	<key>WorkingDirectory</key><string>${xml(plan.directory)}</string>
+	<key>RunAtLoad</key><true/>
+	<key>KeepAlive</key><true/>
+	<key>ThrottleInterval</key><integer>30</integer>
+	<key>StandardOutPath</key><string>${xml(plan.logFile)}</string>
+	<key>StandardErrorPath</key><string>${xml(plan.logFile)}</string>
+</dict>
+</plist>
+`;
+}
+
+/** systemd --user unit with the same lifecycle as the launchd job. */
+export function systemdUnit(plan: MessengerServicePlan): string {
+	const quoted = (value: string): string => `"${value.replace(/(["\\])/g, "\\$1")}"`;
+	return `[Unit]
+Description=jeopi messenger gateway (${plan.label})
+After=network-online.target
+
+[Service]
+WorkingDirectory=${quoted(plan.directory)}
+ExecStart=/bin/sh ${quoted(plan.runScript)}
+Restart=always
+RestartSec=30
+StandardOutput=append:${plan.logFile}
+StandardError=append:${plan.logFile}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/**
+ * Install (or replace) and start the service, then confirm the platform reports it running.
+ * Returns a one-line description of where it was installed.
+ */
+export async function installMessengerService(
+	plan: MessengerServicePlan,
+	platform: NodeJS.Platform = process.platform,
+	home: string = os.homedir(),
+): Promise<string> {
+	if (platform === "darwin") {
+		const file = path.join(home, "Library", "LaunchAgents", `${plan.label}.plist`);
+		await Bun.write(file, launchdPlist(plan));
+		const domain = `gui/${process.getuid?.() ?? 0}`;
+		await $`launchctl bootout ${domain} ${file}`.quiet().nothrow();
+		// bootstrap can fail briefly while a replaced job is still exiting.
+		let loaded = false;
+		for (let attempt = 0; attempt < 5 && !loaded; attempt++) {
+			if (attempt) await Bun.sleep(1_000);
+			loaded = (await $`launchctl bootstrap ${domain} ${file}`.quiet().nothrow()).exitCode === 0;
+		}
+		if (!loaded) throw new Error(`launchctl could not load ${file}`);
+		for (let attempt = 0; attempt < 20; attempt++) {
+			const status = await $`launchctl print ${domain}/${plan.label}`.quiet().nothrow();
+			if (status.exitCode === 0 && /\bstate = running\b/.test(status.text()))
+				return `launchd job ${plan.label} (${file})`;
+			await Bun.sleep(500);
+		}
+		throw new Error(`launchd job ${plan.label} did not reach the running state; see ${plan.logFile}`);
+	}
+	if (platform === "linux") {
+		const unit = `${plan.label}.service`;
+		const file = path.join(home, ".config", "systemd", "user", unit);
+		await fs.mkdir(path.dirname(file), { recursive: true });
+		await Bun.write(file, systemdUnit(plan));
+		const reload = await $`systemctl --user daemon-reload`.quiet().nothrow();
+		const enable = await $`systemctl --user enable ${unit}`.quiet().nothrow();
+		const restart = await $`systemctl --user restart ${unit}`.quiet().nothrow();
+		if (reload.exitCode !== 0 || enable.exitCode !== 0 || restart.exitCode !== 0) {
+			throw new Error(`systemctl --user could not start ${unit}`);
+		}
+		const active = await $`systemctl --user is-active ${unit}`.quiet().nothrow();
+		if (active.text().trim() !== "active") throw new Error(`${unit} is not active; see ${plan.logFile}`);
+		return `systemd user unit ${unit} (${file})`;
+	}
+	throw new Error(
+		`Background services are supported on macOS (launchd) and Linux (systemd --user); run ${plan.runScript} under your own process manager`,
+	);
+}