jeo-code 0.12.18 → 0.12.21

package/src/messenger/discord-setup.ts

@@ -4,19 +4,19 @@ import * as path from "node:path";
 import { DEFAULT_MESSENGER_TOOLS, loadMessengerConfig, messengerProfilePrivatePaths, parseMessengerSandbox, resolveMessengerToken, validateMessengerEnvironment } from "./config";
 import { DISCORD_API, DISCORD_GATEWAY_INTENTS, discordGatewayUrl } from "./discord";
 import { MessengerHttpError, messengerFetchJson } from "./http";
-import { installMessengerService, messengerServicePlan } from "./service";
+import { installMessengerService, messengerServicePlan, restartMessengerService } from "./service";
+import { MESSENGER_RUN_SCRIPT_POSIX, MESSENGER_RUN_SCRIPT_WINDOWS, MESSENGER_TOKEN_FILE, messengerExecutablePath, messengerLauncherContent, writePrivateFile } from "./launcher";
+import { MESSENGER_PACKAGE, messengerRuntimeCommand, messengerRuntimePlan, messengerRuntimeRoot, provisionMessengerRuntime, pruneMessengerRuntimes, readMessengerProfiles, registerMessengerProfile, type MessengerRuntime, type MessengerRuntimeDeps } from "./runtime";
 import { isEnoent, isRecord } from "./types";
 import { jeoHomeDir, notifyDir, notifySessionsDir } from "../agent/notify/paths";
 import { createSandboxPolicy } from "../agent/sandbox/policy";
 import type { SandboxConfig } from "../agent/sandbox/types";
 
 export const DISCORD_TOKEN_ENV = "JEO_DISCORD_BOT_TOKEN";
-const TOKEN_FILE = "discord-token";
+const TOKEN_FILE = MESSENGER_TOKEN_FILE;
 /** Fresh-setup workspace: a jeo-owned directory in the user's home, outside every sandbox-private root. */
 const WORKSPACE_DIR = "jeo-discord-workspace";
 const WORKSPACE_MARKER = ".jeo-workspace";
-const RUN_SCRIPT_POSIX = "run-discord.sh";
-const RUN_SCRIPT_WINDOWS = "run-discord.cmd";
 const MESSAGE_CONTENT = 1 << 18;
 const MESSAGE_CONTENT_LIMITED = 1 << 19;
 /** The only application flags a bot token may change: the limited presence, member, and message intents. */
@@ -87,9 +87,15 @@ export interface DiscordSetupDeps {
 	WebSocket?: typeof WebSocket;
 	env?: Record<string, string | undefined>;
 	sleep?: (ms: number) => Promise<void>;
-	/** argv that starts this jeo build; defaults to the running runtime and entry. */
+	/** argv that starts this jeo build; an explicit value is an external runtime that `jeo update` leaves alone. */
 	jeoCommand?: string[];
+	/** Runtime the running jeo offers; defaults to `messengerRuntimePlan()`. Ignored when `jeoCommand` is set. */
+	runtime?: MessengerRuntime;
+	runtimeDeps?: MessengerRuntimeDeps;
 	installService?: typeof installMessengerService;
+	restartService?: typeof restartMessengerService;
+	/** Registry of messenger profiles `jeo update` refreshes; defaults to the private notify directory. */
+	profilesPath?: string;
 	/** Cancels invite polling and the remaining setup work (the CLI wires Ctrl+C here). */
 	signal?: AbortSignal;
 	/** Injectable platform/path separator for cross-platform release tests. */
@@ -105,6 +111,7 @@ export interface DiscordSetupResult {
 	allowedUserIds: string[];
 	allowedChannelIds: string[];
 	runScript: string;
+	runtime: MessengerRuntime;
 	service?: string;
 }
 
@@ -469,51 +476,8 @@ export async function probeDiscordGateway(
 	}
 }
 
-/** The token is read from the 0600 file at launch, so it never lands in this script or a service definition. */
-export function discordRunScript(command: string[], configName: string, tokenEnv: string, envPath: string): string {
-	const quote = (value: string): string => `'${value.replace(/'/g, `'\\''`)}'`;
-	return `#!/bin/sh
-# Generated by \`jeo messenger setup\`: starts this profile's Discord gateway.
-set -eu
-dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-token_file="$dir/${TOKEN_FILE}"
-case "$(ls -ln "$token_file" | cut -c5-10)" in
-	------) ;;
-	*) echo "${TOKEN_FILE} must be readable by its owner only (chmod 600)" >&2; exit 1 ;;
-esac
-PATH=${quote(envPath)}
-export PATH
-${tokenEnv}=$(cat "$token_file")
-export ${tokenEnv}
-exec ${command.map(quote).join(" ")} messenger run --config "$dir/${configName}"
-`;
-}
-
-/** The Windows launcher inherits PATH at launch; the token remains in the private sidecar. */
-export function discordRunCommand(command: string[], configName: string, tokenEnv: string): string {
-	if (!/^[A-Za-z_]/u.test(tokenEnv) || /[^A-Za-z0-9_]/u.test(tokenEnv)) throw new Error("discord.tokenEnv must name an environment variable");
-	const literal = (value: string, label: string): string => {
-		if (/["\r\n]/.test(value)) throw new Error(`Windows launcher ${label} must not contain quotes or newlines`);
-		if (/[^\x00-\x7f]/.test(value)) throw new Error(`Windows launcher ${label} must contain only ASCII characters; use ASCII paths`);
-		return value.replace(/%/g, "%%");
-	};
-	const quote = (value: string): string => `"${literal(value, "command")}"`;
-	return `@echo off\r\nsetlocal DisableDelayedExpansion\r\nset /p "${tokenEnv}="<"%~dp0${TOKEN_FILE}"\r\n${command.map(quote).join(" ")} messenger run --config "%~dp0${literal(configName, "config name")}"\r\n`;
-}
-
-/** Stage `content` beside `file`, run `validate` on the staged copy, and only then replace `file`; failure leaves `file` untouched. */
-async function writePrivate(file: string, content: string, mode: number, validate?: (staged: string) => Promise<void>): Promise<void> {
-	const temporary = `${file}.${process.pid}.tmp`;
-	try {
-		await Bun.write(temporary, content);
-		await fs.chmod(temporary, mode);
-		await validate?.(temporary);
-		await fs.rename(temporary, file);
-	} catch (error) {
-		await fs.unlink(temporary).catch(() => undefined);
-		throw error;
-	}
-}
+export { currentJeoCommand, discordRunCommand, discordRunScript, messengerExecutablePath } from "./launcher";
+const writePrivate = writePrivateFile;
 
 async function readExistingConfig(configPath: string): Promise<Record<string, unknown> | undefined> {
 	let text: string;
@@ -587,16 +551,6 @@ async function createDefaultWorkspace(admit: (workspace: string) => Promise<void
 	return workspace;
 }
 
-export function currentJeoCommand(entry = Bun.main, execPath = process.execPath): string[] {
-	return entry === execPath || entry.startsWith("/$bunfs/") || entry.replaceAll("\\", "/").startsWith("B:/~BUN/") ? [execPath] : [execPath, entry];
-}
-
-export function messengerExecutablePath(execPath: string, inheritedPath: string | undefined, delimiter: string, platform: NodeJS.Platform): string {
-	const fallbackPath = platform === "win32" ? "" : "/usr/bin:/bin";
-	const runtimeDirectory = platform === "win32" ? path.win32.dirname(execPath) : path.dirname(execPath);
-	return [...new Set([runtimeDirectory, ...(inheritedPath ?? fallbackPath).split(delimiter).filter(Boolean)])].join(delimiter);
-}
-
 /** Create or repair a Discord messenger profile with as few manual steps as Discord allows. */
 export async function setupDiscordMessenger(
 	options: DiscordSetupOptions,
@@ -612,10 +566,11 @@ export async function setupDiscordMessenger(
 	if (options.service && platform !== "darwin" && platform !== "linux") {
 		throw new Error("Background services are supported only on macOS and Linux");
 	}
-	const runScript = path.join(directory, platform === "win32" ? RUN_SCRIPT_WINDOWS : RUN_SCRIPT_POSIX);
+	const runScript = path.join(directory, platform === "win32" ? MESSENGER_RUN_SCRIPT_WINDOWS : MESSENGER_RUN_SCRIPT_POSIX);
 	const delimiter = deps.pathDelimiter ?? path.delimiter;
 	const envPath = messengerExecutablePath(process.execPath, env.PATH, delimiter, platform);
-	const command = deps.jeoCommand ?? currentJeoCommand();
+	const runtime: MessengerRuntime = deps.jeoCommand ? { kind: "external", command: deps.jeoCommand } : (deps.runtime ?? messengerRuntimePlan());
+	const command = messengerRuntimeCommand(directory, runtime, process.execPath);
 	const existing = await readExistingConfig(configPath);
 	const sandbox = existing?.sandbox !== undefined ? parseMessengerSandbox(existing.sandbox) : parseMessengerSandbox({
 		image: await io.ask("Existing local Linux sandbox image (no image will be pulled): "),
@@ -629,7 +584,7 @@ export async function setupDiscordMessenger(
 		delete existing.independentSessions;
 		io.say("Removed obsolete independentSessions setting. Discord threads now keep one persistent session.");
 	}
-	if (platform === "win32") discordRunCommand(command, path.basename(configPath), DISCORD_TOKEN_ENV);
+	messengerLauncherContent(command, path.basename(configPath), DISCORD_TOKEN_ENV, envPath, platform);
 
 	const token = await resolveToken(env, tokenPath, io);
 	throwIfAborted(deps.signal);
@@ -670,7 +625,7 @@ export async function setupDiscordMessenger(
 	throwIfAborted(deps.signal);
 	const allowedChannelIds = [...new Set([...channelIds, ...(dmChannel ? [dmChannel] : [])])];
 	const tokenEnv = str(previous.tokenEnv) ?? DISCORD_TOKEN_ENV;
-	if (platform === "win32") discordRunCommand(command, path.basename(configPath), tokenEnv);
+	messengerLauncherContent(command, path.basename(configPath), tokenEnv, envPath, platform);
 
 	const discord: Record<string, unknown> = { ...previous, tokenEnv, allowedUserIds: userIds, allowedChannelIds };
 	if (options.artifacts) discord.artifactDir = "./artifacts";
@@ -708,25 +663,39 @@ export async function setupDiscordMessenger(
 		}
 	});
 	throwIfAborted(deps.signal);
-	await writePrivate(
-		runScript,
-		platform === "win32"
-			? discordRunCommand(command, path.basename(configPath), tokenEnv)
-			: discordRunScript(command, path.basename(configPath), tokenEnv, envPath),
-		0o700,
-	);
+	const registered = (await readMessengerProfiles(deps.profilesPath)).find(record => record.configPath === configPath);
+	if (runtime.kind === "managed") {
+		io.say(`Installing the messenger runtime ${MESSENGER_PACKAGE}@${runtime.version} under ${messengerRuntimeRoot(directory, runtime.version)}…`);
+		await provisionMessengerRuntime(directory, runtime.version, deps.runtimeDeps);
+		throwIfAborted(deps.signal);
+	}
+	await writePrivate(runScript, messengerLauncherContent(command, path.basename(configPath), tokenEnv, envPath, platform), 0o700);
 	throwIfAborted(deps.signal);
+	io.say(runtime.kind === "managed"
+		? `The launcher runs the pinned runtime ${MESSENGER_PACKAGE}@${runtime.version}; \`jeo update\` installs new versions here and restarts the service.`
+		: `The launcher runs ${command.join(" ")}; \`jeo update\` leaves it unchanged. Run setup from an installed jeo to pin a managed runtime.`);
 
 	await probeDiscordGateway(api, token, deps.WebSocket ?? WebSocket, deps.signal);
 	throwIfAborted(deps.signal);
 	io.say("Discord Gateway accepted the bot session and intents.");
 
+	const plan = messengerServicePlan(directory, runScript);
 	let service: string | undefined;
+	let serviceLabel = registered?.service;
 	if (options.service) {
-		service = await (deps.installService ?? installMessengerService)(messengerServicePlan(directory, runScript));
+		service = await (deps.installService ?? installMessengerService)(plan);
+		serviceLabel = plan.label;
 		throwIfAborted(deps.signal);
 		io.say(`Gateway running as ${service}`);
+	} else if ((await (deps.restartService ?? restartMessengerService)(plan, platform)) === "restarted") {
+		// A rewritten launcher only takes effect on the next start; an installed service restarts now rather than running stale code.
+		serviceLabel = plan.label;
+		io.say(`Restarted ${plan.label} on the new launcher.`);
 	}
+	throwIfAborted(deps.signal);
+	const removedRuntimes = await pruneMessengerRuntimes(directory, [runtime, registered?.runtime].flatMap(item => (item?.kind === "managed" ? [item.version] : [])));
+	if (removedRuntimes.length) io.say(`Removed stale messenger runtimes: ${removedRuntimes.join(", ")}.`);
+	await registerMessengerProfile({ configPath, runScript, runtime, ...(serviceLabel ? { service: serviceLabel } : {}), updatedAt: new Date().toISOString() }, deps.profilesPath);
 	if (dmChannel) {
 		try {
 			await api("POST", `/channels/${dmChannel}/messages`, { content: DM_TEST_MESSAGE });
@@ -747,6 +716,7 @@ export async function setupDiscordMessenger(
 		allowedUserIds: userIds,
 		allowedChannelIds,
 		runScript,
+		runtime,
 		...(service ? { service } : {}),
 	};
 }

package/src/messenger/gateway.ts

@@ -7,7 +7,7 @@ import type {
 	MessengerMessage,
 	MessengerReply,
 } from "./types";
-import { MessengerFatalError } from "./types";
+import { MessengerFatalError, MessengerUnverifiedReplyError } from "./types";
 
 const MAX_MESSAGE_LENGTH = 32_000;
 const MAX_QUEUED_MESSAGES = 100;
@@ -275,6 +275,12 @@ export interface MessengerGatewayOptions {
 	concurrency?: number;
 	/** Authenticated human controls bypass model queues, including busy sessions. */
 	sandboxControl?: (message: MessengerMessage, signal: AbortSignal) => Promise<{ handled: boolean; output: string }>;
+	/**
+	 * Operator log for a request that failed before or during delivery. Users see the generic failure text, except
+	 * an unverified completion, whose marked answer is delivered; this is the one place the cause is observable,
+	 * and it receives the conversation, never message text.
+	 */
+	onRequestError?: (message: MessengerMessage, error: unknown, stage: "prepare" | "reply" | "deliver") => void;
 }
 
 export function createMessengerGateway(
@@ -293,6 +299,9 @@ export function createMessengerGateway(
 	}
 	const seen = new Set<string>();
 	const queue: PendingMessage[] = [];
+	const reportError = (message: MessengerMessage, error: unknown, stage: "prepare" | "reply" | "deliver"): void => {
+		try { options.onRequestError?.(message, error, stage); } catch { /* Operator logging never affects the request. */ }
+	};
 	const activeKeys = new Set<string>();
 	const turns = new Set<Promise<void>>();
 	/** Orders admission (sandbox control, capacity check, destination preparation) per raw lane. */
@@ -363,18 +372,21 @@ export function createMessengerGateway(
 					return;
 				}
 				if (signal.aborted) return;
-				text = error instanceof DiscordModelSelectionError
-					? "Discord could not verify a model. Ask the operator to configure an explicit Discord model, check provider credentials and live model discovery, then restart the messenger service."
-					: "The request could not be completed. Please try again.";
+				reportError(message, error, "reply");
+				text = error instanceof MessengerUnverifiedReplyError
+					? error.reply
+					: error instanceof DiscordModelSelectionError
+						? "Discord could not verify a model. Ask the operator to configure an explicit Discord model, check provider credentials and live model discovery, then restart the messenger service."
+						: "The request could not be completed. Please try again.";
 			}
 			if (!signal.aborted && text.trim()) {
 				// A failed send may already have delivered a chunk: never retry the entire reply.
 				await adapter.send(message, text, signal);
 			}
 			if (!signal.aborted) status(failed ? "failure" : "success");
-		} catch {
+		} catch (error) {
 			failed = true;
-			if (!signal.aborted) status("failure");
+			if (!signal.aborted) { status("failure"); reportError(message, error, "deliver"); }
 		} finally {
 			await activity.close(failed ? "failure" : signal.aborted ? "cancelled" : "success");
 			resolve();
@@ -441,8 +453,8 @@ export function createMessengerGateway(
 			try {
 				destination = (await adapter.prepare?.(message, effectiveSignal)) ?? message;
 				key = messengerConversationKey(destination);
-			} catch {
-				if (!effectiveSignal.aborted) status("failure");
+			} catch (error) {
+				if (!effectiveSignal.aborted) { status("failure"); reportError(message, error, "prepare"); }
 				return;
 			} finally {
 				preparing--;

package/src/messenger/launcher.ts

@@ -0,0 +1,68 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+export const MESSENGER_TOKEN_FILE = "discord-token";
+export const MESSENGER_RUN_SCRIPT_POSIX = "run-discord.sh";
+export const MESSENGER_RUN_SCRIPT_WINDOWS = "run-discord.cmd";
+
+/** argv that starts the running jeo build: the compiled binary alone, or the runtime plus its entry script. */
+export function currentJeoCommand(entry = Bun.main, execPath = process.execPath): string[] {
+	return entry === execPath || entry.startsWith("/$bunfs/") || entry.replaceAll("\\", "/").startsWith("B:/~BUN/") ? [execPath] : [execPath, entry];
+}
+
+export function messengerExecutablePath(execPath: string, inheritedPath: string | undefined, delimiter: string, platform: NodeJS.Platform): string {
+	const fallbackPath = platform === "win32" ? "" : "/usr/bin:/bin";
+	const runtimeDirectory = platform === "win32" ? path.win32.dirname(execPath) : path.dirname(execPath);
+	return [...new Set([runtimeDirectory, ...(inheritedPath ?? fallbackPath).split(delimiter).filter(Boolean)])].join(delimiter);
+}
+
+/** The token is read from the 0600 file at launch, so it never lands in this script or a service definition. */
+export function discordRunScript(command: string[], configName: string, tokenEnv: string, envPath: string): string {
+	const quote = (value: string): string => `'${value.replace(/'/g, `'\\''`)}'`;
+	return `#!/bin/sh
+# Generated by \`jeo messenger setup\`: starts this profile's Discord gateway.
+set -eu
+dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+token_file="$dir/${MESSENGER_TOKEN_FILE}"
+case "$(ls -ln "$token_file" | cut -c5-10)" in
+	------) ;;
+	*) echo "${MESSENGER_TOKEN_FILE} must be readable by its owner only (chmod 600)" >&2; exit 1 ;;
+esac
+PATH=${quote(envPath)}
+export PATH
+${tokenEnv}=$(cat "$token_file")
+export ${tokenEnv}
+exec ${command.map(quote).join(" ")} messenger run --config "$dir/${configName}"
+`;
+}
+
+/** The Windows launcher inherits PATH at launch; the token remains in the private sidecar. */
+export function discordRunCommand(command: string[], configName: string, tokenEnv: string): string {
+	if (!/^[A-Za-z_]/u.test(tokenEnv) || /[^A-Za-z0-9_]/u.test(tokenEnv)) throw new Error("discord.tokenEnv must name an environment variable");
+	const literal = (value: string, label: string): string => {
+		if (/["\r\n]/.test(value)) throw new Error(`Windows launcher ${label} must not contain quotes or newlines`);
+		if (/[^\x00-\x7f]/.test(value)) throw new Error(`Windows launcher ${label} must contain only ASCII characters; use ASCII paths`);
+		return value.replace(/%/g, "%%");
+	};
+	const quote = (value: string): string => `"${literal(value, "command")}"`;
+	return `@echo off\r\nsetlocal DisableDelayedExpansion\r\nset /p "${tokenEnv}="<"%~dp0${MESSENGER_TOKEN_FILE}"\r\n${command.map(quote).join(" ")} messenger run --config "%~dp0${literal(configName, "config name")}"\r\n`;
+}
+
+/** Launcher text for `platform`; Windows input validation happens here, so callers can check before any side effect. */
+export function messengerLauncherContent(command: string[], configName: string, tokenEnv: string, envPath: string, platform: NodeJS.Platform): string {
+	return platform === "win32" ? discordRunCommand(command, configName, tokenEnv) : discordRunScript(command, configName, tokenEnv, envPath);
+}
+
+/** Stage `content` beside `file`, run `validate` on the staged copy, and only then replace `file`; failure leaves `file` untouched. */
+export async function writePrivateFile(file: string, content: string, mode: number, validate?: (staged: string) => Promise<void>): Promise<void> {
+	const temporary = `${file}.${process.pid}.tmp`;
+	try {
+		await Bun.write(temporary, content);
+		await fs.chmod(temporary, mode);
+		await validate?.(temporary);
+		await fs.rename(temporary, file);
+	} catch (error) {
+		await fs.unlink(temporary).catch(() => undefined);
+		throw error;
+	}
+}

package/src/messenger/runtime.ts

@@ -0,0 +1,255 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import pkg from "../../package.json";
+import { notifyDir } from "../agent/notify/paths";
+import { loadMessengerConfig } from "./config";
+import { currentJeoCommand, messengerExecutablePath, messengerLauncherContent, MESSENGER_RUN_SCRIPT_POSIX, MESSENGER_RUN_SCRIPT_WINDOWS, writePrivateFile } from "./launcher";
+import { messengerServicePlan, restartMessengerService } from "./service";
+import { isEnoent, isRecord } from "./types";
+
+/**
+ * A messenger profile runs its gateway and workers from one of two runtimes:
+ *
+ * - `managed`: a private copy of the published `jeo-code` package pinned to one version under
+ *   `<profile>/runtime/<version>` (jeopi's `runtime-<version>` layout). `jeo messenger setup` and
+ *   `jeo update` provision it, rewrite the launcher and restart the service, so the gateway never
+ *   depends on a mutable global install or a source checkout that can move away underneath it.
+ * - `external`: an explicit argv (a source checkout or compiled binary). Updates leave it alone.
+ */
+export type MessengerRuntime =
+	| { kind: "managed"; version: string }
+	| { kind: "external"; command: string[] };
+
+export interface MessengerProfileRecord {
+	configPath: string;
+	runScript: string;
+	runtime: MessengerRuntime;
+	/** Service label when a user service was installed for the profile. */
+	service?: string;
+	updatedAt: string;
+}
+
+export const MESSENGER_PACKAGE = "jeo-code";
+export const MESSENGER_RUNTIME_DIR = "runtime";
+export const MESSENGER_PROFILES_FILE = "messenger-profiles.json";
+const VERSION = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+
+/** `<prefix>/node_modules/jeo-code/src/cli.ts` is a package install (global or a managed runtime); anything else is a checkout or binary. */
+export function messengerRuntimePlan(entry = Bun.main, execPath = process.execPath, version = pkg.version): MessengerRuntime {
+	const command = currentJeoCommand(entry, execPath);
+	const parts = command.length === 2 ? command[1]!.replaceAll("\\", "/").split("/") : [];
+	const installed = parts.length >= 4 && parts.at(-1) === "cli.ts" && parts.at(-2) === "src" && parts.at(-3) === MESSENGER_PACKAGE && parts.at(-4) === "node_modules";
+	return installed && VERSION.test(version) ? { kind: "managed", version } : { kind: "external", command };
+}
+
+export function messengerRuntimeRoot(profileDir: string, version: string): string {
+	if (!VERSION.test(version)) throw new Error(`Invalid messenger runtime version: ${version}`);
+	return path.join(profileDir, MESSENGER_RUNTIME_DIR, version);
+}
+
+/** The argv a launcher uses for `runtime`; pure, so callers can validate it before provisioning. */
+export function messengerRuntimeCommand(profileDir: string, runtime: MessengerRuntime, execPath = process.execPath): string[] {
+	if (runtime.kind === "external") return runtime.command;
+	return [execPath, path.join(messengerRuntimeRoot(profileDir, runtime.version), "node_modules", MESSENGER_PACKAGE, "src", "cli.ts")];
+}
+
+async function installedRuntimeVersion(root: string): Promise<string | undefined> {
+	try {
+		const manifest: unknown = await Bun.file(path.join(root, "node_modules", MESSENGER_PACKAGE, "package.json")).json();
+		if (!isRecord(manifest) || typeof manifest.version !== "string") return undefined;
+		await fs.access(path.join(root, "node_modules", MESSENGER_PACKAGE, "src", "cli.ts"));
+		return manifest.version;
+	} catch (error) {
+		if (isEnoent(error) || error instanceof SyntaxError) return undefined;
+		throw error;
+	}
+}
+
+/** `bun install` the pinned package; `--force` recovers a registry manifest bun cached before a fresh publish. */
+async function installWithBun(root: string, execPath: string): Promise<void> {
+	let failure = "";
+	for (const extra of [[], ["--force"]]) {
+		const proc = Bun.spawn([execPath, "install", "--no-progress", "--no-summary", ...extra], { cwd: root, stdout: "pipe", stderr: "pipe", stdin: "ignore" });
+		const [stderr, code] = await Promise.all([new Response(proc.stderr).text(), proc.exited]);
+		if (code === 0) return;
+		failure = stderr.trim().split("\n").slice(-3).join(" ").trim() || `bun install exited with code ${code}`;
+	}
+	throw new Error(failure);
+}
+
+export interface MessengerRuntimeDeps {
+	/** Install `jeo-code@version` into `root` (its `package.json` is already written). Defaults to `bun install`. */
+	install?: (root: string, version: string) => Promise<void>;
+	execPath?: string;
+}
+
+/** Idempotent: an intact runtime for `version` is reused; a partial one is replaced. Failure leaves no runtime behind. */
+export async function provisionMessengerRuntime(profileDir: string, version: string, deps: MessengerRuntimeDeps = {}): Promise<string[]> {
+	const root = messengerRuntimeRoot(profileDir, version);
+	const execPath = deps.execPath ?? process.execPath;
+	const command = messengerRuntimeCommand(profileDir, { kind: "managed", version }, execPath);
+	if ((await installedRuntimeVersion(root)) === version) return command;
+	await fs.rm(root, { recursive: true, force: true });
+	await fs.mkdir(root, { recursive: true, mode: 0o700 });
+	await Bun.write(path.join(root, "package.json"), `${JSON.stringify({ name: "jeo-messenger-runtime", private: true, dependencies: { [MESSENGER_PACKAGE]: version } }, null, 2)}\n`);
+	try {
+		await (deps.install ?? (dir => installWithBun(dir, execPath)))(root, version);
+		const installed = await installedRuntimeVersion(root);
+		if (installed !== version) throw new Error(`the runtime contains ${MESSENGER_PACKAGE}@${installed ?? "nothing"}`);
+	} catch (error) {
+		await fs.rm(root, { recursive: true, force: true }).catch(() => undefined);
+		throw new Error(`Could not install the messenger runtime ${MESSENGER_PACKAGE}@${version}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+	return command;
+}
+
+/** Remove runtime versions other than `keep` (the active one and its predecessor, for rollback). Returns removed versions. */
+export async function pruneMessengerRuntimes(profileDir: string, keep: string[]): Promise<string[]> {
+	const directory = path.join(profileDir, MESSENGER_RUNTIME_DIR);
+	let entries: string[];
+	try { entries = await fs.readdir(directory); }
+	catch (error) { if (isEnoent(error)) return []; throw error; }
+	const removed: string[] = [];
+	for (const entry of entries) {
+		if (keep.includes(entry) || !VERSION.test(entry)) continue;
+		await fs.rm(path.join(directory, entry), { recursive: true, force: true });
+		removed.push(entry);
+	}
+	return removed;
+}
+
+export function messengerProfilesPath(): string {
+	return path.join(notifyDir(), MESSENGER_PROFILES_FILE);
+}
+
+function parseRuntime(value: unknown): MessengerRuntime | undefined {
+	if (!isRecord(value)) return undefined;
+	if (value.kind === "managed" && typeof value.version === "string" && VERSION.test(value.version)) return { kind: "managed", version: value.version };
+	if (value.kind === "external" && Array.isArray(value.command) && value.command.length && value.command.every(item => typeof item === "string" && item)) {
+		return { kind: "external", command: value.command as string[] };
+	}
+	return undefined;
+}
+
+/** Records whose profile no longer exists are dropped on read, so a deleted profile never fails a later refresh. */
+export async function readMessengerProfiles(file = messengerProfilesPath()): Promise<MessengerProfileRecord[]> {
+	let raw: unknown;
+	try { raw = await Bun.file(file).json(); }
+	catch (error) { if (isEnoent(error) || error instanceof SyntaxError) return []; throw error; }
+	if (!Array.isArray(raw)) return [];
+	const records: MessengerProfileRecord[] = [];
+	for (const item of raw) {
+		if (!isRecord(item) || typeof item.configPath !== "string" || typeof item.runScript !== "string" || !path.isAbsolute(item.configPath)) continue;
+		const runtime = parseRuntime(item.runtime);
+		if (!runtime || !(await fs.stat(item.configPath).then(stat => stat.isFile(), () => false))) continue;
+		records.push({
+			configPath: item.configPath,
+			runScript: item.runScript,
+			runtime,
+			...(typeof item.service === "string" && item.service ? { service: item.service } : {}),
+			updatedAt: typeof item.updatedAt === "string" ? item.updatedAt : new Date(0).toISOString(),
+		});
+	}
+	return records;
+}
+
+export async function registerMessengerProfile(record: MessengerProfileRecord, file = messengerProfilesPath()): Promise<void> {
+	const records = (await readMessengerProfiles(file)).filter(item => item.configPath !== record.configPath);
+	records.push(record);
+	await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+	await writePrivateFile(file, `${JSON.stringify(records, null, 2)}\n`, 0o600);
+}
+
+export interface MessengerRefreshDeps {
+	/** The runtime the running jeo offers; defaults to `messengerRuntimePlan()`. */
+	runtime?: MessengerRuntime;
+	runtimeDeps?: MessengerRuntimeDeps;
+	restartService?: typeof restartMessengerService;
+	profilesPath?: string;
+	env?: Record<string, string | undefined>;
+	platform?: NodeJS.Platform;
+	pathDelimiter?: string;
+	execPath?: string;
+	now?: () => Date;
+}
+
+export interface MessengerRefreshResult {
+	configPath: string;
+	runtime: MessengerRuntime;
+	service: "restarted" | "not installed";
+	removedRuntimes: string[];
+}
+
+/**
+ * Point one profile's launcher at the runtime the running jeo offers, restart its installed service and prune
+ * stale runtimes. A managed runtime is provisioned before the launcher changes, so a failed install leaves the
+ * previous launcher and service untouched.
+ */
+export async function refreshMessengerProfile(configPath: string, deps: MessengerRefreshDeps = {}): Promise<MessengerRefreshResult> {
+	const platform = deps.platform ?? process.platform;
+	const execPath = deps.execPath ?? process.execPath;
+	const runtime = deps.runtime ?? messengerRuntimePlan();
+	const resolvedConfig = path.resolve(configPath);
+	const directory = path.dirname(resolvedConfig);
+	const config = await loadMessengerConfig(resolvedConfig);
+	const tokenEnv = config.platforms.discord?.tokenEnv ?? "JEO_DISCORD_BOT_TOKEN";
+	const configName = path.basename(resolvedConfig);
+	const envPath = messengerExecutablePath(execPath, (deps.env ?? process.env).PATH, deps.pathDelimiter ?? path.delimiter, platform);
+	// Validate launcher inputs for the planned command before provisioning anything.
+	messengerLauncherContent(messengerRuntimeCommand(directory, runtime, execPath), configName, tokenEnv, envPath, platform);
+	const previous = (await readMessengerProfiles(deps.profilesPath)).find(record => record.configPath === resolvedConfig);
+	const command = runtime.kind === "managed" ? await provisionMessengerRuntime(directory, runtime.version, { execPath, ...deps.runtimeDeps }) : runtime.command;
+	const runScript = path.join(directory, platform === "win32" ? MESSENGER_RUN_SCRIPT_WINDOWS : MESSENGER_RUN_SCRIPT_POSIX);
+	await writePrivateFile(runScript, messengerLauncherContent(command, configName, tokenEnv, envPath, platform), 0o700);
+	const plan = messengerServicePlan(directory, runScript);
+	const service = await (deps.restartService ?? restartMessengerService)(plan, platform);
+	const keep = [runtime, previous?.runtime].flatMap(item => (item?.kind === "managed" ? [item.version] : []));
+	const removedRuntimes = runtime.kind === "managed" ? await pruneMessengerRuntimes(directory, keep) : [];
+	await registerMessengerProfile({
+		configPath: resolvedConfig,
+		runScript,
+		runtime,
+		...(service === "restarted" ? { service: plan.label } : previous?.service ? { service: previous.service } : {}),
+		updatedAt: (deps.now ?? (() => new Date()))().toISOString(),
+	}, deps.profilesPath);
+	return { configPath: resolvedConfig, runtime, service, removedRuntimes };
+}
+
+/**
+ * `jeo messenger update`: refresh the named profiles, or every registered managed one. Without explicit
+ * paths, a profile on an external runtime (a checkout or binary the operator chose) is reported and left
+ * alone; naming it with `--config` re-pins it to the running jeo. Failures are reported per profile.
+ */
+export async function refreshMessengerProfiles(
+	configPaths: string[] | undefined,
+	say: (line: string) => void,
+	deps: MessengerRefreshDeps = {},
+): Promise<{ refreshed: number; failed: number; skipped: number }> {
+	const explicit = Boolean(configPaths?.length);
+	const records = explicit ? [] : await readMessengerProfiles(deps.profilesPath);
+	const targets = explicit ? configPaths!.map(file => path.resolve(file)) : records.filter(record => record.runtime.kind === "managed").map(record => record.configPath);
+	let skipped = 0;
+	for (const record of records) {
+		if (record.runtime.kind !== "external") continue;
+		skipped++;
+		say(`${record.configPath}: launcher runs ${record.runtime.command.join(" ")} (external); left unchanged. Pass --config to re-pin it.`);
+	}
+	if (!targets.length && !skipped) {
+		say("No messenger profiles are registered; run `jeo messenger setup --config <file>` first.");
+		return { refreshed: 0, failed: 0, skipped: 0 };
+	}
+	let refreshed = 0;
+	let failed = 0;
+	for (const configPath of targets) {
+		try {
+			const result = await refreshMessengerProfile(configPath, deps);
+			refreshed++;
+			const where = result.runtime.kind === "managed" ? `${MESSENGER_PACKAGE}@${result.runtime.version} (managed runtime)` : `${result.runtime.command.join(" ")} (external; \`jeo update\` leaves it unchanged)`;
+			say(`${configPath}: launcher runs ${where}; service ${result.service}${result.removedRuntimes.length ? `; removed runtimes ${result.removedRuntimes.join(", ")}` : ""}.`);
+		} catch (error) {
+			failed++;
+			say(`${configPath}: not refreshed — ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return { refreshed, failed, skipped };
+}