auto-model-router 0.8.1 → 0.10.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.8.1",
+    "version": "0.10.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.8.1",
+      "version": "0.10.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -1312,18 +1312,33 @@ refresh token beside the key (`--refresh-token`, `--key-expires`, `--refresh-exp
 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.
+the shape a harness key-helper wants. 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.
+
+The refresh token, the long-lived secret, does not sit in a file: `connect` puts it in the
+operating system's credential store — DPAPI on Windows (ciphertext in
+`<router home>/refresh.dpapi`, decryptable only by that Windows user on that machine),
+the login keychain on macOS, the Secret Service on Linux — and `remote.json` only names
+which store holds it. `<router home>/refresh.token`, owner-readable only, is the fallback
+when no store is usable (a CI box), and the note at the end of `connect` says when that
+happened. **Claude Code** gets its settings file written instead of an environment: the
+`env` block carries `ANTHROPIC_BASE_URL`, and `apiKeyHelper` runs
+`auto-model-router token`, so no key is in its environment or on disk for it and a
+short-lived key rotates underneath a running session.
 
 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
-overrides it, and one that pins none follows the workspace. That header rides on the roles
-the extensions register; the **main** model's handle comes from `models.yml`, which is
-machine-wide, so it carries a scope only if you pass `--scope <slug>` to `connect` — right
-for a single-project machine, wrong for one with several repos.
+overrides it, and one that pins none follows the workspace. The roles the extensions
+register carry the header directly. The **main** model's handle comes from `models.yml`,
+which is machine-wide and resolved before extensions load, so `connect` writes that
+entry's header value as the *name* of an environment variable,
+`AUTO_MODEL_ROUTER_SCOPE`; omp resolves it from the environment on every request, and
+the embed extension sets it from the workspace as it loads. If the variable is unset omp
+sends the name itself, which the router does not accept as a scope (a scope is a
+lowercase slug) and falls back to its default. `--scope <slug>` pins one project for the
+whole machine instead; a refresh keeps a pin, and `connect --scope ""` removes it.
 
 ## Multiple coding harnesses, one router
 
@@ -1461,6 +1476,17 @@ move while the loop runs. So the router buffers the assistant's narration across
 the loop and writes it once, together with the closing synthesis, when the
 assistant actually yields back to the user.
 
+### Utility calls get neither the block nor a transcript
+
+A harness drives more than the agent's conversation through this provider: omp
+asks for a session title and a complexity rating with `model: auto`. Those
+calls answer *about* the conversation, carry no tool schemas, and gain nothing
+from the project block, yet each one paid the whole block — measured at ~6k
+prompt tokens per call, 42k across one turn's seven side calls. So the tool
+array is the discriminator for both directions: a request with no tools is
+neither recorded nor injected. `context.injectWithoutTools: true` restores
+injection into tool-less requests for a deliberately tool-less agent.
+
 Write-backs are queued, bounded, and never awaited: agentdox is an enrichment,
 not a dependency. If it is unreachable the turn routes and dispatches normally,
 and a pinned block keeps being served.

package/docs/AGENTDOX-BRIDGE.md

@@ -169,6 +169,16 @@ scope now correct the bridge degrades to **inert** for other projects. Correct a
 means the bridge only helps projects the configured token actually grants. A multi-scope token
 would fix that, at the cost of one credential reaching every project.
 
+## 6b. FIXED — the same discriminator gates injection (0.10)
+
+Recording skipped tool-less calls from 0.2.11, but injection did not: every scoped
+request received the block, so omp's title and rating calls each carried ~6k tokens of
+project context they could not use. Measured 2026-09-08 on one omp turn: seven side
+calls, 23,412 chars each, 42,417 prompt tokens of context in total. `turn.ts` now
+resolves the block only when `req.tools.length > 0`, the same test recording uses, and
+leaves the conversation's pin untouched otherwise. `context.injectWithoutTools` (default
+off) is the escape hatch for an agent that deliberately ships no tools.
+
 ## 7. Also worth doing
 
 - **Context pollution from test turns.** `context_assemble` includes recent session messages,

package/omp-extension/remote-logic.ts

@@ -22,8 +22,16 @@ 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). */
+	/**
+	 * Present only in a remote.json written before the credential store existed:
+	 * the token inline. New files name the store instead (`refreshTokenStore`) and
+	 * the token is read from it when a refresh happens (src/cli/refresh.ts).
+	 */
 	refreshToken?: string;
+	/** Which OS store holds the refresh token: dpapi (Windows), keychain (macOS), secret-service (Linux) or file. */
+	refreshTokenStore?: "dpapi" | "keychain" | "secret-service" | "file";
+	/** The account the store files it under (`<userId>@<remote host>`). */
+	refreshAccount?: string;
 	keyExpiresAtMs?: number;
 	refreshExpiresAtMs?: number;
 	/** What the remote calls this machine. */
@@ -46,6 +54,8 @@ export function parseRemoteRouter(text: string): RemoteRouter | null {
 			name: typeof raw.name === "string" ? raw.name : "",
 			joinedAtMs: typeof raw.joinedAtMs === "number" ? raw.joinedAtMs : 0,
 			...(typeof raw.refreshToken === "string" && raw.refreshToken !== "" ? { refreshToken: raw.refreshToken } : {}),
+			...(raw.refreshTokenStore === "dpapi" || raw.refreshTokenStore === "keychain" || raw.refreshTokenStore === "secret-service" || raw.refreshTokenStore === "file" ? { refreshTokenStore: raw.refreshTokenStore } : {}),
+			...(typeof raw.refreshAccount === "string" && raw.refreshAccount !== "" ? { refreshAccount: raw.refreshAccount } : {}),
 			...(typeof raw.keyExpiresAtMs === "number" ? { keyExpiresAtMs: raw.keyExpiresAtMs } : {}),
 			...(typeof raw.refreshExpiresAtMs === "number" ? { refreshExpiresAtMs: raw.refreshExpiresAtMs } : {}),
 			...(typeof raw.device === "string" && raw.device !== "" ? { device: raw.device } : {}),
@@ -55,6 +65,22 @@ export function parseRemoteRouter(text: string): RemoteRouter | null {
 	}
 }
 
+/** True when this machine can trade for a new key: a refresh token inline, or a store that holds one. */
+export function hasRefresh(remote: RemoteRouter): boolean {
+	return (remote.refreshToken !== undefined && remote.refreshToken !== "") || remote.refreshTokenStore !== undefined;
+}
+
+/** The account a remote user's refresh token is filed under in the OS store. */
+export function refreshAccountOf(url: string, userId: string): string {
+	let host = url;
+	try {
+		host = new URL(url).host;
+	} catch {
+		/* keep the raw url */
+	}
+	return `${userId === "" ? "member" : userId}@${host}`;
+}
+
 export function readRemoteRouter(routerHome: string): RemoteRouter | null {
 	for (const path of [remoteFilePath(routerHome), join(routerHome, LEGACY_FILE)]) {
 		if (!existsSync(path)) continue;

package/omp-extension/router-embed.ts

@@ -34,6 +34,19 @@ import type { RouterConfig } from "../src/config/types.ts";
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
 
 import { EMBED_DUMMY_API_KEY, EMBED_PROVIDER_ID, buildProviderConfig, deriveAgentdoxScope, embedPortPath, modelsYmlPort, probeEmbed, readEmbedPort, resolveEmbedPort, writeEmbedPort } from "./embed-logic.ts";
+import { SCOPE_ENV } from "../src/context/scope.ts";
+
+// The workspace's scope for the MAIN model. omp builds that handle from
+// models.yml before this file loads, so its X-Agentdox-Scope cannot come from
+// the provider we register; instead the managed entry names SCOPE_ENV as the
+// header's value, omp resolves that from the environment on every request,
+// and this module runs inside omp's process — so setting it here reaches
+// every turn of this session, main and side roles alike. A workspace that
+// derives no scope (no folder name) leaves whatever the shell set.
+{
+	const workspaceScope = deriveAgentdoxScope(process.cwd());
+	if (workspaceScope !== "") process.env[SCOPE_ENV] = workspaceScope;
+}
 
 /** omp's models.yml as text, or "" when it does not exist / cannot be read. */
 function readModelsYml(): string {

package/package.json

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

package/src/cli/config-cmd.ts

@@ -15,6 +15,7 @@
  * keys survive.
  */
 
+import { SCOPE_ENV } from "../context/scope.ts";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -59,16 +60,20 @@ export interface SpliceResult {
  */
 /**
  * Headers omp attaches to every request through this provider. Both are
- * optional: absent harness id ⇒ single-harness defaults, absent agentdox scope
- * ⇒ the router falls back to its own `context.defaultScope`.
+ * optional: absent harness id ⇒ single-harness defaults; the agentdox scope
+ * names `SCOPE_ENV`, which omp resolves from its environment per request and
+ * the embed extension sets from the workspace folder, so the MAIN model's turns
+ * carry the repository's own scope rather than one for the whole machine. When
+ * the variable is unset the router ignores the literal and falls back to its
+ * own `context.defaultScope`.
  */
 function providerHeaders(cfg: RouterConfig): Record<string, string> {
 	const headers: Record<string, string> = {};
 	if (cfg.server.harnessId !== undefined && cfg.server.harnessId !== "") {
 		headers["X-Omp-Harness"] = cfg.server.harnessId;
 	}
-	if (cfg.context.enabled && cfg.context.defaultScope !== "") {
-		headers["X-Agentdox-Scope"] = cfg.context.defaultScope;
+	if (cfg.context.enabled) {
+		headers["X-Agentdox-Scope"] = SCOPE_ENV;
 	}
 	return headers;
 }

package/src/cli/config-wizard.ts

@@ -301,6 +301,7 @@ export const WIZARD_SECTIONS: readonly SectionSpec[] = [
 			{ path: "context.sessionLimit", label: "Session items", kind: "number", min: 0 },
 			{ path: "context.briefChars", label: "Brief chars", kind: "number", min: 0 },
 			{ path: "context.recordTurns", label: "Record turns back", kind: "boolean" },
+			{ path: "context.injectWithoutTools", label: "Inject into tool-less calls", kind: "boolean" },
 			{ path: "context.maxQueue", label: "Write-back queue", kind: "number", min: 1 },
 		],
 	},

package/src/cli/connect.ts

@@ -14,7 +14,9 @@
  *               $HERMES_HOME/plugins and .env points them at the remote
  *   Codex       ~/.codex/config.toml gains the auto-model-router provider
  *   Aider       ~/.aider.conf.yml gains the base URL, key and model
- *   Claude Code ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY (printed; --profile persists)
+ *   Claude Code ~/.claude/settings.json gains the base URL (its `env` block) and
+ *               `apiKeyHelper` running `auto-model-router token`, so no key
+ *               sits in its environment or on disk for it
  *
  * Every write is idempotent and announced. `--profile` persists the
  * environment lines (shell rc on POSIX, user environment on Windows).
@@ -26,7 +28,9 @@ import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, writeFileS
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { remoteFilePath } from "../../omp-extension/remote-logic.ts";
+import { refreshAccountOf, remoteFilePath } from "../../omp-extension/remote-logic.ts";
+import { SCOPE_ENV } from "../context/scope.ts";
+import { pickStore, saveRefreshToken, type StoreDeps, type StoreKind } from "./credential-store.ts";
 import { flagString, type CliArgs } from "./args.ts";
 
 export interface ConnectOptions {
@@ -44,10 +48,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. Undefined keeps what the managed block already has. */
+	/** Pins `X-Agentdox-Scope` in omp's models.yml entry to one slug, machine-wide. Without it the entry follows the workspace (see renderRemoteModelsYml). 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;
+	/** Which store takes the refresh token; picked from the platform when absent. Tests inject a backend. */
+	store?: StoreKind;
+	storeDeps?: StoreDeps;
 	keyExpiresAtMs?: number;
 	refreshExpiresAtMs?: number;
 	device?: string;
@@ -135,10 +142,13 @@ const MODELS_YML_END = "  # END auto-model-router (remote)";
  * neither problem — the URL and the key are stable — and the entry is what makes
  * omp's main model resolvable at startup, before extensions load.
  *
- * `scope` adds `X-Agentdox-Scope` to every request through this provider. It is
- * off by default on purpose: the file is machine-wide, so a scope here would
- * label turns from every workspace with one project. The extensions still send
- * the workspace's own scope on the roles that resolve after they load.
+ * `X-Agentdox-Scope` on this entry reaches the MAIN model's turns, which the
+ * extensions' own registration cannot (they load after the handle is built).
+ * The file is machine-wide, so a literal slug here would label every
+ * workspace's turns with one project; by default the value is the NAME of
+ * `SCOPE_ENV`, which omp resolves from its environment per request, and the
+ * embed extension sets that variable from the workspace folder as it loads.
+ * `scope` pins a literal slug instead, for a single-project machine.
  */
 export function renderRemoteModelsYml(url: string, key: string, blend: { inputPerMtok: number; outputPerMtok: number }, scope = ""): string {
 	const round = (v: number): number => Math.round(v * 1e4) / 1e4;
@@ -156,7 +166,7 @@ export function renderRemoteModelsYml(url: string, key: string, blend: { inputPe
 		"    api: openai-completions",
 		`    apiKey: ${key}`,
 	];
-	if (scope !== "") lines.push("    headers:", `      X-Agentdox-Scope: ${scope}`);
+	lines.push("    headers:", `      X-Agentdox-Scope: ${scope !== "" ? scope : SCOPE_ENV}`);
 	lines.push("    models:");
 	for (const m of REMOTE_MODEL_ROWS) {
 		lines.push(
@@ -195,14 +205,15 @@ 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. */
+/** The literal `X-Agentdox-Scope` the managed block pins, or "" when it follows the workspace (or has 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] ?? "";
+	const value = m?.[1] ?? "";
+	return value === SCOPE_ENV ? "" : value;
 }
 
 /** True when the file already defines our provider outside a block we manage. */
@@ -223,6 +234,16 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 	const rh = routerHomeOf(o);
 	report.remoteFile = remoteFilePath(rh);
 	const previous = existsSync(report.remoteFile) ? (JSON.parse(readFileSync(report.remoteFile, "utf8")) as Record<string, unknown>) : {};
+	// The refresh token is the long-lived secret: it goes to the OS credential store, and
+	// remote.json only says which one. The access key stays in the file: it is short-lived,
+	// and the extensions need it without a subprocess on every poll.
+	let refreshTokenStore: StoreKind | undefined;
+	const refreshAccount = refreshAccountOf(o.url, o.userId);
+	if (o.refreshToken !== undefined && o.refreshToken !== "" && !o.dryRun) {
+		const wanted = o.store ?? pickStore(o.platform, o.pathHas);
+		refreshTokenStore = saveRefreshToken(rh, refreshAccount, o.refreshToken, wanted, o.storeDeps ?? { pathHas: o.pathHas });
+		if (refreshTokenStore !== wanted) report.notes.push(`the ${wanted} credential store was not usable; the refresh token is in ${join(rh, "refresh.token")} (owner-readable only)`);
+	} else if (o.refreshToken !== undefined && o.refreshToken !== "") refreshTokenStore = o.store ?? pickStore(o.platform, o.pathHas);
 	write(
 		report.remoteFile,
 		`${JSON.stringify(
@@ -232,7 +253,7 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 				userId: o.userId,
 				name: o.name,
 				joinedAtMs: typeof previous.joinedAtMs === "number" ? previous.joinedAtMs : Date.now(),
-				...(o.refreshToken !== undefined && o.refreshToken !== "" ? { refreshToken: o.refreshToken } : {}),
+				...(refreshTokenStore !== undefined ? { refreshTokenStore, refreshAccount } : {}),
 				...(o.keyExpiresAtMs !== undefined ? { keyExpiresAtMs: o.keyExpiresAtMs } : {}),
 				...(o.refreshExpiresAtMs !== undefined ? { refreshExpiresAtMs: o.refreshExpiresAtMs } : {}),
 				...(o.device !== undefined && o.device !== "" ? { device: o.device } : {}),
@@ -300,11 +321,33 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 		report.configured.push(`Aider (${aiderConf})`);
 	} else report.skipped.push("Aider (not found)");
 
-	// 6. Claude Code: environment only.
-	if (wants(o, "claude") && o.pathHas("claude")) {
-		report.envLines.push(`ANTHROPIC_BASE_URL=${o.url}`, `ANTHROPIC_API_KEY=${o.key}`);
-		report.configured.push("Claude Code (environment)");
-	} else report.skipped.push("Claude Code (not on PATH)");
+	// 6. Claude Code: its settings file carries the base URL (the `env` block) and a key
+	// helper, a command it runs for the key — so the key is never in its environment or
+	// on disk for it. Without a refresh token the helper still works (it prints the key it
+	// holds); the helper is what lets a short-lived key rotate underneath a running session.
+	const claudeDir = join(o.home, ".claude");
+	if (wants(o, "claude") && (o.pathHas("claude") || existsSync(claudeDir))) {
+		const settingsPath = join(claudeDir, "settings.json");
+		let settings: Record<string, unknown> = {};
+		const before = existsSync(settingsPath) ? readFileSync(settingsPath, "utf8") : "";
+		try {
+			settings = before === "" ? {} : (JSON.parse(before) as Record<string, unknown>);
+		} catch {
+			report.notes.push(`${settingsPath} is not valid JSON; left alone — set env.ANTHROPIC_BASE_URL and apiKeyHelper by hand`);
+			settings = {};
+		}
+		const env: Record<string, unknown> = { ...((settings.env as Record<string, unknown> | undefined) ?? {}), ANTHROPIC_BASE_URL: o.url };
+		// Never leave a stale key beside the helper: the helper is the source now.
+		delete env.ANTHROPIC_API_KEY;
+		const entry = resolve(o.packageDir, "src", "index.ts").replaceAll("\\", "/");
+		const next = { ...settings, env, apiKeyHelper: `bun run "${entry}" token` };
+		const after = `${JSON.stringify(next, null, 2)}\n`;
+		if (after !== before) {
+			if (before !== "" && !o.dryRun) writeFileSync(`${settingsPath}.${new Date().toISOString().replaceAll(":", "-")}.bak`, before, "utf8");
+			write(settingsPath, after);
+		}
+		report.configured.push(`Claude Code (${settingsPath}: env.ANTHROPIC_BASE_URL + apiKeyHelper; open a new session)`);
+	} else report.skipped.push("Claude Code (not on PATH and no ~/.claude)");
 	report.envLines.unshift(`AUTO_MODEL_ROUTER_URL=${o.url}`, `AUTO_MODEL_ROUTER_API_KEY=${o.key}`);
 	report.envLines = [...new Set(report.envLines)];
 

package/src/cli/credential-store.ts

@@ -0,0 +1,157 @@
+/**
+ * Where the refresh token lives on a member's machine.
+ *
+ * The access key has to sit in harness config files (a harness needs a literal
+ * bearer), and it is short-lived. The refresh token is the long-lived secret,
+ * so it goes to the operating system's credential store instead of a file:
+ *
+ *   Windows  DPAPI (CurrentUser scope): the token is encrypted so that only
+ *            this Windows user on this machine can decrypt it, and the
+ *            ciphertext is kept in `<router home>/refresh.dpapi`. Built in;
+ *            no module to install. The plaintext passes to PowerShell through
+ *            an environment variable, never an argument.
+ *   macOS    the login keychain, through `security` (service
+ *            `auto-model-router`, one account per remote user).
+ *   Linux    the Secret Service through `secret-tool` when it is installed.
+ *   file     `<router home>/refresh.token`, owner-readable only — the fallback
+ *            when none of the above works, and the choice on CI boxes.
+ *
+ * `remote.json` records which store holds it (`refreshTokenStore`) and the
+ * account name; it never holds the token itself once a store other than
+ * `file` is in use. A remote.json written before this existed may still carry
+ * the token inline; reading honours that until the next refresh moves it.
+ */
+
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type StoreKind = "dpapi" | "keychain" | "secret-service" | "file";
+
+const SERVICE = "auto-model-router";
+
+/** The store this platform offers, given which tools are on PATH. */
+export function pickStore(platform: string, pathHas: (bin: string) => boolean): StoreKind {
+	if (platform === "win32") return pathHas("powershell") || pathHas("pwsh") ? "dpapi" : "file";
+	if (platform === "darwin") return pathHas("security") ? "keychain" : "file";
+	if (platform === "linux") return pathHas("secret-tool") ? "secret-service" : "file";
+	return "file";
+}
+
+const powershell = (pathHas: (bin: string) => boolean): string => (pathHas("pwsh") ? "pwsh" : "powershell");
+
+function dpapiProtect(secret: string, pathHas: (bin: string) => boolean): string {
+	const r = spawnSync(
+		powershell(pathHas),
+		["-NoProfile", "-NonInteractive", "-Command", "Add-Type -AssemblyName System.Security; [Convert]::ToBase64String([System.Security.Cryptography.ProtectedData]::Protect([Text.Encoding]::UTF8.GetBytes($env:AMR_SECRET), $null, 'CurrentUser'))"],
+		{ encoding: "utf8", env: { ...process.env, AMR_SECRET: secret } },
+	);
+	if (r.status !== 0 || r.stdout.trim() === "") throw new Error(`DPAPI protect failed: ${r.stderr.trim() || r.status}`);
+	return r.stdout.trim();
+}
+
+function dpapiUnprotect(blob: string, pathHas: (bin: string) => boolean): string {
+	const r = spawnSync(
+		powershell(pathHas),
+		["-NoProfile", "-NonInteractive", "-Command", "Add-Type -AssemblyName System.Security; [Text.Encoding]::UTF8.GetString([System.Security.Cryptography.ProtectedData]::Unprotect([Convert]::FromBase64String($env:AMR_BLOB), $null, 'CurrentUser'))"],
+		{ encoding: "utf8", env: { ...process.env, AMR_BLOB: blob } },
+	);
+	if (r.status !== 0) throw new Error(`DPAPI unprotect failed: ${r.stderr.trim() || r.status}`);
+	return r.stdout.replace(/\r?\n$/, "");
+}
+
+const filePath = (routerHome: string): string => join(routerHome, "refresh.token");
+const dpapiPath = (routerHome: string): string => join(routerHome, "refresh.dpapi");
+
+export interface StoreDeps {
+	pathHas?: (bin: string) => boolean;
+	/** Injected in tests to stand in for the platform tools. */
+	backend?: { save(account: string, secret: string): void; load(account: string): string | null; remove(account: string): void };
+}
+
+/**
+ * Saves the refresh token and returns the store that took it. A store that
+ * fails (keychain locked, tool missing) falls back to the file, so a member is
+ * never left without a refresh token; the caller records what was used.
+ */
+export function saveRefreshToken(routerHome: string, account: string, secret: string, kind: StoreKind, deps: StoreDeps = {}): StoreKind {
+	const pathHas = deps.pathHas ?? ((bin) => Bun.which(bin) !== null);
+	mkdirSync(routerHome, { recursive: true });
+	try {
+		if (deps.backend !== undefined) {
+			deps.backend.save(account, secret);
+			return kind;
+		}
+		switch (kind) {
+			case "dpapi":
+				writeFileSync(dpapiPath(routerHome), `${dpapiProtect(secret, pathHas)}\n`, { encoding: "utf8", mode: 0o600 });
+				rmSync(filePath(routerHome), { force: true });
+				return "dpapi";
+			case "keychain": {
+				const r = spawnSync("security", ["add-generic-password", "-U", "-a", account, "-s", SERVICE, "-w", secret], { encoding: "utf8" });
+				if (r.status !== 0) throw new Error(r.stderr.trim());
+				rmSync(filePath(routerHome), { force: true });
+				return "keychain";
+			}
+			case "secret-service": {
+				const r = spawnSync("secret-tool", ["store", `--label=${SERVICE} ${account}`, "service", SERVICE, "account", account], { encoding: "utf8", input: secret });
+				if (r.status !== 0) throw new Error(r.stderr.trim());
+				rmSync(filePath(routerHome), { force: true });
+				return "secret-service";
+			}
+			case "file":
+				break;
+		}
+	} catch {
+		// fall through to the file
+	}
+	writeFileSync(filePath(routerHome), `${secret}\n`, { encoding: "utf8", mode: 0o600 });
+	try {
+		chmodSync(filePath(routerHome), 0o600);
+	} catch {
+		/* Windows */
+	}
+	return "file";
+}
+
+/** The refresh token from the store `remote.json` names, or null when it is gone. */
+export function loadRefreshToken(routerHome: string, account: string, kind: StoreKind, deps: StoreDeps = {}): string | null {
+	const pathHas = deps.pathHas ?? ((bin) => Bun.which(bin) !== null);
+	try {
+		if (deps.backend !== undefined) return deps.backend.load(account);
+		switch (kind) {
+			case "dpapi": {
+				const p = dpapiPath(routerHome);
+				if (!existsSync(p)) return null;
+				return dpapiUnprotect(readFileSync(p, "utf8").trim(), pathHas);
+			}
+			case "keychain": {
+				const r = spawnSync("security", ["find-generic-password", "-a", account, "-s", SERVICE, "-w"], { encoding: "utf8" });
+				return r.status === 0 ? r.stdout.replace(/\r?\n$/, "") : null;
+			}
+			case "secret-service": {
+				const r = spawnSync("secret-tool", ["lookup", "service", SERVICE, "account", account], { encoding: "utf8" });
+				return r.status === 0 && r.stdout !== "" ? r.stdout.replace(/\r?\n$/, "") : null;
+			}
+			case "file": {
+				const p = filePath(routerHome);
+				return existsSync(p) ? readFileSync(p, "utf8").trim() : null;
+			}
+		}
+	} catch {
+		return null;
+	}
+	return null;
+}
+
+/** Forgets the token everywhere it might be. */
+export function removeRefreshToken(routerHome: string, account: string, deps: StoreDeps = {}): void {
+	rmSync(filePath(routerHome), { force: true });
+	rmSync(dpapiPath(routerHome), { force: true });
+	if (deps.backend !== undefined) {
+		deps.backend.remove(account);
+		return;
+	}
+	if (process.platform === "darwin") spawnSync("security", ["delete-generic-password", "-a", account, "-s", SERVICE], { encoding: "utf8" });
+	if (process.platform === "linux") spawnSync("secret-tool", ["clear", "service", SERVICE, "account", account], { encoding: "utf8" });
+}

package/src/cli/refresh.ts

@@ -16,7 +16,8 @@
 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 { hasRefresh, readRemoteRouter, refreshAccountOf, type RemoteRouter } from "../../omp-extension/remote-logic.ts";
+import { loadRefreshToken, type StoreDeps } from "./credential-store.ts";
 import { routerHome } from "../../omp-extension/router-url.ts";
 import type { CliArgs } from "./args.ts";
 import { connectRemote } from "./connect.ts";
@@ -34,7 +35,7 @@ export interface RefreshedCredential {
 
 /** 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 (!hasRefresh(remote)) return false;
 	if (remote.keyExpiresAtMs === undefined) return false;
 	return remote.keyExpiresAtMs - nowMs <= REFRESH_AHEAD_MS;
 }
@@ -49,13 +50,21 @@ export class RefreshError extends Error {
 	}
 }
 
+/** The refresh token: inline from an older remote.json, else from the OS store remote.json names. */
+export function resolveRefreshToken(remote: RemoteRouter, routerHome: string, storeDeps: StoreDeps = {}): string | null {
+	if (remote.refreshToken !== undefined && remote.refreshToken !== "") return remote.refreshToken;
+	if (remote.refreshTokenStore === undefined) return null;
+	return loadRefreshToken(routerHome, remote.refreshAccount ?? refreshAccountOf(remote.url, remote.userId), remote.refreshTokenStore, storeDeps);
+}
+
 /** 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");
+export async function refreshCredential(remote: RemoteRouter, fetchImpl: typeof fetch = fetch, routerHomeDir: string = routerHome(), storeDeps: StoreDeps = {}): Promise<RefreshedCredential> {
+	const token = resolveRefreshToken(remote, routerHomeDir, storeDeps);
+	if (token === null || token === "") throw new RefreshError("no_refresh_token", "this machine holds no refresh token (or its credential store no longer has it); 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 }),
+		body: JSON.stringify({ refreshToken: token }),
 		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;
@@ -76,8 +85,9 @@ export async function refreshCredential(remote: RemoteRouter, fetchImpl: typeof
  * 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);
+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; routerHome?: string; storeDeps?: StoreDeps }): Promise<RefreshedCredential> {
+	const rh = opts.routerHome ?? routerHome();
+	const fresh = await refreshCredential(opts.remote, opts.fetchImpl ?? fetch, rh, opts.storeDeps ?? {});
 	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({
@@ -97,6 +107,9 @@ export async function refreshAndRewrite(opts: { remote: RemoteRouter; fetchImpl?
 		packageDir,
 		platform: opts.platform ?? process.platform,
 		pathHas: opts.pathHas ?? ((bin) => Bun.which(bin) !== null),
+		// The store that already holds it keeps it; a machine never silently changes store.
+		...(opts.remote.refreshTokenStore !== undefined ? { store: opts.remote.refreshTokenStore } : {}),
+		...(opts.storeDeps !== undefined ? { storeDeps: opts.storeDeps } : {}),
 		// undefined keeps whatever scope the managed models.yml block already carries.
 	});
 	return fresh;

package/src/config/defaults.ts

@@ -263,6 +263,14 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		// the query-relevant memory/docs tail. 0 omits the brief.
 		briefChars: 12_000,
 		recordTurns: true,
+		// A request with no tool schemas is a harness utility call — omp asks for
+		// a session title or a complexity rating through the same provider — and
+		// it answers ABOUT the conversation, so the project block cannot help it.
+		// Recording already skips those calls (turn.ts); injection did not, and
+		// one omp turn measured seven side calls at ~6k tokens of context each,
+		// 42k prompt tokens for nothing. Off: the block goes only to turns that
+		// ship tools. On: every scoped turn gets it, as before 0.10.
+		injectWithoutTools: false,
 		maxQueue: 64,
 	},
 	compaction: {

package/src/config/schema.ts

@@ -192,6 +192,7 @@ const context = z.strictObject({
 	sessionLimit: z.number().int().nonnegative().optional(),
 	briefChars: z.number().int().nonnegative().optional(),
 	recordTurns: z.boolean().optional(),
+	injectWithoutTools: z.boolean().optional(),
 	maxQueue: z.number().int().positive().optional(),
 });
 

package/src/config/types.ts

@@ -769,6 +769,13 @@ export interface ContextConfig {
 	briefChars: number;
 	/** Write settled turns back to agentdox sessions, tagged with the served model. */
 	recordTurns: boolean;
+	/**
+	 * Inject the block into turns that carry NO tool schemas too. Those are
+	 * harness utility calls (titles, ratings), which recording already skips;
+	 * default off, because each one paid the whole block for an answer that is
+	 * about the conversation, not part of it.
+	 */
+	injectWithoutTools: boolean;
 	/** Bound on queued write-backs; excess turns are dropped, never buffered unbounded. */
 	maxQueue: number;
 }

package/src/context/scope.ts

@@ -0,0 +1,29 @@
+/**
+ * The agentdox scope a request names, and where omp's main model gets it from.
+ *
+ * omp resolves its MAIN model from `models.yml` at startup, before any extension
+ * loads, so the `X-Agentdox-Scope` header on that provider entry cannot be set
+ * by the extension per workspace — but omp resolves a header VALUE that names
+ * an environment variable from the environment on every request, and the
+ * extension runs inside omp's process. So `connect` (and the local sync) write
+ * the header's value as the NAME below, and the extension sets that variable
+ * from the workspace folder when it loads. One machine-wide file, one scope
+ * per repository.
+ */
+export const SCOPE_ENV = "AUTO_MODEL_ROUTER_SCOPE";
+
+/**
+ * A scope is an agentdox project slug: lowercase, starting alphanumeric. The
+ * shape matters because omp sends the header's literal value when the variable
+ * it names is unset — `AUTO_MODEL_ROUTER_SCOPE` itself — and that must never
+ * become a project. Uppercase never passes, so the sentinel cannot.
+ */
+export function isScopeSlug(value: string): boolean {
+	return /^[a-z0-9][a-z0-9._-]{0,127}$/.test(value);
+}
+
+/** The scope to trust from a request header: a slug, or "" for anything else. */
+export function acceptScope(raw: string | null | undefined): string {
+	const s = (raw ?? "").trim();
+	return isScopeSlug(s) ? s : "";
+}

package/src/index.ts

@@ -27,7 +27,7 @@ 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[, --refresh-token]; --scope labels a single-project machine; --profile persists the environment)
+  connect    Point this machine at a remote router (--url, --key[, --refresh-token]; --scope pins one project for the whole machine (default: each workspace's own); --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

package/src/server/turn.ts

@@ -136,6 +136,12 @@ export async function runTurn(
 	// Request header wins; the configured default covers harnesses that send none.
 	const doxScope = req.agentdoxScope !== "" ? req.agentdoxScope : config.context.defaultScope;
 	const doxActive = bridge.enabled && doxScope !== "";
+	// Injection shares recording's discriminator (explained at the record call
+	// below): a tool-less harness utility call answers ABOUT the conversation
+	// and gains nothing from the project block, yet paid its full ~6k tokens on
+	// every title and rating — 42k prompt tokens across one omp turn's seven
+	// side calls. `context.injectWithoutTools` restores the old behaviour.
+	const doxInject = doxActive && (req.tools.length > 0 || config.context.injectWithoutTools);
 
 	// The trigger list is the source of truth for enabled signals, except
 	// length_stop, which rides on its own toggle (escalation.escalateOnLengthStop).
@@ -209,7 +215,7 @@ export async function runTurn(
 		// turn's prefix is already cold — a model switch or a retry — so the
 		// injected bytes stay identical while the cache is worth keeping.
 		let contextBlock: string | undefined;
-		if (doxActive) {
+		if (doxInject) {
 			const pin = await bridge.resolve({
 				scope: doxScope,
 				conversationKey: req.conversationKey,
@@ -233,6 +239,7 @@ export async function runTurn(
 		log.debug("agentdox context", {
 			active: doxActive,
 			scope: doxScope === "" ? "(none)" : doxScope,
+			utilityCall: doxActive && !doxInject,
 			injected: contextBlock !== undefined,
 			chars: contextBlock?.length ?? 0,
 		});

package/src/wire/openai/request.ts

@@ -1,3 +1,4 @@
+import { acceptScope } from "../../context/scope.ts";
 import type {
 	RequestPolicy,
 	CompactionEdit,
@@ -329,8 +330,10 @@ export function parseChatRequest(body: unknown, headers: Headers): NormRequest {
 	const ompSessionId = (headers.get("x-omp-session") ?? "").trim();
 
 	// agentdox project scope. Selects whose shared context is injected; absent
-	// ⇒ the server falls back to its configured default scope.
-	const agentdoxScope = (headers.get("x-agentdox-scope") ?? "").trim();
+	// or not a slug (omp sends the literal env-var NAME when the variable that
+	// models.yml names is unset — see src/context/scope.ts) ⇒ the server falls
+	// back to its configured default scope.
+	const agentdoxScope = acceptScope(headers.get("x-agentdox-scope"));
 
 	// Subagent marker from the embed extension (sessions without a UI).
 	const isSubagent = (headers.get("x-omp-subagent") ?? "").trim() === "1";

package/test/failover.test.ts

@@ -73,7 +73,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1, breakHoldOnMechanical: false, switchHorizonTurns: 1, confirmUpgradesBelowConfidence: 0.6 },
 		exploration: { enabled: false, rates: {}, stickyPolicy: "never", holdTurns: { enabled: false, values: [2, 3, 4] } },
 		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024, milestoneTokens: 20_000 },
-		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, memoryLimit: 8, docsLimit: 2, sessionLimit: 6, briefChars: 0, recordTurns: false, maxQueue: 64 },
+		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, memoryLimit: 8, docsLimit: 2, sessionLimit: 6, briefChars: 0, recordTurns: false, injectWithoutTools: false, maxQueue: 64 },
 		compaction: { enabled: false, budgetTokens: 40_000, floorRatio: 1, fitToWindow: true, protectRecentTurns: 4, maxToolResultBytes: 4_096, keepHeadBytes: 512, keepTailBytes: 512, elideSupersededReads: true, collapseDuplicateResults: true, replanGrowthRatio: 1, digestToolResults: false, digestMaxPerTurn: 2 },
 		budget: { onExceeded: "downgrade" },
 		report: { baselines: [], dailySummary: false },

package/test/remote.test.ts

@@ -1,12 +1,15 @@
 import { describe, expect, test } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 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 { existingBlockScope, hasForeignRouterProvider, mergeModelsYml, renderRemoteModelsYml } from "../src/cli/connect.ts";
-import { refreshAndRewrite, refreshCredential, RefreshError, shouldRefresh } from "../src/cli/refresh.ts";
+import { SCOPE_ENV } from "../src/context/scope.ts";
+import { refreshAndRewrite, refreshCredential, RefreshError, resolveRefreshToken, shouldRefresh } from "../src/cli/refresh.ts";
+import { loadRefreshToken, pickStore, removeRefreshToken, saveRefreshToken } from "../src/cli/credential-store.ts";
+import { hasRefresh, refreshAccountOf } from "../omp-extension/remote-logic.ts";
 
 /**
  * Remote mode: remote.json puts the omp extensions on a router elsewhere,
@@ -78,7 +81,8 @@ describe("connect", () => {
 		expect(readFileSync(join(home, ".codex", "config.toml"), "utf8")).toContain("[model_providers.auto-model-router]");
 		expect(readFileSync(join(home, ".aider.conf.yml"), "utf8")).toContain("openai-api-base: https://team.example/v1");
 		expect(r1.configured.join("\n")).toMatch(/omp[\s\S]*Hermes[\s\S]*Codex[\s\S]*Aider[\s\S]*Claude Code/);
-		expect(r1.envLines).toEqual(["AUTO_MODEL_ROUTER_URL=https://team.example", "AUTO_MODEL_ROUTER_API_KEY=amrt_key", "ANTHROPIC_BASE_URL=https://team.example", "ANTHROPIC_API_KEY=amrt_key"]);
+		// Claude Code is configured through its settings file now, so nothing ANTHROPIC_* rides in the environment.
+		expect(r1.envLines).toEqual(["AUTO_MODEL_ROUTER_URL=https://team.example", "AUTO_MODEL_ROUTER_API_KEY=amrt_key"]);
 		// Running again changes nothing.
 		const snapshot = [ompCfg, readFileSync(join(home, ".codex", "config.toml"), "utf8"), readFileSync(join(home, ".aider.conf.yml"), "utf8")];
 		connectRemote(o);
@@ -99,7 +103,8 @@ describe("connect", () => {
 		connectRemote(o2);
 		const rc = readFileSync(join(h2, ".zshrc"), "utf8");
 		expect(rc.split("# auto-model-router remote").length).toBe(2);
-		expect(rc).toContain("export ANTHROPIC_BASE_URL=https://team.example");
+		expect(rc).toContain("export AUTO_MODEL_ROUTER_URL=https://team.example");
+		expect(rc).not.toContain("ANTHROPIC_");
 		rmSync(home, { recursive: true, force: true });
 		rmSync(h2, { recursive: true, force: true });
 	});
@@ -110,7 +115,7 @@ describe("omp models.yml for a remote router", () => {
 	const NL = String.fromCharCode(10);
 	const yaml = (...lines: string[]): string => lines.join(NL) + NL;
 
-	test("the block names the remote, the key and the three virtual models; a scope is opt-in", () => {
+	test("the block names the remote, the key and the three virtual models; the scope follows the workspace unless pinned", () => {
 		const block = renderRemoteModelsYml("https://team.example/", "amrt_k", BLEND);
 		expect(block).toContain("baseUrl: https://team.example/v1");
 		expect(block).toContain("apiKey: amrt_k");
@@ -118,9 +123,15 @@ describe("omp models.yml for a remote router", () => {
 		expect(block).toContain("- id: auto-cheap");
 		expect(block).toContain("- id: auto-max");
 		expect(block).toContain("cost: { input: 1.1, output: 4.4, cacheRead: 0.11, cacheWrite: 1.375 }");
-		// Machine-wide file: no scope unless the caller asks for one.
-		expect(block).not.toContain("X-Agentdox-Scope");
-		expect(renderRemoteModelsYml("https://team.example", "k", BLEND, "omp-router")).toContain("X-Agentdox-Scope: omp-router");
+		// Machine-wide file: the header names the env var the extension sets per
+		// workspace, so the MAIN model's turns carry each repo's own scope.
+		expect(block).toContain(`X-Agentdox-Scope: ${SCOPE_ENV}`);
+		expect(existingBlockScope(mergeModelsYml("", block))).toBe("");
+		// --scope pins one slug for the whole machine.
+		const pinned = renderRemoteModelsYml("https://team.example", "k", BLEND, "omp-router");
+		expect(pinned).toContain("X-Agentdox-Scope: omp-router");
+		expect(pinned).not.toContain(SCOPE_ENV);
+		expect(existingBlockScope(mergeModelsYml("", pinned))).toBe("omp-router");
 	});
 
 	test("merging keeps other providers, replaces our own block, and is idempotent", () => {
@@ -203,16 +214,21 @@ describe("short-lived remote credentials", () => {
 			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" });
+			// The refresh token is in the store (the file here: no platform tool on PATH); remote.json only names it.
+			expect(before).toMatchObject({ key: "amrt_old", keyExpiresAtMs: 1, device: "laptop", refreshTokenStore: "file", refreshAccount: "u_ada@team.example" });
+			expect(before.refreshToken).toBeUndefined();
+			expect(readFileSync(join(routerHome, "refresh.token"), "utf8").trim()).toBe("amrr_r1");
 			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 });
+			const fresh = await refreshAndRewrite({ remote: parseRemoteRouter(readFileSync(join(routerHome, "remote.json"), "utf8"))!, fetchImpl, home, packageDir: process.cwd(), env, platform: "linux", pathHas: () => false, routerHome });
 			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 });
+			expect(after).toMatchObject({ key: "amrt_new", keyExpiresAtMs: 50, refreshExpiresAtMs: 90, device: "laptop", joinedAtMs: before.joinedAtMs, refreshTokenStore: "file" });
+			expect(after.refreshToken).toBeUndefined();
+			expect(readFileSync(join(routerHome, "refresh.token"), "utf8").trim()).toBe("amrr_r2");
 			const models1 = readFileSync(join(agent, "models.yml"), "utf8");
 			expect(models1).toContain("apiKey: amrt_new");
 			expect(models1).not.toContain("amrt_old");
@@ -222,3 +238,91 @@ describe("short-lived remote credentials", () => {
 		}
 	});
 });
+
+describe("the refresh token lives in the OS credential store", () => {
+	const NL = String.fromCharCode(10);
+	// A fake backend stands in for DPAPI / the keychain / secret-service.
+	const vault = new Map<string, string>();
+	const backend = { save: (a: string, s: string) => void vault.set(a, s), load: (a: string) => vault.get(a) ?? null, remove: (a: string) => void vault.delete(a) };
+
+	test("the store is picked from the platform and its tools; the file is the fallback everywhere", () => {
+		expect(pickStore("win32", (b) => b === "powershell")).toBe("dpapi");
+		expect(pickStore("win32", () => false)).toBe("file");
+		expect(pickStore("darwin", (b) => b === "security")).toBe("keychain");
+		expect(pickStore("linux", (b) => b === "secret-tool")).toBe("secret-service");
+		expect(pickStore("linux", () => false)).toBe("file");
+		expect(refreshAccountOf("https://team.example:8790/", "u_ada")).toBe("u_ada@team.example:8790");
+	});
+
+	test("save/load through a store, and the file fallback keeps the token owner-readable", () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-store-"));
+		try {
+			expect(saveRefreshToken(home, "u@t", "amrr_x", "keychain", { backend })).toBe("keychain");
+			expect(loadRefreshToken(home, "u@t", "keychain", { backend })).toBe("amrr_x");
+			expect(existsSync(join(home, "refresh.token"))).toBe(false); // nothing on disk
+			expect(saveRefreshToken(home, "u@t", "amrr_f", "file")).toBe("file");
+			expect(loadRefreshToken(home, "u@t", "file")).toBe("amrr_f");
+			removeRefreshToken(home, "u@t", { backend });
+			expect(loadRefreshToken(home, "u@t", "keychain", { backend })).toBeNull();
+			expect(existsSync(join(home, "refresh.token"))).toBe(false);
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+
+	test("connect files the token in the store and remote.json only names it; refresh reads it back; an older inline token still works", async () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-store2-"));
+		const agent = join(home, ".omp", "agent");
+		mkdirSync(agent, { recursive: true });
+		writeFileSync(join(agent, "config.yml"), "extensions: []" + NL);
+		const rh = join(home, ".auto-model-router");
+		const env = { HOME: home, PI_CODING_AGENT_DIR: agent, AUTO_MODEL_ROUTER_HOME: rh, HERMES_HOME: join(home, "no-hermes") };
+		try {
+			const { connectRemote } = await import("../src/cli/connect.ts");
+			connectRemote({ url: "https://team.example", key: "amrt_k1", userId: "u_ada", name: "Ada", refreshToken: "amrr_r1", keyExpiresAtMs: 1, refreshExpiresAtMs: 2, device: "laptop", store: "keychain", storeDeps: { backend }, profile: false, dryRun: false, only: ["omp"], env, home, packageDir: process.cwd(), platform: "darwin", pathHas: () => false });
+			const written = readFileSync(join(rh, "remote.json"), "utf8");
+			expect(written).not.toContain("amrr_r1");
+			const remote = parseRemoteRouter(written)!;
+			expect(remote).toMatchObject({ refreshTokenStore: "keychain", refreshAccount: "u_ada@team.example" });
+			expect(remote.refreshToken).toBeUndefined();
+			expect(hasRefresh(remote)).toBe(true);
+			expect(resolveRefreshToken(remote, rh, { backend })).toBe("amrr_r1");
+			// The refresh trades the stored token and files the new one in the same store.
+			const seen: string[] = [];
+			const fetchImpl = (async (_u: string | URL | Request, init?: RequestInit) => {
+				seen.push(String(init?.body));
+				return Response.json({ key: "amrt_k2", keyExpiresAtMs: 50, refreshToken: "amrr_r2", refreshExpiresAtMs: 90 });
+			}) as unknown as typeof fetch;
+			await refreshAndRewrite({ remote, fetchImpl, home, packageDir: process.cwd(), env, platform: "darwin", pathHas: () => false, routerHome: rh, storeDeps: { backend } });
+			expect(seen[0]).toBe(JSON.stringify({ refreshToken: "amrr_r1" }));
+			expect(vault.get("u_ada@team.example")).toBe("amrr_r2");
+			expect(readFileSync(join(rh, "remote.json"), "utf8")).not.toContain("amrr_r2");
+			// An older remote.json with the token inline is honoured until its next refresh.
+			const legacy = parseRemoteRouter(JSON.stringify({ url: "https://t", key: "k", refreshToken: "amrr_inline" }))!;
+			expect(resolveRefreshToken(legacy, rh)).toBe("amrr_inline");
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+
+	test("connect writes Claude Code's settings: base URL in env, a key helper instead of a key, other settings kept", async () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-claude-"));
+		const claude = join(home, ".claude");
+		mkdirSync(claude, { recursive: true });
+		writeFileSync(join(claude, "settings.json"), JSON.stringify({ theme: "dark", env: { ANTHROPIC_API_KEY: "sk-old", FOO: "bar" } }, null, 2) + NL);
+		const env = { HOME: home, PI_CODING_AGENT_DIR: join(home, "no-omp"), AUTO_MODEL_ROUTER_HOME: join(home, ".auto-model-router"), HERMES_HOME: join(home, "no-hermes") };
+		try {
+			const { connectRemote } = await import("../src/cli/connect.ts");
+			const r = connectRemote({ url: "https://team.example", key: "amrt_k", userId: "u_ada", name: "Ada", profile: false, dryRun: false, only: ["claude"], env, home, packageDir: "/pkg", platform: "linux", pathHas: () => false });
+			expect(r.configured.some((c) => c.startsWith("Claude Code ("))).toBe(true);
+			const s = JSON.parse(readFileSync(join(claude, "settings.json"), "utf8")) as { theme: string; env: Record<string, string>; apiKeyHelper: string };
+			expect(s.theme).toBe("dark");
+			expect(s.env).toEqual({ FOO: "bar", ANTHROPIC_BASE_URL: "https://team.example" }); // the stale key is gone
+			expect(s.apiKeyHelper).toMatch(/^bun run ".*\/pkg\/src\/index\.ts" token$/); // an absolute path, drive letter and all on Windows
+			expect(r.envLines.some((l) => l.startsWith("ANTHROPIC_API_KEY="))).toBe(false);
+			expect(readdirSync(claude).some((f) => f.startsWith("settings.json.") && f.endsWith(".bak"))).toBe(true); // the previous file was kept
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+});

package/test/scope.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import { SCOPE_ENV, acceptScope, isScopeSlug } from "../src/context/scope.ts";
+import { parseChatRequest } from "../src/wire/openai/request.ts";
+
+describe("the scope a request may name", () => {
+	test("a slug passes; the env-var sentinel and other non-slugs do not", () => {
+		expect(isScopeSlug("omp-router")).toBe(true);
+		expect(isScopeSlug("ashlands")).toBe(true);
+		expect(isScopeSlug("my.app_v2")).toBe(true);
+		// omp sends the header's literal value when the variable it names is
+		// unset: the NAME must never become a project.
+		expect(isScopeSlug(SCOPE_ENV)).toBe(false);
+		expect(isScopeSlug("")).toBe(false);
+		expect(isScopeSlug("-leading")).toBe(false);
+		expect(isScopeSlug("Has Spaces")).toBe(false);
+		expect(isScopeSlug("a".repeat(129))).toBe(false);
+	});
+
+	test("acceptScope trims and rejects", () => {
+		expect(acceptScope(" omp-router ")).toBe("omp-router");
+		expect(acceptScope(SCOPE_ENV)).toBe("");
+		expect(acceptScope(null)).toBe("");
+	});
+
+	test("the wire parser drops a non-slug X-Agentdox-Scope", () => {
+		const body = { model: "auto", messages: [{ role: "user", content: "hi" }] };
+		const parse = (scope: string) => parseChatRequest(body, new Headers({ "x-agentdox-scope": scope }));
+		expect(parse("omp-router").agentdoxScope).toBe("omp-router");
+		expect(parse(SCOPE_ENV).agentdoxScope).toBe("");
+	});
+});

package/test/turn.test.ts

@@ -73,7 +73,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1, breakHoldOnMechanical: false, switchHorizonTurns: 1, confirmUpgradesBelowConfidence: 0.6 },
 		exploration: { enabled: false, rates: {}, stickyPolicy: "never", holdTurns: { enabled: false, values: [2, 3, 4] } },
 		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024, milestoneTokens: 20_000 },
-		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, memoryLimit: 8, docsLimit: 2, sessionLimit: 6, briefChars: 0, recordTurns: false, maxQueue: 64 },
+		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, memoryLimit: 8, docsLimit: 2, sessionLimit: 6, briefChars: 0, recordTurns: false, injectWithoutTools: false, maxQueue: 64 },
 		compaction: { enabled: false, budgetTokens: 40_000, floorRatio: 1, fitToWindow: true, protectRecentTurns: 4, maxToolResultBytes: 4_096, keepHeadBytes: 512, keepTailBytes: 512, elideSupersededReads: true, collapseDuplicateResults: true, replanGrowthRatio: 1, digestToolResults: false, digestMaxPerTurn: 2 },
 		budget: { onExceeded: "downgrade" },
 		report: { baselines: [], dailySummary: false },
@@ -660,6 +660,81 @@ describe("agentdox write-back sees the shape of the turn", () => {
 	});
 });
 
+describe("agentdox injection sees the shape of the turn", () => {
+	const AGENT_TOOL = { name: "read", description: "read a file", schemaBytes: 128 };
+
+	/** A bridge that always has a block, counting how often it is asked. */
+	function mkServingBridge(): { bridge: ContextBridge; resolves: number[] } {
+		const resolves: number[] = [];
+		return {
+			resolves,
+			bridge: {
+				enabled: true,
+				resolve: () => {
+					resolves.push(1);
+					return Promise.resolve({ block: "<project-context>ctx</project-context>", version: "v1", fetchedAtMs: 1 });
+				},
+				recordTurn: () => {},
+				flush: () => Promise.resolve(),
+				pruneBlocks: () => 0,
+				close: () => {},
+			},
+		};
+	}
+
+	function oneDispatch() {
+		const { router } = mkRouter([mkDecision("trivial", "cheap/model", { escalateTo: null })]);
+		const { upstream } = mkUpstream([
+			{ kind: "chunks", chunks: [startChunk("cheap/model"), textChunk("high"), finishChunk("stop"), usageChunk({}, 0.0001)] },
+		]);
+		const { ledger } = mkLedger();
+		const { store } = mkConversations();
+		const { sink, errors } = mkSink();
+		return { router, upstream, ledger, store, sink, errors };
+	}
+
+	test("a harness utility call gets no context block", async () => {
+		// Measured on one omp turn: seven tool-less side calls (title, ratings)
+		// each received the whole ~6k-token block — 42k prompt tokens for
+		// answers ABOUT the conversation. The tool array is the discriminator,
+		// exactly as for recording.
+		const { router, upstream, ledger, store, sink, errors } = oneDispatch();
+		const { bridge, resolves } = mkServingBridge();
+		const req: NormRequest = { ...mkReq(), agentdoxScope: "proj", tools: [] };
+
+		await runTurn(req, sink, { config: mkConfig({ enabled: false }), router, upstream, ledger, conversations: store, catalog, context: bridge }, new AbortController().signal);
+
+		expect(errors).toHaveLength(0);
+		expect(resolves).toHaveLength(0);
+		expect(store.load(req.conversationKey).contextVersion).toBeNull();
+	});
+
+	test("an agent turn with tools is injected", async () => {
+		const { router, upstream, ledger, store, sink, errors } = oneDispatch();
+		const { bridge, resolves } = mkServingBridge();
+		const req: NormRequest = { ...mkReq(), agentdoxScope: "proj", tools: [AGENT_TOOL] };
+
+		await runTurn(req, sink, { config: mkConfig({ enabled: false }), router, upstream, ledger, conversations: store, catalog, context: bridge }, new AbortController().signal);
+
+		expect(errors).toHaveLength(0);
+		expect(resolves).toHaveLength(1);
+		expect(store.load(req.conversationKey).contextVersion).toBe("v1");
+	});
+
+	test("context.injectWithoutTools restores injection into tool-less calls", async () => {
+		const { router, upstream, ledger, store, sink, errors } = oneDispatch();
+		const { bridge, resolves } = mkServingBridge();
+		const base = mkConfig({ enabled: false });
+		const config: RouterConfig = { ...base, context: { ...base.context, injectWithoutTools: true } };
+		const req: NormRequest = { ...mkReq(), agentdoxScope: "proj", tools: [] };
+
+		await runTurn(req, sink, { config, router, upstream, ledger, conversations: store, catalog, context: bridge }, new AbortController().signal);
+
+		expect(errors).toHaveLength(0);
+		expect(resolves).toHaveLength(1);
+	});
+});
+
 describe("spend reaches the conversation total however the dispatch ends", () => {
 	test("a dispatch that dies mid-stream still books what it was billed", async () => {
 		// Live data: 152 aborted dispatches billed $0.9985 — 30% of all spend —