@intentic/sandbox-contract 1.224.0 → 1.226.0

package/src/contracts/exit.contract.ts

@@ -0,0 +1,42 @@
+import { eventIterator, oc } from "@orpc/contract";
+import { IntenticLineSchema } from "../events.js";
+import { ExitCountriesSchema, ExitIdParamSchema, ExitListSchema, ExitObservationSchema, ExitUseInputSchema, OkSchema } from "../schemas.js";
+
+// The live GEO EXIT surface. An exit is ADDED as an `exit` capability (which provider, a resting country,
+// whether it comes up on boot); it is STARTED, MOVED and ROTATED here. Same split as the vpn contract and for
+// the same reason: switching country is a runtime operation performed many times over one stored pool, by the
+// operator from the Status card and by the agent through `exit` on its PATH, which calls these very routes.
+//
+// The difference from vpn is what "success" means. A dial succeeds when the tunnel is up; a country switch
+// succeeds only when the egress ADDRESS has moved, which is why `use` and `rotate` end by fetching an
+// ExitObservation through the exit's own proxy and fail when it does not agree with what was asked for.
+//
+// Nothing here changes the sandbox's default route, ever. Each exit publishes a SOCKS proxy and callers opt
+// in; the daemon's own traffic, the model endpoint and the tunnel that makes this sandbox reachable stay on
+// the plain uplink no matter what is up.
+export const exitContract = {
+    // Every configured exit with its live state, where it was asked to come out and where it actually does.
+    // Drives the Status card, the browser account picker and `geo list` (the CLI is `geo`: `exit` is a shell
+    // builtin, so a binary of that name is unreachable from a command line).
+    list: oc.route({ method: "GET", path: "/exit" }).output(ExitListSchema),
+    // What this exit can reach, ranked by how much capacity is actually there. Live from the provider when it
+    // answers (Tor's directory, VPN Gate's CSV, the pasted confs), from the baked fallback when it does not,
+    // and `live` says which. This is what auto-fills the country picker instead of a user hunting hostnames.
+    countries: oc.route({ method: "GET", path: "/exit/{id}/countries" }).input(ExitIdParamSchema).output(ExitCountriesSchema),
+    // Bring the exit up at its stored country. Streams, because a first start pulls a catalog, brings up a
+    // tunnel and then verifies the address, which is tens of seconds on the free providers and can fail at
+    // each step with something the user has to read. Idempotent: starting an up exit reports it and stops.
+    start: oc.route({ method: "POST", path: "/exit/{id}/start" }).input(ExitIdParamSchema).output(eventIterator(IntenticLineSchema)),
+    // Move to another country, starting the exit first if it was down. Streams for the same reason as start,
+    // and THROWS when the observed country does not end up matching: a switch that silently left traffic where
+    // it was is the one failure mode this whole feature exists to make impossible.
+    use: oc.route({ method: "POST", path: "/exit/{id}/use" }).input(ExitUseInputSchema).output(eventIterator(IntenticLineSchema)),
+    // A different address in the SAME country. Cheap on tor (a control-port signal), a re-dial to another
+    // server on the rest. Fails when the address does not actually change, which on a small pool it can't.
+    rotate: oc.route({ method: "POST", path: "/exit/{id}/rotate" }).input(ExitIdParamSchema).output(eventIterator(IntenticLineSchema)),
+    // What the world sees through this exit right now. Cheap, unstreamed, and the honest answer to "am I
+    // actually in Germany", which is the question every other route here is judged against.
+    check: oc.route({ method: "POST", path: "/exit/{id}/check" }).input(ExitIdParamSchema).output(ExitObservationSchema),
+    // Take it down. Tolerates an already-down exit: "make it not be up" is the contract, not "it was up".
+    stop: oc.route({ method: "POST", path: "/exit/{id}/stop" }).input(ExitIdParamSchema).output(OkSchema),
+};

package/src/contracts/providers.contract.ts

@@ -3,7 +3,7 @@ import { ModelsSchema, NativeProviderParamSchema } from "../schemas.js";
 
 // EVERY NATIVE PROVIDER'S PICKER CATALOG, ON ONE ROUTE.
 //
-// There were five of these — /claude/models, /codex/models, /grok/models, /kimi/models, /gemini/models, one per
+// There were five of these: /claude/models, /codex/models, /grok/models, /kimi/models, /gemini/models, one per
 // provider, each a contract entry, a route factory and a service field wired separately. They differed in
 // nothing: same method, same output schema, same "the daemon's catalog for this provider, never empty". Three of
 // the five route files were the same fifteen lines with a name swapped, and the daemon paid for that shape twice

package/src/conversation-ids.ts

@@ -165,7 +165,7 @@ const randomBelow = (upperBound: number): number => {
 // browser tabs opened in the same instant are exactly the case this must not produce the same name for.
 const pick = <T>(values: readonly T[]): T => values[randomBelow(values.length)]!;
 
-// Lowercase base36, one character per draw — 0-9a-z, all of which the id guard accepts.
+// Lowercase base36, one character per draw: 0-9a-z, all of which the id guard accepts.
 const tail = (): string => Array.from({ length: TAIL_LENGTH }, () => randomBelow(36).toString(36)).join("");
 
 /* A fresh conversation id: `<adjective>-<noun>-<tail>`, e.g. `swift-otter-k9m2`. Sixteen characters or so

package/src/events.test.ts

@@ -3,8 +3,8 @@ import { RESUME_NOTES, resumeDisclosure, withResumeNote, withoutResumeNote } fro
 
 /* The resume note is a round trip across the wire: the daemon wraps a prompt to tell the model what interrupted
  * it, and the client unwraps the SAME prompt off an attach head to tell whether it already has that bubble. A
- * mismatch between the two halves fails silently and cosmetically — a paragraph of machine prose rendered as
- * something the user typed — which is exactly the kind of drift that stays broken. */
+ * mismatch between the two halves fails silently and cosmetically: a paragraph of machine prose rendered as
+ * something the user typed, which is exactly the kind of drift that stays broken. */
 test("a resume note round-trips back to the user's own words", () => {
     for (const note of Object.values(RESUME_NOTES)) {
         expect(withoutResumeNote(withResumeNote("ship the parser", note))).toBe("ship the parser");
@@ -39,7 +39,7 @@ test("a re-run discloses as a notice, and the answered case as a note on the mes
         const disclosure = resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES[reason]));
         expect(disclosure?.kind).toBe("notice");
     }
-    // The answer is new words the user really did type, so nothing is dropped — the interruption rides them.
+    // The answer is new words the user really did type, so nothing is dropped: the interruption rides them.
     const answered = resumeDisclosure(withResumeNote("option two", RESUME_NOTES.answered));
     expect(answered).toEqual({ kind: "note", note: { title: expect.any(String), text: RESUME_NOTES.answered } });
 });

package/src/events.ts

@@ -737,7 +737,7 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                  * is, so nothing is re-run and nothing asks the user to reconnect, the one recovery that looks
                  * plausible and is guaranteed to waste their time. */
                 "claude-not-entitled",
-                // The model provider itself failed transiently — 500/502/503, a 529 at capacity, a dropped
+                // The model provider itself failed transiently: 500/502/503, a 529 at capacity, a dropped
                 // socket, and the harness's own in-turn retries did not outlast it. Nothing about the workspace
                 // or the request is wrong, so the daemon remembers the turn and re-runs it on an escalating
                 // backoff (provider-health.ts): the frame is a notice about a turn that is coming back, and
@@ -813,7 +813,7 @@ export type AttachFrame = z.infer<typeof AttachFrameSchema>;
 // and telling the model to "continue from that point instead of starting over" about words it has never seen
 // is how a resume reads as the user contradicting themselves.
 const REPEATED =
-    "The interrupted request is repeated below — where part of it was already completed in this session, continue from that point instead of starting over.";
+    "The interrupted request is repeated below, where part of it was already completed in this session, continue from that point instead of starting over.";
 export const RESUME_NOTES = {
     auth: `The Claude credential that interrupted this conversation has been renewed, and this turn resumed automatically. ${REPEATED}`,
     outage: `The model provider was briefly unavailable and interrupted this conversation; this turn resumed automatically. ${REPEATED}`,
@@ -822,7 +822,7 @@ export const RESUME_NOTES = {
     // instead, and this is the turn their answer starts (turn-resume.ts). What rides below the note is the
     // answer itself, so the model picks the session back up at exactly the decision it had handed over.
     answered:
-        "The sandbox restarted while this conversation was waiting for the user to respond; it is back, and their response follows below — continue from where the session left off.",
+        "The sandbox restarted while this conversation was waiting for the user to respond; it is back, and their response follows below: continue from where the session left off.",
 } as const;
 
 // The prompt a resume actually sends: the note (each carries its own account of what the words below are),
@@ -860,9 +860,9 @@ export type ResumeReason = keyof typeof RESUME_NOTES;
 export type ResumeDisclosure = { readonly kind: "notice"; readonly text: string } | { readonly kind: "note"; readonly note: TurnNote };
 
 const RESUME_DISCLOSURES: Record<ResumeReason, ResumeDisclosure> = {
-    auth: { kind: "notice", text: "Claude sign-in renewed — this turn picked up where it left off." },
-    outage: { kind: "notice", text: "The model provider came back — this turn picked up where it left off." },
-    restart: { kind: "notice", text: "The sandbox came back — this turn picked up where it left off." },
+    auth: { kind: "notice", text: "Claude sign-in renewed, this turn picked up where it left off." },
+    outage: { kind: "notice", text: "The model provider came back, this turn picked up where it left off." },
+    restart: { kind: "notice", text: "The sandbox came back, this turn picked up where it left off." },
     answered: { kind: "note", note: { title: "Picked back up after a sandbox restart", text: RESUME_NOTES.answered } },
 };
 

package/src/fast-tier.test.ts

@@ -0,0 +1,88 @@
+import { expect, test } from "vitest";
+import { fastTierModel } from "./fast-tier.js";
+
+/* WHERE A DOWNGRADED TURN ACTUALLY LANDS. The judge (prompt-complexity.ts) says a turn could be cheaper; this
+ * says whether there is anywhere cheaper to put it, on the provider it is already on.
+ *
+ * Two properties carry the whole feature, and everything below is one of them: a downgrade is only ever to a
+ * genuinely CHEAPER rung of the same catalog (so "cheaper" can never quietly become "older", or "the same model
+ * with less thinking"), and it never crosses PROVIDER (because that retires the conversation's session, which
+ * throws away the context that made the follow-up cheap to answer in the first place). */
+
+const CLAUDE = [`claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5-20251001`];
+const GOOGLE = [`gemini-3-pro`, `gemini-3-flash`, `gemini-3-flash-lite`];
+
+const fastFor = (model: string, over: { models?: readonly string[]; pinned?: readonly string[]; provider?: string } = {}) =>
+    fastTierModel({ provider: over.provider ?? `claude`, model, models: over.models ?? CLAUDE, pinned: over.pinned ?? [] });
+
+// --- Auto: the cheapest rung the provider publishes ----------------------------------------------------
+
+test("sends a frontier turn to the provider's own cheap rung", () => {
+    expect(fastFor(`claude-opus-5`)).toBe(`claude-haiku-4-5-20251001`);
+});
+
+test("reads the cheap end the same way the quick model does, on every vendor's vocabulary", () => {
+    expect(fastFor(`gemini-3-pro`, { provider: `gemini`, models: GOOGLE })).toBe(`gemini-3-flash-lite`);
+});
+
+// --- the ceiling: the user's own pick -------------------------------------------------------------------
+
+test("a user already on the cheap rung has nowhere to be sent", () => {
+    // The common case worth being exact about rather than an edge case. Undefined means "run what they asked
+    // for", which is the honest answer and the one that costs nothing to be wrong about.
+    expect(fastFor(`claude-haiku-4-5-20251001`)).toBeUndefined();
+});
+
+test("never swaps a model for an older build of the same tier", () => {
+    // A downgrade has to be legible AS a downgrade. Last year's Sonnet under this year's Sonnet is not a
+    // saving the feature promised, it is a different turn wearing the user's own model name.
+    expect(fastFor(`claude-sonnet-5`, { models: [`claude-sonnet-5`, `claude-sonnet-4`] })).toBeUndefined();
+});
+
+test("never downgrades a model whose family this build does not recognise", () => {
+    // An id carrying no tier word is a provider's base line or a family nobody here has heard of, and betting
+    // a user's turn on the guess that an unknown id is the budget one is the wrong direction to be wrong in.
+    expect(fastFor(`claude-opus-5`, { models: [`some-new-thing`] })).toBeUndefined();
+    expect(fastFor(`some-new-thing`, { models: CLAUDE })).toBeUndefined();
+});
+
+test("an unloaded catalog resolves to no downgrade rather than to a guess", () => {
+    expect(fastFor(`claude-opus-5`, { models: [] })).toBeUndefined();
+});
+
+test("no pick yet means nothing to be cheaper than", () => {
+    expect(fastFor(``)).toBeUndefined();
+});
+
+// --- pins -----------------------------------------------------------------------------------------------
+
+test("a pin on this provider wins over the catalog's own cheap end", () => {
+    expect(fastFor(`claude-opus-5`, { pinned: [`claude:claude-sonnet-5`] })).toBe(`claude-sonnet-5`);
+});
+
+test("takes a pinned id verbatim, so a model the static catalog has not caught up with is still pinnable", () => {
+    // The same call resolveQuickModels makes, and for the same reason: the picker offers a custom-id escape
+    // hatch, and second-guessing the id here would run a different model than the settings row names.
+    expect(fastFor(`claude-opus-5`, { pinned: [`claude:claude-haiku-9`] })).toBe(`claude-haiku-9`);
+});
+
+test("drops a pin naming another provider rather than crossing to it", () => {
+    // Switching provider retires the conversation's session (turnRequest.ts `resumes`). Starting the
+    // conversation over to save a fraction of a cent is not a saving, so the pin is ignored and Auto answers.
+    expect(fastFor(`claude-opus-5`, { pinned: [`gemini:gemini-3-flash-lite`] })).toBe(`claude-haiku-4-5-20251001`);
+});
+
+test("skips a pin that is not actually cheaper than what the user picked", () => {
+    // A pin is a preference about WHICH cheap rung, never a licence to swap a model for its equal or better.
+    expect(fastFor(`claude-sonnet-5`, { pinned: [`claude:claude-opus-5`] })).toBe(`claude-haiku-4-5-20251001`);
+});
+
+test("walks past an unusable pin to the next one that names this provider", () => {
+    const pinned = [`gemini:gemini-3-flash`, `claude:claude-opus-5`, `claude:claude-haiku-4-5`];
+
+    expect(fastFor(`claude-opus-5`, { pinned })).toBe(`claude-haiku-4-5`);
+});
+
+test("falls back to Auto when no pin survives, rather than to no downgrade at all", () => {
+    expect(fastFor(`claude-opus-5`, { pinned: [`nonsense`, `gemini:gemini-3-flash`] })).toBe(`claude-haiku-4-5-20251001`);
+});

package/src/fast-tier.ts

@@ -0,0 +1,72 @@
+import { compareCheapestFirst, isCheaperRung } from "./model-order.js";
+import { parsePinned } from "./quick-model.js";
+import type { AgentProvider } from "./schemas.js";
+
+/* WHICH MODEL A DOWNGRADED TURN ACTUALLY RUNS ON, the second half of automatic tier selection.
+ * prompt-complexity.ts decides a turn COULD be cheaper; this decides whether there is anything cheaper to put
+ * it on, and names it.
+ *
+ * THERE IS NO "STANDARD TIER" SETTING, and its absence is the design rather than an omission. The standard tier
+ * is whatever the user already picked for this conversation. So this mechanism can only ever route DOWN, from a
+ * model somebody chose to a cheaper rung of the same catalog, which means the worst case of a wrong answer is
+ * one turn's quality on a model the user can see and correct, never a bill they did not ask for. Every
+ * ambiguous case in this file therefore resolves to `undefined`, which the caller reads as "run what they
+ * asked for".
+ *
+ * THE PROVIDER IS NEVER CROSSED, and this is the constraint the rest of the app imposes rather than one this
+ * file would have chosen. A conversation's provider session is resumed only while the selection still matches
+ * the runtime and account that minted it (turnRequest.ts `resumes`, which compares provider, account and
+ * harness, and pointedly NOT model). A model swap inside one provider is free, and the session carries on. A
+ * provider swap RETIRES the session and cuts a new segment, which throws away the very context that made the
+ * follow-up cheap to answer. So a cross-provider pin here is dropped rather than honoured: saving a fraction of
+ * a cent by starting the conversation over is not a saving.
+ *
+ * THE ORDER IS A LADDER, for the reason quick-model.ts is one, but a shorter one: the caller spends the head
+ * and falls back to the user's own pick, rather than walking rungs. A downgrade that cannot be started is not
+ * worth a second attempt when the honest answer (their model) is sitting right there. */
+
+export interface FastTierInput {
+    // The provider this turn is on. Both the pick and every candidate belong to it; see above.
+    readonly provider: AgentProvider;
+    // The model the user picked, i.e. the standard tier and the ceiling. Empty when the composer has not
+    // resolved one yet, which resolves to no downgrade: there is nothing to be cheaper THAN.
+    readonly model: string;
+    // That provider's catalog as the caller can see it. Empty is a real state (a catalog that has not loaded),
+    // and it resolves to no downgrade rather than to a guess.
+    readonly models: readonly string[];
+    // settings.autoFastModels: an ordered list of `${provider}:${modelId}` keys (quickModelKey), or empty for
+    // Auto. Entries naming another provider are dropped, not honoured.
+    readonly pinned: readonly string[];
+}
+
+/* THE CHEAPER MODEL TO RUN THIS TURN ON, or undefined for "there isn't one, use their pick".
+ *
+ * A PIN IS TAKEN VERBATIM against the catalog, the same call resolveQuickModels makes and for the same reason:
+ * the model picker offers a custom-id escape hatch for a model the static catalog has not caught up with, and
+ * second-guessing the id here would run a different model than the settings row names. It is still checked for
+ * being CHEAPER, because that is not a fact about the catalog, it is a fact about the id, and a pin that is not
+ * cheaper than the pick is not a downgrade at all.
+ *
+ * AUTO IS THE CHEAPEST ROW THE PROVIDER PUBLISHES, read through the same cheap-end order the quick model uses,
+ * so the two features cannot disagree about which rung is the cheap one. Derived, never stored: connect an
+ * account tomorrow and the answer improves by itself, exactly as quickModel's empty default does.
+ *
+ * NOTHING CHEAPER THAN THE PICK ⇒ UNDEFINED, and that is the common case worth being exact about rather than
+ * the edge case: a user already working on the cheap rung has nowhere to be sent, and a user on a model whose
+ * family this build does not recognize is not going to be downgraded on a guess (isCheaperRung). */
+export const fastTierModel = (input: FastTierInput): string | undefined => {
+    if (input.model === "") {
+        return undefined;
+    }
+    const pinned = input.pinned
+        .flatMap((key) => {
+            const choice = parsePinned(key);
+            return choice === undefined || choice.provider !== input.provider ? [] : [choice.model];
+        })
+        .find((model) => isCheaperRung(model, input.model));
+    if (pinned !== undefined) {
+        return pinned;
+    }
+    const cheapest = input.models.toSorted(compareCheapestFirst)[0];
+    return cheapest !== undefined && isCheaperRung(cheapest, input.model) ? cheapest : undefined;
+};

package/src/history-state.ts

@@ -95,7 +95,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     {
         path: "ssh-hosts/",
         portability: "secret",
-        note: "Re-add each ssh host on the Capabilities view — its key does not travel.",
+        note: "Re-add each ssh host on the Capabilities view, its key does not travel.",
     },
     // The cli-proxy's config, which holds the routed subscriptions' provider tokens.
     {
@@ -108,7 +108,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
 
     /* Signs every browser session cookie. Carrying it would let a bundle's holder mint sessions against the
      * target, an export becomes a credential, and the target minting its own costs exactly one sign-in. */
-    { path: "session-secret", portability: "identity", note: "Sign in again — the target signs its own sessions." },
+    { path: "session-secret", portability: "identity", note: "Sign in again, the target signs its own sessions." },
     {
         path: "browser-access-disabled",
         portability: "identity",
@@ -117,7 +117,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     {
         path: "push.json",
         portability: "identity",
-        note: "Re-enable notifications in the browsers you use — a push subscription is bound to the sandbox that minted it.",
+        note: "Re-enable notifications in the browsers you use, a push subscription is bound to the sandbox that minted it.",
     },
     { path: "sync-enrollments.json", portability: "identity", note: "Re-pair desktop sync from the Sync tab." },
     { path: "sync-pair-consumed.json", portability: "identity" },

package/src/hostnames.test.ts

@@ -42,7 +42,7 @@ test("the local sync folder carries the very id the sandbox's URL does", () => {
     const url = `https://${sandboxHostname(ID, "intentic.dev")}`;
     expect(sandboxIdFromUrl(url)).toBe(ID);
     expect(syncFolder("Radarsu Local", url)).toBe(`~/intentic/radarsu-local-${ID}`);
-    // A bare host (no scheme) and a port are both accepted — the daemon/CLI and the browser pass different shapes.
+    // A bare host (no scheme) and a port are both accepted: the daemon/CLI and the browser pass different shapes.
     expect(sandboxIdFromUrl(`${sandboxHostname(ID, "intentic.dev")}:443`)).toBe(ID);
     // Own-Cloudflare: the owner's chosen subdomain IS the id, so the folder still matches what they browse to.
     expect(syncFolder("shop", "https://dev-box.example.com")).toBe("~/intentic/shop-dev-box");

package/src/index.ts

@@ -10,6 +10,7 @@ import { ciContract } from "./contracts/ci.contract.js";
 import { claudeContract } from "./contracts/claude.contract.js";
 import { draftsContract } from "./contracts/drafts.contract.js";
 import { endpointsContract } from "./contracts/endpoints.contract.js";
+import { exitContract } from "./contracts/exit.contract.js";
 import { extensionsContract } from "./contracts/extensions.contract.js";
 import { personasContract } from "./contracts/personas.contract.js";
 import { gitContract } from "./contracts/git.contract.js";
@@ -47,6 +48,7 @@ export { ciContract } from "./contracts/ci.contract.js";
 export { claudeContract } from "./contracts/claude.contract.js";
 export { draftsContract } from "./contracts/drafts.contract.js";
 export { endpointsContract, type TrialHealth, TrialStatusSchema, type TrialStatusResponse } from "./contracts/endpoints.contract.js";
+export { exitContract } from "./contracts/exit.contract.js";
 export { extensionsContract } from "./contracts/extensions.contract.js";
 export { personasContract } from "./contracts/personas.contract.js";
 export { gitContract } from "./contracts/git.contract.js";
@@ -99,11 +101,13 @@ export * from "./agent-run-model.js";
 export * from "./capability-env.js";
 export * from "./capability-secrets.js";
 export * from "./conversation-ids.js";
+export * from "./fast-tier.js";
 export * from "./host-protocol.js";
 export * from "./listener-protocol.js";
 export * from "./hostnames.js";
 export * from "./model-order.js";
 export * from "./path-refs.js";
+export * from "./prompt-complexity.js";
 export * from "./quick-model.js";
 export * from "./output-fields.js";
 export * from "./publish-drafts.js";
@@ -153,6 +157,7 @@ export const sandboxContract = {
     translator: translatorContract,
     usage: usageContract,
     vpn: vpnContract,
+    exit: exitContract,
     workflows: workflowsContract,
 };
 

package/src/model-order.test.ts

@@ -11,7 +11,7 @@ const CODEX = ["gpt-5.1-codex", "gpt-5.4-mini", "gpt-5.5", "gpt-5.6-luna", "gpt-
 
 test("ranks the frontier line above the cheap one and the newest release above its predecessors", () => {
     // The base line (no tier word) leads, newest first; the mini rung sinks under all of it regardless of how
-    // recently it shipped — which is the whole decision a user makes in this list.
+    // recently it shipped, which is the whole decision a user makes in this list.
     expect(CODEX.toSorted(compareModelIds)).toEqual(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.1-codex", "gpt-5.4-mini"]);
 });
 
@@ -47,7 +47,7 @@ test("the Codex release-tier order is stable across catalog refreshes", () => {
     expect(["gpt-5.4-mini", ...arrivals[0]!].toSorted(compareUnrankedModelIds).at(-1)).toBe("gpt-5.4-mini");
 });
 
-test("leaves a RANKED catalog's ties alone — the id tiebreak is for sets, and Anthropic publishes an opinion", () => {
+test("leaves a RANKED catalog's ties alone: the id tiebreak is for sets, and Anthropic publishes an opinion", () => {
     // compareUnrankedModelIds would seat claude-fable-5 ahead of claude-opus-5 on the id alone. Anthropic's
     // catalog arrives newest-first, so that order is a fact about the provider, not a leftover to be broken.
     expect(["claude-opus-5", "claude-fable-5"].toSorted(compareModelIds)).toEqual(["claude-opus-5", "claude-fable-5"]);
@@ -82,7 +82,7 @@ test("reads Kimi's k-prefixed generation so K3 leads the K2.x catalog", () => {
 });
 
 test("the rightmost tier word wins, because tier words compose", () => {
-    // flash-lite is the cheap end of Flash, codex-max the frontier end of Codex — reading the leftmost word
+    // flash-lite is the cheap end of Flash, codex-max the frontier end of Codex: reading the leftmost word
     // instead would file both under the tier they modify.
     expect(tierRankOf(familyOf("gemini-3-flash-lite"))).toBe(tierRankOf("lite"));
     expect(tierRankOf(familyOf("gpt-5.1-codex-max"))).toBe(tierRankOf("max"));
@@ -95,7 +95,7 @@ test("leads with a family carrying no tier word at all, so a brand-new flagship
 
 test("files a re-served open-weights model on the cheap rung, not at the head of the catalog it visits", () => {
     // Google's channel vends gpt-oss beside Gemini and Claude. It carries no tier word of its own, so the
-    // lead-the-unknown rule would open that whole section on it — above Opus.
+    // lead-the-unknown rule would open that whole section on it: above Opus.
     expect(["gpt-oss-120b-medium", "claude-opus-4-6-thinking", "gemini-pro-agent"].toSorted(compareModelIds)).toEqual([
         "claude-opus-4-6-thinking",
         "gemini-pro-agent",
@@ -103,7 +103,7 @@ test("files a re-served open-weights model on the cheap rung, not at the head of
     ]);
 });
 
-test("keeps the arrival order between ids the rule cannot separate — Anthropic's catalog IS ranked", () => {
+test("keeps the arrival order between ids the rule cannot separate: Anthropic's catalog IS ranked", () => {
     // Same tier, same version: nothing here outranks the order the provider itself reported.
     expect(["claude-opus-5", "claude-fable-5"].toSorted(compareModelIds)).toEqual(["claude-opus-5", "claude-fable-5"]);
     expect(["claude-fable-5", "claude-opus-5"].toSorted(compareModelIds)).toEqual(["claude-fable-5", "claude-opus-5"]);
@@ -124,7 +124,7 @@ test("stands an id with nothing but numbers (and an ACP row's empty one) as its
 
 test("holds date stamps apart from version components, or a dated build outranks the point release after it", () => {
     // The failure this prevents: claude-opus-4-1-20250805 (Opus 4.1) read as (4,1,20250805) loses to
-    // claude-opus-4-20250514 (Opus 4.0) read as (4,20250514) — the older model, by six digits.
+    // claude-opus-4-20250514 (Opus 4.0) read as (4,20250514): the older model, by six digits.
     expect(releaseOf("claude-opus-4-1-20250805")).toEqual({ version: [4, 1], date: 20250805 });
     expect(["claude-opus-4-20250514", "claude-opus-4-1-20250805"].toSorted(compareModelIds)).toEqual([
         "claude-opus-4-1-20250805",
@@ -153,7 +153,7 @@ test("sorts an unversioned rolling alias under the releases that name their vers
 // What the quick model behind a one-click helper resolves against: the same tier scale, read for the weakest
 // row instead of the strongest.
 
-test("opens on the efficient rung and buries the frontier one — the exact inverse of the picker's order", () => {
+test("opens on the efficient rung and buries the frontier one: the exact inverse of the picker's order", () => {
     const claude = ["claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5-20251001"];
 
     expect(claude.toSorted(compareCheapestFirst)).toEqual(["claude-haiku-4-5-20251001", "claude-sonnet-5", "claude-opus-5"]);
@@ -162,7 +162,7 @@ test("opens on the efficient rung and buries the frontier one — the exact inve
 
 test("keeps an UNRANKED family off the cheap end, where a plain reversal would have seated it first", () => {
     // The whole reason this is not `-compareModelIds`. An id with no tier word is the provider's base line, and
-    // an unheard-of family is likelier the next flagship than the next budget tier — so both orders agree it is
+    // an unheard-of family is likelier the next flagship than the next budget tier, so both orders agree it is
     // not the efficient rung, and a helper never spends frontier money on a commit message.
     expect(["gpt-5.6", "gpt-5.4-mini"].toSorted(compareCheapestFirst)).toEqual(["gpt-5.4-mini", "gpt-5.6"]);
     expect(["claude-mythos-1", "claude-haiku-4-5", "claude-sonnet-5"].toSorted(compareCheapestFirst).at(-1)).toBe("claude-mythos-1");
@@ -177,7 +177,7 @@ test("takes the NEWEST build of the cheap rung, not merely any of them", () => {
 test("finds each vendor's own cheap rung, including a re-served open-weights row", () => {
     expect(["gemini-3-pro", "gemini-3-flash", "gemini-3-flash-lite"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3-flash-lite");
     // Google's channel vends gpt-oss beside Gemini's own line; it is there to be the cheap option, and `oss`
-    // is what says so — without that word the id carries no tier at all and would sink to the bottom.
+    // is what says so: without that word the id carries no tier at all and would sink to the bottom.
     expect(["claude-opus-4-6-thinking", "gpt-oss-120b-medium"].toSorted(compareCheapestFirst)[0]).toBe("gpt-oss-120b-medium");
     expect(["grok-4", "grok-4-fast"].toSorted(compareCheapestFirst)[0]).toBe("grok-4-fast");
 });
@@ -188,7 +188,7 @@ test("reads a release-local tier ladder from the cheap end too", () => {
 
 test("refuses the thinking variant of a model, however new it is", () => {
     /* The bug this rule exists for, in the shape the live catalog actually publishes it: a routed channel vends
-     * one row per thinking LEVEL, and the newest row of the cheapest model was the high one — so the ladder
+     * one row per thinking LEVEL, and the newest row of the cheapest model was the high one, so the ladder
      * whose whole job is to be the cheap rung reached for the most expensive reading of it, and a commit
      * message that takes 2s took closer to 30. */
     expect(["gemini-3.6-flash-high", "gemini-3.5-flash-extra-low"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3.5-flash-extra-low");
@@ -219,6 +219,6 @@ test("names the thinking rows, and only those", () => {
 
 test("falls back on the newest release for a catalog that publishes no cheap tier at all", () => {
     // Kimi names no tier word anywhere, so every row is UNRANKED and the tier term cancels. Serving the newest
-    // of what it does publish is the honest answer — there is no cheaper rung to find.
+    // of what it does publish is the honest answer: there is no cheaper rung to find.
     expect(["kimi-k2-0711-preview", "kimi-k2-0905-preview"].toSorted(compareCheapestFirst)[0]).toBe("kimi-k2-0905-preview");
 });

package/src/model-order.ts

@@ -230,6 +230,28 @@ export const compareCheapestFirst = (left: string, right: string): number => {
     );
 };
 
+/* IS `candidate` A STRICTLY CHEAPER RUNG THAN `pick`, on the tier ladder alone. The predicate automatic tier
+ * selection runs on (prompt-complexity.ts judges the turn, fast-tier.ts spends this to find something cheaper
+ * to run it on), and it lives here because it is a question about the tier vocabulary, which is this file's
+ * one curated fact.
+ *
+ * TIER ONLY, deliberately: not release, not thinking level. A downgrade has to be legible as a downgrade, and
+ * "the same model one release older" or "the same model with less thinking" are not the saving this mechanism
+ * promises, they are a different turn wearing the user's model name. Haiku under Sonnet is; Sonnet 4 under
+ * Sonnet 5 is not.
+ *
+ * AN UNRANKED FAMILY IS FALSE ON EITHER SIDE, and both directions matter. A candidate carrying no tier word is
+ * a provider's base line or a family nobody here has heard of, so calling it the budget option is a guess, and
+ * the scale already says the likelier reading is "next flagship". The PICK being unranked is the subtler half:
+ * the safety argument for automatic tier selection is that it can only ever route DOWN, and against an id whose
+ * tier is unknown nothing can be shown to be down. So an unrecognised pick is left alone rather than swapped
+ * for something merely known to be cheap, which is how a saving turns into a bill. */
+export const isCheaperRung = (candidate: string, pick: string): boolean => {
+    const candidateRank = tierRankOf(familyOf(candidate));
+    const pickRank = tierRankOf(familyOf(pick));
+    return candidateRank !== UNRANKED && pickRank !== UNRANKED && candidateRank > pickRank;
+};
+
 /* WOULD RUNNING THIS ID MAKE THE MODEL THINK, as far as its name admits, which for a routed catalog is as far
  * as anyone can tell without running it. True only for an id that spells out a level ABOVE the quiet end, so an
  * ordinary id nobody has annotated (claude-haiku-4-5, kimi-k2) is never accused of it.

package/src/output-fields.ts

@@ -92,7 +92,7 @@ export const fieldsValidator = (fields: readonly OutputField[]): z.ZodType =>
 export const fieldsExample = (fields: readonly OutputField[]): Record<string, unknown> =>
     Object.fromEntries(
         fields.map((field) => {
-            const hint = `${field.description}${field.required ? "" : " (optional — omit if it does not apply)"}`;
+            const hint = `${field.description}${field.required ? "" : " (optional, omit if it does not apply)"}`;
             if (field.type === "number") {
                 return [field.name, 0];
             }
@@ -108,4 +108,4 @@ export const fieldsExample = (fields: readonly OutputField[]): Record<string, un
 
 // One line per field, for surfaces with no room to render an example: "risk (string, required), how likely …".
 export const describeFields = (fields: readonly OutputField[]): string =>
-    fields.map((field) => `- \`${field.name}\` (${field.type}${field.required ? ", required" : ", optional"}) — ${field.description}`).join(`\n`);
+    fields.map((field) => `- \`${field.name}\` (${field.type}${field.required ? ", required" : ", optional"}), ${field.description}`).join(`\n`);

package/src/path-refs.test.ts

@@ -15,7 +15,7 @@ describe("referenceTails", () => {
         expect(referenceTails("/history/worktrees/agent-7/_apps/foo.ts", "/work")).toContain("_apps/foo.ts");
     });
 
-    test("never cuts down to a bare filename — one `index.ts` is as good as another", () => {
+    test("never cuts down to a bare filename: one `index.ts` is as good as another", () => {
         expect(referenceTails("a/b/index.ts", "/work").at(-1)).toBe("b/index.ts");
         expect(referenceTails("index.ts", "/work")).toEqual([]);
     });
@@ -28,11 +28,11 @@ describe("referenceTails", () => {
 
 describe("rankRefCandidates", () => {
     test("keeps only matches that end in the tail on a segment boundary", () => {
-        // `mypages/` merely ends with the same characters — the daemon's glob can't tell, so this must.
+        // `mypages/` merely ends with the same characters: the daemon's glob can't tell, so this must.
         expect(rankRefCandidates("pages/Foo.vue", ["app/mypages/Foo.vue", "app/pages/Foo.vue"])).toEqual(["app/pages/Foo.vue"]);
     });
 
-    test("ranks the shallowest match first — the app's file, not a copy in a fixture tree", () => {
+    test("ranks the shallowest match first: the app's file, not a copy in a fixture tree", () => {
         expect(rankRefCandidates("pages/Foo.vue", ["a/b/c/pages/Foo.vue", "a/pages/Foo.vue"])).toEqual(["a/pages/Foo.vue", "a/b/c/pages/Foo.vue"]);
     });
 
@@ -41,7 +41,7 @@ describe("rankRefCandidates", () => {
     });
 });
 
-test("isTestPath: test files, fixture dirs and runner configs — never product code that merely says 'test'", () => {
+test("isTestPath: test files, fixture dirs and runner configs: never product code that merely says 'test'", () => {
     for (const path of [
         `src/agents/land.test.ts`,
         `src/pages/Foo.spec.tsx`,