@intentic/sandbox-contract 1.223.0 → 1.225.0

package/src/prompt-complexity.ts

@@ -0,0 +1,271 @@
+/* HOW HARD A TURN LOOKS BEFORE ANYTHING HAS BEEN SPENT ON IT, the judge behind automatic tier selection.
+ *
+ * The job is narrow on purpose: decide whether this turn could have run on the cheap rung of the provider the
+ * user is already on. Nothing here picks a model, nothing here reads a catalog, and nothing here calls
+ * anything. It is a pure function over the turn's own words and shape, so the daemon and the composer can both
+ * ask it and get the same answer, which is the same reason quick-model.ts lives in the contract rather than in
+ * either of them.
+ *
+ * IT CAN ONLY EVER ROUTE DOWN. The standard tier is not a setting: it is whatever the user already picked. So
+ * the question this file answers is never "which of two models" but "may we substitute something cheaper for
+ * the one they chose", and every ambiguous answer is NO. That asymmetry is the whole safety argument, and it is
+ * why there is no fail-up branch to get wrong: failing up means doing exactly what was asked.
+ *
+ * WHY RULES AND NOT A MODEL. Two findings decide this. Across the routing literature nothing sophisticated
+ * beats a simple predictor over decent features (a tuned kNN and a linear head tie, and both beat graph and
+ * attention routers costing 13-14x more), and a router that spends an LLM call to save an LLM call has spent
+ * the saving. So the layer is deliberately narrow, transparent, and free. See docs/model-routing-design.md.
+ *
+ * WHY EVERY RULE IS NAMED. A verdict carries the rules that fired, not just a number. That is what lets a
+ * screen say WHY a turn was downgraded, what makes a bad call reportable rather than mysterious, and what makes
+ * the shadow ledger analysable later: a score alone tells you a threshold was crossed, the rules tell you which
+ * feature is doing the work. The interpretable-router literature (Routesplain, COLM 2026) reaches the same
+ * conclusion from the accuracy side, but the operational one is enough on its own. */
+
+// The named features. A verdict lists these, the shadow ledger stores them, and a screen renders them, so they
+// are a vocabulary rather than debug strings: renaming one is a breaking change to what past rows mean.
+export type ComplexityRule =
+    // Gates. Any one of these ends the question: the turn is standard and no score is computed.
+    | "images"
+    | "plan-mode"
+    | "unattended"
+    // Escalating rules. Any one forces standard. Order between them cannot matter, which is the point.
+    | "code-block"
+    | "stack-trace"
+    | "hard-words"
+    | "multi-step"
+    | "cross-cutting"
+    | "long-prompt"
+    | "many-attachments"
+    // Graded features. These only move the score.
+    | "medium-prompt"
+    | "attachment"
+    | "editor-context"
+    | "paths"
+    | "many-verbs"
+    | "after-hard-turn"
+    | "short-prompt"
+    | "easy-words"
+    | "bare-question"
+    | "no-workspace-reference";
+
+export type ComplexityTier = "fast" | "standard";
+
+/* Everything the judge is allowed to know. Deliberately primitive: counts, flags and the prompt itself, no
+ * objects owned by either side, so the daemon's turn and the composer's draft can each build one without
+ * agreeing about anything else. The same "compress route state into cheap primitive fields" shape the serving
+ * literature converges on. */
+export interface ComplexityInput {
+    readonly prompt: string;
+    // Uploaded files plus @-mentioned workspace paths; the daemon resolves both into one list, so one count.
+    readonly attachments: number;
+    // Any attachment the model will read as an image. A cheap rung reading a screenshot is the worst cell in
+    // the matrix: it is the tier most likely to misread it and the turn least likely to notice.
+    readonly hasImages: boolean;
+    // The opt-in editor chip: the user pointed at a file and a selection, so the turn is about real code.
+    readonly editorContext: boolean;
+    // A surface started this, not a person at a composer (AgentTurn.unattended).
+    readonly unattended: boolean;
+    // The turn opens in plan mode: it is being asked to think before it acts, which is the request itself.
+    readonly planMode: boolean;
+    /* THE TURN BEFORE THIS ONE, IN THIS CONVERSATION, WAS JUDGED STANDARD.
+     *
+     * The most important field, and the one a prompt-only judge cannot derive. "now do the same for the other
+     * file" is nine easy words carrying the whole weight of the task before it, and a judge reading only the
+     * words will downgrade it every time. The routing work closest to this product (SWE-Router, over SWE-bench)
+     * states the general form: prompt-only routers inherit an information-theoretic error floor because the
+     * difficulty lives in the trajectory rather than in the request. Their answer is a 7B value model reading
+     * partial trajectories; ours is one boolean, which costs nothing and catches the case that actually bites.
+     *
+     * IT RAISES THE BAR, IT DOES NOT LOCK THE DOOR, and that is a deliberate softening of the rule this was
+     * designed as. A hard "once standard, always standard" lock reads well and is nearly useless: opening
+     * messages are substantive, so almost every conversation would take standard on turn one and never be
+     * eligible again, which is a mechanism that saves nothing while carrying all of the risk. As a weight it
+     * still stops the deceptive follow-up (which scores near the base and cannot afford the penalty) while a
+     * genuinely trivial aside inside a hard conversation still gets through, and that aside is a real and
+     * common turn.
+     *
+     * The JUDGEMENT, not what ran: a turn judged fast that ran standard anyway (nothing cheaper in the catalog,
+     * or the feature switched off) says nothing about the difficulty of the work, and reading it as escalation
+     * would make the sandbox's configuration leak into its opinion about a sentence. */
+    readonly afterHardTurn: boolean;
+}
+
+export interface ComplexityVerdict {
+    readonly tier: ComplexityTier;
+    // 0..1, rounded to three places so ledger rows compare exactly and do not carry float noise. 1 whenever a
+    // gate or an escalating rule fired: those do not produce a degree of difficulty, they produce an answer.
+    readonly score: number;
+    // Every rule that fired, in declaration order. Empty is legal and means "nothing distinctive": the score is
+    // the base, which sits above the fast ceiling, so an unremarkable turn stays on the user's own pick.
+    readonly rules: readonly ComplexityRule[];
+}
+
+/* WHERE AN UNREMARKABLE TURN STARTS, and it starts ABOVE the fast ceiling on purpose: a prompt that matches no
+ * rule at all is medium, not simple. That is the reference keyword-router convention and it is the conservative
+ * reading of silence, which is the only safe one when the downside of a wrong downgrade is a retry, an
+ * escalation, and a user who stops trusting the feature. */
+const BASE_SCORE = 0.5;
+
+// Fast iff the score lands at or below this. Exported because the shadow ledger's whole purpose is to let this
+// be re-fitted against real traffic rather than argued about, and a reader of a stored score needs the ceiling
+// that score was judged against.
+export const FAST_CEILING = 0.25;
+
+// Characters, not tokens: nothing here can tokenize, and for a threshold the constant cancels. ~600 chars is
+// where a request stops being a sentence and starts being a brief; ~2400 is where it is carrying pasted
+// material it has not fenced.
+const MEDIUM_PROMPT_CHARS = 600;
+const LONG_PROMPT_CHARS = 2400;
+const SHORT_PROMPT_CHARS = 140;
+// Three files in is a job about a shape rather than about a file, whatever the words say.
+const MANY_ATTACHMENTS = 3;
+// Three or more distinct imperatives is a list of jobs wearing the grammar of one.
+const MANY_VERBS = 3;
+
+/* THE WORD LISTS. Kept short and boring, because a hand-written lexicon is the part of a router that rots: it
+ * is inflexible by construction and every addition is a guess about traffic nobody has measured yet. It exists
+ * to catch the unambiguous ends of the distribution and to hand everything else to the score.
+ *
+ * Both lists are matched on word boundaries and case-insensitively. `easy` only ever lowers a score; `hard`
+ * forces standard outright, which is the asymmetry the rest of this file is built on. */
+const EASY_WORDS =
+    /\b(?:what(?:'s| is| are)|explain|describe|summari[sz]e|list|show me|where(?:'s| is| are)|rename|typo|reword|reformat|format this|tidy|define|translate|spell|abbreviat)/i;
+
+const HARD_WORDS =
+    /\b(?:refactor|redesign|architect|architecture|migrat|root cause|debug|investigat|diagnos|optimi[sz]|race condition|deadlock|memory leak|regression|security|threat model|benchmark|profil|audit|design a|plan (?:a|the|out)|why (?:does|is|are|did|would|can't|cannot))/i;
+
+// "Do this, and also that." The strongest cheap signal of a job that is several jobs, and the one an easy-
+// sounding sentence hides behind most often.
+const MULTI_STEP = /\b(?:and then|after that|once (?:that|you)|followed by|as well as|then also)\b/i;
+
+// A job whose subject is the shape of the codebase rather than a place in it. A cheap rung asked to be
+// consistent across twenty files is being asked the one thing it is worst at.
+const CROSS_CUTTING =
+    /\b(?:across (?:the|all|every)|every(?: single)? (?:file|module|package|component|usage|call ?site)|all (?:the|of the) (?:files|usages|call ?sites|places)|everywhere|throughout the|codebase-wide|repo-wide)\b/i;
+
+// Fenced code, a unified diff, or an inline patch. Pasted code is not proof of difficulty by itself, but it is
+// proof the turn is about real code rather than about a word, and the cheap rung's failures there are silent.
+const CODE_BLOCK = /```|^diff --git |^@@ .* @@|^[+-]{3} [ab]\//m;
+
+// A thrown error the user has pasted in. Debugging from a trace is the canonical case where the expensive tier
+// earns its price, and it is trivially detectable.
+const STACK_TRACE =
+    /(?:^|\n)\s*(?:at [\w$.<>]+ \(|Traceback \(most recent call last\)|Caused by:|panic:|thread '.*' panicked|Unhandled|[A-Z]\w*(?:Error|Exception): )/;
+
+// A workspace path or an @-mention in the prose. Distinguishes "explain closures" from "explain what this file
+// does" without claiming either is hard.
+const PATH_LIKE =
+    /(?:^|\s)(?:@[\w./-]+|[\w-]+\/[\w./-]+\.[a-z]{1,5}\b|\b[\w-]+\.(?:ts|tsx|js|jsx|vue|py|go|rs|java|rb|css|scss|json|ya?ml|md|sql|sh)\b)/i;
+
+// One sentence, ending in a question mark, with no second clause. Knowledge, not work.
+const BARE_QUESTION = /^[^.!?]{0,200}\?\s*$/;
+
+// Imperatives that start a request. Counted, not matched: one is a task, three is a list.
+const VERBS =
+    /\b(?:add|remove|delete|fix|write|create|make|update|change|move|rename|split|merge|extract|inline|wire|hook|test|check|run|build|deploy|document|implement|replace|convert|handle|support|expose|log|render|validate|parse|sort|filter|cache)\b/gi;
+
+// Bullets and numbered steps, which is a checklist however casually it is written.
+const LIST_LINES = /^\s*(?:[-*+]\s|\d+[.)]\s)/gm;
+
+// Every rule that ends the question on its own, paired with the test that fires it. Split from the graded
+// features below because the two are read differently: these are answers, those are evidence.
+const forcing = (input: ComplexityInput, text: string): ComplexityRule[] => {
+    const rules: ComplexityRule[] = [];
+    // Gates first, cheapest and least arguable. They are about the turn's SITUATION rather than its words.
+    if (input.hasImages) {
+        rules.push("images");
+    }
+    if (input.planMode) {
+        rules.push("plan-mode");
+    }
+    /* An unattended run is billed whole and nobody is watching it fail. The settings this repo already ships
+     * make the same call in the other direction: agentRunModels resolves to NOTHING when empty precisely
+     * because "nothing here can judge whether a job is worth the frontier tier". This file does judge, but not
+     * for the runs where a wrong guess costs a whole session with a worktree in it. */
+    if (input.unattended) {
+        rules.push("unattended");
+    }
+    // Then the words. Every one of these is a claim that the turn is about real code doing something real.
+    if (CODE_BLOCK.test(text)) {
+        rules.push("code-block");
+    }
+    if (STACK_TRACE.test(text)) {
+        rules.push("stack-trace");
+    }
+    if (HARD_WORDS.test(text)) {
+        rules.push("hard-words");
+    }
+    if (MULTI_STEP.test(text) || (text.match(LIST_LINES)?.length ?? 0) >= 2) {
+        rules.push("multi-step");
+    }
+    if (CROSS_CUTTING.test(text)) {
+        rules.push("cross-cutting");
+    }
+    if (text.length > LONG_PROMPT_CHARS) {
+        rules.push("long-prompt");
+    }
+    if (input.attachments >= MANY_ATTACHMENTS) {
+        rules.push("many-attachments");
+    }
+    return rules;
+};
+
+/* The graded half: what nudges an otherwise ordinary request either way. Weights are a starting shape fitted to
+ * nothing, which is exactly why the mechanism ships in shadow first — see docs/model-routing-design.md §4. They
+ * are not a claim, they are a hypothesis with a ledger under it.
+ *
+ * ONE PROPERTY IS NOT A HYPOTHESIS AND MUST SURVIVE ANY REFIT: the two ABSENCE features (`short-prompt`,
+ * `no-workspace-reference`) are too light to reach the ceiling together. Absence of complexity is not evidence
+ * of simplicity — "fix the bug" is four words naming no file and is not a cheap turn — so a downgrade always
+ * requires something POSITIVE to have been said, which in practice means `easy-words` or `bare-question`
+ * carrying it. Weighted the obvious way instead, the judge downgraded every short vague request in the
+ * product, which is the single worst population to be wrong about. */
+const GRADED: readonly { readonly rule: ComplexityRule; readonly weight: number; readonly of: (input: ComplexityInput, text: string) => boolean }[] =
+    [
+        { rule: "medium-prompt", weight: +0.2, of: (_input, text) => text.length > MEDIUM_PROMPT_CHARS },
+        { rule: "attachment", weight: +0.15, of: (input) => input.attachments > 0 },
+        { rule: "editor-context", weight: +0.1, of: (input) => input.editorContext },
+        // Enough on its own to hold an easy-worded question at standard: "explain what this file does" is a
+        // question about real code in this repo, and the cheap rung's failures on real code are the silent kind.
+        { rule: "paths", weight: +0.15, of: (_input, text) => PATH_LIKE.test(text) },
+        {
+            rule: "many-verbs",
+            weight: +0.15,
+            of: (_input, text) => new Set((text.match(VERBS) ?? []).map((verb) => verb.toLowerCase())).size >= MANY_VERBS,
+        },
+        // The heaviest single weight, because it is the only feature that can see past the words. See
+        // ComplexityInput.afterHardTurn for why it is a weight rather than the gate it was designed as.
+        { rule: "after-hard-turn", weight: +0.25, of: (input) => input.afterHardTurn },
+        // The two absence features, deliberately light; see the note above the list.
+        { rule: "short-prompt", weight: -0.1, of: (_input, text) => text.length <= SHORT_PROMPT_CHARS },
+        { rule: "easy-words", weight: -0.25, of: (_input, text) => EASY_WORDS.test(text) },
+        { rule: "bare-question", weight: -0.15, of: (_input, text) => BARE_QUESTION.test(text) },
+        {
+            rule: "no-workspace-reference",
+            weight: -0.1,
+            of: (input, text) => input.attachments === 0 && !input.editorContext && !PATH_LIKE.test(text),
+        },
+    ];
+
+// Three places, so a stored score is a value rather than a float artefact and two rows written by the same
+// rules compare equal.
+const round3 = (value: number): number => Math.round(value * 1000) / 1000;
+
+/* THE VERDICT. Gates and escalating rules first, and if any fired the answer is standard at score 1 — no
+ * partial credit, no weight to tune, and no way for rule ORDER to change the outcome. That monotone-escalation
+ * property is worth more than the accuracy it costs: it means adding a rule tomorrow can only ever move turns
+ * up a tier, never silently move a different set of turns down.
+ *
+ * Only what survives all of that gets scored, which keeps the graded layer doing the one job it is good at:
+ * separating "explain this" from "wire this up" among requests that look alike. */
+export const judgeComplexity = (input: ComplexityInput): ComplexityVerdict => {
+    const text = input.prompt.trim();
+    const forced = forcing(input, text);
+    if (forced.length > 0) {
+        return { tier: "standard", score: 1, rules: forced };
+    }
+    const hits = GRADED.filter((feature) => feature.of(input, text));
+    const score = Math.min(1, Math.max(0, BASE_SCORE + hits.reduce((total, feature) => total + feature.weight, 0)));
+    return { tier: score <= FAST_CEILING ? "fast" : "standard", score: round3(score), rules: hits.map((feature) => feature.rule) };
+};

package/src/publish-drafts.ts

@@ -1,16 +1,16 @@
-/* HOW AN APPROVED POST GETS SENT — the shared half, written once because the daemon acts on it, the app draws
+/* HOW AN APPROVED POST GETS SENT, the shared half, written once because the daemon acts on it, the app draws
  * it, and the two have to agree on the same seconds.
  *
  * THERE IS NO PUBLISHER AUTOMATION ANY MORE, and its absence is the design. Publishing used to be a scheduled
  * automation: a cron waking every few minutes, running a shell guard over the drafts directory, almost always
- * finding nothing — a job whose entire job was to ask "yet?" forever. It also made the approve button
+ * finding nothing, a job whose entire job was to ask "yet?" forever. It also made the approve button
  * conditional on a row in a list nobody had asked for: delete the automation and approvals silently went
  * nowhere, with the button still there and still saying yes. The daemon owns publishing now
  * (drafts-publisher.ts). It knows the moment a draft comes due because it is the process that wrote the draft,
  * so it sleeps until exactly then and costs nothing in between.
  *
  * APPROVAL IS NOT "SEND NOW", IT IS "SEND UNLESS I STOP YOU". A post is public and permanent the instant it
- * lands, and the gap between realising and clicking is about two seconds — so an approved draft carrying no
+ * lands, and the gap between realising and clicking is about two seconds, so an approved draft carrying no
  * date of its own is dated HOLD into the future, and the queue counts it down in the open. The hold is stored
  * as an ordinary scheduledAt rather than as a new state, which is what keeps it honest: it survives a restart,
  * it reads as one number in the same place a scheduled post's date is already read, and calling it off is the
@@ -21,20 +21,20 @@
 export const APPROVAL_HOLD_MS = 60_000;
 
 /* WHO CAN BE SENT BY CODE ALONE. A connector reached through a real API with a stored credential is a request
- * the daemon can make itself — no model, no browser, no turn — and it either got a 200 or it did not. A
+ * the daemon can make itself, no model, no browser, no turn, and it either got a 200 or it did not. A
  * connector that IS a logged-in browser session (reddit, x) has no such door: posting there means driving a
  * page whose markup moves under you, past dialogs and rate screens nobody can enumerate in advance, which is
  * precisely the work an agent turn exists to absorb.
  *
  * So the split follows what the platform actually offers rather than what would be cheaper, and it is stated
- * here rather than guessed at a call site — because being wrong in the optimistic direction means a post that
+ * here rather than guessed at a call site, because being wrong in the optimistic direction means a post that
  * silently never goes out. A platform absent from this set is published by an agent turn, which always works
  * and merely costs more. */
 export const DIRECT_PUBLISH_PLATFORMS: ReadonlySet<string> = new Set(["discord"]);
 
 /* WHAT THE PUBLISH TURN IS TOLD, for the drafts no API can carry. It NAMES the drafts rather than saying "go
  * and look": the daemon has already decided what is due, and a turn that re-derives that decision can disagree
- * with it — sending something the owner pulled back a second ago, or skipping something it judged not ready.
+ * with it, sending something the owner pulled back a second ago, or skipping something it judged not ready.
  * The turn's job is the part only it can do, which is working the platform's own UI.
  *
  * It still writes the outcome back into the file, because the file is where the queue reads it, and a post
@@ -47,7 +47,7 @@ export const publishTurnPrompt = (drafts: readonly { readonly id: string; readon
         ``,
         `Take them ONE AT A TIME, and for each:`,
         `1. Read the file. Set "status":"posting" BEFORE you act, so a turn that dies here cannot double-post.`,
-        `2. Post exactly its "content" — with its "title", "target" and "media" — using that platform's skill.`,
+        `2. Post exactly its "content": with its "title", "target" and "media", using that platform's skill.`,
         `   A "target" that is a URL means this draft is a REPLY to whatever is at it: open that exact URL and`,
         `   reply where it lands. On reddit a comment permalink (.../comments/<post>/<slug>/<comment>/) has to`,
         `   nest under that comment rather than becoming a new top-level comment on the thread.`,
@@ -55,5 +55,5 @@ export const publishTurnPrompt = (drafts: readonly { readonly id: string; readon
         `   If it failed, set "status":"failed" plus an "error" saying what went wrong in plain words the owner`,
         `   can act on, then move to the next draft instead of retrying in a loop.`,
         ``,
-        `Never rewrite the content — the owner approved these exact words. Never touch a draft not listed above.`,
+        `Never rewrite the content: the owner approved these exact words. Never touch a draft not listed above.`,
     ].join(`\n`);

package/src/quick-model.test.ts

@@ -1,8 +1,8 @@
 import { expect, test } from "vitest";
 import { type QuickModelChoice, type QuickModelSource, quickModelKey, resolveQuickModels } from "./quick-model.js";
 
-/* Which models a small automatic helper spends, and in which order. The rule answers two surfaces at once —
- * the daemon walks it, the browser names its head in the settings row — so what these tests pin is that a
+/* Which models a small automatic helper spends, and in which order. The rule answers two surfaces at once:
+ * the daemon walks it, the browser names its head in the settings row, so what these tests pin is that a
  * sandbox's connections alone decide it, with no stored id to go stale, and that there is always a rung
  * underneath the first one whenever the sandbox has another account to reach for. */
 
@@ -14,7 +14,7 @@ const KIMI: QuickModelSource = { provider: `kimi`, ready: true, models: [`kimi-k
 
 const offline = (source: QuickModelSource): QuickModelSource => ({ ...source, ready: false });
 
-// The model that answers when nothing goes wrong — the head of the chain, which is what most of what follows is
+// The model that answers when nothing goes wrong: the head of the chain, which is what most of what follows is
 // about and what every surface naming the spend up front reads.
 const head = (sources: readonly QuickModelSource[], pinned: readonly string[]): QuickModelChoice | undefined =>
     resolveQuickModels(sources, pinned)[0];
@@ -24,12 +24,12 @@ test("reaches for the efficient rung of the one connected provider, never its fl
 });
 
 test("spends the FREE channel over the subscription when both offer the same rung", () => {
-    // Both publish a cheap-tier row, so nothing separates them on capability — and one of them costs the user
+    // Both publish a cheap-tier row, so nothing separates them on capability, and one of them costs the user
     // nothing while the other eats headroom they watch. A background helper should not quietly bill the Claude plan.
     expect(head([CLAUDE, GOOGLE], [])).toEqual({ provider: `gemini`, model: `gemini-3-flash-lite` });
 });
 
-test("puts tier ahead of cost — a free frontier model is still the wrong tool for a commit message", () => {
+test("puts tier ahead of cost: a free frontier model is still the wrong tool for a commit message", () => {
     // Google connected but publishing only its Pro line. Ordering on price first would seat a flagship here,
     // which is the exact outcome the feature exists to avoid.
     const proOnly: QuickModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-pro`] };
@@ -90,7 +90,7 @@ test("skips a connected provider whose catalog has not loaded yet", () => {
     expect(head([unloaded], [])).toBeUndefined();
 });
 
-/* THE CHAIN — what the daemon walks when the model at the top of it refuses. A spent allowance is the ordinary
+/* THE CHAIN: what the daemon walks when the model at the top of it refuses. A spent allowance is the ordinary
  * case, not the exotic one: the account a helper shares with the chat runs out mid-afternoon, and the whole
  * point of the list is that the click still lands on the next rung down. */
 
@@ -111,7 +111,7 @@ test("drops a pin whose provider went away and keeps the rest of the order intac
 
 test("stops at the end of a pinned list rather than reaching for an account the user left out", () => {
     // Google and Kimi are connected and cheaper. The user wrote down one model, so one model is what this may
-    // spend — a pin exists precisely to keep a helper off the accounts it does not name.
+    // spend: a pin exists precisely to keep a helper off the accounts it does not name.
     expect(resolveQuickModels([CLAUDE, GOOGLE, KIMI], [`claude:claude-haiku-4-5`])).toEqual([{ provider: `claude`, model: `claude-haiku-4-5` }]);
 });
 
@@ -122,7 +122,7 @@ test("names each model once, however many times the list repeats it", () => {
     ]);
 });
 
-test("Auto is a ladder too — every connected provider's cheap rung, best first", () => {
+test("Auto is a ladder too, every connected provider's cheap rung, best first", () => {
     expect(resolveQuickModels([CLAUDE, GOOGLE, KIMI], [])).toEqual([
         { provider: `gemini`, model: `gemini-3-flash-lite` },
         { provider: `claude`, model: `claude-haiku-4-5-20251001` },
@@ -135,11 +135,11 @@ test("Auto is a ladder too — every connected provider's cheap rung, best first
  * dropped would print one model's name in the settings row and spend a different account entirely. */
 const OLLAMA: QuickModelSource = { provider: `endpoint/ollama`, ready: true, models: [`qwen3-coder`, `gemma3-27b`] };
 
-test("honours a pin on a configured endpoint — the whole id, not the half before its slash", () => {
+test("honours a pin on a configured endpoint: the whole id, not the half before its slash", () => {
     expect(head([CLAUDE, OLLAMA], [`endpoint/ollama:qwen3-coder`])).toEqual({ provider: `endpoint/ollama`, model: `qwen3-coder` });
     // And it round-trips through the key shape the picker mints, which is where the slash-not-colon rule earns
     // itself: parsePinned splits on the FIRST colon, so an `endpoint:ollama` id would have parsed the provider
-    // as "endpoint" and the model as "ollama:qwen3-coder" — a pin that silently resolves to nothing.
+    // as "endpoint" and the model as "ollama:qwen3-coder": a pin that silently resolves to nothing.
     expect(quickModelKey({ provider: `endpoint/ollama`, model: `qwen3-coder` })).toBe(`endpoint/ollama:qwen3-coder`);
 });
 
@@ -152,7 +152,7 @@ test("leaves Auto to the providers whose price is known, rather than reaching fo
 
 test("still answers from an endpoint when it is the only thing configured", () => {
     // No tier word in either id, so the shared id-derived ordering decides between them exactly as it does for
-    // Kimi above — the point here is that a sandbox whose only model API is its owner's still gets an answer
+    // Kimi above: the point here is that a sandbox whose only model API is its owner's still gets an answer
     // rather than the disabled "nothing connected" button.
     expect(head([offline(CLAUDE), OLLAMA], [])).toEqual({ provider: `endpoint/ollama`, model: `qwen3-coder` });
 });

package/src/quick-model.ts

@@ -2,7 +2,7 @@ import { ACCESS_COST, accessFor, modelsFor, PROVIDERS } from "./agent-catalog.js
 import { compareCheapestFirst, familyOf, tierRankOf } from "./model-order.js";
 import type { AgentProvider } from "./schemas.js";
 
-/* THE QUICK MODEL — the cheap, fast model a small automatic job spends instead of the frontier model the chat
+/* THE QUICK MODEL, the cheap, fast model a small automatic job spends instead of the frontier model the chat
  * runs on. Today that is the commit message written when an agent's work lands; anything else of that shape (a
  * branch name, a PR description) reads the same answer, which is the reason this is a `quickModel` setting
  * rather than a commit-message one.
@@ -11,11 +11,11 @@ import type { AgentProvider } from "./schemas.js";
  * failure: the account it names spends its allowance on the chat all morning, and every job for the rest of the
  * day fails on a limit while three other connected providers sit idle. So the setting is a LIST
  * read top to bottom, the resolver hands back the whole ladder, and the daemon walks it until one answers.
- * Nothing here decides WHICH failures are worth stepping over — that is the daemon's, since only it has run
- * the call — this side only says what the running order is.
+ * Nothing here decides WHICH failures are worth stepping over, that is the daemon's, since only it has run
+ * the call, this side only says what the running order is.
  *
  * The rule lives in the contract because BOTH sides need the same answer for different jobs: the daemon runs
- * the model, and the browser has to NAME it — in the settings row's "Auto (…)" label — before anything has been
+ * the model, and the browser has to NAME it, in the settings row's "Auto (…)" label, before anything has been
  * run. Two implementations would drift precisely where it matters most, since a label promising Haiku while the
  * daemon bills Opus is worse than no label.
  *
@@ -27,14 +27,14 @@ import type { AgentProvider } from "./schemas.js";
 
 /* One provider's standing in the decision: whether a turn on it can be sent at all, and what its catalog holds.
  *
- * ACP agents are deliberately not expressible here — an ACP row's model id is empty because the agent owns its
+ * ACP agents are deliberately not expressible here, an ACP row's model id is empty because the agent owns its
  * own model, so there is no cheap rung to point it at. `endpoint/<id>` providers ARE, and have to be: their
  * models appear in the same picker the settings row builds its options from, so a pin naming one has to hold
  * rather than fall silently back to Auto and spend an account the user was deliberately steering away from. */
 export interface QuickModelSource {
     // AgentProvider, not NativeProvider: an endpoint's id is user-created and cannot be in a fixed union. Auto's
-    // ranking degrades gracefully for one — costOf falls to the metered rung and an id with no tier word is
-    // UNRANKED, which is genuine last place — so an endpoint effectively only wins Auto when nothing else is
+    // ranking degrades gracefully for one, costOf falls to the metered rung and an id with no tier word is
+    // UNRANKED, which is genuine last place, so an endpoint effectively only wins Auto when nothing else is
     // connected, while a PIN on one holds. Both are the right answers: what a turn on someone's own model server
     // costs is not a fact this repo can know, so it is not one Auto should be asserting.
     readonly provider: AgentProvider;
@@ -67,13 +67,13 @@ export const parsePinned = (pinned: string): QuickModelChoice | undefined => {
 
 /* A pin as a person reads it: the catalog's own label for the id, or the id itself for one the static catalog
  * has not caught up with (the picker offers a custom-id escape hatch, so this is a real case rather than a
- * defensive branch). Beside parsePinned because the two are always wanted together — by any surface that has to
+ * defensive branch). Beside parsePinned because the two are always wanted together, by any surface that has to
  * name what a click is about to spend BEFORE it spends it, and the two loudest of those are extensions that
  * share no other code with each other. */
 export const pinnedModelLabel = (choice: QuickModelChoice): string =>
     modelsFor(choice.provider).find((option) => option.value === choice.model)?.label ?? choice.model;
 
-// The cheapest row a provider publishes — its whole catalog read from the cheap end. Undefined for a catalog
+// The cheapest row a provider publishes, its whole catalog read from the cheap end. Undefined for a catalog
 // that hasn't loaded yet, which is a real state: every provider serves a floor, but only once something has
 // asked it.
 const cheapestOf = (source: QuickModelSource): string | undefined => source.models.toSorted(compareCheapestFirst)[0];
@@ -83,28 +83,28 @@ const cheapestOf = (source: QuickModelSource): string | undefined => source.mode
 // so the row is the provider's base line rather than its budget one.
 const tierOf = (model: string): number => tierRankOf(familyOf(model));
 
-// PROVIDERS order, as the final tiebreak. Arbitrary, but the SAME arbitrary answer on every read — the property
+// PROVIDERS order, as the final tiebreak. Arbitrary, but the SAME arbitrary answer on every read, the property
 // compareUnrankedModelIds exists to guarantee, and the one a default actually needs. An endpoint is in no fixed
 // list, so it reads -1 and leads the tiebreak; unreachable in practice, since it can never tie on cost.
 const providerOrder = (provider: AgentProvider): number => PROVIDERS.findIndex((entry) => entry.value === provider);
 
 // How much a call on this provider costs at the margin. Every native provider declares an access kind; an
-// endpoint declares none, and takes the metered rung — the conservative reading of a model API whose bill this
+// endpoint declares none, and takes the metered rung, the conservative reading of a model API whose bill this
 // repo cannot see, which keeps Auto from reaching for someone's paid gateway on its own initiative.
 const costOf = (provider: AgentProvider): number => {
     const access = accessFor(provider);
     return access === undefined ? ACCESS_COST.key : ACCESS_COST[access.kind];
 };
 
-/* AUTO — every connected provider's cheapest row, best-first, as a ladder rather than a winner.
+/* AUTO, every connected provider's cheapest row, best-first, as a ladder rather than a winner.
  *
  * Ranked on TIER FIRST, then cost. That order is the point of the feature: the helper exists to not be the
  * frontier model, so a free flagship is still the wrong tool, while a free Haiku-class row and a subscription
  * Haiku-class row differ only in whose quota they spend. Cost then breaks that tie towards the channel the user
- * is not paying per token for — and against the one they are.
+ * is not paying per token for, and against the one they are.
  *
  * The whole ladder, not just its head, because the same ranking that picks the best answer also states the best
- * SECOND answer — and a sandbox with three accounts connected should not lose its commit messages for six hours
+ * SECOND answer, and a sandbox with three accounts connected should not lose its commit messages for six hours
  * because one of them is spent. */
 const autoLadder = (sources: readonly QuickModelSource[]): readonly QuickModelChoice[] =>
     sources
@@ -144,7 +144,7 @@ export const resolveQuickModels = (sources: readonly QuickModelSource[], pinned:
         const choice = parsePinned(key);
         return choice === undefined || !ready.has(choice.provider) ? [] : [choice];
     });
-    // The same model twice would spend two attempts proving the same account is out — a real state, since the
+    // The same model twice would spend two attempts proving the same account is out, a real state, since the
     // list is edited by hand and Auto's ladder can rank a provider the user has also pinned.
     const chain = [...new Map(requested.map((choice) => [quickModelKey(choice), choice])).values()];
     return chain.length > 0 ? chain : autoLadder(sources);

package/src/routes.test.ts

@@ -87,14 +87,14 @@ describe(`routeShapes`, () => {
         expect(after).not.toBe(before);
     });
 
-    it(`is blind to the order fields are declared in — a reordered object is not a wire change`, () => {
+    it(`is blind to the order fields are declared in: a reordered object is not a wire change`, () => {
         const one = routeShapes(shaped(z.object({ a: z.string(), b: z.number() })))[`vpn.list`];
         const other = routeShapes(shaped(z.object({ b: z.number(), a: z.string() })))[`vpn.list`];
         expect(other).toBe(one);
     });
 
     it(`reads a defaulted field differently on the way in than on the way out`, () => {
-        // `.default()` makes a field optional going in and required coming out — the same declaration, two
+        // `.default()` makes a field optional going in and required coming out: the same declaration, two
         // wire shapes. Reading both directions the same way would call them identical.
         const one = z.object({ a: z.string().default(`x`) });
         const asOutput = routeShapes(shaped(one))[`vpn.list`];
@@ -114,7 +114,7 @@ describe(`routeShapes`, () => {
 
     it(`omits a route whose shape cannot be expressed rather than failing the walk`, () => {
         // An oRPC event iterator wraps its output in an opaque type with no schema underneath. The route keeps
-        // its NAME (it is still advertised as existing) and simply carries no shape — which reads downstream as
+        // its NAME (it is still advertised as existing) and simply carries no shape, which reads downstream as
         // "assume compatible". The two neighbours still get fingerprinted, which is the part that matters: one
         // unexpressable route must not cost the whole walk.
         const withStream = {
@@ -135,12 +135,18 @@ describe(`routeShapes`, () => {
 describe(`the real sandbox contract`, () => {
     it(`fingerprints all but the streaming routes`, () => {
         const unshaped = SANDBOX_ROUTE_NAMES.filter((name) => !(name in SANDBOX_ROUTE_SHAPES));
-        // oRPC wraps an event iterator's output in an opaque type with no schema under it, so these seven
+        // oRPC wraps an event iterator's output in an opaque type with no schema under it, so these ten
         // cannot be fingerprinted and are assumed compatible. Named rather than counted: a NEW entry here is
         // a route that quietly lost its shape check, which is worth failing a test over.
         expect(unshaped.toSorted()).toEqual([
             `agent.attach`,
             `capabilities.add`,
+            // The three geo-exit moves, streaming for the same reason vpn.connect does: bringing an exit up
+            // pulls a catalog, dials, and then verifies the address it landed on, which is tens of seconds on
+            // the free providers and can fail with something the user has to read at each step.
+            `exit.rotate`,
+            `exit.start`,
+            `exit.use`,
             `intentic.applyEvents`,
             `intentic.run`,
             `system.events`,
@@ -151,7 +157,7 @@ describe(`the real sandbox contract`, () => {
 
     it(`fingerprints every other route exactly once`, () => {
         expect(Object.keys(SANDBOX_ROUTE_SHAPES).every((name) => SANDBOX_ROUTE_NAMES.includes(name))).toBe(true);
-        expect(Object.keys(SANDBOX_ROUTE_SHAPES).length).toBe(SANDBOX_ROUTE_NAMES.length - 7);
+        expect(Object.keys(SANDBOX_ROUTE_SHAPES).length).toBe(SANDBOX_ROUTE_NAMES.length - 10);
     });
 
     it(`derives a route table with no duplicate names`, () => {