@intentic/sandbox-contract 1.176.3 → 1.209.0

package/src/path-refs.test.ts

@@ -3,7 +3,7 @@ import { isTestPath, rankRefCandidates, referenceTails } from "./path-refs.js";
 
 describe("referenceTails", () => {
     test("offers the reference itself first, then shorter tails of it", () => {
-        expect(referenceTails("_apps/web/src/foo.ts", "/work")).toEqual(["_apps/web/src/foo.ts", "web/src/foo.ts", "src/foo.ts"]);
+        expect(referenceTails("_editor/web/src/foo.ts", "/work")).toEqual(["_editor/web/src/foo.ts", "web/src/foo.ts", "src/foo.ts"]);
     });
 
     test("anchors an absolute path under the workspace root", () => {
@@ -45,12 +45,12 @@ test("isTestPath: test files, fixture dirs and runner configs — never product
     for (const path of [
         `src/agents/land.test.ts`,
         `src/pages/Foo.spec.tsx`,
-        `_apps/cli/src/cli.e2e.test.ts`,
+        `_deploy/cli/src/cli.e2e.test.ts`,
         `src/e2e-harness.ts`,
         `pkg/__tests__/helper.ts`,
-        `_libs/iq-recall/src/__fixtures__/transcripts/a.jsonl`,
+        `_search/iq-recall/src/__fixtures__/transcripts/a.jsonl`,
         `vitest.config.ts`,
-        `_apps/web/vitest.workspace.config.mts`,
+        `_editor/web/vitest.workspace.config.mts`,
         `playwright.config.ts`,
     ]) {
         expect(isTestPath(path), path).toBe(true);

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 `_apps/web/src` writes `pages/workspace/Foo.vue`, and a turn running in an
- * isolated worktree prints `/history/worktrees/<id>/_apps/web/src/foo.ts` — neither is the workspace-relative
+ * 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
  * 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
@@ -53,7 +53,7 @@ export const rankRefCandidates = (tail: string, paths: readonly string[]): reado
  * `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 = /(?:^|\/)(?:[^/]+\.(?:test|spec)\.[^/.]+|[^/]*\.e2e\.[^/]+|e2e-harness\.[^/]+|(?:vitest|jest|playwright)(?:\.[\w-]+)*\.config\.[^/]+)$/;
+const TEST_FILE =
+    /(?:^|\/)(?:[^/]+\.(?:test|spec)\.[^/.]+|[^/]*\.e2e\.[^/]+|e2e-harness\.[^/]+|(?:vitest|jest|playwright)(?:\.[\w-]+)*\.config\.[^/]+)$/;
 
-export const isTestPath = (path: string): boolean =>
-    TEST_FILE.test(path) || path.split(`/`).some((segment) => TEST_DIRS.has(segment));
+export const isTestPath = (path: string): boolean => TEST_FILE.test(path) || path.split(`/`).some((segment) => TEST_DIRS.has(segment));

package/src/publish-drafts.ts

@@ -0,0 +1,59 @@
+/* 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
+ * 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
+ * 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
+ * "put it back in review" click that was there before any of this.
+ *
+ * A MINUTE, because that is the whole width of the decision: long enough to catch the wrong word you see the
+ * moment the row stops being a form, short enough that approving something still feels like sending it. */
+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
+ * 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
+ * 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.
+ * 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
+ * that went out without saying so is a post the owner sends twice. */
+export const publishTurnPrompt = (drafts: readonly { readonly id: string; readonly platform: string }[]): string =>
+    [
+        `Publish these approved post drafts, which are due now. They live in .intentic/drafts/, one JSON file each:`,
+        ``,
+        ...drafts.map((draft) => `- ${draft.id}.json (${draft.platform})`),
+        ``,
+        `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.`,
+        `   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.`,
+        `3. Set "status":"posted" plus "postedAt" (epoch ms) and, when the platform gives you one, "postedUrl".`,
+        `   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.`,
+    ].join(`\n`);

package/src/quick-model.test.ts

@@ -1,9 +1,10 @@
 import { expect, test } from "vitest";
-import { type QuickModelSource, quickModelKey, resolveQuickModel } from "./quick-model.js";
+import { type QuickModelChoice, type QuickModelSource, quickModelKey, resolveQuickModels } from "./quick-model.js";
 
-/* Which model a one-click helper spends. The rule answers two surfaces at once — the daemon runs it, the
- * browser names it in the sparkle's tooltip — so what these tests pin is that a sandbox's connections alone
- * decide it, with no stored id to go stale. */
+/* 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. */
 
 // Catalogs as their providers actually publish them: Claude's ranked list, the rest in registry order.
 const CLAUDE: QuickModelSource = { provider: `claude`, ready: true, models: [`claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5-20251001`] };
@@ -13,14 +14,19 @@ 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
+// 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];
+
 test("reaches for the efficient rung of the one connected provider, never its flagship", () => {
-    expect(resolveQuickModel([CLAUDE], ``)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+    expect(head([CLAUDE], [])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
 });
 
 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
-    // nothing while the other eats headroom they watch. Clicking sparkle should not quietly bill the Claude plan.
-    expect(resolveQuickModel([CLAUDE, GOOGLE], ``)).toEqual({ provider: `gemini`, model: `gemini-3-flash-lite` });
+    // 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", () => {
@@ -28,37 +34,33 @@ test("puts tier ahead of cost — a free frontier model is still the wrong tool
     // which is the exact outcome the feature exists to avoid.
     const proOnly: QuickModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-pro`] };
 
-    expect(resolveQuickModel([CLAUDE, proOnly], ``)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+    expect(head([CLAUDE, proOnly], [])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
 });
 
 test("uses stable provider order when two subscriptions offer the same tier", () => {
     const kimiCheap: QuickModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2-mini`] };
     const claudeCheap: QuickModelSource = { provider: `claude`, ready: true, models: [`claude-haiku-4-5`] };
 
-    expect(resolveQuickModel([kimiCheap, claudeCheap], ``)?.provider).toBe(`claude`);
+    expect(head([kimiCheap, claudeCheap], [])?.provider).toBe(`claude`);
 });
 
 test("answers the same thing however the connected providers happen to be listed", () => {
     // The daemon assembles these from live stores and the browser from its own refs; neither order is a fact.
-    const answers = [
-        resolveQuickModel([CLAUDE, GOOGLE, CODEX], ``),
-        resolveQuickModel([CODEX, CLAUDE, GOOGLE], ``),
-        resolveQuickModel([GOOGLE, CODEX, CLAUDE], ``),
-    ];
+    const answers = [head([CLAUDE, GOOGLE, CODEX], []), head([CODEX, CLAUDE, GOOGLE], []), head([GOOGLE, CODEX, CLAUDE], [])];
 
     expect(new Set(answers.map((answer) => quickModelKey(answer!))).size).toBe(1);
 });
 
 test("honours a pinned model verbatim, including an id no catalog lists yet", () => {
-    expect(resolveQuickModel([CLAUDE, GOOGLE], `claude:claude-opus-5`)).toEqual({ provider: `claude`, model: `claude-opus-5` });
+    expect(head([CLAUDE, GOOGLE], [`claude:claude-opus-5`])).toEqual({ provider: `claude`, model: `claude-opus-5` });
     // The picker's custom-id escape hatch reaches here too: a catalog can lag a release, and running something
     // other than what the settings row names would be the worse failure.
-    expect(resolveQuickModel([CLAUDE], `claude:claude-haiku-9`)).toEqual({ provider: `claude`, model: `claude-haiku-9` });
+    expect(head([CLAUDE], [`claude:claude-haiku-9`])).toEqual({ provider: `claude`, model: `claude-haiku-9` });
 });
 
 test("falls back to Auto when the pinned provider is no longer connected", () => {
     // Rather than failing every click with a credential error while the sandbox can plainly still answer.
-    expect(resolveQuickModel([offline(CLAUDE), GOOGLE], `claude:claude-haiku-4-5-20251001`)).toEqual({
+    expect(head([offline(CLAUDE), GOOGLE], [`claude:claude-haiku-4-5-20251001`])).toEqual({
         provider: `gemini`,
         model: `gemini-3-flash-lite`,
     });
@@ -66,34 +68,75 @@ test("falls back to Auto when the pinned provider is no longer connected", () =>
 
 test("ignores a malformed pin instead of running an empty model id", () => {
     for (const pinned of [`claude`, `claude:`, `:claude-haiku-4-5`, ` `]) {
-        expect(resolveQuickModel([CLAUDE], pinned)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+        expect(head([CLAUDE], [pinned])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
     }
 });
 
 test("serves the newest of a catalog that publishes no cheap tier at all", () => {
     // Kimi names no tier word anywhere. There is no cheaper rung to find, so the newest row is the honest answer.
-    expect(resolveQuickModel([KIMI], ``)).toEqual({ provider: `kimi`, model: `kimi-k3` });
+    expect(head([KIMI], [])).toEqual({ provider: `kimi`, model: `kimi-k3` });
 });
 
 test("reports nothing when no account is connected, so the button can say so instead of failing on click", () => {
-    expect(resolveQuickModel([offline(CLAUDE), offline(GOOGLE)], ``)).toBeUndefined();
-    expect(resolveQuickModel([], `claude:claude-haiku-4-5`)).toBeUndefined();
+    expect(head([offline(CLAUDE), offline(GOOGLE)], [])).toBeUndefined();
+    expect(resolveQuickModels([offline(CLAUDE), offline(GOOGLE)], [])).toEqual([]);
+    expect(head([], [`claude:claude-haiku-4-5`])).toBeUndefined();
 });
 
 test("skips a connected provider whose catalog has not loaded yet", () => {
     const unloaded: QuickModelSource = { provider: `grok`, ready: true, models: [] };
 
-    expect(resolveQuickModel([unloaded, CLAUDE], ``)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
-    expect(resolveQuickModel([unloaded], ``)).toBeUndefined();
+    expect(head([unloaded, CLAUDE], [])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+    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
+ * 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. */
+
+test("keeps the pinned models in the order they were written", () => {
+    expect(resolveQuickModels([CLAUDE, GOOGLE, CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5-20251001`])).toEqual([
+        { provider: `codex`, model: `gpt-5.6` },
+        { provider: `gemini`, model: `gemini-3-flash` },
+        { provider: `claude`, model: `claude-haiku-4-5-20251001` },
+    ]);
+});
+
+test("drops a pin whose provider went away and keeps the rest of the order intact", () => {
+    expect(resolveQuickModels([CLAUDE, offline(GOOGLE), CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5`])).toEqual([
+        { provider: `codex`, model: `gpt-5.6` },
+        { provider: `claude`, model: `claude-haiku-4-5` },
+    ]);
+});
+
+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.
+    expect(resolveQuickModels([CLAUDE, GOOGLE, KIMI], [`claude:claude-haiku-4-5`])).toEqual([{ provider: `claude`, model: `claude-haiku-4-5` }]);
+});
+
+test("names each model once, however many times the list repeats it", () => {
+    // The list is edited by hand; a duplicate would spend a second attempt proving the same account is out.
+    expect(resolveQuickModels([CLAUDE], [`claude:claude-haiku-4-5`, `claude:claude-haiku-4-5`])).toEqual([
+        { provider: `claude`, model: `claude-haiku-4-5` },
+    ]);
+});
+
+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` },
+        { provider: `kimi`, model: `kimi-k3` },
+    ]);
 });
 
 /* A MODEL ENDPOINT the user configured is a provider like any other here, and the reason it has to be is the
  * settings row: its options are built from the same picker catalog, so a pin naming one that this resolver
- * dropped would print one model's name under the sparkle and spend a different account entirely. */
+ * 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", () => {
-    expect(resolveQuickModel([CLAUDE, OLLAMA], `endpoint/ollama:qwen3-coder`)).toEqual({ provider: `endpoint/ollama`, model: `qwen3-coder` });
+    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.
@@ -104,12 +147,12 @@ test("leaves Auto to the providers whose price is known, rather than reaching fo
     // Claude publishes a Haiku-class row; the endpoint's ids carry no tier word at all, so they are UNRANKED and
     // lose on tier. What a turn on a user's own model API costs is not a fact this repo holds, and Auto should
     // not be asserting one.
-    expect(resolveQuickModel([CLAUDE, OLLAMA], ``)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+    expect(head([CLAUDE, OLLAMA], [])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
 });
 
 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
     // rather than the disabled "nothing connected" button.
-    expect(resolveQuickModel([offline(CLAUDE), OLLAMA], ``)).toEqual({ provider: `endpoint/ollama`, model: `qwen3-coder` });
+    expect(head([offline(CLAUDE), OLLAMA], [])).toEqual({ provider: `endpoint/ollama`, model: `qwen3-coder` });
 });

package/src/quick-model.ts

@@ -1,19 +1,27 @@
-import { ACCESS_COST, accessFor, PROVIDERS } from "./agent-catalog.js";
+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 one-click helper spends instead of the frontier model the chat runs
- * on. Today that is the commit box's autofill; 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.
+/* 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.
+ *
+ * IT IS AN ORDER, NOT A MODEL, and that is the whole shape of this file. A single pick is a single point of
+ * 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.
  *
  * 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 sparkle's tooltip and in the settings row's "Auto (…)"
- * label — before anything has been run. Two implementations would drift precisely where it matters most, since
- * a tooltip promising Haiku while the daemon bills Opus is worse than no tooltip.
+ * 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.
  *
- * The default is DERIVED, NEVER STORED. `quickModel` ships as "" and that empty string means "work it out from
- * whatever is connected right now", so connecting a Google account tomorrow improves the default by itself and
- * disconnecting the pinned provider degrades to Auto instead of to a dead button. Same instinct as the rest of
+ * The default is DERIVED, NEVER STORED. `quickModel` ships EMPTY and that means "work it out from whatever is
+ * connected right now", so connecting a Google account tomorrow improves the default by itself and
+ * disconnecting a pinned provider degrades to Auto instead of to a dead button. Same instinct as the rest of
  * this repo's model handling: model-order.ts derives tier and recency from the id and curates nothing, and the
  * web's defaultModelFor reads the live catalog rather than naming an id that a release will falsify. */
 
@@ -42,12 +50,13 @@ export interface QuickModelChoice {
 }
 
 // A pinned selection on the wire: `${provider}:${modelId}`, the same key shape the model picker already mints
-// for its entries (PickerEntry.key). Empty ⇒ Auto.
+// for its entries (PickerEntry.key). An empty LIST of these ⇒ Auto.
 export const quickModelKey = (choice: QuickModelChoice): string => `${choice.provider}:${choice.model}`;
 
 // Split on the FIRST colon only: a provider id never contains one and a model id might. Exported because the
-// key shape is shared: `prepushFixModel` pins the suggested fix session's model the same way, and the dialog
-// that seeds from it has to read one back.
+// key shape is shared: `agentRunModels` pins what a surface-started run opens with the same keys in the same
+// order (agent-run-model.ts), and both the daemon (filling an unattended turn) and the dialogs that seed from
+// it have to read one back.
 export const parsePinned = (pinned: string): QuickModelChoice | undefined => {
     const separator = pinned.indexOf(`:`);
     if (separator <= 0 || separator === pinned.length - 1) {
@@ -56,6 +65,14 @@ export const parsePinned = (pinned: string): QuickModelChoice | undefined => {
     return { provider: pinned.slice(0, separator), model: pinned.slice(separator + 1) };
 };
 
+/* 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
+ * 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
 // that hasn't loaded yet, which is a real state: every provider serves a floor, but only once something has
 // asked it.
@@ -79,37 +96,56 @@ const costOf = (provider: AgentProvider): number => {
     return access === undefined ? ACCESS_COST.key : ACCESS_COST[access.kind];
 };
 
-/* Which model a quick helper runs, given what this sandbox has connected. `pinned` is the stored setting.
+/* AUTO — every connected provider's cheapest row, best-first, as a ladder rather than a winner.
  *
- * A pin only holds while its provider is READY: an account the user disconnected would otherwise leave the
- * button failing on every click with a credential error, when the sandbox can plainly still answer. Auto taking
- * over is the same move the composer already makes when a live catalog stops offering the selected model.
+ * 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.
  *
- * Auto ranks candidates 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.
- *
- * Undefined when nothing is connected: the caller renders a disabled control that says so, rather than a live
- * button that fails on click. */
-export const resolveQuickModel = (sources: readonly QuickModelSource[], pinned: string): QuickModelChoice | undefined => {
-    const requested = parsePinned(pinned);
-    if (requested !== undefined && sources.some((source) => source.provider === requested.provider && source.ready)) {
-        // Taken verbatim, unvalidated against the catalog on purpose: the picker already offers a custom-id
-        // escape hatch for a model a catalog hasn't caught up with, and second-guessing the user's own id here
-        // would silently run a different model than the settings row names.
-        return requested;
-    }
-    const candidates = sources
+ * 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
+ * because one of them is spent. */
+const autoLadder = (sources: readonly QuickModelSource[]): readonly QuickModelChoice[] =>
+    sources
         .filter((source) => source.ready)
         .flatMap((source) => {
             const model = cheapestOf(source);
             return model === undefined ? [] : [{ provider: source.provider, model }];
-        });
-    return candidates.toSorted(
-        (left, right) =>
-            tierOf(right.model) - tierOf(left.model) ||
-            costOf(left.provider) - costOf(right.provider) ||
-            providerOrder(left.provider) - providerOrder(right.provider),
-    )[0];
+        })
+        .toSorted(
+            (left, right) =>
+                tierOf(right.model) - tierOf(left.model) ||
+                costOf(left.provider) - costOf(right.provider) ||
+                providerOrder(left.provider) - providerOrder(right.provider),
+        );
+
+/* WHICH MODELS A QUICK HELPER MAY RUN, IN THE ORDER IT SHOULD TRY THEM, given what this sandbox has connected.
+ * `pinned` is the stored setting: an ordered list of `${provider}:${model}` keys, empty for Auto.
+ *
+ * A pin only holds while its provider is READY: an account the user disconnected would otherwise sit at the
+ * head of the chain failing on a credential error, when the sandbox can plainly still answer. Dropping it is
+ * the same move the composer already makes when a live catalog stops offering the selected model.
+ *
+ * THE PINNED LIST IS THE WHOLE ANSWER whenever any of it survives that filter. Auto does NOT get appended
+ * underneath, and that is deliberate: a user who writes down three models has said which accounts this feature
+ * may spend, and quietly reaching for a fourth when all three are out is exactly the "spend an account they
+ * were steering away from" failure a pin exists to prevent. When NONE of the pins is connected any more the
+ * list has stopped saying anything about this sandbox, so Auto takes over rather than leaving a dead button.
+ *
+ * Empty when nothing is connected: the caller renders a control that says so, rather than a live button that
+ * fails on click. */
+export const resolveQuickModels = (sources: readonly QuickModelSource[], pinned: readonly string[]): readonly QuickModelChoice[] => {
+    const ready = new Set(sources.filter((source) => source.ready).map((source) => source.provider));
+    const requested = pinned.flatMap((key) => {
+        // Taken verbatim, unvalidated against the catalog on purpose: the picker already offers a custom-id
+        // escape hatch for a model a catalog hasn't caught up with, and second-guessing the user's own id here
+        // would silently run a different model than the settings row names.
+        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
+    // 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

@@ -1,7 +1,8 @@
-import { oc } from "@orpc/contract";
+import { eventIterator, oc } from "@orpc/contract";
 import { describe, expect, it } from "vitest";
-import { SANDBOX_ROUTE_NAMES, SANDBOX_ROUTES, sandboxRouteName } from "./index.js";
-import { contractRoutes, routeNameForRequest } from "./routes.js";
+import { z } from "zod";
+import { SANDBOX_ROUTE_NAMES, SANDBOX_ROUTE_SHAPES, SANDBOX_ROUTES, sandboxRouteName } from "./index.js";
+import { contractRoutes, routeNameForRequest, routeShapes } from "./routes.js";
 
 const fixture = {
     vpn: {
@@ -13,6 +14,9 @@ const fixture = {
     },
 };
 
+// A contract whose one route carries real schemas, so a shape can actually change between "builds".
+const shaped = (output: z.ZodType) => ({ vpn: { list: oc.route({ method: "GET", path: "/vpn" }).output(output) } });
+
 describe(`contractRoutes`, () => {
     it(`names every procedure <group>.<route>, sorted`, () => {
         expect(contractRoutes(fixture).map((route) => route.name)).toEqual([`system.killTerminal`, `vpn.connect`, `vpn.list`]);
@@ -65,7 +69,91 @@ describe(`routeNameForRequest`, () => {
     });
 });
 
+describe(`routeShapes`, () => {
+    it(`gives the same fingerprint for the same shape, twice`, () => {
+        expect(routeShapes(shaped(z.object({ a: z.string() })))).toEqual(routeShapes(shaped(z.object({ a: z.string() }))));
+    });
+
+    it(`changes the fingerprint when a field is added`, () => {
+        const before = routeShapes(shaped(z.object({ a: z.string() })))[`vpn.list`];
+        const after = routeShapes(shaped(z.object({ a: z.string(), b: z.number() })))[`vpn.list`];
+        expect(before).toBeDefined();
+        expect(after).not.toBe(before);
+    });
+
+    it(`changes the fingerprint when a field's type changes`, () => {
+        const before = routeShapes(shaped(z.object({ a: z.string() })))[`vpn.list`];
+        const after = routeShapes(shaped(z.object({ a: z.number() })))[`vpn.list`];
+        expect(after).not.toBe(before);
+    });
+
+    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
+        // 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`];
+        const asInput = routeShapes({ vpn: { list: oc.route({ method: "GET", path: "/vpn" }).input(one) } })[`vpn.list`];
+        expect(asOutput).toBeDefined();
+        expect(asInput).not.toBe(asOutput);
+    });
+
+    it(`treats a route declaring no schemas as a shape of its own`, () => {
+        // Not a special case: "this route carries nothing" is a real shape, and a build that later gives it an
+        // output has genuinely changed it. All three fixture routes declare nothing, so all three agree.
+        const shapes = routeShapes(fixture);
+        expect(Object.keys(shapes).toSorted()).toEqual([`system.killTerminal`, `vpn.connect`, `vpn.list`]);
+        expect(new Set(Object.values(shapes)).size).toBe(1);
+        expect(routeShapes(shaped(z.object({ a: z.string() })))[`vpn.list`]).not.toBe(shapes[`vpn.list`]);
+    });
+
+    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
+        // "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 = {
+            vpn: {
+                list: fixture.vpn.list,
+                watch: oc.route({ method: "GET", path: "/vpn/watch" }).output(eventIterator(z.object({ a: z.string() }))),
+            },
+        };
+        expect(Object.keys(routeShapes(withStream)).toSorted()).toEqual([`vpn.list`]);
+        expect(
+            contractRoutes(withStream)
+                .map((route) => route.name)
+                .toSorted(),
+        ).toEqual([`vpn.list`, `vpn.watch`]);
+    });
+});
+
 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
+        // 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`,
+            `intentic.applyEvents`,
+            `intentic.run`,
+            `system.events`,
+            `system.manageMachineSandbox`,
+            `vpn.connect`,
+        ]);
+    });
+
+    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);
+    });
+
     it(`derives a route table with no duplicate names`, () => {
         expect(SANDBOX_ROUTE_NAMES.length).toBe(SANDBOX_ROUTES.length);
         expect(new Set(SANDBOX_ROUTE_NAMES).size).toBe(SANDBOX_ROUTE_NAMES.length);