@intentic/sandbox-contract 1.223.0 → 1.225.0

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

@@ -1,35 +1,35 @@
-/* HOW A MODEL CATALOG IS ORDERED — one rule for every provider, because only one provider publishes an order
+/* HOW A MODEL CATALOG IS ORDERED, one rule for every provider, because only one provider publishes an order
  * worth keeping.
  *
  * Anthropic's REST /v1/models answers newest-first: that IS a provider opinion, and Claude's catalog rides it
- * (claude-models.ts). Every other provider here is read through an OpenAI-compatible /v1/models — Codex and
- * Gemini and Kimi via the bundled translator — or out of xAI's "Did you mean" rejection, and those
+ * (claude-models.ts). Every other provider here is read through an OpenAI-compatible /v1/models. Codex and
+ * Gemini and Kimi via the bundled translator, or out of xAI's "Did you mean" rejection, and those
  * endpoints publish a SET, not a ranking: they hand the ids back in whatever order their registry iterates,
  * which in practice is alphabetical. Reading that as a preference is what put "GPT 5.4 Mini" at the head of the
  * Codex group with GPT 5.6 below it, and what made a fresh Codex conversation start on whichever id happened to
- * sort first — models[0] is the provider default.
+ * sort first, models[0] is the provider default.
  *
  * So for those providers the order is DERIVED from the id, out of the only two facts an id reliably carries:
- * which TIER the model is (the adjective) and which RELEASE it is (the numbers). Both are provider-agnostic —
- * every vendor names its models the same way — which is what lets the daemon's four catalog services and the
+ * which TIER the model is (the adjective) and which RELEASE it is (the numbers). Both are provider-agnostic,
+ * every vendor names its models the same way, which is what lets the daemon's four catalog services and the
  * web's picker share one rule instead of each inventing a local one. */
 
 // A version-ish segment: digits and dots, optionally prefixed by the vendor's version marker (`4`, `5.1`, `v2`,
 // `k3`, `k2.7`, `20251001`). Kimi is the one provider that fuses the marker with the generation; treating `k3`
 // as a name made the current flagship look unversioned, so K2.x sorted above it. Everything else is a NAME
-// segment and belongs to the family — which is what makes the split below exhaustive.
+// segment and belongs to the family, which is what makes the split below exhaustive.
 const VERSION_SEGMENT = /^(?:v|k)?[\d.]+$/i;
 
 // A date stamp rather than a version component: six digits or more (20251001, 250514). The distinction is not
-// cosmetic — claude-opus-4-1-20250805 (Opus 4.1) and claude-opus-4-20250514 (Opus 4.0) compare as (4,1) vs (4)
-// with the stamps held apart, and as (4,1,20250805) vs (4,20250514) — the OLDER model winning — without.
+// cosmetic, claude-opus-4-1-20250805 (Opus 4.1) and claude-opus-4-20250514 (Opus 4.0) compare as (4,1) vs (4)
+// with the stamps held apart, and as (4,1,20250805) vs (4,20250514), the OLDER model winning, without.
 const DATE_SEGMENT = /^\d{6,}$/;
 
 const segmentsOf = (id: string): string[] => id.split(/[-_]/);
 
-// A model's FAMILY — its id with every version-ish segment dropped, so claude-opus-5 and claude-opus-4-8 land
+// A model's FAMILY, its id with every version-ish segment dropped, so claude-opus-5 and claude-opus-4-8 land
 // together (as do gpt-5.1/gpt-5, and claude-haiku-4-5-20251001 with its date suffix). Derived, never listed: a
-// family that ships tomorrow groups itself. The id is the stable key here — labels get renamed, ids don't.
+// family that ships tomorrow groups itself. The id is the stable key here, labels get renamed, ids don't.
 export const familyOf = (id: string): string => {
     const stem = segmentsOf(id)
         .filter((segment) => !VERSION_SEGMENT.test(segment))
@@ -43,7 +43,7 @@ export interface ModelRelease {
     // id (kimi-latest, gemini-pro-agent), which therefore reads as the oldest of its tier: a rolling alias names
     // no release, and inventing one for it would outrank the models that do name theirs.
     readonly version: readonly number[];
-    // The id's date stamp, 0 for none — the tiebreak between two builds of the SAME version.
+    // The id's date stamp, 0 for none, the tiebreak between two builds of the SAME version.
     readonly date: number;
 }
 
@@ -75,14 +75,14 @@ const compareRelease = (left: ModelRelease, right: ModelRelease): number => {
 
 /* THE ONE CURATED FACT in this file, and the only one the providers publish nowhere the app can read: which tier
  * is the frontier and which is the cheap one. It ranks FAMILIES, never models, and it is a vocabulary of tier
- * ADJECTIVES rather than a table of ids — that scoping is the whole point, because a per-model ranking table
+ * ADJECTIVES rather than a table of ids, that scoping is the whole point, because a per-model ranking table
  * failed here once already. The words are the ones every vendor reaches for, so a release that ships tomorrow
  * ranks itself as long as it is named like its predecessors, and a release named some other way ranks as unknown.
  *
  * An UNKNOWN family LEADS rather than sinks, and that direction is the point: the ranking this replaced sank
  * unrecognized ids to a floor below the everyday tier, so a brand-new flagship sorted beneath the model it
- * replaced. An id carrying no tier word at all is the provider's BASE line (gpt-5.6, grok-4, kimi-k2) — which is
- * exactly the line a user reaches for — and a family nobody here has heard of is far likelier to be the next
+ * replaced. An id carrying no tier word at all is the provider's BASE line (gpt-5.6, grok-4, kimi-k2), which is
+ * exactly the line a user reaches for, and a family nobody here has heard of is far likelier to be the next
  * flagship than the next budget tier. Being wrong costs one row's position; being wrong the other way hides a
  * launch. */
 const TIER_RANK: Readonly<Record<string, number>> = {
@@ -113,7 +113,7 @@ const UNRANKED = -1;
 
 /* Some providers name a capability ladder INSIDE one release instead of using the cross-release adjectives
  * above. Codex 5.6's Sol/Terra/Luna rows are that shape: they must remain together ahead of the older 5.5 line,
- * but their order is not an arbitrary id tiebreak — Sol is the strongest, followed by Terra, then Luna. Keeping
+ * but their order is not an arbitrary id tiebreak. Sol is the strongest, followed by Terra, then Luna. Keeping
  * this as a separate rank lets release recency still win across generations (a future GPT 5.7 base model must
  * not be buried under a recognized 5.6 suffix), while the three siblings sort by their real tier. */
 const RELEASE_TIER_RANK: Readonly<Record<string, number>> = {
@@ -135,23 +135,23 @@ const lastRankOf = (family: string, ranks: Readonly<Record<string, number>>): nu
 
 const releaseTierRankOf = (family: string): number => lastRankOf(family, RELEASE_TIER_RANK);
 
-/* HOW HARD AN ID SAYS IT WILL THINK. A routed catalog does not publish one row per model — it publishes one row
+/* HOW HARD AN ID SAYS IT WILL THINK. A routed catalog does not publish one row per model, it publishes one row
  * per model PER THINKING LEVEL, spelling the level into the id: `gemini-3.6-flash-high` and
  * `gemini-3.5-flash-extra-low` are the same Flash at opposite ends of its reasoning budget.
  *
  * Which the ranking above cannot see at all, and that blind spot has a direction: `high` and `low` are both
- * unrecognized words, so two variants of one model tie on tier and the RELEASE tiebreak settles them — and the
+ * unrecognized words, so two variants of one model tie on tier and the RELEASE tiebreak settles them, and the
  * newest variant a channel publishes is routinely the high one. The quick model, whose entire job is to be the
  * cheap rung, would therefore reach for the most expensive reading of the cheapest model it can find.
  *
  * That is not a small mis-sort. Thinking is the difference between a commit message that is in the box before
- * the user has finished reading the file list and one that arrives half a minute later — measured at ~2s versus
+ * the user has finished reading the file list and one that arrives half a minute later, measured at ~2s versus
  * ~27s on the same model and the same diff (agent/one-shot.ts, which disables thinking for the rungs where a
  * request parameter can). For a routed rung there is no such parameter: the id IS the setting, so this ranking
  * is the only place the choice can be made.
  *
  * Read ONLY by the cheap-end order. A picker orders a catalog by what a person reaches for, and a person
- * pinning `-high` on purpose means it — see compareCheapestFirst for the seam this belongs to. */
+ * pinning `-high` on purpose means it, see compareCheapestFirst for the seam this belongs to. */
 const THINKING_RANK: Readonly<Record<string, number>> = {
     minimal: 0,
     none: 0,
@@ -164,7 +164,7 @@ const THINKING_RANK: Readonly<Record<string, number>> = {
     thinking: 4,
 };
 
-/* An id naming NO level sits between the two ends rather than at either — the provider's own default, which for
+/* An id naming NO level sits between the two ends rather than at either, the provider's own default, which for
  * a model that can think is usually some thinking. Ranking it cheapest would seat a silent default ahead of an
  * id that explicitly says `minimal`, and ranking it dearest would bury every model whose channel publishes no
  * variants at all (Anthropic's, Kimi's) beneath one that does. Neither is what the id claims. */
@@ -180,7 +180,7 @@ const thinkingRankOf = (family: string): number => {
 export const tierRankOf = (family: string): number => lastRankOf(family, TIER_RANK);
 
 // The canonical order of two model ids: broad tier first, then release, then a tier declared within that release.
-// Hand it straight to Array#toSorted — that sort is stable, so two ids this rule cannot separate keep the order
+// Hand it straight to Array#toSorted, that sort is stable, so two ids this rule cannot separate keep the order
 // they arrived in (for Claude, the provider's own).
 export const compareModelIds = (left: string, right: string): number => {
     const leftFamily = familyOf(left);
@@ -192,28 +192,28 @@ export const compareModelIds = (left: string, right: string): number => {
     );
 };
 
-/* The order for a catalog its endpoint published as a SET — Codex, Gemini, Kimi and Grok, i.e. everything but
+/* The order for a catalog its endpoint published as a SET. Codex, Gemini, Kimi and Grok, i.e. everything but
  * Anthropic's ranked list. Falling back on arrival order is what the rule above does with a tie, and for a RANKED
  * catalog that is exactly right: the tie is the provider's own opinion, so claude-opus-5 stays ahead of
  * claude-fable-5. For a set there is no opinion to keep, and the header of this file assumed the leftover order
- * was at least alphabetical — it is not. A subscription can hand tied rows back in whatever order its registry
+ * was at least alphabetical, it is not. A subscription can hand tied rows back in whatever order its registry
  * iterated THIS request, so the tie decides which model a fresh conversation opens on and can flip between
  * catalog refreshes.
  *
- * So a set breaks its own ties on the id. Which sibling that seats first is arbitrary — but it is the same
+ * So a set breaks its own ties on the id. Which sibling that seats first is arbitrary, but it is the same
  * arbitrary answer every refresh, which is the property `default` actually needs. */
 export const compareUnrankedModelIds = (left: string, right: string): number => compareModelIds(left, right) || left.localeCompare(right);
 
 /* THE SAME TIER SCALE READ FROM THE OTHER END, for the one caller that wants the WEAKEST model rather than the
  * strongest: the quick model behind an automatic helper (the commit message written at land time). A picker
  * orders a catalog by what a user reaches for; this orders it by what a helper should spend, and the two are
- * exact opposites — so they share TIER_RANK rather than each naming its own list of cheap ids.
+ * exact opposites, so they share TIER_RANK rather than each naming its own list of cheap ids.
  *
  * The direction of UNRANKED is the reason this can't just be compareModelIds reversed. There, an unrecognized
  * family LEADS, because an id carrying no tier word is the provider's base line and a family nobody here has
  * heard of is likelier the next flagship than the next budget tier. Reversing would therefore seat exactly that
- * unknown-probably-flagship id as the cheap pick. So unknown sinks to LAST here too — both orders agree it is
- * not the efficient rung — and the cheap end is only ever a family whose tier word is actually recognized.
+ * unknown-probably-flagship id as the cheap pick. So unknown sinks to LAST here too, both orders agree it is
+ * not the efficient rung, and the cheap end is only ever a family whose tier word is actually recognized.
  * Falling off the end of a catalog with no efficient tier at all (Kimi publishes none) is then honest: the
  * newest of what it does publish, chosen by the release tiebreak below. */
 export const compareCheapestFirst = (left: string, right: string): number => {
@@ -223,14 +223,36 @@ export const compareCheapestFirst = (left: string, right: string): number => {
         tierRankOf(rightFamily) - tierRankOf(leftFamily) ||
         // BEFORE release, and that placement is the point: two rows of one model differing only in thinking
         // level are the same model, so recency has nothing to say between them, and letting it speak is what
-        // seated the high variant. Tier still wins over both — a thinking Haiku is cheaper than a silent Opus.
+        // seated the high variant. Tier still wins over both, a thinking Haiku is cheaper than a silent Opus.
         thinkingRankOf(leftFamily) - thinkingRankOf(rightFamily) ||
         compareRelease(releaseOf(left), releaseOf(right)) ||
         releaseTierRankOf(rightFamily) - releaseTierRankOf(leftFamily)
     );
 };
 
-/* WOULD RUNNING THIS ID MAKE THE MODEL THINK — as far as its name admits, which for a routed catalog is as far
+/* 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

@@ -1,23 +1,23 @@
 import { z } from "zod";
 
-/* A DECLARED OUTPUT SHAPE — the answer to "what does this session produce?", written once and used three ways.
+/* A DECLARED OUTPUT SHAPE, the answer to "what does this session produce?", written once and used three ways.
  *
  * An agentic session's natural output is prose, and prose is unusable as an input to the next session: a step
  * that must hand "the three files worth changing" to the step after it cannot hand over a paragraph that
  * mentions them. So a session that feeds another one declares its shape here, and that one declaration
  * becomes: the sentence in the prompt that tells the model what to write, the validator that decides whether
  * it complied, and the table the run view renders. Written once because the three drift apart the moment they
- * are written twice — a prompt asking for `files` and a validator wanting `paths` fails on every iteration and
+ * are written twice, a prompt asking for `files` and a validator wanting `paths` fails on every iteration and
  * says nothing useful about why.
  *
  * WHY A FIELD LIST AND NOT JSON SCHEMA. JSON Schema is strictly more expressive and completely unauthorable in
  * a form: nobody designing a workflow is going to hand-write `{"type":"object","properties":{...}}`, and a UI
  * that generates it becomes a schema editor, which is a product of its own. Four scalar types plus a string
- * list covers what one session actually hands another — a verdict, a count, a list of paths, a summary — and
+ * list covers what one session actually hands another, a verdict, a count, a list of paths, a summary, and
  * anything past that is better carried as a file the next step reads.
  *
  * `description` IS REQUIRED, and that is the field that decides whether this works at all. `{name: "risk"}`
- * gets you the model's guess at what risk means; `{name: "risk", description: "high | medium | low — how
+ * gets you the model's guess at what risk means; `{name: "risk", description: "high | medium | low, how
  * likely this change is to break something at runtime"}` gets you the answer to the question you asked.
  */
 
@@ -28,14 +28,14 @@ const FIELD_NAME = /^[a-zA-Z_][a-zA-Z0-9_]{0,39}$/;
 export const OutputFieldSchema = z.object({
     name: z.string().regex(FIELD_NAME),
     type: z.enum(["string", "number", "boolean", "string[]"]),
-    // What the field means, in the words the model is given. Not optional — see the note above.
+    // What the field means, in the words the model is given. Not optional, see the note above.
     description: z.string().min(1),
     // An absent optional field validates; an absent required one does not, and the iteration is told which.
     required: z.boolean(),
 });
 export type OutputField = z.infer<typeof OutputFieldSchema>;
 
-// How many fields one output may declare. A shape past this is not a handoff, it is a report — and a report is
+// How many fields one output may declare. A shape past this is not a handoff, it is a report, and a report is
 // what the prose half of the document is for.
 export const OUTPUT_FIELDS_MAX = 16;
 
@@ -81,18 +81,18 @@ const validatorFor = (field: OutputField): z.ZodType => {
 /* The declared shape as a validator. Unknown keys are ALLOWED THROUGH: a model that answered everything asked
  * of it and then added a `notes` key has complied, and failing it there would burn an iteration teaching it to
  * write less. What is enforced is that every required field is present and every present field has the
- * declared type — the two things the reader downstream is entitled to assume.
+ * declared type, the two things the reader downstream is entitled to assume.
  */
 export const fieldsValidator = (fields: readonly OutputField[]): z.ZodType =>
     z.looseObject(Object.fromEntries(fields.map((field) => [field.name, field.required ? validatorFor(field) : validatorFor(field).optional()])));
 
 // A worked example of the declared shape, so the prompt can show rather than describe. Values are the field's
-// own description — a model copying the example's structure has the description in front of it as it fills each
+// own description, a model copying the example's structure has the description in front of it as it fills each
 // slot, which is where it is needed rather than in a legend three lines up.
 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];
             }
@@ -106,6 +106,6 @@ 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 …".
+// 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`,

package/src/path-refs.ts

@@ -1,6 +1,6 @@
 /* Which file a NAMED reference means. A path written in prose is only loosely anchored to the workspace: an
  * agent that has been working in `_editor/web/src` writes `pages/workspace/Foo.vue`, and a turn running in an
- * isolated worktree prints `/history/worktrees/<id>/_editor/web/src/foo.ts` — neither is the workspace-relative
+ * isolated worktree prints `/history/worktrees/<id>/_editor/web/src/foo.ts`, neither is the workspace-relative
  * path the file routes speak, but both END in it.
  *
  * So a reference is resolved by matching progressively shorter TAILS of it against the real tree. The rules
@@ -32,17 +32,17 @@ export const referenceTails = (raw: string, root: string): readonly string[] =>
     return tails;
 };
 
-// The paths that genuinely END in `tail` on a segment boundary, best first — the shared ranking both matchers
+// The paths that genuinely END in `tail` on a segment boundary, best first, the shared ranking both matchers
 // return their candidates in. Shallowest wins: `pages/Foo.vue` means the app's page, not the copy six
-// directories down in a fixture tree. (The daemon's glob is anchored only at the string level — `**/pages/x.vue`
-// also matches `mypages/x.vue` — so the boundary is enforced here rather than by the pattern.)
+// directories down in a fixture tree. (The daemon's glob is anchored only at the string level, `**/pages/x.vue`
+// also matches `mypages/x.vue`, so the boundary is enforced here rather than by the pattern.)
 export const rankRefCandidates = (tail: string, paths: readonly string[]): readonly string[] =>
     paths
         .filter((path) => path === tail || path.endsWith(`/${tail}`))
         .toSorted((a, b) => a.split(`/`).length - b.split(`/`).length || a.length - b.length || (a < b ? -1 : 1))
         .slice(0, MAX_REF_CANDIDATES);
 
-/* IS THIS FILE TEST CODE — the one classification rule for every surface that splits a diff into "the
+/* IS THIS FILE TEST CODE, the one classification rule for every surface that splits a diff into "the
  * change" and "the proof". The agent review header answers "how much of this is tests?" with it; anything
  * else that wants the split (fleet cards, commit summaries) must use this same predicate, because two
  * classifiers that disagree turn the readout into a lie the user can't detect.
@@ -50,7 +50,7 @@ export const rankRefCandidates = (tail: string, paths: readonly string[]): reado
  * Convention-based, matching what this monorepo (and the ecosystems it scaffolds) actually writes: a
  * `.test.` / `.spec.` filename in any extension, a `__tests__` / `__fixtures__` directory anywhere on the
  * path, an `e2e-harness`, or a test-runner config. Deliberately NOT "anything containing 'test'": a
- * `testimonials/` page or a `latest.ts` is product code, and a false "tests" tag is worse than a missed one —
+ * `testimonials/` page or a `latest.ts` is product code, and a false "tests" tag is worse than a missed one,
  * it tells a reviewer not to look. */
 const TEST_DIRS = new Set([`__tests__`, `__fixtures__`, `__mocks__`, `__snapshots__`]);
 const TEST_FILE =

package/src/prompt-complexity.test.ts

@@ -0,0 +1,160 @@
+import { expect, test } from "vitest";
+import { type ComplexityInput, FAST_CEILING, judgeComplexity } from "./prompt-complexity.js";
+
+/* WHETHER A TURN COULD HAVE RUN ON THE CHEAP RUNG, judged before anything is spent.
+ *
+ * What these tests pin is the ASYMMETRY, not the accuracy: the judge can only ever route down, so every one of
+ * its mistakes in the "standard" direction costs a fraction of a cent and every mistake in the "fast" direction
+ * costs a user their turn. So the properties worth nailing down are that silence resolves to standard, that a
+ * gate or an escalating rule ends the question whatever else the sentence says, and that no rule ORDER can
+ * change an answer. The weights themselves are a hypothesis with a ledger under it (settings.autoTier
+ * "shadow"), and a test that froze them would be a test that made them impossible to fit. */
+
+const turn = (prompt: string, over: Partial<ComplexityInput> = {}): ComplexityInput => ({
+    prompt,
+    attachments: 0,
+    hasImages: false,
+    editorContext: false,
+    unattended: false,
+    planMode: false,
+    afterHardTurn: false,
+    ...over,
+});
+
+const tierOf = (prompt: string, over: Partial<ComplexityInput> = {}) => judgeComplexity(turn(prompt, over)).tier;
+
+// --- silence, and what it is read as -----------------------------------------------------------------
+
+test("a prompt matching nothing at all stays on the model the user picked", () => {
+    // The single most important default in the file. An unrecognised request is MEDIUM, never simple: the
+    // conservative reading of silence is the only safe one when a wrong downgrade costs a retry and a
+    // user who stops trusting the feature.
+    const verdict = judgeComplexity(turn(`Have another go at the thing we were discussing yesterday afternoon`));
+
+    expect(verdict.tier).toBe(`standard`);
+    expect(verdict.score).toBeGreaterThan(FAST_CEILING);
+    // Nothing in the sentence made a positive claim in either direction, so only the two absence features
+    // fired, and the pair of them cannot reach the ceiling by design.
+    expect(verdict.rules).toEqual([`short-prompt`, `no-workspace-reference`]);
+});
+
+test("a short vague request is not read as an easy one", () => {
+    // Absence of complexity is not evidence of simplicity. Weighted the obvious way, "short and naming no
+    // file" reached the ceiling by itself and downgraded every terse request in the product.
+    expect(tierOf(`fix the bug`)).toBe(`standard`);
+    expect(tierOf(`have a look at the thing we discussed`)).toBe(`standard`);
+});
+
+test("an empty-ish prompt is not mistaken for an easy one", () => {
+    expect(tierOf(`   `)).toBe(`standard`);
+});
+
+// --- the fast end ------------------------------------------------------------------------------------
+
+test("a short question about nothing in the workspace is the case this feature exists for", () => {
+    expect(tierOf(`what is a closure?`)).toBe(`fast`);
+});
+
+test("naming a file keeps an otherwise easy question on the user's own model", () => {
+    // "explain" is the easiest word in the lexicon, but the turn is now about real code in this repo rather
+    // than about a concept, and the cheap rung's failures on real code are the silent kind.
+    expect(tierOf(`explain what is a closure`)).toBe(`fast`);
+    expect(tierOf(`explain what src/agent/turn-plan.ts does`)).toBe(`standard`);
+});
+
+test("a trivial aside inside a hard conversation still gets through", () => {
+    // The reason afterHardTurn is a weight and not a lock: a conversation that has been doing hard work is
+    // still allowed to be asked an easy question, and locking it out is a mechanism that saves nothing.
+    expect(tierOf(`what is a closure?`, { afterHardTurn: true })).toBe(`fast`);
+});
+
+test("a workspace-adjacent errand stops being cheap once the conversation has done hard work", () => {
+    // The contrast with the test above is the whole rule. A pure knowledge question survives the penalty
+    // because it earns every easing feature there is; an errand about this repo does not, and after hard work
+    // it is far likelier to be the deceptive follow-up than a genuine aside.
+    expect(tierOf(`list the exports`, { afterHardTurn: false })).toBe(`fast`);
+    expect(tierOf(`list the exports`, { afterHardTurn: true })).toBe(`standard`);
+});
+
+// --- gates: the turn's situation, whatever its words say ---------------------------------------------
+
+test("a screenshot is never sent to the cheap rung, however simple the question about it", () => {
+    // The tier most likely to misread an image, on the turn least likely to notice that it did.
+    expect(tierOf(`what is this?`, { hasImages: true, attachments: 1 })).toBe(`standard`);
+});
+
+test("plan mode is a request to think, so it is never answered by the model that thinks least", () => {
+    expect(tierOf(`what is a closure?`, { planMode: true })).toBe(`standard`);
+});
+
+test("a surface-started run is never downgraded, because nobody is watching it fail", () => {
+    // Same call agentRunModels already makes in the other direction: a run billed whole, with a worktree in
+    // it, is not the place to spend a guess.
+    expect(tierOf(`what is a closure?`, { unattended: true })).toBe(`standard`);
+});
+
+test("a gate reports itself and scores 1, so the ledger can tell a gate from a hard sentence", () => {
+    const verdict = judgeComplexity(turn(`hi`, { unattended: true }));
+
+    expect(verdict.score).toBe(1);
+    expect(verdict.rules).toContain(`unattended`);
+});
+
+// --- escalating rules: any one ends the question ------------------------------------------------------
+
+test.each([
+    [`pasted code`, "explain this\n```ts\nconst x = 1;\n```"],
+    [`a stack trace`, "it broke\n  at Object.run (/work/x.ts:12:3)"],
+    [`a thrown error`, "help\nTypeError: cannot read properties of undefined"],
+    [`a hard word`, `why does the picker reset`],
+    [`another hard word`, `refactor this`],
+    [`a second job`, `rename it and then update the tests`],
+    [`a checklist`, `- rename it\n- update the tests`],
+    [`a cross-cutting scope`, `rename it across the codebase`],
+])("%s forces the user's own model even in an otherwise tiny prompt", (_name, prompt) => {
+    expect(tierOf(prompt)).toBe(`standard`);
+});
+
+test("an escalating rule beats every easing feature at once, so rule order cannot change an answer", () => {
+    // Short, easy-worded, no workspace reference, a bare question: every negative weight in the file, plus one
+    // escalating rule. Monotone escalation means the rule wins, which is what makes adding a rule tomorrow a
+    // safe change: it can only ever move turns UP a tier.
+    const verdict = judgeComplexity(turn(`what is a race condition?`));
+
+    expect(verdict.tier).toBe(`standard`);
+    expect(verdict.score).toBe(1);
+    expect(verdict.rules).toEqual([`hard-words`]);
+});
+
+test("a long brief is standard on its length alone, whatever words it happens to use", () => {
+    expect(tierOf(`explain `.repeat(400))).toBe(`standard`);
+});
+
+test("three files in, the job is about a shape rather than about a file", () => {
+    expect(tierOf(`have a look`, { attachments: 3 })).toBe(`standard`);
+    expect(tierOf(`have a look`, { attachments: 1 })).toBe(`standard`);
+});
+
+// --- the verdict as a record --------------------------------------------------------------------------
+
+test("names every rule that fired, because a score alone cannot say which feature did the work", () => {
+    // The ledger stores these. Re-fitting the weights against real traffic needs to know WHICH feature moved a
+    // turn, not merely that a threshold was crossed.
+    const verdict = judgeComplexity(turn(`what is this?`));
+
+    expect(verdict.rules).toEqual([`short-prompt`, `easy-words`, `bare-question`, `no-workspace-reference`]);
+});
+
+test("scores are rounded, so two turns the same rules judged compare equal on the ledger", () => {
+    const score = judgeComplexity(turn(`what is this?`)).score;
+
+    expect(score).toBe(Number(score.toFixed(3)));
+});
+
+test("the score never leaves 0..1, so a stored row is always comparable against the ceiling", () => {
+    const floor = judgeComplexity(turn(`what is this?`));
+    const ceiling = judgeComplexity(turn(`refactor everything`));
+
+    expect(floor.score).toBeGreaterThanOrEqual(0);
+    expect(ceiling.score).toBeLessThanOrEqual(1);
+});