auto-model-router 0.2.21 → 0.2.23

package/.claude/skills/agentdox/SKILL.md

@@ -43,7 +43,8 @@ Deterministic, so the same folder always resolves to the same slug:
      stop and ask for a distinguishing slug.
    - **Near match** (`my-app` vs `my-app-v2`) — a stop sign: ask, rather than fork a second
      namespace for one project.
-4. `project_ensure {slug, name}` — `name` is the readable form of the folder.
+4. `project_ensure {slug}` — `name` is optional and only used if the project is new; it
+   defaults to the slug, so pass one only when the readable form differs.
 5. **Make `.env.agentdox` un-committable *before* writing it.** Run `git check-ignore -v
    .env.agentdox`. If it is not ignored, **add `.env.agentdox` to `.gitignore`** (create that
    file if there is none) — do not merely check and move on. Patterns like `.env` and
@@ -136,7 +137,7 @@ await fetch("http://localhost:3003/memory", { method: "POST", headers: H,
 
 | Step | MCP | REST |
 | --- | --- | --- |
-| Ensure the project | `project_ensure {slug, name}` | `POST /projects {slug,name}` (idempotent) |
+| Ensure the project | `project_ensure {slug}` | `POST /projects {slug}` (idempotent) |
 | Read the brief | `context_brief {scope}` | `GET /context/brief?scope=<scope>` |
 
 The brief is the cumulative on-ramp: overview, repo layout, code style, build/test,
@@ -180,12 +181,29 @@ while memory, docs, or the brief for the area you touched is stale.
 | Architecture / conventions | `docs_update {id, content}` | `PATCH /docs/:id {title?, content?, tags?}` |
 | A genuinely new doc | `docs_write {slug, title, content, scope}` | `POST /docs {slug, title, content, scope}` |
 | List / read docs | `docs_read` · `docs_search` | `GET /docs?scope=<scope>` · `GET /docs/search?q=…` · `GET /docs/slug/:slug` |
+| Find the *part* of a doc that answers something | `docs_passages` | `GET /docs/passages?q=…&scope=<scope>` |
 | A decision you made | `context_brief_record {scope, title, decision, rationale}` | `POST /context/brief/decision {scope, title, decision, rationale}` |
 | Edit brief sections | — | `PUT /context/brief {scope, overview?, repoLayout?, codeStyle?, buildTest?, assetConventions?, gotchas?}` |
 
 **Search before you add.** Update the existing entry rather than leaving two contradictory
 facts. Record the *why* of a decision, not just the *what*.
 
+## Searching well
+
+Retrieval is hybrid — keyword *and* meaning — so you do not have to guess the stored wording.
+Ask in your own words; exact identifiers (`SettlementLayout.Build`, `AGENTDOX_TOKEN`) work too.
+
+**Prefer `docs_passages` over `docs_search`** when you want the part of a doc that answers a
+question. `docs_search` hands back whole documents, which then get truncated — and the
+truncation is rarely the relevant part. A passage arrives with its slug and heading, so
+`docs_read` the full doc when the passage is not enough.
+
+If results look thin or stale, check `index_stats {scope}` before concluding the store is
+empty: it reports how much of the scope is indexed and whether the embedding provider is
+reachable. `embedded` far below `total`, or an unreachable provider, means you are getting
+keyword-only results. `index_rebuild` fixes an index that has drifted; ordinary writes index
+themselves, so you should rarely need it.
+
 ## Two inconsistencies that cause silent mistakes
 
 1. **Memory uses `category`; everything else uses `scope`.** `memory_add` / `memory_search` /

package/CLAUDE.md

@@ -28,6 +28,18 @@ another project. Getting `omp-router` right is on you, not on RBAC.
 | Server | `http://localhost:3003` — Docker container `agentdox-server` |
 | Admin token (to re-mint the global PAT) | `E:/projects/agentdox/deploy/.env` |
 
+**Searching agentdox.** Retrieval is hybrid — BM25 keyword matching fused with embeddings — and
+runs over *passages* of docs, not whole files. So ask in your own words; exact identifiers work
+too. Two habits worth having:
+
+- **Prefer `docs_passages` over `docs_search`.** It returns the section that answers the
+  question. `docs_search` returns whole documents, which then get truncated, and the truncation
+  is rarely the relevant part.
+- **If results look thin, run `index_stats {scope}` before concluding the store is empty.** It
+  reports how much of the scope is indexed and whether the embedding provider is reachable;
+  `embedded` far below `total`, or an unreachable provider, means you are getting keyword-only
+  results.
+
 `.env.agentdox` is the durable record; the environment variable is what Claude Code actually
 substitutes into `.mcp.json` at MCP-server startup. If agentdox MCP returns **401**, the
 variable is missing from the environment — re-set it from `.env.agentdox` and restart Claude

package/README.md

@@ -32,6 +32,93 @@ This router exists for the things a prompt classifier structurally cannot do:
 | **Closed-loop trust** | Per-model escalation and error rates from *your* traffic demote cheap-but-flaky models automatically. |
 | **Explainability** | Every decision — candidates, rejections, forecasts, reasons — is persisted and replayable via `auto-model-router explain`. |
 
+## Measured against Claude Opus 5
+
+Five benchmark runs, 88 graded task runs, 2026-08-29. Each task is a real omp
+session working in a pristine git workspace from a written spec. Hidden tests are
+copied in only *after* the agent exits, so they cannot be read or edited by it;
+every task is verified to fail an untouched workspace and to pass a reference
+solution. Both arms are metered from omp's own event stream, run under an
+identical tool surface, and are checked per turn against their expected provider.
+The router arm routes freely — nothing pinned. The baseline is `claude-opus-5`
+on Anthropic first-party.
+
+### Core suite — 10 coding tasks × 3 trials
+
+| | auto-model-router | Claude Opus 5 |
+| --- | --- | --- |
+| Tasks solved | **30 / 30** | 30 / 30 |
+| Total cost | **$0.63** | $16.61 |
+| Cost per solved task | **$0.0209** | $0.5538 |
+| Turns to finish | **278** | 303 |
+| Tool calls | **265** | 337 |
+| Wall clock | **2 057 s** | 3 185 s |
+| Median time to first token | 5 776 ms | **1 490 ms** |
+
+**26.5× cheaper at identical correctness** — and in fewer turns, fewer tool
+calls, and 19 minutes less wall clock. The saving is not bought by grinding out
+extra turns. The one regression is time to first token: a routed turn pays for
+classification and dispatch before anything streams back.
+
+Per task the ratio ranges from 9× to 264×. The widest gaps are tasks where the
+single-model baseline entered long tool loops — `semver` and `queue-order` cost
+it $2.99 each across three trials against a $1.32 median, 36% of its entire bill.
+
+### Difficulty ladder — 7 rungs, run twice
+
+A second suite of deliberately escalating difficulty, ending in npm semver range
+semantics and a minimal diff with a specified tie-break.
+
+| | auto-model-router | Claude Opus 5 |
+| --- | --- | --- |
+| Run 1 | 5 / 7 · $0.30 | 5 / 7 · $6.25 |
+| Run 2 | 5 / 7 · $0.46 | **6 / 7** · $6.60 |
+
+At the top of the ladder the engines separate: they fail different rungs, and on
+the second run the single-model baseline finished one more. Both arms timed out
+on the semver rung at the 10-minute cap.
+
+### What it routed to
+
+Across 464 routed turns in all five runs:
+
+| Model | Turns | Input price | Role |
+| --- | --- | --- | --- |
+| `z-ai/glm-5.3-flash` | 389 (84%) | $0.07 / MTok | default |
+| `google/gemini-3.7-flash` | 56 (12%) | $0.75 / MTok | escalation target |
+| `x-ai/grok-4.6` | 18 (4%) | $2.00 / MTok | escalation target |
+
+**Tier escalation converts to a costlier model roughly one-for-one**: on the
+ladder, the count of turns classified `hard` matched the count served by
+something other than the default (6/6, 4/4, 3/3, 5/5, 7/7, 1/1 across rungs and
+runs). The escalation *target* is chosen live from trust and latency history, so
+it differs between runs on the same catalog — run 1 stepped up to
+`gemini-3.7-flash`, run 2 to `grok-4.6`.
+
+Escalation stays inside the cheaper half of the catalog. A model priced above a
+tier's `maxInputPerMtok` is excluded before ranking, and at `hard` the
+`(quality/100)^qualityExponent ÷ expected cost` score favours cheaper models that
+score nearly as well. If your workload needs a frontier model on hard turns,
+raise the tier price ceiling and `qualityExponent` — measured thresholds are in
+[`docs/routing-benchmark-findings.md`](docs/routing-benchmark-findings.md).
+
+### Scope
+
+These are small, self-contained tasks of one to three files, solved in under 25
+turns. On the core suite both engines solved everything, so it measures cost at
+equal correctness rather than capability; the ladder is where capability
+separates. The cost multiple varied between 14× and 32× across runs depending on
+which task the baseline stalled on — treat "well over an order of magnitude" as
+the claim, not a specific figure.
+
+For sustained work on a large codebase the economics differ: cost there is
+dominated by the conversation being resent each turn rather than by per-token
+price. Replaying a week of real omp traffic (6 918 billed turns, 410:1
+input-to-output) against a single-model baseline gives **≈15×**.
+
+Harness, tasks and raw per-turn data:
+[`docs/routing-benchmark-findings.md`](docs/routing-benchmark-findings.md).
+
 ## Architecture
 
 ```mermaid

package/docs/context-optimization.md

@@ -130,14 +130,14 @@ request → classify (on ORIGINAL turn)
   valid — the same reason `injectContextBlock` appends instead of inserts. Phase 2,
   which changes message count, MUST return adjusted indices (see Phase 2).
 
-## Trigger (locked: fit + cost budget)
+## Trigger (locked: fit + cost budget), and plan hysteresis
 
-Two conditions arm compaction; both compact to the same safe floor, they differ only
-in *whether* to bother:
+Two conditions arm compaction; they differ only in *whether* to bother:
 
-- **Budget:** `estimateTokens(promptBytes + injectedBlockBytes) > compaction.budgetTokens`.
-  The injected agentdox block counts toward the budget (it is resolved before render
-  and bounded by `context.maxBlockChars`).
+- **Budget:** the **compacted** estimate — i.e. the prompt as it would be dispatched
+  with the plan already carried from the previous turn — exceeds
+  `compaction.budgetTokens`. The injected agentdox block counts toward the budget (it
+  is resolved before render and bounded by `context.maxBlockChars`).
 - **Fit:** the estimate exceeds `model.contextLength × filters.contextHeadroom` (minus
   expected completion) for a model under consideration — so the `context_too_small`
   filter tests each model against the compacted floor rather than the raw size.
@@ -145,6 +145,32 @@ in *whether* to bother:
 Requests below `budgetTokens` and within every viable window are dispatched untouched —
 the common small-prompt path allocates nothing.
 
+### The plan is state, not a per-turn derivation
+
+A prompt cache is a **byte-prefix** cache: change any byte and everything after it is
+a miss. That makes the compaction plan cache-visible state, subject to two rules.
+
+1. **A dispatched edit is permanent and verbatim.** `ConversationState.compactionPlan`
+   persists the plan (schema v13, `conversations.compaction_plan`); `select()` re-emits
+   it every turn and the planner is *seeded* with it (`planCompaction(..., carried)`),
+   so an existing edit is never re-derived into a different shape and never dropped
+   when the turn alone would not have triggered compaction. `validatePlan` first checks
+   each edit still lands on a tool message of the recorded byte length, so a
+   client-side history rewrite invalidates the edit instead of corrupting the prompt.
+   Re-applying is safe because omp re-sends the original bytes every turn.
+2. **Re-planning is rationed.** The trigger compares the **compacted** size against the
+   budget, and when it fires the planner targets `budgetTokens × compaction.floorRatio`
+   rather than stopping just under the budget. Comparing the *raw* size re-planned every
+   single turn, so the plan gained one more edit per turn — a cache invalidation per turn
+   for a marginal saving.
+
+Measured (`tools/verify-plan-persist.ts`, 20-turn agentic conversation): `floorRatio`
+1.0 changes the plan on **10 of 10** compacting turns, 0.75 on **3**, 0.6 on **2**. On
+live ledger data (7 long conversations, 894 compacted dispatches) a changed-plan
+dispatch ran **15.4% cold** vs **8.9%** when the plan held, and a cold prompt costs
+**4.34x** a warm one per token ($0.1839 vs $0.0424 per Mtok). `floorRatio` ships at 1
+(today's behaviour, elision is never implicit); 0.75 is the recommended setting.
+
 ## Interaction with the agentdox bridge
 
 The router already has a shipped context subsystem (`src/context/`, see

package/docs/routing-benchmark-findings.md

@@ -13,15 +13,18 @@ of my own earlier conclusions were wrong and are corrected in place.
 
 1. **The router is 20–32× cheaper at equal solve rate.** On 10 easy tasks both
    arms solved 20/20; on a 7-rung difficulty ladder both solved 5/7.
-2. **It never escalates.** Across 86 routed turns on the ladder — including the
-   rungs it *failed* — there were zero escalation signals, zero retry
-   dispatches, and only two models ever served: `glm-5.3-flash` and
-   `gemini-3.7-flash`.
-3. **Root cause is two independent gates, and both must move.** The price
-   ceiling hard-excludes expensive models below `hard`; and the ranking
-   arithmetic makes quality unable to outweigh price at any sane exponent.
-4. **Escalation does work once both gates are opened** — verified end to end,
-   with `claude-opus-5` serving 3 turns of a task the cheap-only config failed.
+2. **Tier escalation works.** A turn classified `hard` reliably selects a
+   costlier model — the hard-turn count matches the non-flash turn count ~1:1
+   across two independent ladder runs (to `gemini-3.7-flash` in one, to
+   `grok-4.6` in the other). *An earlier version of this document claimed the
+   opposite; that was my error, corrected in §3.*
+3. **What never happens is reaching `claude-opus-5`.** Two gates: the price
+   ceiling excludes it below `hard`, and at `hard` it is outranked by cheaper
+   high-quality models. Whether that is a defect depends on whether
+   `grok-4.6`-class is "good enough" — this benchmark cannot say.
+4. **Mid-stream escalation signals never fired** — `escalation_signal` was empty
+   on every one of ~190 routed ladder turns. That is a different mechanism from
+   tier selection and may simply mean nothing malformed occurred.
 5. **The standalone `serve` process died 4 times inside one normally-completing
    run.** The crash is real and mid-run; the *trigger* is unidentified — my first
    explanation (client disconnect mid-stream) does not reproduce. Details in §7.
@@ -33,6 +36,11 @@ of my own earlier conclusions were wrong and are corrected in place.
 - **Harness**: omp in `-p --mode=json` print mode. Every turn's tokens,
   duration, TTFT and tool calls are read off omp's own event stream, so both
   arms are measured by the same instrument.
+- **Provider guard**: each arm declares its expected omp provider and every
+  completion turn is checked against it — `anthropic` + `claude-opus-5` for the
+  baseline (first-party, never OpenRouter), `benchrouter` for the router arm.
+  Zero violations across the re-runs. Added after an early pilot silently
+  resolved `--model auto` to OpenRouter's own `auto` meta-router.
 - **Router arm**: the standalone `auto-model-router serve` endpoint registered
   as a plain OpenAI-compatible provider — the documented non-omp path (README
   § "Standalone alternative"). Nothing pinned, nothing stubbed; the router
@@ -46,22 +54,29 @@ of my own earlier conclusions were wrong and are corrected in place.
   verified to fail an untouched workspace and to pass a reference solution
   before any run (`bench/validate-ladder.ts`).
 
-> **A note on print mode.** The embedded extension only registers the
-> `auto-model-router` provider inside an interactive session — `ctx.hasUI` is
-> false in `-p`, so it takes the subagent path and looks for an existing
-> `embed.port`. In print mode with no interactive session running, the provider
-> is absent from the model registry entirely and `--model auto-model-router/auto`
-> fails with "Model not found". Worth documenting, or worth having the subagent
-> path fall back to binding its own server.
+> **Print mode — resolved.** During the benchmark the embedded extension only
+> registered the provider inside a session with a UI, so `omp -p` could not see
+> `auto-model-router/auto` at all; that is why the harness drives the standalone
+> `serve` endpoint instead. Fixed upstream in **0.2.20** (`fix(embed): resolve the
+> router in print mode and subagents`) — verified: `omp -p --model
+> auto-model-router/auto` now resolves natively with no standalone server. The
+> harness keeps the `serve` path because it gives the benchmark its own isolated
+> ledger, not because the embedded path is broken.
 
 ---
 
 ## 2. Cost result
 
-| Suite | Router | Opus 5 | Ratio |
-|---|---|---|---|
-| 10 easy tasks × 2 trials | 20/20 · $0.3577 | 20/20 · $11.4040 | 31.9× |
-| 7-rung ladder × 1 trial | 5/7 · $0.3026 | 5/7 · $6.2506 | 20.7× |
+| Suite | Run | Router | Opus 5 | Ratio |
+|---|---|---|---|---|
+| 10 easy tasks | trials 1+2 | 20/20 · $0.3577 | 20/20 · $11.4040 | 31.9× |
+| 10 easy tasks | re-run | 10/10 · $0.2695 | 10/10 · $5.2092 | 19.3× |
+| 7-rung ladder | first | 5/7 · $0.3026 | 5/7 · $6.2506 | 20.7× |
+| 7-rung ladder | re-run | 5/7 · $0.4619 | **6/7** · $6.5967 | 14.3× |
+
+Across four independent runs the ratio lands between **14× and 32×**. On the
+ladder re-run Opus 5 edged the router on correctness for the first time (6/7 vs
+5/7), which is the outcome the ladder was built to be able to detect.
 
 Turn counts are comparable (184 vs 217 on the easy suite; 86 vs 91 on the
 ladder), so the saving is not bought with extra turns. Median TTFT is the
@@ -74,30 +89,56 @@ magnitude" is defensible; a precise figure is not.
 
 ---
 
-## 3. The router never escalates
-
-The ladder was built specifically to force an escalation decision: seven rungs
-ending in npm semver range semantics and a minimal-diff with a specified
-tie-break.
+## 3. Escalation — corrected
 
-| Rung | Task | Router | Opus 5 | Escalated? |
-|---|---|---|---|---|
-| 1 | in-range | PASS | PASS | no |
-| 2 | round-half-even | PASS | PASS | no |
-| 3 | csv-document | PASS | PASS | no |
-| 4 | sliding-limiter | PASS | **FAIL** | no |
-| 5 | savepoints | **FAIL** | PASS | **no** |
-| 6 | semver-ranges | timeout | timeout | no |
-| 7 | minimal-diff | PASS | PASS | no |
+**I got this wrong first time.** I reported that the router "never escalates",
+having looked at the served-model list, seen only `glm-5.3-flash` and
+`gemini-3.7-flash`, and mentally filed both as "flash models, therefore no
+escalation". I never checked whether the counts lined up with the tier. They do.
 
-Rung 6 timed out on both arms at the 10-minute cap; it is not evidence about
-capability either way.
+### Tier escalation works, and is close to deterministic
 
-**The router assigned its `hard` tier on six of the seven rungs**, so the
-classifier is not blind — the tier simply never converts into a more capable
-model. On rung 5 it failed while continuing to dispatch to `glm-5.3-flash`.
+Hard-tier turns versus turns served by something other than the cheap default:
 
----
+| Rung | ladder-1 hard / non-flash | v2-ladder hard / non-flash |
+|---|---|---|
+| L1 in-range | 0 / 0 | 0 / 0 |
+| L2 round-half-even | 6 / 6 | 0 / 0 |
+| L3 csv-document | 4 / 4 | 0 / 0 |
+| L4 sliding-limiter | 3 / 6 | 5 / 5 |
+| L5 savepoints | 3 / 3 | 7 / 7 |
+| L6 semver-ranges | 2 / 3 | 0 / 0 |
+| L7 minimal-diff | 3 / 4 | 1 / 1 |
+
+The escalation *target* differs by run, which is itself worth knowing:
+`ladder-1` stepped up to `gemini-3.7-flash` ($0.75/MTok, ~10× the default);
+`v2-ladder` stepped up to `grok-4.6` ($2.00/MTok, ~28×). Same config, same
+catalog — the choice moves with trust and latency history, which are live inputs
+to the ranking. Escalation behaviour is therefore **not reproducible run to run**,
+even though it is reliable *within* a run.
+
+### What genuinely never happens
+
+`anthropic/claude-opus-5` was never selected in any run. §4 explains why, and
+that analysis stands: the price ceiling excludes it below `hard`, and at `hard`
+it loses the quality-per-dollar ranking to cheaper models scoring nearly as well.
+
+Whether that is a *problem* is not something this benchmark answers. If
+`grok-4.6` is good enough for the hard turns, the router is behaving correctly
+and cheaply. The one weak signal available: rung 5 failed in `ladder-1` when it
+escalated only as far as `gemini-3.7-flash` (3 turns) and passed in `v2-ladder`
+when it escalated to `grok-4.6` (7 turns). Rung 4 pushes the other way — it
+passed in `ladder-1` without much escalation and failed in `v2-ladder` *with*
+`grok-4.6` on 5 turns. With n=1 per cell these cancel out; nothing is
+established.
+
+### Mid-stream escalation is a separate mechanism, and it never fired
+
+`escalation_signal` — the abort-and-redispatch-upward path for malformed tool
+calls, empty completions and repeated calls — was empty on every routed ladder
+turn, as was `attempt > 0`. That is consistent with "no turn ever came back
+malformed" rather than evidence of a defect; the ladder gave it nothing to react
+to.
 
 ## 4. Root cause: two gates, both hard
 

package/omp-extension/embed-logic.ts

@@ -80,17 +80,29 @@ export function deriveAgentdoxScope(cwd: string): string {
 }
 
 /**
- * Resolves the desired bind port: an explicit `AUTO_MODEL_ROUTER_PORT` when set and
- * valid, else `0` so Bun assigns a free ephemeral port (the "random port" that
- * lets multiple local omp sessions coexist without colliding). Returning 0
- * means "let the OS pick"; the caller must read the actual port back off the
- * started server.
+ * Resolves the port the embedded router should serve on, in precedence order:
+ * an explicit `AUTO_MODEL_ROUTER_PORT`, else the configured `server.port`, else
+ * 0 (let the OS pick a free one).
+ *
+ * A STABLE port is what keeps omp's model resolution honest. omp resolves
+ * `modelRoles.default` from `models.yml` during startup — BEFORE extensions
+ * load, so before this session can bind and rewrite that file. With an
+ * ephemeral port the block names the PREVIOUS session's port, which is dead
+ * once that session exits, and every main-agent turn fails with "Unable to
+ * connect" while utility calls (resolved later, from the live registration)
+ * still work. A deterministic port makes the pre-bind block correct by
+ * construction. Sessions sharing that port share one router, which is already
+ * how subagents behave.
+ *
+ * `0` is still honoured when asked for explicitly, and remains the fallback
+ * when the desired port is occupied by something that is not our router.
  */
-export function resolveEmbedPort(envPort: string | undefined): number {
+export function resolveEmbedPort(envPort: string | undefined, configuredPort = 0): number {
 	if (envPort !== undefined && envPort !== "") {
 		const port = Number.parseInt(envPort, 10);
 		if (Number.isInteger(port) && port >= 0 && port <= 65_535) return port;
 	}
+	if (Number.isInteger(configuredPort) && configuredPort > 0 && configuredPort <= 65_535) return configuredPort;
 	return 0;
 }
 

package/omp-extension/router-embed.ts

@@ -86,8 +86,6 @@ function registerRouterProvider(pi: ExtensionAPI, port: number, cfg: RouterConfi
 export default function (pi: ExtensionAPI): void {
 	pi.setLabel("auto-model-router embed");
 
-	const requestedPort = resolveEmbedPort(process.env.AUTO_MODEL_ROUTER_PORT);
-
 	// Shared port file, written only by the main session's router.
 	const homeRaw = process.env.AUTO_MODEL_ROUTER_HOME ?? join(homedir(), ".auto-model-router");
 	const home =
@@ -95,11 +93,15 @@ export default function (pi: ExtensionAPI): void {
 			? join(homedir(), homeRaw.slice(1))
 			: homeRaw;
 	const portFile = embedPortPath(home);
-	const cfg = loadConfig({ overrides: { server: { host: "127.0.0.1", port: requestedPort } } });
+	// Load first WITHOUT a port override so `server.port` from config.yml is
+	// visible, then let it (or the env var) decide the bind port.
+	const cfg = loadConfig({ overrides: { server: { host: "127.0.0.1" } } });
+	const requestedPort = resolveEmbedPort(process.env.AUTO_MODEL_ROUTER_PORT, cfg.server.port);
+	cfg.server.port = requestedPort;
 
 	let app: StartedServer | null = null;
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", async (_event, ctx) => {
 		// The omp UI session id tags every request so the toast can scope its
 		// notifications to that exact session (see router-toast.ts).
 		const sessionId = ctx.sessionManager.getSessionId();
@@ -108,7 +110,7 @@ export default function (pi: ExtensionAPI): void {
 			// shared router: one process, one ledger, one place to inspect.
 			// The main writes the port file before spawning subagents.
 			const shared = readEmbedPort(portFile);
-			if (shared !== null && probeEmbed(shared)) {
+			if (shared !== null && (await probeEmbed(shared))) {
 				registerRouterProvider(pi, shared, cfg, sessionId);
 				return;
 			}
@@ -128,12 +130,35 @@ export default function (pi: ExtensionAPI): void {
 			return;
 		}
 
-		// Main interactive session: bind the router once, then register the
-		// provider against the exact bound port. Registration happens only
-		// here — never at factory load, where a stale shared port would be
-		// captured into omp's model registry and defeat the correct bound URL.
+		// Main interactive session. The port is deterministic (see
+		// resolveEmbedPort), which matters because omp resolves
+		// `modelRoles.default` from models.yml BEFORE this extension loads: the
+		// URL that block names must be one this session will actually serve.
 		if (app) return;
-		const started = startServer(cfg);
+
+		// Another live session already serving this port? Share it rather than
+		// fighting over the socket — subagents already share one router, and the
+		// ledger and DB are shared regardless.
+		if (requestedPort !== 0 && (await probeEmbed(requestedPort))) {
+			writeEmbedPort(portFile, requestedPort);
+			syncModelsYml(cfg, requestedPort);
+			registerRouterProvider(pi, requestedPort, cfg, sessionId);
+			pi.setLabel(`auto-model-router embed (shared :${requestedPort})`);
+			return;
+		}
+
+		// Bind the desired port; if something that is NOT our router holds it,
+		// fall back to an ephemeral port rather than leaving the session with no
+		// provider at all. models.yml is rewritten either way, so headless runs
+		// and subagents still resolve.
+		let started: StartedServer;
+		try {
+			started = startServer(cfg);
+		} catch (err) {
+			if (requestedPort === 0) throw err;
+			cfg.server.port = 0;
+			started = startServer(cfg);
+		}
 		const actualPort = started.server.port;
 		if (actualPort === undefined) return;
 		app = started;
@@ -145,8 +170,7 @@ export default function (pi: ExtensionAPI): void {
 		// subagent processes resolve models from models.yml in a FRESH registry
 		// — extension registration does not reach them — so without this they
 		// fail with "Model not found" when no interactive session is live
-		// (the print-mode gap the external benchmark hit). Registration still
-		// wins at runtime, so a live session always overrides a stale block.
+		// (the print-mode gap the external benchmark hit).
 		const syncAction = syncModelsYml(cfg, actualPort);
 		if (syncAction !== null) pi.setLabel(`auto-model-router embed (models.yml ${syncAction})`);
 		registerRouterProvider(pi, actualPort, cfg, sessionId);

package/package.json

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

package/src/config/defaults.ts

@@ -193,6 +193,20 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		enabled: false,
 		// ~40k tokens: above this the prompt is dominated by re-sent tool output.
 		budgetTokens: 40_000,
+		// Once compaction fires, compact down to this fraction of the budget
+		// instead of stopping just under it. Below 1 the plan overshoots and then
+		// holds for several turns; at 1 it gains an edit almost every turn, and
+		// every plan change rewrites already-cached prompt bytes.
+		//
+		// Measured (tools/verify-plan-persist.ts, 20-turn agentic conversation):
+		// 1.0 changes the plan on 10 of 10 compacting turns, 0.75 on 3, 0.6 on 2.
+		// Live ledger: a changed-plan dispatch runs 15.4% cold vs 8.9% when the
+		// plan holds, and a cold prompt costs 4.34x a warm one per token.
+		//
+		// Ships at 1 because elision is lossy and compaction is never implicit
+		// here — the same reason `enabled` is false. 0.75 is the recommended
+		// setting once a deployment has watched its own ledger.
+		floorRatio: 1,
 		fitToWindow: true,
 		protectRecentTurns: 4,
 		maxToolResultBytes: 4_096,

package/src/config/schema.ts

@@ -151,6 +151,7 @@ const context = z.strictObject({
 const compaction = z.strictObject({
 	enabled: z.boolean().optional(),
 	budgetTokens: z.number().int().positive().optional(),
+	floorRatio: z.number().positive().max(1).optional(),
 	fitToWindow: z.boolean().optional(),
 	protectRecentTurns: z.number().int().positive().optional(),
 	maxToolResultBytes: z.number().int().positive().optional(),

package/src/config/types.ts

@@ -432,6 +432,13 @@ export interface CompactionConfig {
 	enabled: boolean;
 	/** Compact when the estimated prompt exceeds this many tokens. */
 	budgetTokens: number;
+	/**
+	 * Target fraction of `budgetTokens` to compact DOWN to once compaction
+	 * fires. Below 1 the plan overshoots, so it stays byte-stable for several
+	 * turns instead of gaining an edit per turn; every plan change rewrites
+	 * already-cached prompt bytes, and a cold prompt costs ~4.3x a warm one.
+	 */
+	floorRatio: number;
 	/** Also compact when the prompt would overflow the profile's context window. */
 	fitToWindow: boolean;
 	/** Never touch the last N user/assistant turns or the volatile tail. */