auto-model-router 0.7.3 → 0.8.0

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.7.3",
+    "version": "0.8.0",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.7.3",
+      "version": "0.8.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -1306,6 +1306,17 @@ whatever else is authenticated. A local router deliberately gets no such entry
 is ephemeral, so a persisted one names a dead socket next launch — but a remote's URL and
 key are stable. **The file then holds the member key: treat it as a secret.**
 
+**Short-lived keys.** A remote that issues them (the team edition does) hands `connect` a
+refresh token beside the key (`--refresh-token`, `--key-expires`, `--refresh-expires`,
+`--device`), all kept in `remote.json`. The omp extension trades the refresh token for a
+new key a day before expiry, at session start, and re-writes every config `connect`
+wrote; `auto-model-router refresh` does the same by hand (`--force` to do it early), and
+`auto-model-router token` prints a key that is good right now, refreshing first if needed —
+the shape a harness key-helper wants (Claude Code's `apiKeyHelper`). The remote keeps the
+old key valid until its own expiry, so a session still holding it is never cut. A refresh
+token presented twice means the credential was copied: the remote revokes that device, and
+the machine onboards again.
+
 In remote mode omp sends `X-Agentdox-Scope` derived from the workspace folder, so one
 remote router serves every repo on the machine with that repo's shared context. The remote
 decides what to do with it: a team edition that pins a scope on the member's group

package/omp-extension/remote-logic.ts

@@ -22,6 +22,12 @@ export interface RemoteRouter {
 	userId: string;
 	name: string;
 	joinedAtMs: number;
+	/** Present when the remote issues short-lived keys: trades for the next key (see src/cli/refresh.ts). */
+	refreshToken?: string;
+	keyExpiresAtMs?: number;
+	refreshExpiresAtMs?: number;
+	/** What the remote calls this machine. */
+	device?: string;
 }
 
 export function remoteFilePath(routerHome: string): string {
@@ -33,7 +39,17 @@ export function parseRemoteRouter(text: string): RemoteRouter | null {
 	try {
 		const raw = JSON.parse(text) as Record<string, unknown>;
 		if (typeof raw.url !== "string" || typeof raw.key !== "string" || raw.url === "" || raw.key === "") return null;
-		return { url: raw.url.replace(/\/+$/, ""), key: raw.key, userId: typeof raw.userId === "string" ? raw.userId : "", name: typeof raw.name === "string" ? raw.name : "", joinedAtMs: typeof raw.joinedAtMs === "number" ? raw.joinedAtMs : 0 };
+		return {
+			url: raw.url.replace(/\/+$/, ""),
+			key: raw.key,
+			userId: typeof raw.userId === "string" ? raw.userId : "",
+			name: typeof raw.name === "string" ? raw.name : "",
+			joinedAtMs: typeof raw.joinedAtMs === "number" ? raw.joinedAtMs : 0,
+			...(typeof raw.refreshToken === "string" && raw.refreshToken !== "" ? { refreshToken: raw.refreshToken } : {}),
+			...(typeof raw.keyExpiresAtMs === "number" ? { keyExpiresAtMs: raw.keyExpiresAtMs } : {}),
+			...(typeof raw.refreshExpiresAtMs === "number" ? { refreshExpiresAtMs: raw.refreshExpiresAtMs } : {}),
+			...(typeof raw.device === "string" && raw.device !== "" ? { device: raw.device } : {}),
+		};
 	} catch {
 		return null;
 	}

package/omp-extension/router-embed.ts

@@ -27,6 +27,7 @@ import { ompModelsPath } from "../src/cli/config-cmd.ts";
 import { loadConfig } from "../src/config/load.ts";
 import { startServer } from "../src/server/http.ts";
 import { readRemoteRouter, remoteProviderRegistration } from "./remote-logic.ts";
+import { refreshAndRewrite, shouldRefresh } from "../src/cli/refresh.ts";
 import type { StartedServer } from "../src/server/http.ts";
 import type { RouterConfig } from "../src/config/types.ts";
 
@@ -161,8 +162,21 @@ export default function (pi: ExtensionAPI): void {
 		// Remote mode (`auto-model-router connect`): a router elsewhere is the
 		// router. Register it as the provider with its key and bind nothing
 		// locally; the other extensions find it through remote.json.
-		const remote = readRemoteRouter(routerHome());
+		let remote = readRemoteRouter(routerHome());
 		if (remote !== null) {
+			// A short-lived key is traded a day ahead of its expiry, and every config
+			// re-written, so no session ever starts on a dead key. The remote keeps the
+			// old key valid until its own expiry, so this session's main handle (which
+			// omp resolved from models.yml before we loaded) is not cut either way.
+			if (shouldRefresh(remote)) {
+				try {
+					const fresh = await refreshAndRewrite({ remote });
+					remote = { ...remote, key: fresh.key, refreshToken: fresh.refreshToken, keyExpiresAtMs: fresh.keyExpiresAtMs, refreshExpiresAtMs: fresh.refreshExpiresAtMs };
+					writeEmbedLog(`remote credential refreshed; key valid until ${new Date(fresh.keyExpiresAtMs).toISOString()}`);
+				} catch (err) {
+					writeEmbedLog(`remote credential refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}
 			pi.registerProvider(EMBED_PROVIDER_ID, remoteProviderRegistration(remote, sessionId, !ctx.hasUI, cfg.ledger.fallbackBlend, deriveAgentdoxScope(process.cwd())));
 			pi.setLabel(`auto-model-router remote (${remote.url.replace(/^https?:\/\//, "")})`);
 			writeEmbedLog(`remote mode url=${remote.url} user=${remote.userId} session=${sessionId}`);

package/omp-extension/toast-logic.ts

@@ -152,14 +152,13 @@ const clip = (text: string, max: number): string => (text.length > max ? `${text
 export function whyReasons(reasons: readonly string[] | undefined, limit = 2): string[] {
 	if (reasons === undefined || reasons.length === 0) return [];
 	const picked: string[] = [];
-	const seen = new Set<number>();
+	// One line per category: the router often records the same fact twice from
+	// different angles ("policy: pinned to x" beside "pinned to x by session
+	// override"), and a toast that says it twice has wasted half its room.
 	for (const re of REASON_PRIORITY) {
-		for (let i = 0; i < reasons.length && picked.length < limit; i++) {
-			const r = reasons[i];
-			if (r === undefined || seen.has(i) || !re.test(r)) continue;
-			seen.add(i);
-			picked.push(clip(r.replace(/\s+/g, " ").trim(), 90));
-		}
+		const hit = reasons.find((r) => re.test(r));
+		if (hit === undefined) continue;
+		picked.push(clip(hit.replace(/\s+/g, " ").trim(), 90));
 		if (picked.length >= limit) break;
 	}
 	// Nothing matched a pattern: the first reason is the ranking rationale itself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/cli/connect.ts

@@ -44,8 +44,13 @@ export interface ConnectOptions {
 	packageDir: string;
 	/** Cost figures omp shows for the remote's virtual models, USD per million tokens. */
 	blend?: { inputPerMtok: number; outputPerMtok: number };
-	/** Adds `X-Agentdox-Scope` to omp's models.yml entry. Machine-wide: only for a single-project machine. */
+	/** Adds `X-Agentdox-Scope` to omp's models.yml entry. Machine-wide: only for a single-project machine. Undefined keeps what the managed block already has. */
 	agentdoxScope?: string;
+	/** Short-lived credential fields from a remote that issues them; absent for a permanent key. */
+	refreshToken?: string;
+	keyExpiresAtMs?: number;
+	refreshExpiresAtMs?: number;
+	device?: string;
 	platform: string;
 	pathHas: (bin: string) => boolean;
 }
@@ -190,6 +195,16 @@ export function mergeModelsYml(before: string, blockText: string): string {
 	return `${body.replace(/\s*$/, "")}${eol}providers:${eol}${block}${eol}`;
 }
 
+/** The `X-Agentdox-Scope` the managed block carries, or "" when none. */
+export function existingBlockScope(text: string): string {
+	const begin = text.indexOf(MODELS_YML_BEGIN);
+	if (begin < 0) return "";
+	const end = text.indexOf(MODELS_YML_END, begin);
+	const block = text.slice(begin, end < 0 ? text.length : end);
+	const m = /X-Agentdox-Scope:\s*(\S+)/.exec(block);
+	return m?.[1] ?? "";
+}
+
 /** True when the file already defines our provider outside a block we manage. */
 export function hasForeignRouterProvider(text: string): boolean {
 	if (text.includes(MODELS_YML_BEGIN)) return false;
@@ -207,7 +222,25 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 	// 1. remote.json: what puts the omp extensions into remote mode.
 	const rh = routerHomeOf(o);
 	report.remoteFile = remoteFilePath(rh);
-	write(report.remoteFile, `${JSON.stringify({ url: o.url, key: o.key, userId: o.userId, name: o.name, joinedAtMs: Date.now() }, null, 2)}\n`);
+	const previous = existsSync(report.remoteFile) ? (JSON.parse(readFileSync(report.remoteFile, "utf8")) as Record<string, unknown>) : {};
+	write(
+		report.remoteFile,
+		`${JSON.stringify(
+			{
+				url: o.url,
+				key: o.key,
+				userId: o.userId,
+				name: o.name,
+				joinedAtMs: typeof previous.joinedAtMs === "number" ? previous.joinedAtMs : Date.now(),
+				...(o.refreshToken !== undefined && o.refreshToken !== "" ? { refreshToken: o.refreshToken } : {}),
+				...(o.keyExpiresAtMs !== undefined ? { keyExpiresAtMs: o.keyExpiresAtMs } : {}),
+				...(o.refreshExpiresAtMs !== undefined ? { refreshExpiresAtMs: o.refreshExpiresAtMs } : {}),
+				...(o.device !== undefined && o.device !== "" ? { device: o.device } : {}),
+			},
+			null,
+			2,
+		)}\n`,
+	);
 
 	// 2. omp
 	const agentDir = ompAgentDir(o);
@@ -225,7 +258,9 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 			report.notes.push(`${modelsPath} already defines an auto-model-router provider by hand; left alone — remove it to let connect manage the remote entry`);
 			report.configured.push(`omp (${cfgPath}; extensions only)`);
 		} else {
-			const modelsAfter = mergeModelsYml(modelsBefore, renderRemoteModelsYml(o.url, o.key, o.blend ?? { inputPerMtok: 1.1, outputPerMtok: 4.4 }, o.agentdoxScope ?? ""));
+			// A refresh re-writes the block without knowing the scope: keep the one already there.
+			const scope = o.agentdoxScope ?? existingBlockScope(modelsBefore);
+			const modelsAfter = mergeModelsYml(modelsBefore, renderRemoteModelsYml(o.url, o.key, o.blend ?? { inputPerMtok: 1.1, outputPerMtok: 4.4 }, scope));
 			if (modelsAfter !== modelsBefore) {
 				// Never overwrite another provider's work without a way back.
 				if (modelsBefore !== "" && !o.dryRun) writeFileSync(`${modelsPath}.${new Date().toISOString().replaceAll(":", "-")}.bak`, modelsBefore, "utf8");
@@ -292,6 +327,7 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 		}
 	} else report.notes.push("add the environment lines to your shell profile, or re-run with --profile");
 	report.notes.push("omp's models.yml now carries the member key; treat that file as a secret");
+	if (o.refreshToken !== undefined && o.refreshToken !== "") report.notes.push("the key is short-lived: omp refreshes it at session start; `auto-model-router refresh` does it by hand, and `auto-model-router token` prints a current key for a harness key-helper");
 	return report;
 }
 
@@ -316,8 +352,31 @@ export async function connectCommand(args: CliArgs): Promise<void> {
 	const home = process.env.HOME !== undefined && process.env.HOME !== "" ? process.env.HOME : homedir();
 	// A single-project machine can label every request; a machine with several
 	// repos should leave it off and let the extensions send the workspace's own.
-	const agentdoxScope = flagString(args, "scope") ?? "";
-	const report = connectRemote({ url, key, userId, name, profile: args.flags.has("profile"), dryRun: args.flags.has("dry-run"), only, env: process.env, home, packageDir, platform: process.platform, pathHas, agentdoxScope });
+	const scopeFlag = flagString(args, "scope");
+	// A remote that issues short-lived keys hands these over beside the key.
+	const refreshToken = flagString(args, "refresh-token") ?? "";
+	const keyExpires = Number.parseInt(flagString(args, "key-expires") ?? "", 10);
+	const refreshExpires = Number.parseInt(flagString(args, "refresh-expires") ?? "", 10);
+	const device = flagString(args, "device") ?? "";
+	const report = connectRemote({
+		url,
+		key,
+		userId,
+		name,
+		profile: args.flags.has("profile"),
+		dryRun: args.flags.has("dry-run"),
+		only,
+		env: process.env,
+		home,
+		packageDir,
+		platform: process.platform,
+		pathHas,
+		...(scopeFlag === undefined ? {} : { agentdoxScope: scopeFlag }),
+		...(refreshToken === "" ? {} : { refreshToken }),
+		...(Number.isFinite(keyExpires) ? { keyExpiresAtMs: keyExpires } : {}),
+		...(Number.isFinite(refreshExpires) ? { refreshExpiresAtMs: refreshExpires } : {}),
+		...(device === "" ? {} : { device }),
+	});
 	console.log(`${args.flags.has("dry-run") ? "would write" : "wrote"} ${report.remoteFile}${name === "" ? "" : ` for ${name}`}`);
 	for (const c of report.configured) console.log(`  configured ${c}`);
 	for (const s of report.skipped) console.log(`  skipped    ${s}`);

package/src/cli/refresh.ts

@@ -0,0 +1,139 @@
+/**
+ * Short-lived remote credentials.
+ *
+ * A remote router (the team edition) may hand a machine an access key that
+ * expires plus a refresh token that trades for the next one. `remote.json`
+ * carries all of it; `auto-model-router refresh` trades early and re-writes
+ * every harness config `connect` wrote, and `auto-model-router token` prints a
+ * key that is good right now (refreshing first when needed), which is what a
+ * harness that can run a command for its key — Claude Code's `apiKeyHelper` —
+ * wants. The omp extension refreshes on its own at session start.
+ *
+ * A refresh a day early costs nothing: the remote keeps the old key valid until
+ * its own expiry, so a session still holding it is never cut.
+ */
+
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readRemoteRouter, type RemoteRouter } from "../../omp-extension/remote-logic.ts";
+import { routerHome } from "../../omp-extension/router-url.ts";
+import type { CliArgs } from "./args.ts";
+import { connectRemote } from "./connect.ts";
+
+/** How close to expiry a key is refreshed. Wide, so a machine used once a day never sees a dead key. */
+export const REFRESH_AHEAD_MS = 24 * 3_600_000;
+
+export interface RefreshedCredential {
+	key: string;
+	keyExpiresAtMs: number;
+	refreshToken: string;
+	refreshExpiresAtMs: number;
+	device?: string;
+}
+
+/** True when the credential can and should be traded now: it has a refresh token and its key is near or past expiry. */
+export function shouldRefresh(remote: RemoteRouter, nowMs = Date.now()): boolean {
+	if (remote.refreshToken === undefined || remote.refreshToken === "") return false;
+	if (remote.keyExpiresAtMs === undefined) return false;
+	return remote.keyExpiresAtMs - nowMs <= REFRESH_AHEAD_MS;
+}
+
+export class RefreshError extends Error {
+	constructor(
+		public readonly code: string,
+		message: string,
+	) {
+		super(message);
+		this.name = "RefreshError";
+	}
+}
+
+/** Trades the refresh token at the remote for the next credential. */
+export async function refreshCredential(remote: RemoteRouter, fetchImpl: typeof fetch = fetch): Promise<RefreshedCredential> {
+	if (remote.refreshToken === undefined || remote.refreshToken === "") throw new RefreshError("no_refresh_token", "this machine holds no refresh token; onboard it again with a setup token");
+	const res = await fetchImpl(`${remote.url}/auth/refresh`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ refreshToken: remote.refreshToken }),
+		signal: AbortSignal.timeout(15_000),
+	});
+	const body = (await res.json().catch(() => null)) as { key?: unknown; keyExpiresAtMs?: unknown; refreshToken?: unknown; refreshExpiresAtMs?: unknown; device?: unknown; error?: { code?: string; message?: string } } | null;
+	if (!res.ok || body === null || typeof body.key !== "string" || typeof body.refreshToken !== "string") {
+		throw new RefreshError(body?.error?.code ?? `http_${res.status}`, body?.error?.message ?? `the remote answered ${res.status} to the refresh`);
+	}
+	return {
+		key: body.key,
+		keyExpiresAtMs: typeof body.keyExpiresAtMs === "number" ? body.keyExpiresAtMs : Date.now(),
+		refreshToken: body.refreshToken,
+		refreshExpiresAtMs: typeof body.refreshExpiresAtMs === "number" ? body.refreshExpiresAtMs : Date.now(),
+		...(typeof body.device === "string" ? { device: body.device } : {}),
+	};
+}
+
+/**
+ * Refreshes and re-writes every place the key lives: remote.json and the
+ * harness configs `connect` manages. Returns the fresh credential. `home` and
+ * `packageDir` are injectable for tests.
+ */
+export async function refreshAndRewrite(opts: { remote: RemoteRouter; fetchImpl?: typeof fetch; home?: string; packageDir?: string; env?: Record<string, string | undefined>; platform?: string; pathHas?: (bin: string) => boolean }): Promise<RefreshedCredential> {
+	const fresh = await refreshCredential(opts.remote, opts.fetchImpl ?? fetch);
+	const home = opts.home ?? (process.env.HOME !== undefined && process.env.HOME !== "" ? process.env.HOME : homedir());
+	const packageDir = opts.packageDir ?? resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+	connectRemote({
+		url: opts.remote.url,
+		key: fresh.key,
+		userId: opts.remote.userId,
+		name: opts.remote.name,
+		refreshToken: fresh.refreshToken,
+		keyExpiresAtMs: fresh.keyExpiresAtMs,
+		refreshExpiresAtMs: fresh.refreshExpiresAtMs,
+		device: fresh.device ?? opts.remote.device ?? "",
+		profile: false,
+		dryRun: false,
+		only: [],
+		env: opts.env ?? process.env,
+		home,
+		packageDir,
+		platform: opts.platform ?? process.platform,
+		pathHas: opts.pathHas ?? ((bin) => Bun.which(bin) !== null),
+		// undefined keeps whatever scope the managed models.yml block already carries.
+	});
+	return fresh;
+}
+
+/** `auto-model-router refresh [--force]` */
+export async function refreshCommand(args: CliArgs): Promise<void> {
+	const remote = readRemoteRouter(routerHome());
+	if (remote === null) throw new Error(`no remote router configured (${routerHome()}/remote.json); run connect first`);
+	if (!args.flags.has("force") && !shouldRefresh(remote)) {
+		const left = remote.keyExpiresAtMs === undefined ? "no expiry" : `${Math.max(0, Math.round((remote.keyExpiresAtMs - Date.now()) / 3_600_000))}h left`;
+		console.log(`the access key does not need refreshing yet (${left}); --force refreshes anyway`);
+		return;
+	}
+	const fresh = await refreshAndRewrite({ remote });
+	console.log(`refreshed: the new access key lasts until ${new Date(fresh.keyExpiresAtMs).toISOString()}; every harness config was re-written`);
+}
+
+/**
+ * `auto-model-router token`: a key that is good right now, on stdout and
+ * nothing else — the shape a harness's key-helper command expects. Refreshes
+ * first when the key is near expiry.
+ */
+export async function tokenCommand(args: CliArgs): Promise<void> {
+	const remote = readRemoteRouter(routerHome());
+	if (remote === null) throw new Error(`no remote router configured (${routerHome()}/remote.json); run connect first`);
+	if (!args.flags.has("no-refresh") && shouldRefresh(remote)) {
+		try {
+			const fresh = await refreshAndRewrite({ remote });
+			process.stdout.write(`${fresh.key}\n`);
+			return;
+		} catch (err) {
+			// A key that is still valid beats no key: fall through and print what we hold.
+			if (remote.keyExpiresAtMs !== undefined && remote.keyExpiresAtMs <= Date.now()) throw err;
+			console.error(`warning: refresh failed (${err instanceof Error ? err.message : String(err)}); printing the current key`);
+		}
+	}
+	process.stdout.write(`${remote.key}\n`);
+}
+

package/src/index.ts

@@ -13,6 +13,7 @@ import { configCommand } from "./cli/config-cmd.ts";
 import { explainCommand } from "./cli/explain.ts";
 import { exportCommand } from "./cli/export.ts";
 import { connectCommand } from "./cli/connect.ts";
+import { refreshCommand, tokenCommand } from "./cli/refresh.ts";
 import { modelsCommand } from "./cli/models.ts";
 import { reportCommand } from "./cli/report.ts";
 import { serveCommand } from "./cli/serve.ts";
@@ -26,7 +27,9 @@ Usage: auto-model-router <command> [options]
   stats      Show routed spend, per-model share, and escalation rates
   report     Usage analytics: providers, models, tiers, cost, speed, cache hit rate
   export     One row per day, harness and model as CSV (--json for rows)
-  connect    Point this machine at a remote router (--url, --key; --scope labels a single-project machine; --profile persists the environment)
+  connect    Point this machine at a remote router (--url, --key[, --refresh-token]; --scope labels a single-project machine; --profile persists the environment)
+  refresh    Trade the refresh token for a new access key and re-write every harness config (--force: even when not near expiry)
+  token      Print an access key that is good right now, refreshing first if needed (for a harness key-helper)
   models     Show what each complexity tier would consider, and why
   explain    Route a saved request without dispatching it, and explain the decision
   config     Interactive wizard over the router's own config.yml
@@ -84,6 +87,12 @@ async function main(): Promise<number> {
 		case "join": // the first release's name
 			await connectCommand(args);
 			return 0;
+		case "refresh":
+			await refreshCommand(args);
+			return 0;
+		case "token":
+			await tokenCommand(args);
+			return 0;
 		case "models":
 			await modelsCommand(args);
 			return 0;

package/test/remote.test.ts

@@ -5,7 +5,8 @@ import { join } from "node:path";
 
 import { addExtensions, codexBlock, connectRemote, setDotenv, type ConnectOptions } from "../src/cli/connect.ts";
 import { parseRemoteRouter, readRemoteRouter, remoteProviderRegistration } from "../omp-extension/remote-logic.ts";
-import { hasForeignRouterProvider, mergeModelsYml, renderRemoteModelsYml } from "../src/cli/connect.ts";
+import { existingBlockScope, hasForeignRouterProvider, mergeModelsYml, renderRemoteModelsYml } from "../src/cli/connect.ts";
+import { refreshAndRewrite, refreshCredential, RefreshError, shouldRefresh } from "../src/cli/refresh.ts";
 
 /**
  * Remote mode: remote.json puts the omp extensions on a router elsewhere,
@@ -147,3 +148,77 @@ describe("omp models.yml for a remote router", () => {
 		expect(hasForeignRouterProvider(yaml("providers:", "  openai: {}"))).toBe(false);
 	});
 });
+
+describe("short-lived remote credentials", () => {
+	const NL = String.fromCharCode(10);
+	const remote = { url: "https://team.example", key: "amrt_old", userId: "u_ada", name: "Ada", joinedAtMs: 1, refreshToken: "amrr_r1", keyExpiresAtMs: 0, refreshExpiresAtMs: 0, device: "laptop" };
+
+	test("remote.json round-trips the credential fields, and a permanent key has none", () => {
+		const parsed = parseRemoteRouter(JSON.stringify(remote))!;
+		expect(parsed).toMatchObject({ refreshToken: "amrr_r1", keyExpiresAtMs: 0, refreshExpiresAtMs: 0, device: "laptop" });
+		const permanent = parseRemoteRouter(JSON.stringify({ url: "https://t", key: "k" }))!;
+		expect(permanent.refreshToken).toBeUndefined();
+		expect(shouldRefresh(permanent)).toBe(false);
+	});
+
+	test("a key is refreshed a day ahead of expiry, never without a refresh token", () => {
+		const now = 1_000_000_000_000;
+		const day = 24 * 3_600_000;
+		expect(shouldRefresh({ ...remote, keyExpiresAtMs: now + 3 * day }, now)).toBe(false);
+		expect(shouldRefresh({ ...remote, keyExpiresAtMs: now + day - 1 }, now)).toBe(true);
+		expect(shouldRefresh({ ...remote, keyExpiresAtMs: now - 1 }, now)).toBe(true); // already dead: still worth a try
+		expect(shouldRefresh({ ...remote, keyExpiresAtMs: now - 1, refreshToken: "" }, now)).toBe(false);
+	});
+
+	test("refreshCredential trades at /auth/refresh and surfaces the remote's refusal code", async () => {
+		const calls: { url: string; body: string }[] = [];
+		const ok = (async (url: string | URL | Request, init?: RequestInit) => {
+			calls.push({ url: String(url), body: String(init?.body) });
+			return Response.json({ key: "amrt_new", keyExpiresAtMs: 5, refreshToken: "amrr_r2", refreshExpiresAtMs: 9, device: "laptop" });
+		}) as unknown as typeof fetch;
+		const fresh = await refreshCredential(remote, ok);
+		expect(fresh).toEqual({ key: "amrt_new", keyExpiresAtMs: 5, refreshToken: "amrr_r2", refreshExpiresAtMs: 9, device: "laptop" });
+		expect(calls[0]).toEqual({ url: "https://team.example/auth/refresh", body: JSON.stringify({ refreshToken: "amrr_r1" }) });
+		const refused = (async () => Response.json({ error: { code: "refresh_reused", message: "already used" } }, { status: 401 })) as unknown as typeof fetch;
+		let err: RefreshError | null = null;
+		try {
+			await refreshCredential(remote, refused);
+		} catch (e) {
+			err = e as RefreshError;
+		}
+		expect(err?.code).toBe("refresh_reused");
+		expect(err?.message).toBe("already used");
+		await expect(refreshCredential({ ...remote, refreshToken: "" }, ok)).rejects.toBeInstanceOf(RefreshError);
+	});
+
+	test("refreshAndRewrite re-writes remote.json and the managed models.yml block, keeping its scope and join time", async () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-refresh-"));
+		const agent = join(home, ".omp", "agent");
+		mkdirSync(agent, { recursive: true });
+		writeFileSync(join(agent, "config.yml"), "extensions: []" + NL);
+		const routerHome = join(home, ".auto-model-router");
+		const env = { HOME: home, PI_CODING_AGENT_DIR: agent, AUTO_MODEL_ROUTER_HOME: routerHome, HERMES_HOME: join(home, "no-hermes") };
+		try {
+			// First: a connect with a scope and a credential.
+			const { connectRemote } = await import("../src/cli/connect.ts");
+			connectRemote({ url: "https://team.example", key: "amrt_old", userId: "u_ada", name: "Ada", refreshToken: "amrr_r1", keyExpiresAtMs: 1, refreshExpiresAtMs: 2, device: "laptop", agentdoxScope: "omp-router", profile: false, dryRun: false, only: ["omp"], env, home, packageDir: process.cwd(), platform: "linux", pathHas: () => false });
+			const before = JSON.parse(readFileSync(join(routerHome, "remote.json"), "utf8")) as Record<string, unknown>;
+			expect(before).toMatchObject({ key: "amrt_old", refreshToken: "amrr_r1", keyExpiresAtMs: 1, device: "laptop" });
+			const models0 = readFileSync(join(agent, "models.yml"), "utf8");
+			expect(models0).toContain("apiKey: amrt_old");
+			expect(existingBlockScope(models0)).toBe("omp-router");
+			// Then a refresh, which knows nothing about the scope.
+			const fetchImpl = (async () => Response.json({ key: "amrt_new", keyExpiresAtMs: 50, refreshToken: "amrr_r2", refreshExpiresAtMs: 90 })) as unknown as typeof fetch;
+			const fresh = await refreshAndRewrite({ remote: parseRemoteRouter(readFileSync(join(routerHome, "remote.json"), "utf8"))!, fetchImpl, home, packageDir: process.cwd(), env, platform: "linux", pathHas: () => false });
+			expect(fresh.key).toBe("amrt_new");
+			const after = JSON.parse(readFileSync(join(routerHome, "remote.json"), "utf8")) as Record<string, unknown>;
+			expect(after).toMatchObject({ key: "amrt_new", refreshToken: "amrr_r2", keyExpiresAtMs: 50, refreshExpiresAtMs: 90, device: "laptop", joinedAtMs: before.joinedAtMs });
+			const models1 = readFileSync(join(agent, "models.yml"), "utf8");
+			expect(models1).toContain("apiKey: amrt_new");
+			expect(models1).not.toContain("amrt_old");
+			expect(existingBlockScope(models1)).toBe("omp-router"); // kept, not lost
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+});

package/test/toast-logic.test.ts

@@ -242,6 +242,8 @@ describe("verbose toast", () => {
 		expect(whyReasons(undefined)).toEqual([]);
 		// At most two lines, however many reasons the router recorded.
 		expect(whyReasons(["failover: a", "policy: b", "held: c", "cache warm"]).length).toBe(2);
+		// The same fact recorded twice from different angles takes one line, not both.
+		expect(whyReasons(["policy: pinned to ollama/gpt-oss:20b", "pinned to ollama/gpt-oss:20b by session override"])).toEqual(["policy: pinned to ollama/gpt-oss:20b"]);
 	});
 
 	test("an unreported cost falls back to the prediction, and thin decisions stay short", () => {