jeo-code 0.12.7 → 0.12.8

package/src/messenger/gateway.ts

@@ -0,0 +1,444 @@
+import { MessengerHttpError } from "./http";
+import type {
+	MessengerActivityReporter,
+	MessengerAdapter,
+	MessengerConfig,
+	MessengerMessage,
+	MessengerReply,
+} from "./types";
+import { MessengerFatalError } from "./types";
+
+const MAX_MESSAGE_LENGTH = 32_000;
+const MAX_QUEUED_MESSAGES = 100;
+const MAX_SEEN_MESSAGES = 10_000;
+const STATUS_TIMEOUT_MS = 1000;
+const MAX_STATUS_IN_FLIGHT = 8;
+const MAX_ACTIVITY_LENGTH = 120;
+// Status edits are cosmetic: keep them sparse so they never compete with reply delivery for rate limits.
+const ACTIVITY_INTERVAL_MS = 2_000;
+const ACTIVITY_TIMEOUT_MS = 3_000;
+
+/** Collapse to one bounded line: drop invisible format characters, fold control and whitespace runs. */
+export function activityLine(text: string): string {
+	const line = text
+		.replace(/\p{Cf}/gu, "")
+		.replace(/[\p{Cc}\p{Z}\s]+/gu, " ")
+		.trim();
+	if (line.length <= MAX_ACTIVITY_LENGTH) return line;
+	let end = MAX_ACTIVITY_LENGTH - 1;
+	const last = line.charCodeAt(end - 1);
+	if (last >= 0xd800 && last <= 0xdbff) end--;
+	return `${line.slice(0, end).trimEnd()}…`;
+}
+
+export interface ActivityReporter {
+	report: MessengerActivityReporter;
+	/** Stop updates and remove any shown line; idempotent and never rejects. */
+	close(): Promise<void>;
+}
+
+const NO_ACTIVITY: ActivityReporter = { report() {}, close: () => Promise.resolve() };
+
+/**
+ * Bound a cosmetic adapter call: a stalled provider request must not hold up the request queue. A timeout
+ * rejects so callers can retry; cancellation through `signal` resolves because the request is ending.
+ */
+async function boundedActivity(run: (signal: AbortSignal) => Promise<void>, signal?: AbortSignal): Promise<void> {
+	const timeout = new AbortController();
+	const callSignal = signal ? AbortSignal.any([signal, timeout.signal]) : timeout.signal;
+	const stopped = Promise.withResolvers<void>();
+	const onStop = (): void => {
+		if (timeout.signal.aborted) stopped.reject(new Error("Messenger activity update timed out"));
+		else stopped.resolve();
+	};
+	callSignal.addEventListener("abort", onStop, { once: true });
+	const timer = setTimeout(() => timeout.abort(), ACTIVITY_TIMEOUT_MS);
+	try {
+		await Promise.race([Promise.resolve().then(() => run(callSignal)), stopped.promise]);
+	} finally {
+		clearTimeout(timer);
+		callSignal.removeEventListener("abort", onStop);
+	}
+}
+
+/**
+ * Coalesce a request's activity into one status line: show the first report at once, then at most the
+ * latest line per interval. Removal skips the request signal so an aborted request still retires its line.
+ */
+export function createActivityReporter(
+	adapter: MessengerAdapter,
+	destination: MessengerMessage,
+	signal: AbortSignal,
+	intervalMs: number,
+): ActivityReporter {
+	const activity = adapter.activity;
+	if (!activity) return NO_ACTIVITY;
+	let latest: string | undefined;
+	let sent: string | undefined;
+	let shown = false;
+	let closed = false;
+	let pumping = false;
+	let pump = Promise.resolve();
+	let nextAt = 0;
+	let wake: (() => void) | undefined;
+	let closing: Promise<void> | undefined;
+	const pause = async (ms: number): Promise<void> => {
+		const { promise, resolve } = Promise.withResolvers<void>();
+		const timer = setTimeout(resolve, ms);
+		wake = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		try {
+			await promise;
+		} finally {
+			wake = undefined;
+		}
+	};
+	const run = async (): Promise<void> => {
+		try {
+			while (!closed && !signal.aborted && latest !== sent) {
+				const delay = nextAt - Date.now();
+				if (delay > 0) {
+					await pause(delay);
+					continue;
+				}
+				const text = latest;
+				sent = text;
+				shown = true;
+				let spacing = intervalMs;
+				try {
+					await boundedActivity(bounded => activity.call(adapter, destination, text, bounded), signal);
+				} catch (error) {
+					if (error instanceof MessengerHttpError && error.status === 429) {
+						// Keep the line pending: a rate-limited update is retried unless a newer line replaces it.
+						sent = undefined;
+						spacing = Math.max(spacing, error.retryAfterMs ?? 1_000);
+					}
+				}
+				nextAt = Date.now() + spacing;
+			}
+		} finally {
+			pumping = false;
+		}
+	};
+	return {
+		report(text) {
+			if (closed || signal.aborted) return;
+			const line = activityLine(text);
+			if (!line) return;
+			latest = line;
+			if (pumping) return;
+			pumping = true;
+			pump = run();
+		},
+		close() {
+			closing ??= (async () => {
+				closed = true;
+				wake?.();
+				await pump;
+				if (!shown) return;
+				for (let attempt = 0; ; attempt++) {
+					try {
+						await boundedActivity(bounded => activity.call(adapter, destination, undefined, bounded));
+						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) return;
+						await Bun.sleep(wait);
+					}
+				}
+			})();
+			return closing;
+		},
+	};
+}
+
+type OptionalIdentity = readonly ["absent"] | readonly ["present", string];
+
+/**
+ * Canonical, ordered remote-session identity. `thread` and `conversation` are mutually exclusive
+ * alternatives; Discord supplies `thread`, while adapters with another conversation primitive may
+ * supply `conversation`. IDs are opaque and therefore are never trimmed or case-folded.
+ */
+export type MessengerSessionIdentity = readonly [
+	version: "messenger-session-v1",
+	platform: MessengerMessage["platform"],
+	account: string,
+	guild: OptionalIdentity,
+	channel: string,
+	thread: OptionalIdentity,
+	conversation: OptionalIdentity,
+	user: string,
+];
+
+function optionalIdentity(name: string, value: string | undefined): OptionalIdentity {
+	if (value === undefined) return ["absent"];
+	if (!value || value.trim() !== value) throw new Error(`Messenger ${name} identifier is invalid`);
+	return ["present", value];
+}
+
+export function messengerSessionIdentity(message: MessengerMessage): MessengerSessionIdentity {
+	if (message.threadId !== undefined && message.conversationId !== undefined) {
+		throw new Error("Messenger thread and conversation identifiers are mutually exclusive");
+	}
+	for (const [name, value] of [
+		["account", message.accountId],
+		["channel", message.parentChannelId ?? message.channelId],
+		["user", message.senderId],
+	] as const) {
+		if (!value || value.trim() !== value) throw new Error(`Messenger ${name} identifier is invalid`);
+	}
+	return [
+		"messenger-session-v1",
+		message.platform,
+		message.accountId,
+		optionalIdentity("guild", message.guildId),
+		message.parentChannelId ?? message.channelId,
+		optionalIdentity("thread", message.threadId),
+		optionalIdentity("conversation", message.conversationId),
+		message.senderId,
+	];
+}
+
+/** Collision-safe JSON serialization of the canonical identity tuple. */
+export function messengerConversationKey(message: MessengerMessage): string {
+	return JSON.stringify(messengerSessionIdentity(message));
+}
+
+/** Stable per-conversation route shared by the persisted session file and its session process. */
+export function messengerSessionRoute(cwd: string, message: MessengerMessage): string {
+	return new Bun.CryptoHasher("sha256").update(JSON.stringify([cwd, messengerConversationKey(message)])).digest("hex");
+}
+
+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]);
+	}
+	return messengerConversationKey(message);
+}
+
+export function isMessengerMessageAllowed(message: MessengerMessage, config: MessengerConfig): boolean {
+	const platform = config.platforms[message.platform];
+	return Boolean(
+		platform &&
+			message.accountId &&
+			message.channelId &&
+			message.senderId &&
+			message.messageId &&
+			(message.text.trim() ||
+				(message.platform === "discord" && config.platforms.discord?.artifactDir && message.attachments?.length)) &&
+			message.text.length <= MAX_MESSAGE_LENGTH &&
+			platform.allowedUserIds.includes(message.senderId) &&
+			(!platform.allowedChannelIds ||
+				platform.allowedChannelIds.includes(message.channelId) ||
+				(Boolean(message.parentChannelId) && platform.allowedChannelIds.includes(message.parentChannelId!))) &&
+			(message.direct || message.mentioned || (message.platform === "discord" && Boolean(message.parentChannelId))),
+	);
+}
+
+interface PendingMessage {
+	message: MessengerMessage;
+	adapter: MessengerAdapter;
+	signal: AbortSignal;
+	resolve: () => void;
+	/** Requests sharing a key never run at the same time. */
+	key: string;
+}
+
+export interface MessengerGateway {
+	run(signal: AbortSignal): Promise<void>;
+	handle(message: MessengerMessage, signal?: AbortSignal): Promise<void>;
+}
+
+export interface MessengerGatewayOptions {
+	/** Minimum spacing between in-place activity edits for one request. */
+	activityIntervalMs?: number;
+	/**
+	 * Requests processed at once (default 1). Requests of one prepared conversation still answer and deliver in
+	 * order; above 1 the reply implementation must accept concurrent turns for different conversations.
+	 */
+	concurrency?: number;
+}
+
+export function createMessengerGateway(
+	config: MessengerConfig,
+	adapters: MessengerAdapter[],
+	reply: MessengerReply,
+	options: MessengerGatewayOptions = {},
+): MessengerGateway {
+	const activityIntervalMs = Math.max(0, options.activityIntervalMs ?? ACTIVITY_INTERVAL_MS);
+	const concurrency = Math.max(1, Math.trunc(options.concurrency ?? 1));
+	const byPlatform = new Map(adapters.map(adapter => [adapter.platform, adapter]));
+	if (byPlatform.size !== adapters.length) throw new Error("Duplicate messenger adapter");
+	for (const platform of Object.keys(config.platforms)) {
+		if (!adapters.some(adapter => adapter.platform === platform))
+			throw new Error("Missing configured messenger adapter");
+	}
+	const seen = new Set<string>();
+	const queue: PendingMessage[] = [];
+	const activeKeys = new Set<string>();
+	const turns = new Set<Promise<void>>();
+	/** Settles when the latest request of a prepared conversation has delivered its reply. */
+	const conversationTails = new Map<string, Promise<void>>();
+	const lifetime = new AbortController();
+	let running = false;
+	let fatalError: MessengerFatalError | undefined;
+	let statusInFlight = 0;
+
+	async function processRequest(pending: PendingMessage): Promise<void> {
+		const { message, adapter, signal, resolve } = pending;
+		let failed = false;
+		let activity = NO_ACTIVITY;
+		let release = (): void => {};
+		let tail: Promise<void> | undefined;
+		let conversation = "";
+		let statusChain = Promise.resolve();
+		const status = (state: "processing" | "success" | "failure"): void => {
+			if (!adapter.status) return;
+			statusChain = statusChain.then(async () => {
+				if (signal.aborted || statusInFlight >= MAX_STATUS_IN_FLIGHT) return;
+				const timeout = new AbortController();
+				const statusSignal = AbortSignal.any([signal, timeout.signal]);
+				const stopped = Promise.withResolvers<void>();
+				const onAbort = (): void => stopped.resolve();
+				statusSignal.addEventListener("abort", onAbort, { once: true });
+				statusInFlight++;
+				const operation = Promise.resolve().then(() => adapter.status!(message, state, statusSignal));
+				void operation.then(
+					() => {
+						statusInFlight--;
+					},
+					() => {
+						statusInFlight--;
+					},
+				);
+				const timer = setTimeout(() => timeout.abort(), STATUS_TIMEOUT_MS);
+				try {
+					await Promise.race([operation, stopped.promise]);
+				} catch {
+					/* best-effort status reaction */
+				} finally {
+					clearTimeout(timer);
+					statusSignal.removeEventListener("abort", onAbort);
+				}
+			});
+		};
+		try {
+			if (signal.aborted) return;
+			status("processing");
+			const destination = (await adapter.prepare?.(message, signal)) ?? message;
+			conversation = messengerConversationKey(destination);
+			const previous = conversationTails.get(conversation);
+			const done = Promise.withResolvers<void>();
+			release = done.resolve;
+			tail = done.promise;
+			conversationTails.set(conversation, tail);
+			await previous;
+			activity = createActivityReporter(adapter, destination, signal, activityIntervalMs);
+			let text: string;
+			try {
+				text = await reply(destination, signal, activity.report);
+			} catch (error) {
+				failed = true;
+				if (error instanceof MessengerFatalError) {
+					fatalError = error;
+					status("failure");
+					lifetime.abort();
+					return;
+				}
+				if (signal.aborted) return;
+				text = "The request could not be completed. Please try again.";
+			} finally {
+				// Retire the status line alongside reply delivery rather than delaying the reply on it.
+				void activity.close();
+			}
+			if (!signal.aborted && text.trim()) {
+				// A failed send may already have delivered a chunk: never retry the entire reply.
+				await adapter.send(destination, text, signal);
+			}
+			if (!signal.aborted) status(failed ? "failure" : "success");
+		} catch {
+			if (!signal.aborted) status("failure");
+		} finally {
+			await activity.close();
+			release();
+			if (tail && conversationTails.get(conversation) === tail) conversationTails.delete(conversation);
+			resolve();
+		}
+	}
+
+	/** Start queued requests in arrival order while capacity allows, skipping conversations already running. */
+	function schedule(): void {
+		for (let index = 0; index < queue.length && turns.size < concurrency; ) {
+			const pending = queue[index]!;
+			if (activeKeys.has(pending.key)) {
+				index++;
+				continue;
+			}
+			queue.splice(index, 1);
+			activeKeys.add(pending.key);
+			const turn = processRequest(pending).finally(() => {
+				activeKeys.delete(pending.key);
+				turns.delete(turn);
+				schedule();
+			});
+			turns.add(turn);
+		}
+	}
+
+	function handle(message: MessengerMessage, signal?: AbortSignal): Promise<void> {
+		const adapter = byPlatform.get(message.platform);
+		const effectiveSignal = signal ? AbortSignal.any([lifetime.signal, signal]) : lifetime.signal;
+		if (effectiveSignal.aborted || !adapter || !isMessengerMessageAllowed(message, config)) return Promise.resolve();
+		const id = JSON.stringify([message.platform, message.accountId, message.channelId, message.messageId]);
+		if (seen.has(id) || queue.length >= MAX_QUEUED_MESSAGES) return Promise.resolve();
+		seen.add(id);
+		if (seen.size > MAX_SEEN_MESSAGES) {
+			const oldest = seen.values().next().value;
+			if (oldest !== undefined) seen.delete(oldest);
+		}
+		const { promise, resolve } = Promise.withResolvers<void>();
+		queue.push({ message, adapter, signal: effectiveSignal, resolve, key: schedulingKey(message, adapter) });
+		schedule();
+		return promise;
+	}
+
+	return {
+		handle,
+		async run(signal) {
+			if (running || lifetime.signal.aborted) throw new Error("Messenger gateway cannot be restarted");
+			running = true;
+			const abort = (): void => lifetime.abort();
+			signal.addEventListener("abort", abort, { once: true });
+			if (signal.aborted) abort();
+			const starts: Promise<void>[] = [];
+			try {
+				if (lifetime.signal.aborted) return;
+				for (const adapter of adapters) {
+					starts.push(
+						Promise.resolve().then(async () => {
+							await adapter.start(msg => handle(msg, lifetime.signal), lifetime.signal);
+							if (!lifetime.signal.aborted) throw new Error(`${adapter.platform} adapter stopped unexpectedly`);
+						}),
+					);
+				}
+				await Promise.all(starts);
+			} catch (error) {
+				lifetime.abort();
+				await Promise.allSettled(starts);
+				throw fatalError ?? error;
+			} finally {
+				lifetime.abort();
+				signal.removeEventListener("abort", abort);
+				while (queue.length > 0) queue.shift()?.resolve();
+				await Promise.allSettled(turns);
+				if (fatalError) throw fatalError;
+			}
+		},
+	};
+}

package/src/messenger/http.ts

@@ -0,0 +1,88 @@
+export class MessengerHttpError extends Error {
+	constructor(
+		readonly status: number,
+		readonly retryAfterMs?: number,
+	) {
+		super(`Messenger request failed (HTTP ${status})`);
+		this.name = "MessengerHttpError";
+	}
+}
+
+/** Provider limits count UTF-16 units; do not bisect supplementary characters. */
+export function splitMessengerText(text: string, limit: number): string[] {
+	if (!Number.isSafeInteger(limit) || limit < 2)
+		throw new Error("Message chunk limit must be an integer of at least two");
+	const chunks: string[] = [];
+	for (let start = 0; start < text.length; ) {
+		let end = Math.min(start + limit, text.length);
+		const last = text.charCodeAt(end - 1);
+		if (end < text.length && last >= 0xd800 && last <= 0xdbff) end--;
+		chunks.push(text.slice(start, end));
+		start = end;
+	}
+	return chunks;
+}
+
+export async function messengerFetchJson(
+	url: string,
+	init: RequestInit,
+	signal?: AbortSignal,
+	fetchImpl: typeof fetch = fetch,
+): Promise<unknown> {
+	const signals: AbortSignal[] = [AbortSignal.timeout(35_000)];
+	if (signal) signals.push(signal);
+	if (init.signal) signals.push(init.signal);
+	const requestSignal = AbortSignal.any(signals);
+	try {
+		const response = await fetchImpl(url, { ...init, redirect: "error", signal: requestSignal });
+		if (!response.ok) {
+			let retryAfterMs: number | undefined;
+			if (response.status === 429) {
+				let seconds = Number(response.headers.get("retry-after"));
+				if (!seconds) {
+					try {
+						const body: unknown = await response.json();
+						if (typeof body === "object" && body !== null) {
+							if ("retry_after" in body && typeof body.retry_after === "number") {
+								seconds = body.retry_after;
+							} else if (
+								"parameters" in body &&
+								typeof body.parameters === "object" &&
+								body.parameters !== null &&
+								"retry_after" in body.parameters &&
+								typeof body.parameters.retry_after === "number"
+							) {
+								seconds = body.parameters.retry_after;
+							}
+						}
+					} catch {
+						/* Retry metadata is optional; never surface provider response text. */
+					}
+				}
+				// Larger delays overflow native timers into immediate retries.
+				if (Number.isFinite(seconds) && seconds > 0) retryAfterMs = Math.min(seconds * 1000, 2_147_483_647);
+			}
+			if (!response.bodyUsed) await response.body?.cancel();
+			throw new MessengerHttpError(response.status, retryAfterMs);
+		}
+		if (response.status === 204) return undefined;
+		return await response.json();
+	} catch (error) {
+		if (error instanceof MessengerHttpError) throw error;
+		if (signal?.aborted || init.signal?.aborted) throw new Error("Messenger request cancelled");
+		throw new Error("Messenger request failed");
+	}
+}
+
+export async function waitForMessengerRetry(ms: number, signal: AbortSignal): Promise<void> {
+	if (signal.aborted) return;
+	const { promise, resolve } = Promise.withResolvers<void>();
+	const done = (): void => {
+		clearTimeout(timer);
+		signal.removeEventListener("abort", done);
+		resolve();
+	};
+	const timer = setTimeout(done, ms);
+	signal.addEventListener("abort", done, { once: true });
+	await promise;
+}

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.jeo.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=jeo 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`,
+	);
+}