@intentic/sandbox-contract 1.159.0 → 1.160.0

package/src/contracts/git.contract.ts

@@ -1,5 +1,7 @@
 import { oc } from "@orpc/contract";
 import {
+    CommitMessageDraftSchema,
+    CommitMessageSchema,
     CommitResultSchema,
     CommitSchema,
     DiscardSchema,
@@ -39,6 +41,10 @@ import {
 // Changes panel renders; commit/discard take optional `paths` for per-file actions.
 export const gitContract = {
     changes: oc.route({ method: "GET", path: "/git/changes" }).output(GitChangesSchema),
+    // Drafts a commit message for what the commit box is about to record, on the sandbox's quick model (the
+    // cheap rung — see quick-model.ts). Workspace-wide like `changes` and for the same reason: one commit box,
+    // one message, every staged repo. POST because it spends a model call, not because it writes anything.
+    commitMessage: oc.route({ method: "POST", path: "/git/commit-message" }).input(CommitMessageDraftSchema).output(CommitMessageSchema),
     // The git-history graph over one repo's real commits: the repo list (for the tree affordance + switcher),
     // one repo's commit log, and lazy per-commit detail (changed files, then a file's before/after AT the
     // commit). Read-only — commit/discard on the working tree stay the write path (above).

package/src/contracts/kimi.contract.ts

@@ -1,15 +1,26 @@
 import { oc } from "@orpc/contract";
-import { AccountIdSchema, KimiConnectSchema, ModelsSchema, OauthAccountListSchema, OauthAccountSchema, OkSchema } from "../schemas.js";
+import {
+    AccountIdSchema,
+    AccountRenameSchema,
+    KimiConnectSchema,
+    ModelsSchema,
+    OauthAccountListSchema,
+    OauthAccountSchema,
+    OkSchema,
+} from "../schemas.js";
 
 // Kimi Code (Moonshot) — the sandbox owns the credential, an API key rather than an OAuth grant. Kimi speaks the
 // Anthropic Messages protocol, so a Kimi turn runs on the SAME Claude Code harness as Claude, with the harness
 // pointed at Moonshot's Anthropic-compatible endpoint and authenticated with the stored key (see agent.routes).
 // `connect` stores a pasted key as a new account and returns it; `models` is the live catalog for the picker;
-// `accounts` lists connected keys (tokens never ride back); `disconnect` clears the one named by id.
+// `accounts` lists connected keys (tokens never ride back); `rename` renames one (a pasted key carries no
+// identity to derive a name from, so this is the ONLY way a Kimi row gets a distinguishing name);
+// `disconnect` clears the one named by id.
 export const kimiContract = {
     connect: oc.route({ method: "POST", path: "/kimi/account/connect" }).input(KimiConnectSchema).output(OauthAccountSchema),
     // Kimi/Moonshot's live models for the picker — the source of valid ids (see kimi-models.ts).
     models: oc.route({ method: "GET", path: "/kimi/models" }).output(ModelsSchema),
     accounts: oc.route({ method: "GET", path: "/kimi/accounts" }).output(OauthAccountListSchema),
+    rename: oc.route({ method: "POST", path: "/kimi/account/rename" }).input(AccountRenameSchema).output(OauthAccountSchema),
     disconnect: oc.route({ method: "POST", path: "/kimi/account/disconnect" }).input(AccountIdSchema).output(OkSchema),
 };

package/src/contracts/memory.contract.ts

@@ -0,0 +1,13 @@
+import { oc } from "@orpc/contract";
+import { MemoryFileQuerySchema, MemoryFileSchema, MemoryListSchema, MemoryWriteSchema, OkSchema } from "../schemas.js";
+
+// The agent's persistent memory notes (.intentic/claude/projects/<project>/memory) — the one browser surface
+// for that control-plane subtree (see schemas.ts). Read for the memory panel; write/delete so the owner can
+// curate what the agent remembers (fix a stale fact, drop a wrong one). oRPC's OpenAPI codec reads non-GET
+// input from the JSON body, so write and delete send {project, name} in the body (same as /workspace/entry).
+export const memoryContract = {
+    list: oc.route({ method: "GET", path: "/memory" }).output(MemoryListSchema),
+    read: oc.route({ method: "GET", path: "/memory/file" }).input(MemoryFileQuerySchema).output(MemoryFileSchema),
+    write: oc.route({ method: "PUT", path: "/memory/file" }).input(MemoryWriteSchema).output(OkSchema),
+    delete: oc.route({ method: "DELETE", path: "/memory/file" }).input(MemoryFileQuerySchema).output(OkSchema),
+};

package/src/contracts/push.contract.ts

@@ -1,5 +1,5 @@
 import { oc } from "@orpc/contract";
-import { OkSchema, PushConfigQuerySchema, PushConfigSchema, PushEndpointSchema, PushSubscriptionSchema } from "../schemas.js";
+import { OkSchema, PushConfigQuerySchema, PushConfigSchema, PushEndpointSchema, PushSubscriptionSchema, PushTestSchema } from "../schemas.js";
 
 // Web-push notifications for this sandbox. The daemon owns the VAPID keypair and the subscription list (see
 // push/push-store.ts for why the key lives on the history volume), and sends on the three moments where the
@@ -13,5 +13,5 @@ export const pushContract = {
     config: oc.route({ method: "GET", path: "/push/config" }).input(PushConfigQuerySchema).output(PushConfigSchema),
     subscribe: oc.route({ method: "POST", path: "/push/subscribe" }).input(PushSubscriptionSchema).output(OkSchema),
     unsubscribe: oc.route({ method: "POST", path: "/push/unsubscribe" }).input(PushEndpointSchema).output(OkSchema),
-    test: oc.route({ method: "POST", path: "/push/test" }).output(OkSchema),
+    test: oc.route({ method: "POST", path: "/push/test" }).output(PushTestSchema),
 };

package/src/contracts/settings.contract.ts

@@ -1,11 +1,15 @@
 import { oc } from "@orpc/contract";
-import { CleanerSavingsSchema, OkSchema, SandboxSettingsSchema } from "../schemas.js";
+import { BuiltinPromptSchema, BuiltinPromptTextSchema, CleanerSavingsSchema, OkSchema, SandboxSettingsSchema } from "../schemas.js";
 
 // Per-sandbox agent settings (.intentic/settings.json). `get` returns the current flags with defaults applied
 // when the file is absent; `set` overwrites them. `savings` reports the output-cleaner token savings aggregated
 // from the live filter-stats ledger (the rtk-`gain` surface — read-only, so a UI card can show what's working).
+// `builtinPrompt` returns one of the two built-in system prompts as text — Intentic's own, or Claude Code's
+// read out of the installed CLI — so the settings page can SHOW the prompt behind a mode instead of asking the
+// user to trust a description of it, and can fork either into a custom one.
 export const settingsContract = {
     get: oc.route({ method: "GET", path: "/settings" }).output(SandboxSettingsSchema),
     set: oc.route({ method: "POST", path: "/settings" }).input(SandboxSettingsSchema).output(OkSchema),
     savings: oc.route({ method: "GET", path: "/settings/savings" }).output(CleanerSavingsSchema),
+    builtinPrompt: oc.route({ method: "GET", path: "/settings/system-prompt/{base}" }).input(BuiltinPromptSchema).output(BuiltinPromptTextSchema),
 };

package/src/contracts/system.contract.ts

@@ -2,6 +2,7 @@ import { eventIterator, oc } from "@orpc/contract";
 import { z } from "zod";
 import { SystemEventSchema } from "../events.js";
 import {
+    DaemonSessionSchema,
     HostTunnelInputSchema,
     HostTunnelSchema,
     InfoSchema,
@@ -19,6 +20,9 @@ import {
 // connection simply never joins the roster.
 export const systemContract = {
     info: oc.route({ method: "GET", path: "/info" }).output(InfoSchema),
+    // Exchange the request's verified bearer (a Google ID token — or a still-valid session, which makes this
+    // route sliding renewal) for a daemon-minted session, the credential every steady-state call presents.
+    session: oc.route({ method: "POST", path: "/system/session" }).output(DaemonSessionSchema),
     events: oc
         .route({ method: "GET", path: "/events" })
         .input(z.object({ clientId: z.string().optional() }))

package/src/contracts/translator.contract.ts

@@ -4,7 +4,8 @@ import { KeyedProviderSchema, OkSchema, TranslatorAccountsSchema, TranslatorComp
 
 // Routed-provider subscriptions (Sandbox ▸ Agent). The bundled translator (CLIProxyAPI) runs a non-Claude model
 // UNDER the Claude Code harness on the user's SUBSCRIPTION, so each provider connects via an OAuth login rather
-// than an API key. `accounts` reports which subscriptions are connected; `disconnect` clears a provider's tokens.
+// than an API key. A provider can hold several accounts side by side (the translator balances across them);
+// `accounts` lists what's connected per provider and `disconnect` clears ONE account by its auth-file `name`.
 //
 // Two login shapes ride one pair of routes. Codex and Grok mint a one-time device `code`: the user enters it at
 // the provider's site and the translator polls to completion in the background, so the UI just polls `accounts`
@@ -21,6 +22,6 @@ export const translatorContract = {
     complete: oc.route({ method: "POST", path: "/translator/{provider}/complete" }).input(TranslatorCompleteSchema).output(OkSchema),
     disconnect: oc
         .route({ method: "POST", path: "/translator/{provider}/disconnect" })
-        .input(z.object({ provider: KeyedProviderSchema }))
+        .input(z.object({ provider: KeyedProviderSchema, name: z.string().min(1) }))
         .output(OkSchema),
 };

package/src/contracts/workspace.contract.ts

@@ -19,6 +19,8 @@ import {
     WorkspaceFileQuerySchema,
     WorkspaceFileSchema,
     WorkspaceGraphSchema,
+    WorkspaceHealthQuerySchema,
+    WorkspaceHealthSchema,
     WorkspaceInstallResultSchema,
     WorkspaceInstallSchema,
     WorkspaceMoveSchema,
@@ -45,6 +47,10 @@ export const workspaceContract = {
     // Ranked groups, match-reason tags, freshness, resumable cursor. `mode` narrows to one verb; default is
     // auto-mode fusion. (Implementation detail: the daemon backs this with a resident in-process iq engine.)
     search: oc.route({ method: "GET", path: "/workspace/search" }).input(WorkspaceSearchQuerySchema).output(WorkspaceSearchResultSchema),
+    // One repository's health in numbers: churn × complexity per file, index totals, and the import graph's
+    // top modules — the `hotspots` and `map` rankings the CLI prints, shaped for a panel. Repo-scoped, because
+    // "the codebase" is a repo, not the whole /work drop.
+    health: oc.route({ method: "GET", path: "/workspace/health" }).input(WorkspaceHealthQuerySchema).output(WorkspaceHealthSchema),
     // Deterministic, no-LLM classification of the dropped workspace into coarse buckets (repositories / documents
     // / media / archives / other). Read-only proposal: the browser renders it and applies accepted moves via the
     // existing /workspace/move route — this route never touches the tree.

package/src/events.ts

@@ -3,6 +3,7 @@ import {
     AgentProviderSchema,
     AgentReplySchema,
     AgentSummarySchema,
+    LandConflictSchema,
     PermissionModeSchema,
     RateLimitInfoSchema,
     UsageWindowSchema,
@@ -79,7 +80,7 @@ export const ContextUsageSchema = z.object({
 export type ContextUsage = z.infer<typeof ContextUsageSchema>;
 
 // ACP-aligned tool taxonomy (Agent Client Protocol's ToolKind, verbatim): what a tool call *does*, driving
-// the card icon and follow-along behavior regardless of which backend named the tool.
+// the card icon and the live-writes bookkeeping regardless of which backend named the tool.
 export const ToolKindSchema = z.enum(["read", "edit", "delete", "move", "search", "execute", "think", "fetch", "other"]);
 export type ToolKind = z.infer<typeof ToolKindSchema>;
 
@@ -136,12 +137,16 @@ export type RestoredToolCall = z.infer<typeof RestoredToolCallSchema>;
 export const RestoredMessageSchema = z.object({
     role: z.enum(["user", "assistant"]),
     text: z.string(),
+    // Files the user attached to this turn (user bubbles only) as workspace-relative paths, recovered from
+    // the stored prompt's attachment note — so a reopened tab redraws chips, not the injected protocol text.
+    attachments: z.array(z.string()).optional(),
     thinking: z.string().optional(),
     tools: z.array(RestoredToolCallSchema).optional(),
 });
 export type RestoredMessage = z.infer<typeof RestoredMessageSchema>;
 
 export const SessionTranscriptSchema = z.object({ messages: z.array(RestoredMessageSchema) });
+export const AgentTranscriptSchema = SessionTranscriptSchema.extend({ sessionId: z.string().optional() });
 
 // One frame from an agent turn, relayed to the UI. `kind`-discriminated. The daemon normalizes the SDK's
 // ~40 SDKMessage types down to this union: high-value block types get a dedicated frame
@@ -152,16 +157,26 @@ export const SessionTranscriptSchema = z.object({ messages: z.array(RestoredMess
 // `parentToolUseId` tags frames produced inside a subagent (Task tool).
 export const AgentEventSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("session"), sessionId: z.string() }),
-    // First frame of an isolated turn: the conversation's worktree identity — its branch (agent/<id>) and the
-    // ROOT repo's short base sha (the checkout moment). Emitted before any provider frames.
-    z.object({ kind: z.literal("worktree"), branch: z.string(), base: z.string() }),
+    /* First frame of an isolated turn: the conversation's worktree identity — its branch (agent/<id>) and the
+     * ROOT repo's short base sha (the checkout moment). Emitted before any provider frames.
+     *
+     * `unenforced` marks the degraded container: no CAP_SYS_ADMIN, so the turn's worktree could not be
+     * bind-mounted over the workspace root and the harness is rewriting tool paths into it instead. That
+     * fallback covers what arrives as tool input and not what a subprocess computes for itself, so the
+     * operator needs to know — this state used to be one line in the daemon log at boot, and the way it got
+     * noticed was files appearing in the main tree from agents that were supposed to be on branches. */
+    z.object({ kind: z.literal("worktree"), branch: z.string(), base: z.string(), unenforced: z.boolean().optional() }),
     // Emitted after a clean isolated turn whose delta auto-landed (or failed to): landed ⇒ the work is now
     // UNCOMMITTED changes in the main tree (the Changes panel is the review); conflicts ⇒ it stayed safely in
-    // the worktree — the named paths collide with the user's own edits, "Land now" recovers after they resolve.
+    // the worktree, and each named path carries WHY it would not apply (see LandConflictSchema) so the report
+    // can say whether the user's own copy is at risk or the main line simply moved on underneath the agent.
+    // held ⇒ auto-land is off for this agent: nothing was applied and nothing failed — the delta is waiting
+    // on the branch for a deliberate Land (landed is false, conflicts absent).
     z.object({
         kind: z.literal("landed"),
         landed: z.boolean(),
-        conflicts: z.array(z.object({ repo: z.string(), paths: z.array(z.string()) })).optional(),
+        conflicts: z.array(LandConflictSchema).optional(),
+        held: z.boolean().optional(),
     }),
     // The SDK's init handshake; carries the model it actually resolved for the turn.
     z.object({ kind: z.literal("init"), model: z.string() }),
@@ -266,12 +281,38 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 // Codex ran the turn but warned about it (fallback model metadata) — a notice, not a failure.
                 "codex-advisory",
                 "codex-reauth",
+                // The Claude subscription credential is dead (revoked, or its refresh token rejected) and only a
+                // reconnect fixes it. Distinct from "no account connected": the account IS there, so the UI can
+                // offer reconnect where the user already is and replay the message that bounced.
+                "claude-reauth",
+                // The API refused this turn's token MID-FLIGHT — nearly always one superseded by a rotation,
+                // which Anthropic retires the moment its successor is minted. Distinct from claude-reauth: the
+                // account is fine and the daemon re-mints on the spot, so this frame is a notice about a turn
+                // that resumed itself, not a request for the user to do anything. It only reaches the client
+                // when the resume could NOT start, which is when reconnecting really is the fix.
+                "claude-token-refused",
+                // The harness read the message as a slash command it doesn't have, and discarded everything
+                // after the name — the model never saw the message. Nothing was processed, so the client holds
+                // the text back instead of leaving the user to retype it (same treatment as claude-reauth).
+                "unknown-command",
                 "grok-model-invalid",
                 "codex-model-invalid",
                 "subscription-required",
                 "agent-busy",
             ])
             .optional(),
+        // rate_limit only: when the exhausted window reopens (epoch seconds, from the stream's own
+        // rate_limit_event or the account's persisted usage windows), and what the daemon did about it —
+        // "scheduled" = auto-resume is on and this turn re-runs itself a minute after `resetsAt`;
+        // "available" = the daemon remembered the failed turn and enabling the autoResumeOnLimit setting
+        // arms that same resume, which is what the chat's offer banner hangs off. Absent together when the
+        // reset instant is unknown (nothing to schedule against).
+        resetsAt: z.number().optional(),
+        autoResume: z.enum(["scheduled", "available"]).optional(),
+        // rate_limit only: the account whose allowance is spent, as the DAEMON resolved it (the client's own
+        // selection can be empty, which means "the provider's first"). It is what lets the chat offer the
+        // provider's OTHER accounts as a resume-now instead of a wait — see /agent/resume-limit.
+        account: z.string().optional(),
     }),
     z.object({ kind: z.literal("done") }),
 ]);

package/src/index.ts

@@ -17,6 +17,7 @@ import { intenticContract } from "./contracts/intentic.contract.js";
 import { inventoryContract } from "./contracts/inventory.contract.js";
 import { kimiContract } from "./contracts/kimi.contract.js";
 import { logsContract } from "./contracts/logs.contract.js";
+import { memoryContract } from "./contracts/memory.contract.js";
 import { panelsContract } from "./contracts/panels.contract.js";
 import { portsContract } from "./contracts/ports.contract.js";
 import { pushContract } from "./contracts/push.contract.js";
@@ -46,6 +47,7 @@ export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
 export { kimiContract } from "./contracts/kimi.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
+export { memoryContract } from "./contracts/memory.contract.js";
 export { panelsContract } from "./contracts/panels.contract.js";
 export { portsContract } from "./contracts/ports.contract.js";
 export { pushContract } from "./contracts/push.contract.js";
@@ -65,8 +67,10 @@ export * from "./agent-catalog.js";
 export * from "./hostnames.js";
 export * from "./model-order.js";
 export * from "./path-refs.js";
+export * from "./quick-model.js";
 export * from "./schemas.js";
 export * from "./terminal-protocol.js";
+export * from "./title.js";
 
 // The aggregated contract — implemented on the server by the per-domain route factories and consumed by the
 // browser's typed oRPC client (ContractRouterClient<typeof sandboxContract>). The wire paths it declares are
@@ -92,6 +96,7 @@ export const sandboxContract = {
     workspace: workspaceContract,
     inventory: inventoryContract,
     logs: logsContract,
+    memory: memoryContract,
     panels: panelsContract,
     ports: portsContract,
     push: pushContract,
@@ -110,4 +115,5 @@ export const SANDBOX_ROUTES: readonly ContractRoute[] = contractRoutes(sandboxCo
 export const SANDBOX_ROUTE_NAMES: readonly string[] = SANDBOX_ROUTES.map((route) => route.name);
 
 // The contract route a concrete browser request belongs to, bound to this build's route table.
-export const sandboxRouteName = (method: string, pathWithQuery: string): string | undefined => routeNameForRequest(SANDBOX_ROUTES, method, pathWithQuery);
+export const sandboxRouteName = (method: string, pathWithQuery: string): string | undefined =>
+    routeNameForRequest(SANDBOX_ROUTES, method, pathWithQuery);

package/src/model-order.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "vitest";
-import { compareModelIds, compareUnrankedModelIds, familyOf, releaseOf, tierRankOf } from "./model-order.js";
+import { compareCheapestFirst, compareModelIds, compareUnrankedModelIds, familyOf, releaseOf, tierRankOf } from "./model-order.js";
 
 /* The order every provider's catalog is served and browsed in. The rule exists because only Anthropic publishes
  * a ranking: the OpenAI-compatible endpoints behind Codex, Gemini, Kimi and Grok hand back a SET, and taking
@@ -135,3 +135,42 @@ test("sorts an unversioned rolling alias under the releases that name their vers
     expect(releaseOf("kimi-latest").version).toEqual([]);
     expect(["kimi-latest", "kimi-k2-0711-preview"].toSorted(compareModelIds)).toEqual(["kimi-k2-0711-preview", "kimi-latest"]);
 });
+
+// --- the cheap end (compareCheapestFirst) ---------------------------------------------------------------
+// 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", () => {
+    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"]);
+    expect(claude.toSorted(compareModelIds)).toEqual(["claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5-20251001"]);
+});
+
+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
+    // 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");
+});
+
+test("takes the NEWEST build of the cheap rung, not merely any of them", () => {
+    // Within one tier the release rule runs unchanged: cheap is a tier, not an excuse to serve a stale model.
+    expect(["claude-haiku-4-5-20251001", "claude-haiku-4-5-20260210"].toSorted(compareCheapestFirst)[0]).toBe("claude-haiku-4-5-20260210");
+    expect(["gemini-3-flash-lite", "gemini-2-flash-lite"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3-flash-lite");
+});
+
+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.
+    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");
+});
+
+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.
+    expect(["kimi-k2-0711-preview", "kimi-k2-0905-preview"].toSorted(compareCheapestFirst)[0]).toBe("kimi-k2-0905-preview");
+});

package/src/model-order.ts

@@ -138,3 +138,18 @@ export const compareModelIds = (left: string, right: string): number =>
  * 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 a one-click helper (the commit box's autofill). 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.
+ *
+ * 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.
+ * 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 =>
+    tierRankOf(familyOf(right)) - tierRankOf(familyOf(left)) || compareRelease(releaseOf(left), releaseOf(right));

package/src/path-refs.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { rankRefCandidates, referenceTails } from "./path-refs.js";
+import { isTestPath, rankRefCandidates, referenceTails } from "./path-refs.js";
 
 describe("referenceTails", () => {
     test("offers the reference itself first, then shorter tails of it", () => {
@@ -40,3 +40,29 @@ describe("rankRefCandidates", () => {
         expect(rankRefCandidates("src/foo.ts", ["src/foo.ts", "vendor/src/foo.ts"])).toEqual(["src/foo.ts", "vendor/src/foo.ts"]);
     });
 });
+
+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`,
+        `_apps/cli/src/cli.e2e.test.ts`,
+        `src/e2e-harness.ts`,
+        `pkg/__tests__/helper.ts`,
+        `_libs/iq-recall/src/__fixtures__/transcripts/a.jsonl`,
+        `vitest.config.ts`,
+        `_apps/web/vitest.workspace.config.mts`,
+        `playwright.config.ts`,
+    ]) {
+        expect(isTestPath(path), path).toBe(true);
+    }
+    for (const path of [
+        `src/pages/testimonials.vue`,
+        `src/latest.ts`,
+        `src/test-utils.ts`,
+        `contest/results.ts`,
+        `src/attestation.spec.md.bak`,
+        `docs/testing.md`,
+    ]) {
+        expect(isTestPath(path), path).toBe(false);
+    }
+});

package/src/path-refs.ts

@@ -41,3 +41,19 @@ export const rankRefCandidates = (tail: string, paths: readonly string[]): reado
         .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
+ * 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.
+ *
+ * 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 —
+ * 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\.[^/]+)$/;
+
+export const isTestPath = (path: string): boolean =>
+    TEST_FILE.test(path) || path.split(`/`).some((segment) => TEST_DIRS.has(segment));

package/src/quick-model.test.ts

@@ -0,0 +1,88 @@
+import { expect, test } from "vitest";
+import { type QuickModelSource, quickModelKey, resolveQuickModel } 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. */
+
+// 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`] };
+const GOOGLE: QuickModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-flash`, `gemini-3-flash-lite`, `gemini-3-pro`] };
+const CODEX: QuickModelSource = { provider: `codex`, ready: true, models: [`gpt-5.4-mini`, `gpt-5.6`] };
+const KIMI: QuickModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2-0711-preview`, `kimi-k2-0905-preview`] };
+
+const offline = (source: QuickModelSource): QuickModelSource => ({ ...source, ready: false });
+
+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` });
+});
+
+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` });
+});
+
+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`] };
+
+    expect(resolveQuickModel([CLAUDE, proOnly], ``)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+});
+
+test("prefers a subscription to a metered key at equal tier, since only one of them charges per click", () => {
+    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`);
+});
+
+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], ``),
+    ];
+
+    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` });
+    // 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` });
+});
+
+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({
+        provider: `gemini`,
+        model: `gemini-3-flash-lite`,
+    });
+});
+
+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` });
+    }
+});
+
+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-k2-0905-preview` });
+});
+
+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();
+});
+
+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();
+});

package/src/quick-model.ts

@@ -0,0 +1,103 @@
+import { ACCESS_COST, accessFor, PROVIDERS } from "./agent-catalog.js";
+import { compareCheapestFirst, familyOf, tierRankOf } from "./model-order.js";
+import type { NativeProvider } 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 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 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
+ * 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. */
+
+// 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
+// own model, so there is no cheap rung to point it at.
+export interface QuickModelSource {
+    readonly provider: NativeProvider;
+    // The same connection predicate every other surface gates on (access.ts web-side, the daemon's own account
+    // stores daemon-side). A catalog is never empty by construction, so "has rows" says nothing about "can send".
+    readonly ready: boolean;
+    readonly models: readonly string[];
+}
+
+export interface QuickModelChoice {
+    readonly provider: NativeProvider;
+    readonly model: string;
+}
+
+// A pinned selection on the wire: `${provider}:${modelId}`, the same key shape the model picker already mints
+// for its entries (PickerEntry.key). Empty ⇒ 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.
+const parsePinned = (pinned: string): QuickModelChoice | undefined => {
+    const separator = pinned.indexOf(`:`);
+    if (separator <= 0 || separator === pinned.length - 1) {
+        return undefined;
+    }
+    return { provider: pinned.slice(0, separator) as NativeProvider, model: pinned.slice(separator + 1) };
+};
+
+// 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];
+
+// Where a provider's cheapest row sits on the shared tier scale, and therefore how well it answers the question
+// this whole module asks. UNRANKED (-1) is a genuine last place: it means the id carries no tier word we know,
+// 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
+// compareUnrankedModelIds exists to guarantee, and the one a default actually needs.
+const providerOrder = (provider: NativeProvider): 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, so the
+// fallback is unreachable — it exists because AgentProvider is a bare string on the wire.
+const costOf = (provider: NativeProvider): number => {
+    const access = accessFor(provider);
+    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.
+ *
+ * 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.
+ *
+ * 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
+        .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];
+};