primcli 1.75.0 → 3.0.0-preview.10

package/dist/{listen-background-C0F9gNDD.js → listen-background-DyBYca28.js}

@@ -10,6 +10,7 @@ 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 BACKGROUND_LISTEN_RELAUNCH_ENV = "PRIMITIVE_LISTEN_RELAUNCH_FOR";
 const STALE_AFTER_MS = 15e3;
 const RESTART_WINDOW_MS = 6e5;
 const HEALTHY_RESET_MS = 6e5;
@@ -38,6 +39,27 @@ const HOLDING_FAILURE_CODES = [
 	"connection-changed",
 	"unrecognized"
 ];
+const startFailureReasons = [
+	"timed-out",
+	"cancelled",
+	"supervisor-exited",
+	"spawn-failed",
+	"worker-failed",
+	"ownership-changed",
+	"options-changed",
+	"existing-kept",
+	"unverifiable"
+];
+/**
+* A failure code as a worker reported it. One from a newer CLI keeps its name
+* in supervisor.json, so that CLI reads its own code back; readers that do
+* not know it see "unrecognized". Anything that is not a plain code name is
+* "unrecognized" outright.
+*/
+function reportedFailureCode(value) {
+	if (value === null || value === void 0) return null;
+	return typeof value === "string" && /^[a-z][a-z0-9-]{0,63}$/.test(value) ? value : "unrecognized";
+}
 function knownFailureCode(value) {
 	return failureCodes.includes(value) ? value : null;
 }
@@ -83,8 +105,38 @@ function failureGuidance(code) {
 		case "unrecognized": return "A newer Primitive CLI recorded this receiver's state. Inspect it with that version before restarting.";
 	}
 }
+function startFailureCause(reason) {
+	switch (reason) {
+		case "timed-out": return "the receiver was not ready before the startup timeout";
+		case "cancelled": return "the start was cancelled, or the receiver was stopped while it started";
+		case "supervisor-exited": return "its supervisor exited before the receiver was ready";
+		case "spawn-failed": return "its supervisor could not be started";
+		case "worker-failed": return "the receiver reported a failure while starting";
+		case "ownership-changed": return "another listener held this receiver, or its supervisor no longer did, when startup was checked";
+		case "options-changed": return "the receiver ran with options other than those requested";
+		case "existing-kept": return "the receiver already recorded for this session could not be verified or stopped, so it was left in place";
+		case "unverifiable": return "its records could not be read to confirm it";
+		case "unrecognized": return "its reason is one this version of the CLI does not recognize";
+	}
+}
+/**
+* A failed start is history once the receiver is healthy and receiving. A
+* healthy receiver that is still starting or reconnecting has not shown that
+* the start which failed was recovered from.
+*/
+function startFailureCurrent(status) {
+	return !(status.healthy && status.phase === "receiving");
+}
 /** One sentence an owner or agent can act on; never raw error text. */
 function statusDetail(status) {
+	const base = receiverDetail(status);
+	const failure = status.lastStartFailure;
+	if (!failure || !startFailureCurrent(status)) return base;
+	const restart = status.reason === "stopped" || status.reason === "absent" ? " Start it again with the same listen command, or run it without --background for details." : "";
+	const note = `The last background start, at ${new Date(failure.at).toISOString()}, failed: ${startFailureCause(failure.reason)}.${restart}`;
+	return base ? `${base} ${note}` : note;
+}
+function receiverDetail(status) {
 	if (status.healthy) return null;
 	const guidance = status.failureCode ? failureGuidance(status.failureCode) : "";
 	const withGuidance = (text) => guidance ? `${text} ${guidance}` : text;
@@ -103,6 +155,23 @@ function backgroundListenToken(env = process.env) {
 	const value = env[BACKGROUND_LISTEN_TOKEN_ENV];
 	return value === void 0 ? null : mailId(value);
 }
+/**
+* The fingerprint of the options a receiver runs with. A supervisor restarts
+* its worker with the same command, also after the CLI was upgraded in place,
+* so the value must not depend on the CLI version or anything else that
+* changes between releases. Earlier releases included their version; a worker
+* restarted by a supervisor of one of them hands its receiver over (see
+* verifyBackgroundListenTarget).
+*/
+function backgroundListenConfiguration(options) {
+	return createHash("sha256").update(JSON.stringify({
+		contacts: options.contacts,
+		contactRequests: options.contactRequests,
+		senders: [...options.senders].sort(),
+		socketPath: options.socketPath,
+		events: options.events?.map((event) => event.trim()).sort()
+	})).digest("hex");
+}
 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.");
@@ -110,7 +179,10 @@ function configurationFingerprint(value) {
 }
 /** Verify the parent's selection before a child reads or mutates listener state. */
 function verifyBackgroundListenTarget(target, env = process.env) {
-	if (backgroundListenToken(env) === null) return;
+	const token = backgroundListenToken(env);
+	if (token === null) return;
+	let changedConnection = true;
+	let changedOptions = false;
 	try {
 		const value = JSON.parse(env["PRIMITIVE_LISTEN_BACKGROUND_TARGET"] ?? "");
 		const expected = mailObject(value, [
@@ -122,11 +194,34 @@ function verifyBackgroundListenTarget(target, env = process.env) {
 		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");
+		if (mailString(expected.scope) !== mailString(target.scope) || mailId(expected.threadId) !== mailId(target.threadId)) throw new Error("Changed listener target");
+		let resolved;
+		try {
+			resolved = [realpathSync(configDir), realpathSync(target.configDir)];
+		} catch (error) {
+			if (storageFailureCode(error) !== null) changedConnection = false;
+			throw error;
+		}
+		if (resolved.some((path) => path !== configDir)) throw new Error("Changed listener target");
+		changedConnection = false;
+		changedOptions = configuration !== configurationFingerprint(target.configuration);
+		if (changedOptions) throw new Error("Changed listener options");
 	} catch {
+		if (changedConnection && env === process.env) announce(token, "failed", "connection-changed");
+		if (changedOptions && env === process.env && env[SUPERVISOR_WORKER_ENV] === token) handOverReceiver(target, token);
 		throw new ListenStateError("Background listener target changed or its parent expectation is invalid. No listener was started.");
 	}
 }
+/**
+* Relaunch this worker's command with --background to replace the supervisor
+* generation `token`. The claim allows one handover per restart interval: the
+* supervisor may restart this worker again before the relaunch stops it.
+*/
+function handOverReceiver(target, token) {
+	try {
+		if (claimBackgroundListenRestart(target)) relaunchSupervisor(token);
+	} catch {}
+}
 function configDirectory(path, create) {
 	let info;
 	try {
@@ -157,9 +252,51 @@ function files(target, create = false) {
 		directory,
 		state: join(directory, "state.json"),
 		stop: join(directory, "stop.json"),
-		supervisor: join(directory, "supervisor.json")
+		supervisor: join(directory, "supervisor.json"),
+		startFailure: join(directory, "start-failure.json"),
+		ownerStop: join(directory, "owner-stop.json")
 	};
 }
+/** A diagnostic only: an unreadable record is reported as none, never as an error. */
+function readStartFailure(path) {
+	try {
+		const value = readMailJson(path, 1024);
+		if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+		const row = value;
+		if (row.version !== 1 || !Number.isSafeInteger(row.at) || Number(row.at) < 0 || Number(row.at) > 864e13 || typeof row.reason !== "string" || row.failureCode !== null && typeof row.failureCode !== "string") return null;
+		return {
+			at: Number(row.at),
+			reason: startFailureReasons.includes(row.reason) ? row.reason : "unrecognized",
+			failureCode: savedFailureCode(row.failureCode)
+		};
+	} catch {
+		return null;
+	}
+}
+function recordStartFailure(paths, reason, failureCode) {
+	try {
+		writeMailJson(paths.startFailure, {
+			version: 1,
+			at: Date.now(),
+			reason,
+			failureCode
+		});
+	} catch {}
+}
+/** Whether an owner asked generation `token` to stop; unreadable means no. */
+function ownerStopped(paths, token) {
+	try {
+		const value = readMailJson(paths.ownerStop, 512);
+		return !!value && typeof value === "object" && !Array.isArray(value) && typeof value.token === "string" && String(value.token).toLowerCase() === token;
+	} catch {
+		return false;
+	}
+}
+function clearStartFailure(paths) {
+	try {
+		removeMailFile(paths.startFailure);
+	} catch {}
+}
 function readSupervisor(path) {
 	const value = readMailJson(path, 2048);
 	if (value === null) return null;
@@ -264,7 +401,15 @@ function backgroundListenStatus(target) {
 	const paths = files(target);
 	const worker = status(readState(paths.state));
 	const supervisor = readSupervisor(paths.supervisor);
-	if (!supervisor) return worker;
+	const saved = readStartFailure(paths.startFailure);
+	if (!supervisor) return saved && startFailureCurrent(worker) ? {
+		...worker,
+		lastStartFailure: saved,
+		detail: statusDetail({
+			...worker,
+			lastStartFailure: saved
+		})
+	} : worker;
 	const ownership = owner(supervisor);
 	const age = Date.now() - supervisor.updatedAt;
 	const fresh = age >= 0 && age < STALE_AFTER_MS;
@@ -272,9 +417,14 @@ function backgroundListenStatus(target) {
 	const reason = supervisor.phase === "failed" ? "failed" : supervisor.phase === "stopped" ? "stopped" : ownership === "gone" ? "exited" : ownership === "unknown" ? "unverifiable" : !fresh ? "stale" : worker.healthy ? null : "restarting";
 	const healthy = active && reason === null;
 	const failureCode = healthy ? null : supervisor.failureCode ?? worker.failureCode;
+	const phase = supervisor.phase === "failed" ? "failed" : reason === "restarting" ? "reconnecting" : worker.phase;
+	const lastStartFailure = saved && startFailureCurrent({
+		healthy,
+		phase
+	}) ? saved : null;
 	return {
 		...worker,
-		phase: supervisor.phase === "failed" ? "failed" : reason === "restarting" ? "reconnecting" : worker.phase,
+		phase,
 		healthy,
 		reason,
 		failureCode,
@@ -283,8 +433,11 @@ function backgroundListenStatus(target) {
 		detail: statusDetail({
 			healthy,
 			reason,
-			failureCode
-		})
+			failureCode,
+			phase,
+			lastStartFailure
+		}),
+		...lastStartFailure ? { lastStartFailure } : {}
 	};
 }
 /**
@@ -328,6 +481,10 @@ async function stopBackgroundListen(target, expectedToken) {
 	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.ownerStop, {
+		version: 1,
+		token
+	});
 	writeMailJson(paths.stop, { token });
 	const deadline = Date.now() + 5e3;
 	for (;;) {
@@ -399,7 +556,8 @@ async function runBackgroundListen(options) {
 			return;
 		}
 		relaunched = true;
-		(options.relaunchSupervisor ?? relaunchSupervisor)();
+		if (options.relaunchSupervisor) options.relaunchSupervisor();
+		else relaunchSupervisor(token);
 	};
 	const tick = () => {
 		try {
@@ -483,8 +641,11 @@ async function runBackgroundListen(options) {
 	if (failure) throw failure.error;
 }
 /** Relaunch this worker's own command detached, with --background restored. */
-function relaunchSupervisor() {
-	const env = { ...process.env };
+function relaunchSupervisor(token) {
+	const env = {
+		...process.env,
+		[BACKGROUND_LISTEN_RELAUNCH_ENV]: token
+	};
 	delete env[BACKGROUND_LISTEN_TOKEN_ENV];
 	delete env[BACKGROUND_LISTEN_TARGET_ENV];
 	delete env[SUPERVISOR_WORKER_ENV];
@@ -580,6 +741,7 @@ async function runBackgroundListenSupervisor(options = {}) {
 	};
 	process.on("uncaughtException", crashed);
 	process.on("unhandledRejection", crashed);
+	let workerReceiving = false;
 	const heartbeat = setInterval(() => {
 		try {
 			if (stopRequested()) {
@@ -587,6 +749,10 @@ async function runBackgroundListenSupervisor(options = {}) {
 				child?.kill("SIGTERM");
 			}
 			tryPublish();
+			if (workerReceiving) try {
+				const worker = readState(paths.state);
+				if (worker?.token === token && worker.phase === "receiving" && status(worker).healthy) clearStartFailure(paths);
+			} catch {}
 		} catch {
 			cancel();
 		}
@@ -618,14 +784,16 @@ async function runBackgroundListenSupervisor(options = {}) {
 				if (!message || typeof message !== "object") return;
 				const row = message;
 				if (row.type !== "primitive-listen-state" || row.token !== token) return;
+				if (typeof row.phase === "string") workerReceiving = row.phase === "receiving";
 				if (row.phase === "receiving") {
 					if (readyAt === null) readyAt = Date.now();
+					clearStartFailure(paths);
 					if (record.failureCode !== null) {
 						record.failureCode = null;
 						tryPublish();
 					}
 				}
-				if (row.phase === "failed") reported = knownFailureCode(row.failureCode) ?? "receiving-failed";
+				if (row.phase === "failed") reported = reportedFailureCode(row.failureCode) ?? "receiving-failed";
 				try {
 					if (process.connected) process.send?.(message, () => {});
 				} catch {}
@@ -643,6 +811,7 @@ async function runBackgroundListenSupervisor(options = {}) {
 				}));
 			});
 			child = void 0;
+			workerReceiving = false;
 			if (stopped || stopRequested()) break;
 			let worker = null;
 			try {
@@ -650,7 +819,8 @@ async function runBackgroundListenSupervisor(options = {}) {
 			} catch {}
 			const recorded = worker?.token === token && worker.phase === "failed" ? worker.failureCode : null;
 			const failureCode = reported ?? recorded ?? (exit.code === 0 && exit.signal === null ? "receiving-failed" : "crashed");
-			if (HOLDING_FAILURE_CODES.includes(failureCode)) {
+			const known = knownFailureCode(failureCode);
+			if (known === null || HOLDING_FAILURE_CODES.includes(known)) {
 				record.phase = "failed";
 				record.failureCode = failureCode;
 				tryPublish();
@@ -702,6 +872,59 @@ async function stopOrphanedWorker(paths, token) {
 		await setTimeout$1(50);
 	}
 }
+/**
+* Prepare a start that a worker relaunched for its own generation `token`:
+* its supervisor was lost, or runs another CLI build. Nothing starts once the
+* owner stopped that generation, or while its supervisor is stopped or holds
+* a failure. A supervisor of that generation that is alive while its
+* receiver is not healthy is stopped first, and this waits until its process
+* has exited, so its cleanup cannot touch the replacement. Anything else is
+* left to the ordinary start that follows.
+*/
+async function prepareRelaunch(paths, target, token, timeout, signal) {
+	const supervisor = readSupervisor(paths.supervisor);
+	if (ownerStopped(paths, token) || supervisor?.token === token && (supervisor.phase === "stopped" || supervisor.phase === "failed" && supervisor.failureCode !== "crashed")) throw relaunchCancelled();
+	if (supervisor?.token !== token || supervisor.phase !== "starting" && supervisor.phase !== "running" || owner(supervisor) === "gone" || backgroundListenStatus(target).healthy) return;
+	writeMailJson(paths.stop, { token });
+	const deadline = Date.now() + timeout;
+	let exited = false;
+	try {
+		while (Date.now() < deadline) {
+			if (owner(supervisor) === "gone") {
+				exited = true;
+				return;
+			}
+			await setTimeout$1(50, void 0, { signal });
+		}
+	} finally {
+		if (!exited) try {
+			if (stopToken(paths.stop) === token && !ownerStopped(paths, token)) removeMailFile(paths.stop);
+		} catch {}
+	}
+	recordStartFailure(paths, "existing-kept", null);
+	throw new ListenStateError("The supervisor this relaunch was to replace did not stop, so it was left running. Stop it, then start again.");
+}
+/**
+* A start refused because a healthy receiver runs with another options
+* fingerprint. Earlier releases put their version in it, so a receiver one
+* of them started differs even when the command is the same. From here the
+* two causes look alike, and stopping it is the remedy for both. The stop
+* must reach the same connection, so the flags that chose it are named, never
+* their values.
+*/
+function keptWithOtherOptions(threadId, argv) {
+	const given = (flag) => argv.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
+	const stop = [
+		`primitive listen --notify-session ${threadId}`,
+		...given("--api-key") ? ["--api-key <the same key>"] : [],
+		...given("--api-base-url") ? ["--api-base-url <the same URL>"] : [],
+		"--stop"
+	].join(" ");
+	return new ListenStateError(`A background listener for this session is still running, started by an older version of the CLI or with different receiving options, so it was kept. To restart it with this command, run \`${stop}\` with the same profile and environment, then run this command again.`);
+}
+function relaunchCancelled() {
+	return new ListenStateError("The receiver this relaunch was for was stopped or holds a failure, so nothing was started.");
+}
 /** Spawn the same CLI entrypoint. Overrides travel only in the child's environment. */
 async function startBackgroundListen(options) {
 	const configuration = configurationFingerprint(options.configuration);
@@ -719,12 +942,19 @@ async function startBackgroundListen(options) {
 		}
 	}
 	try {
+		const relaunchValue = process.env[BACKGROUND_LISTEN_RELAUNCH_ENV];
+		const relaunchFor = relaunchValue === void 0 ? null : mailId(relaunchValue);
+		if (relaunchFor !== null) await prepareRelaunch(paths, options, relaunchFor, timeout, options.signal);
 		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.");
+			if (!current.healthy) {
+				if (current.reason !== "restarting") recordStartFailure(paths, "existing-kept", current.failureCode);
+				throw new ListenStateError("Existing supervisor ownership is stale or unverifiable. Inspect status before restarting.");
+			}
+			if (prior?.configuration !== configuration) throw keptWithOtherOptions(options.threadId, options.argv);
+			if (!startFailureCurrent(current)) clearStartFailure(paths);
 			return {
 				started: false,
 				status: current
@@ -732,17 +962,25 @@ async function startBackgroundListen(options) {
 		}
 		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 (!current.healthy) {
+				recordStartFailure(paths, "existing-kept", current.failureCode);
+				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 (!priorSupervisor) {
-				if (prior.configuration !== configuration) throw new ListenStateError("Stop the existing listener before changing receiving options.");
+				if (prior.configuration !== configuration) throw keptWithOtherOptions(options.threadId, options.argv);
+				if (!startFailureCurrent(current)) clearStartFailure(paths);
 				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.");
+			if (!await stopOrphanedWorker(paths, prior.token)) {
+				recordStartFailure(paths, "existing-kept", null);
+				throw new ListenStateError("The existing background listener lost its supervisor and did not stop. Stop it, then start again.");
+			}
 		}
+		if (relaunchFor !== null && ownerStopped(paths, relaunchFor)) throw relaunchCancelled();
 		const token = randomUUID();
 		const env = {
 			...process.env,
@@ -755,6 +993,7 @@ async function startBackgroundListen(options) {
 				configuration
 			})
 		};
+		delete env[BACKGROUND_LISTEN_RELAUNCH_ENV];
 		const argv = [];
 		for (let index = 0; index < options.argv.length; index++) {
 			const arg = options.argv[index];
@@ -782,30 +1021,49 @@ async function startBackgroundListen(options) {
 			]
 		});
 		let startupFailureCode = null;
+		let supervisorFailureCode = null;
+		let decision = "unverifiable";
+		let keptReason = "timed-out";
+		let outcome = null;
+		const holds = (supervisor) => child.exitCode === null && child.signalCode === null && supervisor?.token === token && supervisor.pid === child.pid && (supervisor.phase === "starting" || supervisor.phase === "running") && owner(supervisor) !== "gone";
+		const confirm = (waited) => {
+			const current = readState(paths.state);
+			if (current && current.token !== token && current.phase !== "stopped" && current.phase !== "failed" && owner(current) !== "gone") return "ownership-changed";
+			const mine = current?.token === token ? current : null;
+			if (mine && (mine.configuration !== configuration || !mine.detached)) return "options-changed";
+			const supervisor = readSupervisor(paths.supervisor);
+			const own = supervisor?.token === token ? supervisor : null;
+			supervisorFailureCode = own?.failureCode ?? null;
+			if (mine && own && (waited === "ready" || mine.phase === "receiving" || mine.phase === "reconnecting") && backgroundListenStatus(options).healthy) return "started";
+			if (holds(supervisor)) return waited === "ready" ? "started" : "kept";
+			if (own?.phase === "failed") return own.failureCode === "crashed" ? "supervisor-exited" : "worker-failed";
+			if (own?.phase === "stopped") return "cancelled";
+			if (child.exitCode !== null || child.signalCode !== null) return "supervisor-exited";
+			return waited === "ready" ? "ownership-changed" : "timed-out";
+		};
 		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 waited = await new Promise((resolve) => {
+				const timer = setTimeout(() => finish("timed-out"), timeout);
+				const abort = () => finish("cancelled");
+				const exit = () => finish("supervisor-exited");
+				const error = () => finish("spawn-failed");
 				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();
+					if (next.phase === "receiving" || next.phase === "reconnecting") finish("ready");
 					else if (next.phase === "failed") {
 						startupFailureCode = knownFailureCode(next.failureCode);
-						error();
+						finish("worker-failed");
 					}
 				};
-				const finish = (failure) => {
+				const finish = (outcome) => {
 					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();
+					resolve(outcome);
 				};
 				child.once("exit", exit);
 				child.once("error", error);
@@ -813,20 +1071,49 @@ async function startBackgroundListen(options) {
 				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)
-			};
+			outcome = waited;
+			if (waited === "timed-out") decision = "timed-out";
+			if (waited === "ready") await options.beforeStartupCheck?.();
+			decision = waited === "ready" || waited === "timed-out" ? confirm(waited) : waited;
 		} catch {
+			if ((outcome === "ready" || outcome === "timed-out") && child.exitCode === null && child.signalCode === null) {
+				decision = "kept";
+				keptReason = "unverifiable";
+			}
+		}
+		try {
+			if (decision === "started") {
+				clearStartFailure(paths);
+				return {
+					started: true,
+					status: backgroundListenStatus(options)
+				};
+			}
+			if (decision === "kept") {
+				recordStartFailure(paths, keptReason, supervisorFailureCode);
+				try {
+					const now = readState(paths.state);
+					if (now?.token === token && now.phase === "receiving") {
+						clearStartFailure(paths);
+						return {
+							started: true,
+							status: backgroundListenStatus(options)
+						};
+					}
+				} catch {}
+				const guidance = supervisorFailureCode ? ` ${failureGuidance(supervisorFailureCode)}` : "";
+				throw new ListenStateError(`${keptReason === "timed-out" ? "Background listener was not ready before the startup timeout." : "Background listener startup could not be confirmed because its records could not be read."} Its supervisor is still running and keeps the receiver, restarting it if it exits, so it was not stopped. Inspect status, or stop it before starting again.${guidance}`);
+			}
 			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);
+			let current = null;
+			try {
+				current = readState(paths.state);
+			} catch {}
 			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);
+			recordStartFailure(paths, decision, code ?? supervisorFailureCode);
 			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 {
@@ -837,4 +1124,4 @@ async function startBackgroundListen(options) {
 		release();
 	}
 }
-export { claimBackgroundListenRestart as a, startBackgroundListen as c, backgroundListenToken as i, stopBackgroundListen as l, backgroundListenRestartable as n, runBackgroundListen as o, backgroundListenStatus as r, runBackgroundListenSupervisor as s, BACKGROUND_LISTEN_TOKEN_ENV as t, verifyBackgroundListenTarget as u };
+export { backgroundListenStatus as a, runBackgroundListen as c, stopBackgroundListen as d, verifyBackgroundListenTarget as f, backgroundListenRestartable as i, runBackgroundListenSupervisor as l, BACKGROUND_LISTEN_TOKEN_ENV as n, backgroundListenToken as o, backgroundListenConfiguration as r, claimBackgroundListenRestart as s, BACKGROUND_LISTEN_RELAUNCH_ENV as t, startBackgroundListen as u };