@intentic/sandbox-contract 1.159.0 → 1.161.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,23 @@
 import { oc } from "@orpc/contract";
-import { CleanerSavingsSchema, OkSchema, SandboxSettingsSchema } from "../schemas.js";
+import {
+    BuiltinPromptSchema,
+    BuiltinPromptTextSchema,
+    DayWindowQuerySchema,
+    OkSchema,
+    SandboxSettingsSchema,
+    SavingsReportSchema,
+} 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).
+// when the file is absent; `set` overwrites them. `savings` reports what each token-reduction mechanism was
+// worth — the cleaners' realized per-command savings and the terse steer's measured A/B — over an inclusive
+// UTC day window, the same one the spend ledger takes, so a screen can filter both with one calendar.
+// `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),
+    savings: oc.route({ method: "GET", path: "/settings/savings" }).input(DayWindowQuerySchema).output(SavingsReportSchema),
+    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/usage.contract.ts

@@ -1,10 +1,10 @@
 import { oc } from "@orpc/contract";
-import { UsageRollupQuerySchema, UsageRollupSchema } from "../schemas.js";
+import { DayWindowQuerySchema, UsageRollupSchema } from "../schemas.js";
 
 // The durable spend ledger (see UsageTurnSchema). Read-only over the wire — rows are appended daemon-side at
 // turn end, so the ledger stays a trustworthy record of what was actually spent, the same principle as the
 // activity log. `rollup` serves every cost/usage panel: it groups by day × provider × account × model, and the
 // browser re-projects from there (spend per day, cost by model, cache hit rate) without another round trip.
 export const usageContract = {
-    rollup: oc.route({ method: "GET", path: "/usage/rollup" }).input(UsageRollupQuerySchema).output(UsageRollupSchema),
+    rollup: oc.route({ method: "GET", path: "/usage/rollup" }).input(DayWindowQuerySchema).output(UsageRollupSchema),
 };

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() }),
@@ -224,6 +239,27 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // The live gate: the provider's answer to "may this turn run", pushed mid-turn. Drives the rate-limited
     // notice, not the headroom readouts — see RateLimitInfoSchema.
     RateLimitInfoSchema.extend({ kind: z.literal("rate_limit_info"), account: z.string().optional() }),
+    /* The turn is alive but WAITING on the provider: a request failed transiently (5xx, 529, a dropped socket)
+     * and the harness is retrying it inside this same turn. A status, not a failure — nothing has been lost and
+     * the turn may still finish normally, so the client renders it where "thinking" goes rather than in the
+     * transcript.
+     *
+     * It exists because the retry budget is deliberately long (see CLAUDE_CODE_RETRY_WATCHDOG in
+     * harness-credentials.ts): a turn can now sit silent for minutes riding out an outage, and silence reads as
+     * a hang. The one action a user takes against an apparent hang is Stop, which is the only action that
+     * actually loses the work — so the wait has to be visible, with its own next-attempt clock.
+     *
+     * `attempt`/`maxAttempts` are the harness's own counters; `nextAttemptAt` (epoch ms) is when it will try
+     * again, so the readout counts down instead of freezing on a number nobody can interpret. */
+    z.object({
+        kind: z.literal("provider_retry"),
+        attempt: z.number(),
+        maxAttempts: z.number(),
+        nextAttemptAt: z.number(),
+        // The HTTP status behind it when there was one (529 reads as capacity, 500 as a fault — the client says
+        // which). Absent for a transport failure that never got a response.
+        status: z.number().optional(),
+    }),
     // Every plan-limit pool for the account that served the turn, read from the CLI's usage endpoint once the
     // turn settles. `account` tags which Claude account it belongs to, so the client keys headroom by account;
     // absent on an env-token turn, which has no account to attribute it to. No `measuredAt` on the wire: both
@@ -266,12 +302,55 @@ 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 model provider itself failed transiently — 500/502/503, a 529 at capacity, a dropped
+                // socket — and the harness's own in-turn retries did not outlast it. Nothing about the workspace
+                // or the request is wrong, so the daemon remembers the turn and re-runs it on an escalating
+                // backoff (provider-health.ts): the frame is a notice about a turn that is coming back, and
+                // reaches the client as a plain failure only once the attempts are spent.
+                "provider-outage",
+                // 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). Absent when the reset instant is unknown
+        // (nothing to schedule against).
+        resetsAt: z.number().optional(),
+        // Where the daemon's resume of THIS turn stands — the same two states for a spent allowance and for a
+        // provider outage, because the client's reading of them is the same: "scheduled" = the resume is armed
+        // and this turn comes back by itself; "available" = the daemon remembered the failed turn and turning
+        // the setting on (autoResumeOnLimit / resumeAfterOutage) arms that same resume, which is what the
+        // chat's offer banner hangs off. Absent ⇒ there is nothing to resume.
+        autoResume: z.enum(["scheduled", "available"]).optional(),
+        /* provider-outage only: the shape of the wait. `retryAt` (epoch seconds) is when the next attempt is
+         * due — not a fixed cadence, because an outage has no reset instant to aim at and hammering a provider
+         * that is down only spends tokens on refusals, so each attempt waits longer than the last
+         * (provider-health.ts owns the schedule).
+         *
+         * `attempt`/`maxAttempts` are on the wire so the notice can say the automation is BOUNDED. An
+         * on-by-default retry that gives no account of how long it will keep going is the kind users switch off
+         * defensively; one that says "attempt 2 of 6" is one they leave on. */
+        outage: z.object({ retryAt: z.number(), attempt: z.number(), maxAttempts: z.number() }).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();
+});