primcli 1.34.0 → 1.35.0

package/dist/listen-background-D6UhIbkO.js

@@ -0,0 +1,647 @@
+import { _ as acquireListenLock, a as mailLockBusy, b as listenProcessIdentity, d as readMailJson, f as removeMailFile, g as ListenStateError, h as writeMailJson, i as mailId, l as privateMailDirectory, o as mailObject, s as mailString, v as compareListenProcessIdentity } from "./shared-mail-files-Cbwnf79a.js";
+import { lstatSync, realpathSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { spawn } from "node:child_process";
+//#region src/oclif/listen-background.ts
+const BACKGROUND_LISTEN_TOKEN_ENV = "PRIMITIVE_LISTEN_BACKGROUND_TOKEN";
+const BACKGROUND_LISTEN_TARGET_ENV = "PRIMITIVE_LISTEN_BACKGROUND_TARGET";
+const SUPERVISOR_ENV = "PRIMITIVE_LISTEN_SUPERVISOR";
+const SUPERVISOR_ARGV_ENV = "PRIMITIVE_LISTEN_SUPERVISOR_ARGV";
+const SUPERVISOR_WORKER_ENV = "PRIMITIVE_LISTEN_SUPERVISOR_WORKER";
+const STALE_AFTER_MS = 15e3;
+const RESTART_WINDOW_MS = 10 * 6e4;
+const HEALTHY_RESET_MS = 10 * 6e4;
+const MAX_FAILURES = 5;
+const phases = [
+	"starting",
+	"receiving",
+	"reconnecting",
+	"stopped",
+	"failed"
+];
+const failureCodes = [
+	"native-session-unavailable",
+	"notification-outcome-unknown",
+	"connection-changed",
+	"receiving-failed",
+	"restart-budget-exhausted"
+];
+function knownFailureCode(value) {
+	return failureCodes.includes(value) ? value : null;
+}
+function failureGuidance(code) {
+	switch (code) {
+		case "native-session-unavailable": return "Open the same native session with local-session support and check its socket permissions before restarting the listener.";
+		case "notification-outcome-unknown": return "A notification outcome is unknown and is held. Inspect the exact session and saved receipts before any manual resend; do not delete receipts or send again automatically.";
+		case "connection-changed": return "The selected connection changed. Check the intended profile and API origin before starting the listener again.";
+		case "receiving-failed": return "Inspect listener status and run the same command without --background for details.";
+		case "restart-budget-exhausted": return "The listener repeatedly exited. Inspect listener status before starting it again.";
+	}
+}
+function backgroundListenToken(env = process.env) {
+	const value = env[BACKGROUND_LISTEN_TOKEN_ENV];
+	return value === void 0 ? null : mailId(value);
+}
+function configurationFingerprint(value) {
+	if (value === void 0) return null;
+	if (!/^[a-f0-9]{64}$/i.test(value)) throw new ListenStateError("Listener configuration fingerprint is invalid.");
+	return value.toLowerCase();
+}
+/** Verify the parent's selection before a child reads or mutates listener state. */
+function verifyBackgroundListenTarget(target, env = process.env) {
+	if (backgroundListenToken(env) === null) return;
+	try {
+		const expected = mailObject(JSON.parse(env["PRIMITIVE_LISTEN_BACKGROUND_TARGET"] ?? ""), [
+			"scope",
+			"threadId",
+			"configDir",
+			"configuration"
+		]);
+		if (expected.configuration !== null && typeof expected.configuration !== "string") throw new Error("Invalid configuration fingerprint");
+		const configuration = configurationFingerprint(expected.configuration === null ? void 0 : String(expected.configuration));
+		const configDir = mailString(expected.configDir, 4096);
+		if (mailString(expected.scope) !== mailString(target.scope) || mailId(expected.threadId) !== mailId(target.threadId) || configDir !== realpathSync(configDir) || configDir !== realpathSync(target.configDir) || configuration !== configurationFingerprint(target.configuration)) throw new Error("Changed listener target");
+	} catch {
+		throw new ListenStateError("Background listener target changed or its parent expectation is invalid. No listener was started.");
+	}
+}
+function configDirectory(path, create) {
+	let info;
+	try {
+		info = lstatSync(path);
+	} catch (error) {
+		if (!create || error.code !== "ENOENT") throw error;
+		privateMailDirectory(path, true);
+		info = lstatSync(path);
+	}
+	if (!info.isDirectory() || process.platform !== "win32" && (info.uid !== process.getuid?.() || (info.mode & 18) !== 0)) throw new ListenStateError("Listener config directory must be an owned directory without group or other write access, not a symlink.");
+}
+function files(target, create = false) {
+	const key = createHash("sha256").update(JSON.stringify([mailString(target.scope), mailId(target.threadId)])).digest("hex");
+	const root = join(target.configDir, "listen-background");
+	const directory = join(root, key);
+	for (const path of [
+		target.configDir,
+		root,
+		directory
+	]) try {
+		if (path === target.configDir) configDirectory(path, create);
+		else privateMailDirectory(path, create);
+	} catch (error) {
+		if (!create && error.code === "ENOENT") break;
+		throw error;
+	}
+	return {
+		directory,
+		state: join(directory, "state.json"),
+		stop: join(directory, "stop.json"),
+		supervisor: join(directory, "supervisor.json")
+	};
+}
+function readSupervisor(path) {
+	const value = readMailJson(path, 2048);
+	if (value === null) return null;
+	const row = mailObject(value, [
+		"version",
+		"token",
+		"pid",
+		"identity",
+		"phase",
+		"updatedAt",
+		"failureCode"
+	]);
+	if (row.version !== 1 || !Number.isSafeInteger(row.pid) || Number(row.pid) < 1 || ![
+		"starting",
+		"running",
+		"stopped",
+		"failed"
+	].includes(String(row.phase)) || !Number.isSafeInteger(row.updatedAt) || Number(row.updatedAt) < 0 || row.failureCode !== null && knownFailureCode(row.failureCode) === null) throw new ListenStateError("Background supervisor state is invalid. Preserve it before retrying.");
+	return {
+		version: 1,
+		token: mailId(row.token),
+		pid: Number(row.pid),
+		identity: mailString(row.identity),
+		phase: row.phase,
+		updatedAt: Number(row.updatedAt),
+		failureCode: knownFailureCode(row.failureCode)
+	};
+}
+function readState(path) {
+	const value = readMailJson(path, 2048);
+	if (value === null) return null;
+	const row = mailObject(value, [
+		"version",
+		"token",
+		"pid",
+		"identity",
+		"phase",
+		"detached",
+		"configuration",
+		...typeof value === "object" && Object.hasOwn(value, "failureCode") ? ["failureCode"] : [],
+		"updatedAt"
+	]);
+	if (row.version !== 1 || !Number.isSafeInteger(row.pid) || Number(row.pid) < 1 || !phases.includes(row.phase) || typeof row.detached !== "boolean" || row.configuration !== null && typeof row.configuration !== "string" || row.failureCode !== void 0 && row.failureCode !== null && knownFailureCode(row.failureCode) === null || !Number.isSafeInteger(row.updatedAt) || Number(row.updatedAt) < 0) throw new ListenStateError("Background listener state is invalid. Preserve it before retrying.");
+	return {
+		version: 1,
+		token: mailId(row.token),
+		pid: Number(row.pid),
+		identity: mailString(row.identity),
+		phase: row.phase,
+		detached: row.detached,
+		configuration: configurationFingerprint(row.configuration === null ? void 0 : String(row.configuration)),
+		failureCode: knownFailureCode(row.failureCode),
+		updatedAt: Number(row.updatedAt)
+	};
+}
+function owner(state) {
+	const current = listenProcessIdentity(state.pid);
+	const matches = compareListenProcessIdentity(state.identity, current);
+	if (matches !== null) return matches ? "verified" : "gone";
+	try {
+		process.kill(state.pid, 0);
+	} catch (error) {
+		if (error.code === "ESRCH") return "gone";
+	}
+	return "unknown";
+}
+function status(state) {
+	if (!state) return {
+		phase: null,
+		pid: null,
+		detached: null,
+		healthy: false,
+		failureCode: null,
+		reason: "absent",
+		updatedAt: null
+	};
+	const age = Date.now() - state.updatedAt;
+	const ownership = owner(state);
+	const reason = state.phase === "stopped" || state.phase === "failed" ? state.phase : ownership === "gone" ? "exited" : ownership === "unknown" ? "unverifiable" : age < 0 || age >= STALE_AFTER_MS ? "stale" : null;
+	return {
+		phase: state.phase,
+		pid: state.pid,
+		detached: state.detached,
+		healthy: reason === null,
+		failureCode: state.failureCode,
+		reason,
+		updatedAt: state.updatedAt
+	};
+}
+/** Absence means no managed record, not proof that an older foreground listener is absent. */
+function backgroundListenStatus(target) {
+	const paths = files(target);
+	const worker = status(readState(paths.state));
+	const supervisor = readSupervisor(paths.supervisor);
+	if (!supervisor) return worker;
+	const ownership = owner(supervisor);
+	const age = Date.now() - supervisor.updatedAt;
+	const fresh = age >= 0 && age < STALE_AFTER_MS;
+	const active = supervisor.phase === "starting" || supervisor.phase === "running";
+	const reason = supervisor.phase === "failed" ? "failed" : supervisor.phase === "stopped" ? "stopped" : ownership === "gone" ? "exited" : ownership === "unknown" ? "unverifiable" : !fresh ? "stale" : worker.healthy ? null : "restarting";
+	return {
+		...worker,
+		phase: supervisor.phase === "failed" ? "failed" : reason === "restarting" ? "reconnecting" : worker.phase,
+		healthy: active && reason === null,
+		reason,
+		failureCode: supervisor.failureCode ?? worker.failureCode,
+		supervisorPid: supervisor.pid,
+		supervisorUpdatedAt: supervisor.updatedAt
+	};
+}
+function stopToken(path) {
+	const value = readMailJson(path, 512);
+	if (value === null) return null;
+	return mailId(mailObject(value, ["token"]).token);
+}
+/** Signal only the verified generation through its private mailbox, never its PID. */
+async function stopBackgroundListen(target, expectedToken) {
+	const paths = files(target);
+	const state = readState(paths.state);
+	const supervisor = readSupervisor(paths.supervisor);
+	if (!state && !supervisor) return status(null);
+	const token = supervisor?.token ?? state?.token;
+	if (!token) return status(null);
+	if (expectedToken !== void 0 && mailId(expectedToken) !== token) throw new ListenStateError("Background listener ownership changed; no stop was requested.");
+	if (state && !supervisor && (state.phase === "stopped" || state.phase === "failed" || owner(state) === "gone")) return status(state);
+	if (supervisor && owner(supervisor) === "unknown") throw new ListenStateError("Background supervisor ownership cannot be verified; no stop was requested.");
+	if (!supervisor && state && owner(state) !== "verified" && !state.identity.startsWith("darwin:")) throw new ListenStateError("Background listener ownership cannot be verified; no stop was requested.");
+	writeMailJson(paths.stop, { token });
+	const deadline = Date.now() + 5e3;
+	for (;;) {
+		const current = readState(paths.state);
+		const currentSupervisor = readSupervisor(paths.supervisor);
+		if (currentSupervisor?.token === token && currentSupervisor.phase === "stopped") return backgroundListenStatus(target);
+		if (currentSupervisor?.token === token && currentSupervisor.phase === "failed") return backgroundListenStatus(target);
+		if (current && current.token !== token) return backgroundListenStatus(target);
+		if (!current && !currentSupervisor) return backgroundListenStatus(target);
+		if (!supervisor && current && (current.phase === "stopped" || current.phase === "failed" || owner(current) === "gone")) return backgroundListenStatus(target);
+		if (Date.now() >= deadline) return backgroundListenStatus(target);
+		await setTimeout$1(50);
+	}
+}
+function announce(token, phase, failureCode = null) {
+	try {
+		if (process.connected && process.send) process.send({
+			type: "primitive-listen-state",
+			token,
+			phase,
+			...phase === "failed" ? { failureCode } : {}
+		}, () => {});
+	} catch {}
+}
+/** Hold exclusive ownership across safe retries; the caller decides which errors are retryable. */
+async function runBackgroundListen(options) {
+	verifyBackgroundListenTarget(options);
+	const token = mailId(options.token);
+	const configuration = configurationFingerprint(options.configuration);
+	const paths = files(options, true);
+	const identity = listenProcessIdentity(process.pid);
+	if (!identity) throw new ListenStateError("Listener process ownership cannot be verified.");
+	const release = acquireListenLock(paths.directory, "background-runtime");
+	const controller = new AbortController();
+	const cancel = () => controller.abort();
+	const state = {
+		version: 1,
+		token,
+		pid: process.pid,
+		identity,
+		phase: "starting",
+		detached: options.detached ?? false,
+		configuration,
+		failureCode: null,
+		updatedAt: Date.now()
+	};
+	let failure;
+	let timer;
+	let started = false;
+	const publish = (phase = state.phase) => {
+		const previous = readState(paths.state);
+		if (started && previous?.token !== token) throw new ListenStateError("Listener process ownership changed.");
+		state.phase = phase;
+		state.updatedAt = Date.now();
+		writeMailJson(paths.state, state);
+		started = true;
+	};
+	const tick = () => {
+		try {
+			if (stopToken(paths.stop) === token) cancel();
+			publish();
+		} catch (error) {
+			failure ??= { error };
+			cancel();
+		}
+	};
+	options.signal?.addEventListener("abort", cancel, { once: true });
+	process.on("SIGTERM", cancel);
+	process.on("SIGINT", cancel);
+	try {
+		if (options.signal?.aborted) cancel();
+		publish();
+		tick();
+		timer = setInterval(tick, options.heartbeatMs ?? 1e3);
+		let attempts = 0;
+		while (!controller.signal.aborted) {
+			const attempt = new AbortController();
+			const signal = AbortSignal.any([controller.signal, attempt.signal]);
+			try {
+				await options.run(signal, () => {
+					signal.throwIfAborted();
+					publish("receiving");
+					announce(token, "receiving");
+				});
+				break;
+			} catch (error) {
+				if (controller.signal.aborted) {
+					if (error === signal.reason || error instanceof Error && error.name === "AbortError") break;
+					throw error;
+				}
+				if (!options.retryable(error)) throw error;
+				publish("reconnecting");
+				announce(token, "reconnecting");
+			} finally {
+				attempt.abort();
+			}
+			await setTimeout$1(Math.min((options.retryDelayMs ?? 1e3) * 2 ** Math.min(attempts++, 5), 3e4), void 0, { signal: controller.signal }).catch((error) => {
+				if (!controller.signal.aborted) throw error;
+			});
+		}
+		if (failure) throw failure.error;
+		publish("stopped");
+	} catch (error) {
+		failure ??= { error };
+		try {
+			state.failureCode = knownFailureCode(options.failureCode?.(failure.error)) ?? "receiving-failed";
+		} catch {
+			state.failureCode = "receiving-failed";
+		}
+		try {
+			if (readState(paths.state)?.token === token) publish("failed");
+		} catch {}
+		announce(token, "failed", state.failureCode);
+	} finally {
+		if (timer) clearInterval(timer);
+		options.signal?.removeEventListener("abort", cancel);
+		process.off("SIGTERM", cancel);
+		process.off("SIGINT", cancel);
+		try {
+			if (process.env[SUPERVISOR_WORKER_ENV] !== token && stopToken(paths.stop) === token) removeMailFile(paths.stop);
+		} catch (error) {
+			failure ??= { error };
+		}
+		try {
+			release();
+		} catch (error) {
+			failure ??= { error };
+		}
+	}
+	if (failure) throw failure.error;
+}
+/** Supervise one exact listener generation until a stop or the restart budget is exhausted. */
+async function runBackgroundListenSupervisor() {
+	const token = mailId(process.env[BACKGROUND_LISTEN_TOKEN_ENV]);
+	const expected = mailObject(JSON.parse(process.env["PRIMITIVE_LISTEN_BACKGROUND_TARGET"] ?? ""), [
+		"scope",
+		"threadId",
+		"configDir",
+		"configuration"
+	]);
+	const target = {
+		scope: mailString(expected.scope),
+		threadId: mailId(expected.threadId),
+		configDir: mailString(expected.configDir, 4096)
+	};
+	if (realpathSync(target.configDir) !== target.configDir) throw new ListenStateError("Background supervisor target changed.");
+	const argvValue = JSON.parse(process.env[SUPERVISOR_ARGV_ENV] ?? "");
+	if (!Array.isArray(argvValue) || argvValue.length < 1 || argvValue.some((part) => typeof part !== "string" || part.length > 4096)) throw new ListenStateError("Background supervisor command is invalid.");
+	const argv = argvValue;
+	const paths = files(target, true);
+	const release = acquireListenLock(paths.directory, "background-supervisor");
+	const identity = listenProcessIdentity(process.pid);
+	if (!identity) {
+		release();
+		throw new ListenStateError("Supervisor process ownership cannot be verified.");
+	}
+	const record = {
+		version: 1,
+		token,
+		pid: process.pid,
+		identity,
+		phase: "starting",
+		updatedAt: Date.now(),
+		failureCode: null
+	};
+	const publish = () => {
+		const prior = readSupervisor(paths.supervisor);
+		if (prior && prior.token !== token && owner(prior) !== "gone" && prior.phase !== "stopped" && prior.phase !== "failed") throw new ListenStateError("Another supervisor owns this listener.");
+		record.updatedAt = Date.now();
+		writeMailJson(paths.supervisor, record);
+	};
+	let child;
+	let stopped = false;
+	const cancel = () => {
+		stopped = true;
+		writeMailJson(paths.stop, { token });
+		child?.kill("SIGTERM");
+	};
+	process.on("SIGTERM", cancel);
+	process.on("SIGINT", cancel);
+	const heartbeat = setInterval(() => {
+		try {
+			if (stopToken(paths.stop) === token) {
+				stopped = true;
+				child?.kill("SIGTERM");
+			}
+			publish();
+		} catch {
+			cancel();
+		}
+	}, 1e3);
+	const failures = [];
+	try {
+		publish();
+		while (!stopped) {
+			if (stopToken(paths.stop) === token) break;
+			const env = {
+				...process.env,
+				[SUPERVISOR_WORKER_ENV]: token
+			};
+			delete env[SUPERVISOR_ENV];
+			delete env[SUPERVISOR_ARGV_ENV];
+			child = spawn(process.execPath, argv, {
+				env,
+				windowsHide: true,
+				stdio: [
+					"ignore",
+					"ignore",
+					"ignore",
+					"ipc"
+				]
+			});
+			let readyAt = null;
+			child.on("message", (message) => {
+				if (!message || typeof message !== "object") return;
+				const row = message;
+				if (row.type !== "primitive-listen-state" || row.token !== token) return;
+				if (row.phase === "receiving" && readyAt === null) readyAt = Date.now();
+				try {
+					if (process.connected) process.send?.(message, () => {});
+				} catch {}
+			});
+			record.phase = "running";
+			publish();
+			await new Promise((resolve) => {
+				child?.once("exit", () => resolve());
+				child?.once("error", () => resolve());
+			});
+			child = void 0;
+			if (stopped || stopToken(paths.stop) === token) break;
+			const worker = readState(paths.state);
+			if (worker?.token === token && worker.phase === "failed" && ["notification-outcome-unknown", "connection-changed"].includes(worker.failureCode ?? "")) {
+				record.phase = "failed";
+				record.failureCode = worker.failureCode;
+				publish();
+				return;
+			}
+			const now = Date.now();
+			if (readyAt !== null && now - readyAt >= HEALTHY_RESET_MS) failures.length = 0;
+			failures.push(now);
+			while (failures.length && (failures[0] ?? now) < now - RESTART_WINDOW_MS) failures.shift();
+			if (failures.length >= MAX_FAILURES) {
+				record.phase = "failed";
+				record.failureCode = "restart-budget-exhausted";
+				publish();
+				return;
+			}
+			record.phase = "starting";
+			publish();
+			const backoff = Math.min(1e3 * 2 ** (failures.length - 1), 3e4);
+			const end = Date.now() + backoff;
+			while (!stopped && Date.now() < end && stopToken(paths.stop) !== token) await setTimeout$1(Math.min(200, end - Date.now()));
+		}
+		record.phase = "stopped";
+		publish();
+	} catch (error) {
+		record.phase = "failed";
+		record.failureCode = "receiving-failed";
+		try {
+			publish();
+		} catch {}
+		throw error;
+	} finally {
+		clearInterval(heartbeat);
+		process.off("SIGTERM", cancel);
+		process.off("SIGINT", cancel);
+		child?.kill("SIGTERM");
+		if (stopToken(paths.stop) === token) removeMailFile(paths.stop);
+		if (record.phase === "stopped" && readState(paths.state) === null) removeMailFile(paths.supervisor);
+		release();
+	}
+}
+/** Ask one worker generation to stop and wait briefly until it has. */
+async function stopOrphanedWorker(paths, token) {
+	writeMailJson(paths.stop, { token });
+	const deadline = Date.now() + 5e3;
+	for (;;) {
+		const current = readState(paths.state);
+		if (!current || current.token !== token || current.phase === "stopped" || current.phase === "failed" || owner(current) === "gone") return true;
+		if (Date.now() >= deadline) return false;
+		await setTimeout$1(50);
+	}
+}
+/** Spawn the same CLI entrypoint. Overrides travel only in the child's environment. */
+async function startBackgroundListen(options) {
+	const configuration = configurationFingerprint(options.configuration);
+	const paths = files(options, true);
+	const timeout = options.startupTimeoutMs ?? 15e3;
+	const deadline = Date.now() + timeout;
+	let release;
+	while (!release) {
+		options.signal?.throwIfAborted();
+		try {
+			release = acquireListenLock(paths.directory, "background-start");
+		} catch (error) {
+			if (!mailLockBusy(error) || Date.now() >= deadline) throw error;
+			await setTimeout$1(25, void 0, { signal: options.signal });
+		}
+	}
+	try {
+		const prior = readState(paths.state);
+		const priorSupervisor = readSupervisor(paths.supervisor);
+		if (priorSupervisor && ["starting", "running"].includes(priorSupervisor.phase) && owner(priorSupervisor) !== "gone") {
+			const current = backgroundListenStatus(options);
+			if (!current.healthy) throw new ListenStateError("Existing supervisor ownership is stale or unverifiable. Inspect status before restarting.");
+			if (prior?.configuration !== configuration) throw new ListenStateError("Stop the existing listener before changing receiving options.");
+			return {
+				started: false,
+				status: current
+			};
+		}
+		if (prior && prior.phase !== "stopped" && prior.phase !== "failed" && owner(prior) !== "gone") {
+			const current = status(prior);
+			if (!current.healthy) throw new ListenStateError("Existing listener ownership is stale or unverifiable; the worker was retained. Inspect status or request a stop before restarting.");
+			if (!prior.detached) throw new ListenStateError("An existing foreground listener owns this session. Stop it before restarting with --background.");
+			if (prior.configuration !== configuration) throw new ListenStateError("Stop the existing listener before changing receiving options.");
+			if (!priorSupervisor) return {
+				started: false,
+				status: current
+			};
+			if (!await stopOrphanedWorker(paths, prior.token)) throw new ListenStateError("The existing background listener lost its supervisor and did not stop. Stop it, then start again.");
+		}
+		const token = randomUUID();
+		const env = {
+			...process.env,
+			...options.env,
+			[BACKGROUND_LISTEN_TOKEN_ENV]: token,
+			[BACKGROUND_LISTEN_TARGET_ENV]: JSON.stringify({
+				scope: mailString(options.scope),
+				threadId: mailId(options.threadId),
+				configDir: realpathSync(options.configDir),
+				configuration
+			})
+		};
+		const argv = [];
+		for (let index = 0; index < options.argv.length; index++) {
+			const arg = options.argv[index];
+			if (arg === void 0) continue;
+			if (arg === "--background" || arg.startsWith("--background=")) continue;
+			if (arg === "--api-key") {
+				const key = options.argv[++index];
+				if (key === void 0) throw new ListenStateError("An API key value is required.");
+				env.PRIMITIVE_API_KEY = key.trim();
+			} else if (arg.startsWith("--api-key=")) env.PRIMITIVE_API_KEY = arg.slice(10).trim();
+			else argv.push(arg);
+		}
+		if (!argv.length) throw new ListenStateError("The CLI entrypoint is required.");
+		env[SUPERVISOR_ENV] = "1";
+		env[SUPERVISOR_ARGV_ENV] = JSON.stringify(argv);
+		const child = spawn(process.execPath, [argv[0] ?? ""], {
+			env,
+			detached: true,
+			windowsHide: true,
+			stdio: [
+				"ignore",
+				"ignore",
+				"ignore",
+				"ipc"
+			]
+		});
+		let startupFailureCode = null;
+		try {
+			await new Promise((resolve, reject) => {
+				const timer = setTimeout(() => finish(new ListenStateError("Background listener startup timed out.")), timeout);
+				const abort = () => finish(new ListenStateError("Background listener startup was cancelled."));
+				const exit = () => finish(new ListenStateError("Background listener stopped before it became ready."));
+				const error = () => finish(new ListenStateError("Background listener could not be started."));
+				const message = (value) => {
+					if (!value || typeof value !== "object") return;
+					const next = value;
+					if (next.type !== "primitive-listen-state" || next.token !== token) return;
+					if (next.phase === "receiving" || next.phase === "reconnecting") finish();
+					else if (next.phase === "failed") {
+						startupFailureCode = knownFailureCode(next.failureCode);
+						error();
+					}
+				};
+				const finish = (failure) => {
+					clearTimeout(timer);
+					options.signal?.removeEventListener("abort", abort);
+					child.off("exit", exit);
+					child.off("error", error);
+					child.off("message", message);
+					if (failure) reject(failure);
+					else resolve();
+				};
+				child.once("exit", exit);
+				child.once("error", error);
+				child.on("message", message);
+				options.signal?.addEventListener("abort", abort, { once: true });
+				if (options.signal?.aborted) abort();
+			});
+			const current = readState(paths.state);
+			const supervisor = readSupervisor(paths.supervisor);
+			if (current?.token !== token || supervisor?.token !== token || current.configuration !== configuration || !current.detached || !backgroundListenStatus(options).healthy) throw new ListenStateError("Background listener ownership changed during startup.");
+			return {
+				started: true,
+				status: backgroundListenStatus(options)
+			};
+		} catch {
+			writeMailJson(paths.stop, { token });
+			const until = Date.now() + 2e3;
+			while (Date.now() < until && child.exitCode === null && child.signalCode === null) await setTimeout$1(50);
+			const current = readState(paths.state);
+			const unconfirmed = current?.token === token && owner(current) !== "gone" && current.phase !== "stopped" && current.phase !== "failed" || child.exitCode === null && child.signalCode === null;
+			const code = startupFailureCode ?? (current?.token === token ? current.failureCode : null);
+			const guidance = code ? unconfirmed && code === "receiving-failed" ? "" : failureGuidance(code) : unconfirmed ? "" : "Run the same command without --background for details.";
+			throw new ListenStateError(`${unconfirmed ? "Background listener did not become ready; a stop was requested, but worker termination is unconfirmed. Inspect status before retrying." : "Background listener did not become ready and stopped."}${guidance ? ` ${guidance}` : ""}`);
+		} finally {
+			if (child.connected) child.disconnect();
+			child.unref();
+		}
+	} finally {
+		release();
+	}
+}
+//#endregion
+export { startBackgroundListen as a, runBackgroundListenSupervisor as i, backgroundListenToken as n, stopBackgroundListen as o, runBackgroundListen as r, verifyBackgroundListenTarget as s, backgroundListenStatus as t };