jeo-code 0.12.17 → 0.12.20

package/src/commands/launch.ts

@@ -66,6 +66,7 @@ import type { SandboxConfig, SandboxSupervisor } from "../agent/sandbox/types";
 import { runAgySessionTurn } from "./launch/agy-turn";
 import { listProviderModels } from "../ai/model-discovery";
 import { rememberModelPatch, recentModelsForDisplay } from "../agent/model-recency";
+import { resolveStartupDefaultModel } from "../agent/session-model";
 import { describeModel, describeAllProviders, describeProvider, resolveProvider, thinkingMaxTokens, resolveMaxOutputTokens, thinkingToReasoningEffort, discoverModels, flattenModels, resolveSelection, catalogMetadata, catalogByProvider, liveProviderCatalogModels, resolveRoleModel, CODEX_MODELS, qualifyModelId, modelServableWithConfig, isLocalProviderReachable } from "../ai";
 import { rehydrateLiveModels, writeModelCache } from "../ai/model-cache";
 import type { ProviderModelsResult, PickEntry, ProviderName, ModelRole, ThinkLevel } from "../ai";
@@ -544,7 +545,6 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
     }
   } catch {}
   const cfg = await readGlobalConfig();
-  const defaultModel = cfg.defaultModel;
   let initialSessionModel =
     flags.model ??
     (flags.modelRole ? resolveRoleModel(flags.modelRole, cfg) : flags.provider ? providerDefaultModel(flags.provider) : undefined);
@@ -564,6 +564,11 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
       return;
     }
   }
+  // A session always opens on the configured default model, or, when the stored login cannot
+  // serve it, on the first authenticated model (session-local; the saved default is untouched).
+  // An explicit --model/--model-role/--provider pin takes precedence and skips this.
+  const startupModel = initialSessionModel === undefined ? await resolveStartupDefaultModel(cfg) : { model: cfg.defaultModel, notice: undefined };
+  const defaultModel = startupModel.model;
 
   if (flags.tmux) {
     if (!process.env.TMUX && jeoEnv("TMUX_LAUNCHED") !== "1") {
@@ -987,7 +992,6 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
             const { header, messages } = await loadSession(id, cwd);
             for (const m of messages) history.push(m);
             sessionId = id;
-            if (!initialSessionModel && header.model) sessionModel = header.model;
             const modelNote = sessionModel ? ` · model ${sessionModel}` : "";
             console.log(`Resumed session ${id} (${messages.length} messages).${modelNote}`);
             // Reproduce the prior screen exactly (gjc/gajae-code parity): a bare
@@ -1049,9 +1053,6 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
           const { header, messages } = await loadSession(id, cwd);
           for (const m of messages) history.push(m);
           sessionId = id;
-          // Restore the model this session was last using unless the CLI explicitly
-          // pinned one (flags.model/role/provider → initialSessionModel wins).
-          if (!initialSessionModel && header.model) sessionModel = header.model;
           // Restore the unsent input-box draft (gajae-code parity) — see
           // startupDraft's own doc comment for why this path can't feed
           // queuedPromptInput.partial directly yet.
@@ -2497,6 +2498,7 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
   };
 
   if (isOneShot) {
+    if (startupModel.notice) console.error(startupModel.notice);
     // A one-shot run has ~17 exit points below. The session notify endpoint (a
     // listening socket + a discovery file the Telegram daemon polls) is created for
     // the WHOLE launch lifetime up at `startSessionNotifyEndpoint`, but its teardown
@@ -2843,6 +2845,7 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
     if (sweepable) await playWelcomeSweep(welcomeData, { cycles: sweepCycles });
     else console.log(renderWelcome(welcomeData).join("\n"));
   }
+  if (startupModel.notice) console.log(chalk.yellow(startupModel.notice));
 
 
 

package/src/commands/messenger.ts

@@ -6,6 +6,7 @@ import { Writable } from "node:stream";
 import { loadMessengerConfig, parseMessengerSandbox, validateMessengerEnvironment, validateMessengerStorage } from "../messenger/config";
 import { createDiscordAdapter } from "../messenger/discord";
 import { setupDiscordMessenger } from "../messenger/discord-setup";
+import { refreshMessengerProfiles } from "../messenger/runtime";
 import { messengerArtifactPrompt } from "../messenger/artifacts";
 import { createMessengerGateway, messengerSessionRoute } from "../messenger/gateway";
 import { createMessengerSessionPool } from "../messenger/session-pool";
@@ -61,11 +62,12 @@ async function sendSandboxControl(config: MessengerConfig, id: string, userId: s
 	return promise;
 }
 
+type MessengerAction = "setup" | "check" | "run" | "update";
 type Flags = { config?: string; channel: string[]; user: string[]; tools?: string; artifacts: boolean; service: boolean; noDm: boolean };
 
-function parse(args: string[]): { action: "setup" | "check" | "run"; flags: Flags } {
+function parse(args: string[]): { action: MessengerAction; flags: Flags } {
 	const action = args.shift();
-	if (action !== "setup" && action !== "check" && action !== "run") throw new Error("Usage: jeo messenger setup|check|run --config <file>");
+	if (action !== "setup" && action !== "check" && action !== "run" && action !== "update") throw new Error("Usage: jeo messenger setup|check|run --config <file> | jeo messenger update [--config <file>]");
 	const flags: Flags = { channel: [], user: [], artifacts: false, service: false, noDm: false };
 	for (let index = 0; index < args.length; index++) {
 		const arg = args[index]!;
@@ -80,7 +82,7 @@ function parse(args: string[]): { action: "setup" | "check" | "run"; flags: Flag
 			else flags[arg === "--channel" ? "channel" : "user"].push(...value.split(",").filter(Boolean));
 		} else throw new Error(`Unknown messenger option: ${arg}`);
 	}
-	if (!flags.config) throw new Error("Messenger requires --config <file>");
+	if (!flags.config && action !== "update") throw new Error("Messenger requires --config <file>");
 	return { action, flags };
 }
 
@@ -113,11 +115,20 @@ function routeUuid(config: MessengerConfig, message: Parameters<MessengerReply>[
 	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
 }
 
+export interface MessengerCliReplyOptions {
+	/** Operator log line sink (gateway stderr); receives bounded worker diagnostics, never message text or tokens. */
+	log?: (line: string) => void;
+}
+
 /** Run each conversation in its own reusable agent process. */
-export function createMessengerCliReply(config: MessengerConfig, spawn: typeof Bun.spawn = Bun.spawn, selectModel: typeof selectDiscordModel = selectDiscordModel): MessengerReply & { close(): Promise<void>; sandboxControl: NonNullable<MessengerGatewayOptions["sandboxControl"]> } {
+export function createMessengerCliReply(config: MessengerConfig, spawn: typeof Bun.spawn = Bun.spawn, selectModel: typeof selectDiscordModel = selectDiscordModel, options: MessengerCliReplyOptions = {}): MessengerReply & { close(): Promise<void>; sandboxControl: NonNullable<MessengerGatewayOptions["sandboxControl"]> } {
 	const sandbox = config.sandbox !== undefined || config.platforms.discord ? parseMessengerSandbox(config.sandbox) : undefined;
 	// Launch may inherit a global sandbox even when this platform has no local override.
-	const pool = createMessengerSessionPool(spawn, undefined, undefined, undefined, { requireSandboxCleanup: true });
+	const log = options.log;
+	const pool = createMessengerSessionPool(spawn, undefined, undefined, undefined, {
+		requireSandboxCleanup: true,
+		...(log ? { onDiagnostic: (key: string, line: string) => log(`worker ${key.slice(0, 8)}: ${line}`) } : {}),
+	});
 	const reply: MessengerReply = async (message, signal, onActivity) => {
 		if (signal.aborted) throw new Error("Messenger request aborted");
 		await validateMessengerStorage(config);
@@ -208,6 +219,12 @@ export async function runMessengerCommand(args: string[]): Promise<void> {
 		} finally { process.off("SIGINT", stop); process.off("SIGTERM", stop); io.close(); }
 		return;
 	}
+	if (action === "update") {
+		// Re-pin every registered profile (or the named one) to the jeo running this command, then restart its service.
+		const { failed } = await refreshMessengerProfiles(flags.config ? [flags.config] : undefined, line => process.stdout.write(`${line}\n`));
+		if (failed) process.exitCode = 1;
+		return;
+	}
 	let config: MessengerConfig;
 	try { config = await loadMessengerConfig(flags.config!); validateMessengerEnvironment(config); }
 	catch (error) { throw new Error(error instanceof Error ? error.message : "Messenger configuration or required environment is invalid"); }
@@ -221,7 +238,10 @@ export async function runMessengerCommand(args: string[]): Promise<void> {
 	const controller = new AbortController();
 	const stop = () => controller.abort();
 	process.once("SIGINT", stop); process.once("SIGTERM", stop);
-	const reply = createMessengerCliReply(config);
-	try { process.stdout.write(`Starting messenger: ${platforms.join(", ")}. Press Ctrl+C to stop.\n`); await createMessengerGateway(config, adapters, reply, { concurrency: 4, sandboxControl: reply.sandboxControl }).run(controller.signal); }
+	const log = (line: string): void => { process.stderr.write(`[jeo messenger ${new Date().toISOString()}] ${line}\n`); };
+	const reply = createMessengerCliReply(config, undefined, undefined, { log });
+	const onRequestError: NonNullable<MessengerGatewayOptions["onRequestError"]> = (message, error, stage) =>
+		log(`${message.platform} request failed at ${stage} (conversation ${routeUuid(config, message).slice(0, 8)}): ${error instanceof Error ? error.message : String(error)}`);
+	try { process.stdout.write(`Starting messenger: ${platforms.join(", ")}. Press Ctrl+C to stop.\n`); await createMessengerGateway(config, adapters, reply, { concurrency: 4, sandboxControl: reply.sandboxControl, onRequestError }).run(controller.signal); }
 	finally { controller.abort(); await reply.close(); process.off("SIGINT", stop); process.off("SIGTERM", stop); }
 }

package/src/commands/update.ts

@@ -1,4 +1,6 @@
+import { existsSync } from "node:fs";
 import pkg from "../../package.json";
+import { messengerProfilesPath } from "../messenger/runtime";
 
 /**
  * Compares two semver-ish version strings.
@@ -38,6 +40,13 @@ export interface UpdateDeps {
   install: (version?: string) => Promise<{ success: boolean; stdout?: string; stderr?: string }>;
   /** Display release notes after a successful self-update (best-effort, no-op in tests). */
   showWhatsNew?: () => void;
+  /**
+   * Re-pin registered messenger profiles to the freshly installed jeo and restart their services
+   * (`jeo messenger update` of the NEW binary). Returns null when no profile is registered, else whether
+   * every profile was refreshed. `quiet` keeps the child's output off stdout for `--json`. Optional in
+   * tests; failures never fail the update.
+   */
+  refreshMessengers?: (quiet: boolean) => boolean | null;
   /** Version of the `jeo` actually on PATH, read after install to catch a silent no-op
    *  (installed but PATH still points at a different/older binary). Optional in tests. */
   activeVersion?: () => string | null;
@@ -129,6 +138,20 @@ export const defaultDeps: UpdateDeps = {
     } catch {
       // Notes are a courtesy; a spawn failure must never fail the update.
     }
+  },
+  refreshMessengers: quiet => {
+    // Only profiles registered by `jeo messenger setup` have runtimes to move; everyone else sees nothing.
+    if (!existsSync(messengerProfilesPath())) return null;
+    try {
+      if (!quiet) console.log("Refreshing messenger runtimes...");
+      // The NEW binary knows its own launcher format and version, so it performs the refresh.
+      const proc = Bun.spawnSync(["jeo", "messenger", "update"], quiet ? { stdout: "ignore", stderr: "ignore" } : { stdout: "inherit", stderr: "inherit" });
+      if (!proc.success && !quiet) console.error("Messenger runtimes were not all refreshed; run 'jeo messenger update' to retry.");
+      return proc.success;
+    } catch {
+      if (!quiet) console.error("Messenger runtimes were not refreshed; run 'jeo messenger update' to retry.");
+      return false;
+    }
   }
 };
 
@@ -310,11 +333,13 @@ export async function runUpdateCommandWith(args: string[], deps: UpdateDeps): Pr
           const active = deps.activeVersion?.();
           const stale = !!(active && latest && compareVersions(active, latest) < 0);
           if (hasJson) {
+            const messengersRefreshed = stale ? null : (deps.refreshMessengers?.(true) ?? null);
             console.log(JSON.stringify({
               current,
               latest,
               upToDate: false,
               installed: !stale,
+              ...(messengersRefreshed === null ? {} : { messengersRefreshed }),
               ...(stale ? { activeVersion: active, error: "active jeo still reports an older version" } : {}),
             }));
             if (stale) process.exitCode = 1;
@@ -327,6 +352,7 @@ export async function runUpdateCommandWith(args: string[], deps: UpdateDeps): Pr
             process.exitCode = 1;
           } else {
             console.log(`Successfully installed jeo-code@${latest}`);
+            deps.refreshMessengers?.(false);
             deps.showWhatsNew?.();
           }
         } else {
@@ -337,15 +363,18 @@ export async function runUpdateCommandWith(args: string[], deps: UpdateDeps): Pr
           const recovered = deps.activeVersion?.();
           if (recovered && latest && compareVersions(recovered, latest) >= 0) {
             if (hasJson) {
+              const messengersRefreshed = deps.refreshMessengers?.(true) ?? null;
               console.log(JSON.stringify({
                 current,
                 latest,
                 upToDate: false,
                 installed: true,
-                recovered: true
+                recovered: true,
+                ...(messengersRefreshed === null ? {} : { messengersRefreshed })
               }));
             } else {
               console.log(`Successfully installed jeo-code@${latest} (package manager reported an error, but the runtime verified clean).`);
+              deps.refreshMessengers?.(false);
               deps.showWhatsNew?.();
             }
           } else {

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

@@ -275,6 +275,11 @@ 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 only ever see the generic failure
+	 * text, so this is the one place the cause is observable; it receives the conversation, never message text.
+	 */
+	onRequestError?: (message: MessengerMessage, error: unknown, stage: "prepare" | "reply" | "deliver") => void;
 }
 
 export function createMessengerGateway(
@@ -293,6 +298,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,6 +371,7 @@ export function createMessengerGateway(
 					return;
 				}
 				if (signal.aborted) return;
+				reportError(message, error, "reply");
 				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.";
@@ -372,9 +381,9 @@ export function createMessengerGateway(
 				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 +450,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;
+	}
+}