auto-model-router 0.9.0 → 0.11.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.9.0",
+    "version": "0.11.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.9.0",
+      "version": "0.11.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -1330,10 +1330,30 @@ 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.
+
+### One file to install
+
+A remote that serves members can hand them this package as a single executable: the CLI
+compiled by `bun build --compile` for their operating system (`buildExecutable` in the
+library, one of `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`,
+`windows-x64`), with the package's own source files embedded. Nothing else is installed —
+no bun, no npm. omp still loads the extensions from disk and Hermes still copies its
+plugin, so the first `connect` from the executable writes the embedded files out under
+`<router home>/package/<version>/` and points every harness there; the executable itself
+becomes Claude Code's key helper and, with `--profile`, goes on PATH. `connect
+--setup-token <token>` trades a one-time onboarding token at the remote's
+`/setup/exchange` for the credential, so the install command carries no key at all.
+`remote.json` records the executable, and a refresh from inside omp keeps the helper
+pointed at it.
 
 ## Multiple coding harnesses, one router
 
@@ -1471,6 +1491,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

@@ -36,6 +36,12 @@ export interface RemoteRouter {
 	refreshExpiresAtMs?: number;
 	/** What the remote calls this machine. */
 	device?: string;
+	/**
+	 * The compiled executable that ran `connect`, when one did. A refresh from
+	 * inside omp re-writes every harness config and must point Claude Code's key
+	 * helper at it, not at a `bun run` of the extracted source.
+	 */
+	executable?: string;
 }
 
 export function remoteFilePath(routerHome: string): string {
@@ -59,6 +65,7 @@ export function parseRemoteRouter(text: string): RemoteRouter | null {
 			...(typeof raw.keyExpiresAtMs === "number" ? { keyExpiresAtMs: raw.keyExpiresAtMs } : {}),
 			...(typeof raw.refreshExpiresAtMs === "number" ? { refreshExpiresAtMs: raw.refreshExpiresAtMs } : {}),
 			...(typeof raw.device === "string" && raw.device !== "" ? { device: raw.device } : {}),
+			...(typeof raw.executable === "string" && raw.executable !== "" ? { executable: raw.executable } : {}),
 		};
 	} catch {
 		return null;

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.9.0",
+  "version": "0.11.0",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/cli/build-executable.ts

@@ -0,0 +1,142 @@
+/**
+ * Builds the single-file member install: this package compiled by
+ * `bun build --compile` for one operating system, with the package's own source
+ * files embedded so `connect` can write out what omp and Hermes load from disk
+ * (see `embedded.ts`). A team server calls this once per router version and
+ * target and serves the result; nothing here runs on a member's machine.
+ *
+ * Cross-compiling needs bun's runtime for the target, which bun downloads on
+ * first use and caches; a host without network access to bun's releases can
+ * only build its own platform.
+ */
+
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { EMBEDDED_GLOBAL, type EmbeddedPackage } from "./embedded.ts";
+
+export const EXECUTABLE_TARGETS = ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "windows-x64"] as const;
+export type ExecutableTarget = (typeof EXECUTABLE_TARGETS)[number];
+
+export function isExecutableTarget(value: string): value is ExecutableTarget {
+	return (EXECUTABLE_TARGETS as readonly string[]).includes(value);
+}
+
+/** The target of the machine this process runs on, or null when bun has no build for it. */
+export function hostTarget(platform = process.platform, arch = process.arch): ExecutableTarget | null {
+	const cpu = arch === "x64" ? "x64" : arch === "arm64" ? "arm64" : null;
+	if (cpu === null) return null;
+	if (platform === "linux") return `linux-${cpu}`;
+	if (platform === "darwin") return `darwin-${cpu}`;
+	if (platform === "win32" && cpu === "x64") return "windows-x64";
+	return null;
+}
+
+/** The file name a build for `target` is served under. */
+export function executableFileName(target: ExecutableTarget): string {
+	return `auto-model-router-${target}${target.startsWith("windows") ? ".exe" : ""}`;
+}
+
+/** The package entries the install needs: the CLI, the harness integrations, and the two runtime deps. */
+const PACKAGE_ENTRIES = ["package.json", "README.md", "src", "omp-extension", "hermes-plugin", "opencode-plugin"] as const;
+const RUNTIME_DEPS = ["yaml", "zod"] as const;
+
+function walk(root: string, rel: string, keep: (rel: string) => boolean, out: Record<string, string>): void {
+	const abs = join(root, ...rel.split("/").filter((s) => s !== ""));
+	const st = statSync(abs);
+	if (st.isDirectory()) {
+		for (const name of readdirSync(abs)) walk(root, rel === "" ? name : `${rel}/${name}`, keep, out);
+		return;
+	}
+	if (!keep(rel)) return;
+	// Everything the filters let through is text (ts, py, yaml, js, json, md). No byte-level
+	// sniffing: src/util/hash.ts holds a NUL inside a string literal and was silently dropped
+	// by one, which broke the extension on a member machine and nowhere else.
+	out[rel] = readFileSync(abs, "utf8");
+}
+
+const keepPackageFile = (rel: string): boolean => !rel.includes("__pycache__") && !rel.endsWith(".pyc") && !rel.endsWith(".test.ts");
+const keepDepFile = (rel: string): boolean => !/(^|\/)(tests?|__tests__)\//.test(rel) && !/\.(d\.[cm]?ts|map)$/.test(rel) && !/\.test\.[cm]?[jt]sx?$/.test(rel);
+
+/**
+ * Every file the executable embeds, keyed by path relative to the package
+ * root. The runtime dependencies are resolved from the package's own location,
+ * so a `bun link`ed package finds them too.
+ */
+export function collectPackageFiles(packageDir: string): EmbeddedPackage {
+	const files: Record<string, string> = {};
+	for (const entry of PACKAGE_ENTRIES) {
+		if (existsSync(join(packageDir, entry))) walk(packageDir, entry, keepPackageFile, files);
+	}
+	for (const dep of RUNTIME_DEPS) {
+		let depDir: string;
+		try {
+			depDir = dirname(Bun.resolveSync(`${dep}/package.json`, packageDir));
+		} catch {
+			continue;
+		}
+		const depFiles: Record<string, string> = {};
+		walk(depDir, "", keepDepFile, depFiles);
+		for (const [rel, content] of Object.entries(depFiles)) files[`node_modules/${dep}/${rel}`] = content;
+	}
+	const version = (JSON.parse(files["package.json"] ?? "{}") as { version?: string }).version ?? "0.0.0";
+	return { version, files };
+}
+
+export interface BuildExecutableOptions {
+	packageDir: string;
+	target: ExecutableTarget;
+	/** Where the executable goes; created or replaced. */
+	outFile: string;
+	/** The bun binary to build with; this process's own when it is bun. */
+	bun?: string;
+	/** A directory for the manifest and entry module; a temp dir when absent, removed afterwards. */
+	stageDir?: string;
+}
+
+export type BuildExecutableResult = { ok: true; path: string; bytes: number } | { ok: false; reason: string };
+
+function bunBinary(explicit: string | undefined): string | null {
+	if (explicit !== undefined) return explicit;
+	if (/(^|[\\/])bun(\.exe)?$/i.test(process.execPath)) return process.execPath;
+	return Bun.which("bun");
+}
+
+/**
+ * Compiles the package at `packageDir` into `outFile` for `target`. The entry
+ * module sets the global `embedded.ts` reads and then loads the CLI, so the CLI
+ * itself never knows at build time whether it will be compiled.
+ */
+export async function buildExecutable(opts: BuildExecutableOptions): Promise<BuildExecutableResult> {
+	const bun = bunBinary(opts.bun);
+	if (bun === null) return { ok: false, reason: "bun is not available to build with" };
+	const stage = opts.stageDir ?? mkdtempSync(join(tmpdir(), "amr-exe-"));
+	mkdirSync(stage, { recursive: true });
+	try {
+		const pkg = collectPackageFiles(opts.packageDir);
+		if (pkg.files["src/index.ts"] === undefined) return { ok: false, reason: `${opts.packageDir} does not hold the router package (no src/index.ts)` };
+		writeFileSync(join(stage, "manifest.json"), JSON.stringify(pkg), "utf8");
+		const entry = join(opts.packageDir, "src", "index.ts").replaceAll("\\", "/");
+		writeFileSync(
+			join(stage, "entry.ts"),
+			[
+				`import manifest from "./manifest.json" with { type: "file" };`,
+				`(globalThis as Record<string, unknown>)[${JSON.stringify(EMBEDDED_GLOBAL)}] = { manifestPath: manifest };`,
+				`await import(${JSON.stringify(entry)});`,
+				"",
+			].join("\n"),
+			"utf8",
+		);
+		mkdirSync(dirname(opts.outFile), { recursive: true });
+		const proc = Bun.spawn([bun, "build", "--compile", `--target=bun-${opts.target}`, join(stage, "entry.ts"), "--outfile", opts.outFile], { stdout: "pipe", stderr: "pipe", cwd: opts.packageDir });
+		const [stdout, stderr, exitCode] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+		if (exitCode !== 0 || !existsSync(opts.outFile)) {
+			const tail = `${stderr}\n${stdout}`.trim().split("\n").slice(-6).join("\n");
+			return { ok: false, reason: `bun build --compile for ${opts.target} failed (exit ${exitCode}): ${tail}` };
+		}
+		return { ok: true, path: opts.outFile, bytes: statSync(opts.outFile).size };
+	} finally {
+		if (opts.stageDir === undefined) rmSync(stage, { recursive: true, force: true });
+	}
+}
+

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

@@ -25,10 +25,12 @@
  */
 
 import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { refreshAccountOf, remoteFilePath } from "../../omp-extension/remote-logic.ts";
+import { SCOPE_ENV } from "../context/scope.ts";
+import { executablePath, materializePackage, readEmbeddedPackage } from "./embedded.ts";
 import { pickStore, saveRefreshToken, type StoreDeps, type StoreKind } from "./credential-store.ts";
 import { flagString, type CliArgs } from "./args.ts";
 
@@ -47,7 +49,7 @@ 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;
@@ -57,6 +59,12 @@ export interface ConnectOptions {
 	keyExpiresAtMs?: number;
 	refreshExpiresAtMs?: number;
 	device?: string;
+	/**
+	 * The compiled executable running this, when one is (see embedded.ts). It
+	 * becomes Claude Code's key helper and goes on PATH with --profile, and
+	 * remote.json records it so a refresh from omp keeps pointing at it.
+	 */
+	exePath?: string;
 	platform: string;
 	pathHas: (bin: string) => boolean;
 }
@@ -141,10 +149,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;
@@ -162,7 +173,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(
@@ -201,14 +212,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. */
@@ -252,6 +264,7 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 				...(o.keyExpiresAtMs !== undefined ? { keyExpiresAtMs: o.keyExpiresAtMs } : {}),
 				...(o.refreshExpiresAtMs !== undefined ? { refreshExpiresAtMs: o.refreshExpiresAtMs } : {}),
 				...(o.device !== undefined && o.device !== "" ? { device: o.device } : {}),
+				...(o.exePath !== undefined && o.exePath !== "" ? { executable: o.exePath } : {}),
 			},
 			null,
 			2,
@@ -334,8 +347,9 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 		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` };
+		// The executable is its own helper; under bun the source entry is.
+		const helper = o.exePath !== undefined && o.exePath !== "" ? `"${o.exePath.replaceAll("\\", "/")}" token` : `bun run "${resolve(o.packageDir, "src", "index.ts").replaceAll("\\", "/")}" token`;
+		const next = { ...settings, env, apiKeyHelper: helper };
 		const after = `${JSON.stringify(next, null, 2)}\n`;
 		if (after !== before) {
 			if (before !== "" && !o.dryRun) writeFileSync(`${settingsPath}.${new Date().toISOString().replaceAll(":", "-")}.bak`, before, "utf8");
@@ -353,11 +367,14 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 				const [k, ...v] = line.split("=");
 				Bun.spawnSync(["setx", k!, v.join("=")], { stdout: "ignore", stderr: "ignore" });
 			}
+			// Not setx for PATH: it truncates at 1024 characters and would eat the rest.
+			if (o.exePath !== undefined && o.exePath !== "") addToUserPathWindows(dirname(o.exePath));
 			report.notes.push("user environment variables set with setx; open a new terminal");
 		} else {
 			const shell = o.env.SHELL ?? "";
 			const rc = shell.includes("zsh") ? join(o.home, ".zshrc") : join(o.home, ".bashrc");
-			const block = `\n# auto-model-router remote (added by \`auto-model-router connect\`)\n${report.envLines.map((l) => `export ${l}`).join("\n")}\n`;
+			const pathLine = o.exePath !== undefined && o.exePath !== "" ? [`export PATH="${dirname(o.exePath)}:$PATH"`] : [];
+			const block = `\n# auto-model-router remote (added by \`auto-model-router connect\`)\n${[...report.envLines.map((l) => `export ${l}`), ...pathLine].join("\n")}\n`;
 			const before = existsSync(rc) ? readFileSync(rc, "utf8") : "";
 			if (!before.includes("# auto-model-router remote") && !before.includes("# auto-model-router team")) appendFileSync(rc, block, "utf8");
 			else write(rc, before.replace(/\n# auto-model-router (?:remote|team)[^\n]*\n(?:export [^\n]*\n)*/, block));
@@ -369,16 +386,84 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 	return report;
 }
 
+/** What a team's one-time setup token is traded for. */
+export interface IssuedCredential {
+	key: string;
+	refreshToken: string;
+	keyExpiresAtMs?: number;
+	refreshExpiresAtMs?: number;
+	userId: string;
+	name: string;
+}
+
+/**
+ * Trades a one-time setup token for this machine's credential at the team's
+ * exchange route, so the install needs nothing on the machine but this
+ * program: the token is the only secret in the install command and dies on use.
+ */
+export async function exchangeSetupToken(url: string, token: string, device: string, fetchImpl: typeof fetch = fetch): Promise<IssuedCredential> {
+	const res = await fetchImpl(`${url}/setup/exchange`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ token, device }), signal: AbortSignal.timeout(15_000) });
+	if (res.status === 401) throw new Error("the setup token was refused (expired or already used); get a new one from the team's portal");
+	if (!res.ok) throw new Error(`the team's setup exchange answered ${res.status}`);
+	const body = (await res.json()) as Record<string, unknown>;
+	if (typeof body.key !== "string" || body.key === "") throw new Error("the team's setup exchange returned no key");
+	return {
+		key: body.key,
+		refreshToken: typeof body.refreshToken === "string" ? body.refreshToken : "",
+		...(typeof body.keyExpiresAtMs === "number" ? { keyExpiresAtMs: body.keyExpiresAtMs } : {}),
+		...(typeof body.refreshExpiresAtMs === "number" ? { refreshExpiresAtMs: body.refreshExpiresAtMs } : {}),
+		userId: typeof body.userId === "string" ? body.userId : "",
+		name: typeof body.name === "string" ? body.name : "",
+	};
+}
+
+/** Adds `dir` to the user's PATH on Windows, once, through the registry-backed API rather than setx. */
+function addToUserPathWindows(dir: string): void {
+	const quoted = `'${dir.replaceAll("'", "''")}'`;
+	const script = `$d=${quoted}; $p=[Environment]::GetEnvironmentVariable('Path','User'); if ($null -eq $p) { $p='' }; if (($p -split ';') -notcontains $d) { [Environment]::SetEnvironmentVariable('Path', (($p.TrimEnd(';') + ';' + $d).TrimStart(';')), 'User') }`;
+	Bun.spawnSync(["powershell", "-NoProfile", "-NonInteractive", "-Command", script], { stdout: "ignore", stderr: "ignore" });
+}
+
+/**
+ * Where the harness integrations are read from. Under bun that is this
+ * package; in the compiled executable it is the copy written out from the
+ * executable's own embedded files.
+ */
+async function resolvePackageDir(): Promise<string> {
+	const embedded = await readEmbeddedPackage();
+	if (embedded === null) return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+	const raw = process.env.AUTO_MODEL_ROUTER_HOME ?? join(homedir(), ".auto-model-router");
+	return materializePackage(expand(raw, homedir()), embedded);
+}
+
 export async function connectCommand(args: CliArgs): Promise<void> {
 	const url = (flagString(args, "url") ?? process.env.AUTO_MODEL_ROUTER_URL ?? "").replace(/\/+$/, "");
-	const key = flagString(args, "key") ?? process.env.AUTO_MODEL_ROUTER_API_KEY ?? "";
-	if (url === "" || key === "") throw new Error("connect needs --url <remote router> and --key <its key>");
+	let key = flagString(args, "key") ?? process.env.AUTO_MODEL_ROUTER_API_KEY ?? "";
+	const setupToken = flagString(args, "setup-token") ?? "";
+	if (url === "" || (key === "" && setupToken === "")) throw new Error("connect needs --url <remote router> and either --key <its key> or --setup-token <one-time token from the team>");
 	const only = (flagString(args, "harness") ?? "").split(",").map((s) => s.trim().toLowerCase()).filter((s) => s !== "");
 	const pathHas = (bin: string): boolean => Bun.which(bin) !== null;
-	const packageDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
-	// Verify the key against the route every router serves before touching anything.
+	const packageDir = await resolvePackageDir();
+	const exePath = executablePath();
 	let name = flagString(args, "name") ?? "";
 	let userId = flagString(args, "user-id") ?? "";
+	let device = flagString(args, "device") ?? "";
+	// A remote that issues short-lived keys hands these over beside the key.
+	let refreshToken = flagString(args, "refresh-token") ?? "";
+	let keyExpires = Number.parseInt(flagString(args, "key-expires") ?? "", 10);
+	let refreshExpires = Number.parseInt(flagString(args, "refresh-expires") ?? "", 10);
+	if (setupToken !== "") {
+		if (device === "") device = hostname();
+		const issued = await exchangeSetupToken(url, setupToken, device);
+		key = issued.key;
+		refreshToken = issued.refreshToken;
+		keyExpires = issued.keyExpiresAtMs ?? Number.NaN;
+		refreshExpires = issued.refreshExpiresAtMs ?? Number.NaN;
+		if (issued.userId !== "") userId = issued.userId;
+		if (issued.name !== "") name = issued.name;
+		console.log(`credential issued for ${name === "" ? userId : name} (device ${device})`);
+	}
+	// Verify the key against the route every router serves before touching anything.
 	try {
 		const res = await fetch(`${url}/v1/models`, { headers: { authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(10_000) });
 		if (res.status === 401) throw new Error("the remote router rejected this key");
@@ -391,11 +476,6 @@ export async function connectCommand(args: CliArgs): Promise<void> {
 	// 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 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,
@@ -414,7 +494,9 @@ export async function connectCommand(args: CliArgs): Promise<void> {
 		...(Number.isFinite(keyExpires) ? { keyExpiresAtMs: keyExpires } : {}),
 		...(Number.isFinite(refreshExpires) ? { refreshExpiresAtMs: refreshExpires } : {}),
 		...(device === "" ? {} : { device }),
+		...(exePath === null ? {} : { exePath }),
 	});
+	if (exePath !== null) console.log(`executable ${exePath}; package files under ${packageDir}`);
 	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/embedded.ts

@@ -0,0 +1,78 @@
+/**
+ * The router package carried inside a compiled executable.
+ *
+ * `bun build --compile` turns this CLI into one file per operating system, and
+ * that is what a team member downloads: no bun, no npm, nothing else. But the
+ * harness integrations are not the CLI — omp loads `omp-extension/*.ts` with
+ * its own runtime and Hermes copies `hermes-plugin/` — so the executable also
+ * carries the package's source files and writes them out under the router home
+ * the first time `connect` runs. The build side (`build-executable.ts`) puts a
+ * JSON manifest of those files into the executable and sets a global that names
+ * it; this side reads it.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface EmbeddedPackage {
+	/** The router package's version, which also names the extracted directory. */
+	version: string;
+	/** Relative path (forward slashes) → file content. Text only: the package has no binaries. */
+	files: Record<string, string>;
+}
+
+/** What the build's entry module sets before the CLI loads. */
+export interface EmbeddedHandle {
+	/** Path of the manifest inside the executable's embedded filesystem. */
+	manifestPath: string;
+}
+
+export const EMBEDDED_GLOBAL = "AUTO_MODEL_ROUTER_EMBEDDED";
+
+export function embeddedHandle(): EmbeddedHandle | null {
+	const h = (globalThis as Record<string, unknown>)[EMBEDDED_GLOBAL];
+	return typeof h === "object" && h !== null && typeof (h as EmbeddedHandle).manifestPath === "string" ? (h as EmbeddedHandle) : null;
+}
+
+/** True when this process is the compiled executable rather than `bun run src/index.ts`. */
+export function isCompiled(): boolean {
+	return embeddedHandle() !== null;
+}
+
+/** The executable's own path when compiled, for key helpers and PATH; null under bun. */
+export function executablePath(): string | null {
+	return isCompiled() ? process.execPath : null;
+}
+
+export async function readEmbeddedPackage(): Promise<EmbeddedPackage | null> {
+	const h = embeddedHandle();
+	if (h === null) return null;
+	const parsed = JSON.parse(await Bun.file(h.manifestPath).text()) as EmbeddedPackage;
+	return typeof parsed.version === "string" && typeof parsed.files === "object" && parsed.files !== null ? parsed : null;
+}
+
+const MARKER = ".materialized";
+
+/**
+ * Writes the embedded package under `<routerHome>/package/<version>/` and
+ * returns that directory, the `packageDir` every harness config then points
+ * at. Idempotent: a marker records the manifest's hash, so an unchanged
+ * executable writes nothing on later runs and a rebuilt one of the same
+ * version refreshes the files.
+ */
+export function materializePackage(routerHome: string, pkg: EmbeddedPackage): string {
+	const dir = join(routerHome, "package", pkg.version);
+	const digest = Bun.hash(JSON.stringify(pkg.files)).toString(16);
+	try {
+		if (readFileSync(join(dir, MARKER), "utf8").trim() === digest) return dir;
+	} catch {
+		/* not written yet */
+	}
+	for (const [rel, content] of Object.entries(pkg.files)) {
+		const target = join(dir, ...rel.split("/"));
+		mkdirSync(dirname(target), { recursive: true });
+		writeFileSync(target, content, "utf8");
+	}
+	writeFileSync(join(dir, MARKER), `${digest}\n`, "utf8");
+	return dir;
+}

package/src/cli/refresh.ts

@@ -13,6 +13,7 @@
  * its own expiry, so a session still holding it is never cut.
  */
 
+import { executablePath, materializePackage, readEmbeddedPackage } from "./embedded.ts";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -89,7 +90,12 @@ export async function refreshAndRewrite(opts: { remote: RemoteRouter; fetchImpl?
 	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)), "..", "..");
+	// The compiled executable rewrites from its own extracted package and keeps
+	// itself as the key helper; the omp extension, running from that extracted
+	// package, learns the executable from remote.json.
+	const embedded = opts.packageDir === undefined ? await readEmbeddedPackage() : null;
+	const packageDir = opts.packageDir ?? (embedded === null ? resolve(dirname(fileURLToPath(import.meta.url)), "..", "..") : materializePackage(rh, embedded));
+	const exePath = opts.remote.executable ?? executablePath() ?? undefined;
 	connectRemote({
 		url: opts.remote.url,
 		key: fresh.key,
@@ -110,6 +116,7 @@ export async function refreshAndRewrite(opts: { remote: RemoteRouter; fetchImpl?
 		// 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 } : {}),
+		...(exePath !== undefined ? { exePath } : {}),
 		// 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

@@ -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 { isCompiled, readEmbeddedPackage } from "./cli/embedded.ts";
 import { refreshCommand, tokenCommand } from "./cli/refresh.ts";
 import { modelsCommand } from "./cli/models.ts";
 import { reportCommand } from "./cli/report.ts";
@@ -27,7 +28,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 with --key[, --refresh-token] or --setup-token <one-time token from a team>; --scope pins one project for the whole machine (default: each workspace's own); --profile persists the environment and, from the compiled executable, PATH)
   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
@@ -56,7 +57,9 @@ async function main(): Promise<number> {
 	const args = parseArgv(process.argv.slice(2));
 
 	if (args.flags.has("version")) {
-		const pkg: unknown = await Bun.file(join(import.meta.dir, "..", "package.json")).json();
+		// The compiled executable has no package.json beside it; its embedded copy answers.
+		const embedded = await readEmbeddedPackage();
+		const pkg: unknown = embedded ?? (await Bun.file(join(import.meta.dir, "..", "package.json")).json());
 		const value =
 			typeof pkg === "object" && pkg !== null && "version" in pkg && typeof pkg.version === "string"
 				? pkg.version
@@ -108,7 +111,8 @@ async function main(): Promise<number> {
 	}
 }
 
-if (import.meta.main) {
+// The compiled executable loads this module from its entry, so it is never import.meta.main there.
+if (import.meta.main || isCompiled()) {
 	try {
 		const code = await main();
 		if (code !== 0) process.exit(code);

package/src/lib.ts

@@ -23,5 +23,6 @@ export { openDb } from "./util/sqlite.ts";
 export { spendUsdSince, feedbackView, exportRows, exportCsv, harnessScopeParam, type HarnessScope, type ExportRow, type FeedbackRow, type FeedbackByModel, type FeedbackView } from "./cost/views.ts";
 export { createLedger } from "./cost/ledger.ts";
 export { createFeedbackStore, type FeedbackStore, type FeedbackRecord } from "./cost/feedback.ts";
+export { buildExecutable, collectPackageFiles, executableFileName, hostTarget, isExecutableTarget, EXECUTABLE_TARGETS, type ExecutableTarget, type BuildExecutableResult } from "./cli/build-executable.ts";
 export type { RequestPolicy } from "./wire/types.ts";
 export type { Ledger, LedgerEntry } from "./cost/types.ts";

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/executable.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildExecutable, collectPackageFiles, executableFileName, hostTarget, isExecutableTarget } from "../src/cli/build-executable.ts";
+import { connectRemote, exchangeSetupToken } from "../src/cli/connect.ts";
+import { EMBEDDED_GLOBAL, embeddedHandle, isCompiled, materializePackage, readEmbeddedPackage } from "../src/cli/embedded.ts";
+import { parseRemoteRouter } from "../omp-extension/remote-logic.ts";
+
+const NL = String.fromCharCode(10);
+
+describe("the single-file member install", () => {
+	test("the embedded package is the install: CLI, harness integrations, runtime deps; no tests, no caches", () => {
+		const pkg = collectPackageFiles(process.cwd());
+		expect(pkg.version).toBe((JSON.parse(readFileSync("package.json", "utf8")) as { version: string }).version);
+		expect(pkg.files["src/index.ts"]).toContain("connect");
+		expect(pkg.files["omp-extension/router-embed.ts"]).toBeDefined();
+		expect(pkg.files["hermes-plugin/native/__init__.py"] ?? pkg.files[Object.keys(pkg.files).find((k) => k.startsWith("hermes-plugin/")) ?? ""]).toBeDefined();
+		expect(pkg.files["node_modules/zod/package.json"]).toBeDefined();
+		expect(pkg.files["node_modules/yaml/package.json"]).toBeDefined();
+		const names = Object.keys(pkg.files);
+		// Every non-test source file, none missing: a dropped one only fails on a member machine, when the extension imports it.
+		const onDisk = readdirSync("src", { recursive: true }).map(String).filter((f) => /\.(ts|py|yaml)$/.test(f) && !f.endsWith(".test.ts")).map((f) => `src/${f.replaceAll("\\", "/")}`);
+		expect(onDisk.length).toBeGreaterThan(50);
+		for (const f of onDisk) expect(names).toContain(f);
+		expect(names.some((n) => n.endsWith(".test.ts"))).toBe(false);
+		expect(names.some((n) => n.includes("__pycache__") || n.endsWith(".pyc"))).toBe(false);
+		expect(names.some((n) => /\.d\.ts$/.test(n) && n.startsWith("node_modules/"))).toBe(false);
+	});
+
+	test("targets and file names", () => {
+		expect(isExecutableTarget("linux-x64")).toBe(true);
+		expect(isExecutableTarget("linux-x86")).toBe(false);
+		expect(executableFileName("windows-x64")).toBe("auto-model-router-windows-x64.exe");
+		expect(executableFileName("darwin-arm64")).toBe("auto-model-router-darwin-arm64");
+		expect(hostTarget("win32", "x64")).toBe("windows-x64");
+		expect(hostTarget("darwin", "arm64")).toBe("darwin-arm64");
+		expect(hostTarget("win32", "arm64")).toBeNull();
+	});
+
+	test("under bun there is no embedded package", async () => {
+		expect(isCompiled()).toBe(false);
+		expect(embeddedHandle()).toBeNull();
+		expect(await readEmbeddedPackage()).toBeNull();
+	});
+
+	test("materializing writes the files once, keyed by content, under the router home", () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-mat-"));
+		try {
+			const pkg = { version: "9.9.9", files: { "package.json": `{"version":"9.9.9"}${NL}`, "src/index.ts": `console.log(1)${NL}`, "omp-extension/x.ts": "export {}" } };
+			const dir = materializePackage(home, pkg);
+			expect(dir).toBe(join(home, "package", "9.9.9"));
+			expect(readFileSync(join(dir, "src", "index.ts"), "utf8")).toBe(`console.log(1)${NL}`);
+			// Unchanged: a second call leaves a hand-edited file alone (nothing is rewritten).
+			writeFileSync(join(dir, "src", "index.ts"), "edited", "utf8");
+			expect(materializePackage(home, pkg)).toBe(dir);
+			expect(readFileSync(join(dir, "src", "index.ts"), "utf8")).toBe("edited");
+			// A rebuilt executable of the same version with different content refreshes it.
+			expect(materializePackage(home, { ...pkg, files: { ...pkg.files, "src/index.ts": "v2" } })).toBe(dir);
+			expect(readFileSync(join(dir, "src", "index.ts"), "utf8")).toBe("v2");
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+
+	test("connect from the executable: it is Claude Code's key helper, goes on PATH, and remote.json names it", () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-exe-connect-"));
+		const claude = join(home, ".claude");
+		mkdirSync(claude, { recursive: true });
+		const rh = join(home, ".auto-model-router");
+		const env = { HOME: home, PI_CODING_AGENT_DIR: join(home, "no-omp"), AUTO_MODEL_ROUTER_HOME: rh, HERMES_HOME: join(home, "no-hermes"), SHELL: "/bin/zsh" };
+		const exe = join(rh, "bin", "auto-model-router");
+		try {
+			const r = connectRemote({ url: "https://team.example", key: "amrt_k", userId: "u_ada", name: "Ada", profile: true, dryRun: false, only: ["claude"], env, home, packageDir: join(rh, "package", "1.0.0"), exePath: exe, 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 { apiKeyHelper: string };
+			expect(s.apiKeyHelper).toBe(`"${exe.replaceAll("\\", "/")}" token`);
+			expect(parseRemoteRouter(readFileSync(join(rh, "remote.json"), "utf8"))?.executable).toBe(exe);
+			const rc = readFileSync(join(home, ".zshrc"), "utf8");
+			expect(rc).toContain(`export PATH="${join(rh, "bin")}:$PATH"`);
+			expect(rc).toContain("export AUTO_MODEL_ROUTER_URL=https://team.example");
+			// Re-running keeps one block.
+			connectRemote({ url: "https://team.example", key: "amrt_k2", userId: "u_ada", name: "Ada", profile: true, dryRun: false, only: ["claude"], env, home, packageDir: join(rh, "package", "1.0.0"), exePath: exe, platform: "linux", pathHas: () => false });
+			expect(readFileSync(join(home, ".zshrc"), "utf8").split("# auto-model-router remote").length).toBe(2);
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+
+	test("a setup token is traded for the credential; a refused token says so", async () => {
+		const seen: { url: string; body: string }[] = [];
+		const ok = (async (url: string | URL | Request, init?: RequestInit) => {
+			seen.push({ url: String(url), body: String(init?.body) });
+			return Response.json({ key: "amrt_new", refreshToken: "amrr_new", keyExpiresAtMs: 10, refreshExpiresAtMs: 20, userId: "u_ada", name: "Ada", teamUrl: "https://team.example" });
+		}) as unknown as typeof fetch;
+		const issued = await exchangeSetupToken("https://team.example", "amrs_t", "laptop", ok);
+		expect(issued).toEqual({ key: "amrt_new", refreshToken: "amrr_new", keyExpiresAtMs: 10, refreshExpiresAtMs: 20, userId: "u_ada", name: "Ada" });
+		expect(seen[0]?.url).toBe("https://team.example/setup/exchange");
+		expect(JSON.parse(seen[0]?.body ?? "{}")).toEqual({ token: "amrs_t", device: "laptop" });
+		const refused = (async () => Response.json({ error: "invalid_token" }, { status: 401 })) as unknown as typeof fetch;
+		await expect(exchangeSetupToken("https://team.example", "amrs_old", "laptop", refused)).rejects.toThrow("refused");
+	});
+
+	test("the executable builds for this host and knows its version from the embedded package", async () => {
+		const target = hostTarget();
+		if (target === null) return;
+		const dir = mkdtempSync(join(tmpdir(), "amr-build-"));
+		try {
+			const out = join(dir, executableFileName(target));
+			const r = await buildExecutable({ packageDir: process.cwd(), target, outFile: out });
+			if (!r.ok) throw new Error(r.reason);
+			expect(existsSync(out)).toBe(true);
+			expect(r.bytes).toBeGreaterThan(10_000_000);
+			const version = Bun.spawnSync([out, "--version"], { stdout: "pipe", stderr: "pipe" }).stdout.toString().trim();
+			expect(version).toBe((JSON.parse(readFileSync("package.json", "utf8")) as { version: string }).version);
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	}, 120_000);
+
+	test("the global handle is what marks a compiled process", () => {
+		const g = globalThis as Record<string, unknown>;
+		g[EMBEDDED_GLOBAL] = { manifestPath: "/$bunfs/root/manifest.json" };
+		try {
+			expect(isCompiled()).toBe(true);
+			expect(embeddedHandle()?.manifestPath).toBe("/$bunfs/root/manifest.json");
+		} finally {
+			delete g[EMBEDDED_GLOBAL];
+		}
+		expect(isCompiled()).toBe(false);
+	});
+});

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

@@ -6,6 +6,7 @@ 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 { 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";
@@ -114,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");
@@ -122,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", () => {

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 —