@intentic/sandbox-contract 1.245.0 → 1.247.0

package/src/schemas/plan-limits.ts

@@ -58,6 +58,56 @@ export const AccountUsageSchema = z.object({
     measuredAt: z.number(),
 });
 export type AccountUsage = z.infer<typeof AccountUsageSchema>;
+/* THE ONE WAY PAST A SPENT SESSION WINDOW THAT IS NOT WAITING, which Anthropic grants once a week per account.
+ *
+ * Every other affordance around a refused turn is about WHEN: arm the appointment, count down to the reset,
+ * press when it opens. This one moves the clock. The provider reopens the five-hour window immediately and
+ * charges the account one of its weekly resets; the WEEKLY allowance is untouched and still binds, so this
+ * buys back the session pool and nothing else. Upstream's own CLI spells it `/limit-reset`.
+ *
+ * THE ANSWER IS THE PROVIDER'S, NEVER OURS. There is no rule here to re-derive: eligibility turns on the plan
+ * tier, how long the account has existed, whether it is actually at the wall, whether another experiment holds
+ * it, and whether the week's reset is already spent — all of it decided server-side and none of it visible from
+ * a usage reading. So this shape is a transcription of what the endpoint said, and the button exists only while
+ * it says `available`. A client must never infer availability from a 100% window.
+ *
+ * `reason` is the provider's own word for the refusal ("tier", "tenure", "not_at_wall", "weekly_limit",
+ * "already_used", …) and is carried rather than translated, because the set is the provider's to extend and a
+ * word we don't recognise is still worth showing to somebody asking why the button is not there. */
+export const LimitResetStatusSchema = z.object({
+    available: z
+        .boolean()
+        .describe("Whether the provider will reopen this account's session window right now. The only thing a button may be drawn from."),
+    reason: z
+        .string()
+        .optional()
+        .describe("Why not, in the provider's own word, when it gave one. Absent when it is available, or when the provider said nothing."),
+    // Both epoch SECONDS, matching every other reset instant on the wire (UsageWindow.resetsAt, limitResetsAt).
+    nextAvailableAt: z
+        .number()
+        .optional()
+        .describe("When the next reset may be claimed, in epoch seconds, where the provider publishes it. Absent means unknown, never 'now'."),
+    weeklyResetsAt: z.number().optional().describe("When the weekly allowance itself reopens, in epoch seconds, where the provider publishes it."),
+});
+export type LimitResetStatus = z.infer<typeof LimitResetStatusSchema>;
+/* WHAT CLAIMING IT DID, in the provider's own vocabulary plus the two failures that are ours.
+ *
+ * `reset` is the only outcome that changed anything, and the caller's cue to send the held turn again. The rest
+ * are all "nothing happened", and they are kept APART rather than folded into one failure because they are read
+ * by somebody who just pressed a button and is owed the difference: `already_used` means come back next week,
+ * `not_limited` means the window reopened while they were reading, `ineligible` means this account never had
+ * it, and `unavailable`/`error` mean try again. Collapsing them would make every one of those read as a fault.
+ *
+ * Never throws over the wire: a claim that fails leaves the account exactly as it was, and the honest answer to
+ * a press is a word, not a stack trace. */
+export const LimitResetClaimSchema = z.object({
+    result: z
+        .enum(["reset", "already_used", "not_limited", "ineligible", "unavailable", "error"])
+        .describe("What the provider did. Only `reset` reopened the window; every other value means nothing changed."),
+    nextAvailableAt: z.number().optional().describe("When another reset may be claimed, in epoch seconds, where the provider published it."),
+    detail: z.string().optional().describe("What went wrong, in words, for the two outcomes that are this sandbox's fault rather than the plan's."),
+});
+export type LimitResetClaim = z.infer<typeof LimitResetClaimSchema>;
 /* THE LAST TIME A PROVIDER ACTUALLY REFUSED A TURN, the other half of "can I run on this", and the half no
  * meter can supply.
  *

package/src/schemas/provider-oauth.ts

@@ -64,68 +64,65 @@ export const AccountListQuerySchema = z.object({
 });
 // Address one account of a provider (disconnect, and the turn's `account`).
 export const AccountIdSchema = z.object({ id: z.string().min(1).describe("Which account.") });
-// Rename one account of a provider whose credential the sandbox owns (Claude, Kimi). Blank ⇒ the daemon falls
-// back to the derived name, so clearing a label restores the sign-in identity rather than leaving a nameless
-// row. Grok is absent for the same reason it holds one account: OpenCode owns that credential, not this store.
+// Rename one account of a provider whose credential the sandbox owns. Blank ⇒ the daemon falls back to the
+// derived name, so clearing a label restores the sign-in identity rather than leaving a nameless row.
 export const AccountRenameSchema = z.object({
     id: z.string().min(1).describe("Which account."),
     label: z.string().max(80).describe("The new name. Blank restores the one derived from the sign-in, rather than leaving a nameless row."),
 });
-// The completing calls carry the user-chosen label (blank ⇒ the daemon derives one from the sign-in identity
-// or a provider default).
-export const OauthExchangeSchema = z.object({
-    code: z.string().min(1).describe("The code the sign-in handed back."),
-    verifier: z.string().min(1).describe("The proof from the start of the handshake, which is what stops somebody else's code being redeemed here."),
-    state: z.string().min(1).describe("The handshake this belongs to. A mismatch is refused."),
-    label: z.string().optional().describe("What to call the account. Blank derives one from the sign-in."),
-});
-export const AuthorizeChallengeSchema = z.object({
-    authorizeUrl: z.string().describe("Where to send somebody to sign in."),
-    verifier: z.string().describe("Keep this and send it back when finishing. It is what proves the code that comes back belongs to this handshake."),
-    state: z.string().describe("The handshake's own id, sent back with it."),
-});
-/* CURSOR'S SIGN-IN START. A third login shape, and the reason it is not one of the two above is where the
- * SECRET lives during the handshake.
+/* ONE SIGN-IN SHAPE FOR EVERY ACCOUNT THE SANDBOX ITSELF HOLDS, whatever the vendor's mechanism underneath.
  *
- * Claude's is paste-back: the browser receives a code and the caller hands it plus its verifier to `exchange`,
- * so the handshake's proof has to travel on the wire and AuthorizeChallengeSchema carries it. Cursor's PKCE
- * verifier must never leave the process that generated it, anyone holding it can redeem the login and mint a
- * durable key, so the daemon starts the whole flow, keeps the verifier in memory, polls Cursor itself, and
- * writes the account when it lands. Nothing redeemable is on this shape at all.
- *
- * Which makes it behave like a DEVICE flow from the caller's side (open the page, then watch the account list),
- * except that there is no one-time code to display: the login page is addressed to this handshake already. So
- * DeviceStartSchema's `code` would be a permanently blank field on every card, and TranslatorStartSchema's
- * `state` a value nothing sends back. `handshake` is neither, it is a cancellation handle. */
-export const CursorLoginStartSchema = z.object({
-    url: z.string().describe("The page to open and sign in on. It is already addressed to this attempt, so there is no code to type."),
+ * Four handshakes used to answer four shapes, and the shapes differed in where the SECRET lived during the
+ * handshake. Anthropic's is paste-back: the browser shows a code and the user brings it here. Cursor's PKCE
+ * verifier must never leave the process that generated it (anyone holding it can redeem the login and mint a
+ * durable key), so the daemon runs the whole flow and the caller only watches the account list. xAI's is a
+ * device code. Meta's and Z.ai's mint the vendor's own key, by a device poll or by a redirect that dead-ends in
+ * the user's address bar. Every one of them is now the daemon's to hold: nothing redeemable is on this shape,
+ * and the one thing the caller can hand back (a code off a page, or the address a redirect landed on) goes to
+ * `complete` with the attempt's handshake. `flow` says how the attempt ENDS, which is the only thing a card
+ * cannot infer from the fields: a device sign-in finishes upstream and the account appears on its own; a
+ * redirect needs the landing address brought back; a paste needs the code the page showed. */
+export const LoginFlowSchema = z.enum(["device", "redirect", "paste"]);
+export type LoginFlow = z.infer<typeof LoginFlowSchema>;
+export const LoginStartSchema = z.object({
+    url: z.string().describe("The page to open and sign in on."),
+    code: z.string().describe("The one-time code the page will ask for, where the vendor issues one. Blank when the page is already addressed to this attempt."),
+    state: z
+        .string()
+        .describe("For a redirect sign-in, the marker in the address the browser lands on, so a pasted URL can be recognised as this attempt's. Blank otherwise."),
+    flow: LoginFlowSchema.describe(
+        "How this attempt ends. A device sign-in finishes by itself and you watch the account list; a redirect needs the address it landed on handed back; a paste needs the code the page showed.",
+    ),
+    variant: z.string().describe("Which of the provider's estates this attempt signs in to. Blank for a provider with one."),
     handshake: z
         .string()
-        .describe(
-            "This attempt's id, for abandoning it. Not a credential and not redeemable: the proof that finishes the sign-in never leaves the sandbox.",
-        ),
+        .describe("This attempt's id, for finishing or abandoning it. Not a credential and not redeemable: the proof that completes the sign-in never leaves the sandbox."),
     expiresAt: z.number().describe("When this attempt stops being answerable, in milliseconds, so a card can stop waiting instead of spinning."),
 });
-export type CursorLoginStart = z.infer<typeof CursorLoginStartSchema>;
-// Abandon a sign-in nobody completed, so the daemon stops polling Cursor for it. Ordinary tidiness rather than
-// a security boundary: an unanswered attempt also times out on its own (see `expiresAt`).
-export const CursorLoginCancelSchema = z.object({ handshake: z.string().min(1).describe("Which attempt to stop waiting on.") });
-// xAI Grok (via OpenCode) uses subscription OAuth via the headless device-code method. `start` returns the
-// `url` the user opens (xAI's verification_uri_complete, which pre-fills the code) and `code`, the same
-// one-time code, surfaced so the card matches x.ai exactly. There is no paste-back: OpenCode polls to
-// completion and the UI polls `/grok/accounts`.
-// ponytail: OpenCode holds one xAI auth per data dir, so Grok stays single-account, the list is 0 or 1. Per
-// account would need an OpenCode server per data dir; add when there's demand.
-// A device-code login start: the verification URL + the one-time code the user enters there. The native Grok
-// flow (via OpenCode), see TranslatorStartSchema for the routed-provider connect, which adds `state`.
-export const DeviceStartSchema = z.object({
-    url: z.string().describe("The page to open, which already has the code in it."),
-    code: z
-        .string()
-        .describe(
-            "The one-time code, shown as well so the page and the card say the same thing. Nothing is pasted back: the sandbox waits for the sign-in to complete on its own.",
-        ),
+export type LoginStart = z.infer<typeof LoginStartSchema>;
+// The estate to sign in to, where a provider has more than one (Z.ai's international and mainland plans). Absent
+// takes the provider's default, which is what a provider with a single estate always sends.
+export const LoginRequestSchema = z.object({
+    variant: z.string().min(1).optional().describe("Which estate to sign in to. Absent takes the provider's default."),
+});
+/* The half a person brings back, for the two flows that have one: the code the page showed (a paste), or the
+ * whole address a redirect landed on. Not the handshake's state, unlike the translator's version below: that
+ * one addresses a session CLIProxyAPI holds, so the state has to travel, while this handshake is held right
+ * here and taking the caller's word for its own state would be checking a claim against itself. */
+export const LoginCompleteSchema = z.object({
+    handshake: z.string().min(1).describe("Which attempt this belongs to."),
+    code: z.string().optional().describe("The code the sign-in page showed, for a paste sign-in."),
+    redirectUrl: z.string().optional().describe("The address the browser was sent to, whole, for a redirect sign-in. The grant is inside it."),
+    label: z.string().optional().describe("What to call the account. Blank derives one from the sign-in."),
+});
+// What finishing hands back: the account, where the exchange answers with one at once (a paste); absent where
+// the daemon still has a mint to do behind the answer and the row lands in the account list minutes later.
+export const LoginCompletedSchema = z.object({
+    account: OauthAccountSchema.optional().describe("The account it connected, where the sign-in ends here. Absent means keep watching the account list."),
 });
+// Abandon a sign-in nobody completed, so the daemon stops polling the vendor for it. Ordinary tidiness rather
+// than a security boundary: an unanswered attempt also times out on its own (see `expiresAt`).
+export const LoginCancelSchema = z.object({ handshake: z.string().min(1).describe("Which attempt to stop waiting on.") });
 // A routed-provider subscription login start (codex/grok/kimi/gemini via CLIProxyAPI). Device flows poll to
 // completion after the user approves upstream; redirect flows need the browser's landing URL pasted back. The
 // explicit flow discriminator matters even when a provider's verification URL already embeds its optional code.

package/src/schemas/settings.ts

@@ -1,7 +1,8 @@
 // settings: per-sandbox agent settings (.intentic/config/settings.json)
 import { z } from "zod";
 import { CommandJudgeModeSchema } from "../safety-policy.js";
-import { AdmissionPolicySchema, AdmissionRuleSchema, AgentRunPinSchema } from "./agent.js";
+import { ModelRoleSchema } from "../model-roles.js";
+import { AdmissionPolicySchema, AdmissionRuleSchema, ModelPinSchema } from "./agent.js";
 // Which prompt the agent is, before this turn composes anything on top. Two built-in bases and an escape
 // hatch: Intentic's own (the default), Claude Code's preset, or the owner's text. Declared out here rather
 // than inline in the settings object because both sides of the wire branch on it, the daemon to build the
@@ -251,8 +252,6 @@ export const SkillRemoveSchema = z.object({
 //                        tool is one daemon-side registry entry, not a new settings field.
 //   hashlineEdits    , swaps the native Read/Edit/Write for hash-anchored edits on the Claude path (stale-file
 //                        guard + fewer output tokens); off ⇒ the native file tools.
-//   terseOutput      , appends a concise-response steer to the end of the system prompt (a stable suffix, so it
-//                        composes with stableSystemPrompt) to cut the model's OWN output tokens.
 //   systemPromptMode , which base the agent's prompt is: "intentic" (default), "claude", or "custom".
 //   systemPrompt     , the owner's own prompt text, used only by "custom" mode, where it is the ENTIRE system
 //                        prompt and nothing the daemon would otherwise append rides with it, see its own note.
@@ -264,6 +263,8 @@ export const SkillRemoveSchema = z.object({
 //   workspaceMap     , computes an AREA index of the project a run starts in and prepends it to the
 //                        conversation's opening message, so the turn does not have to buy its own orientation
 //                        with a directory listing. Generated from the filesystem every time, never stored.
+//   workspaceMapHoldout, conversation-level measurement control for workspaceMap (UsageTurn.mapArm), judged on
+//                        the directory listings the opening turn ran rather than on its searches.
 //   sidecars         , the background pass converging a markdown shadow of every binary workspace file
 //                        (docx/pdf/images/audio → .intentic/local/cache/derived/) the moment it lands, via
 //                        the baked fileq CLI, so reasoning-time reads are pre-derived. The CLI itself is
@@ -306,28 +307,24 @@ export const SandboxSettingsSchema = z.object({
             "Keep the instructions identical between turns so the provider can cache them, moving anything that varies into the message instead. Cheaper, at the cost of some flexibility.",
         ),
     skills: z.array(z.string()).default(["lsp", "fileq"]).describe("Which skills are switched on."),
+    /* WHICH CONTEXT SHELF A CONVERSATION OPENS ON when nothing closer to it says (schemas/context.ts). A persona
+     * card's own `context` wins where a turn wears one; this is the sandbox's answer for the turns that do not.
+     * Empty means no shelf, so a conversation carries every repository the workspace has, which is what every
+     * conversation did before shelves existed. Empty rather than optional because a settings object is parsed
+     * from `{}` until the owner first changes something, and every field here has to answer to that. */
+    contextShelf: z
+        .string()
+        .max(60)
+        .default("")
+        .describe(
+            "Which context shelf a conversation opens on when its persona names none: the part of the workspace it carries. Empty means every repository, as before shelves existed.",
+        ),
     hashlineEdits: z
         .boolean()
         .default(false)
         .describe(
             "Have the agent edit files by line number rather than by quoting the text it wants replaced. Cheaper on large files, and less forgiving of a stale read.",
         ),
-    terseOutput: z.boolean().default(false).describe("Ask the agent to say less. It changes how much it narrates, not how much it does."),
-    /* Measurement control for the terse steer, at TURN level, the same trick `outputHoldout` plays over
-     * commands, one layer up. A fraction [0,1] of otherwise-eligible turns run WITHOUT the steer and record
-     * which arm they ran on (UsageTurn.terse), so the savings report can compare two real populations.
-     *
-     * It has to be an experiment: unlike a cleaned command, which yields its own raw baseline in the same
-     * event, a turn cannot be re-run to see what it would have said unsteered. 0 ⇒ no measurement (every
-     * eligible turn is steered), which is the default because the control costs the very tokens it measures. */
-    terseHoldout: z
-        .number()
-        .min(0)
-        .max(1)
-        .default(0)
-        .describe(
-            "What share of turns to run without that instruction, so the two can be compared honestly. It has to be measured this way, because a turn cannot be re-run to see what it would have said. Zero means no measurement, which is the default, since the comparison costs the very tokens it is measuring.",
-        ),
     /* WHICH SYSTEM PROMPT THE AGENT RUNS ON, the base, before anything this turn composes.
      *
      *   intentic. Intentic's own prompt, tuned for this harness (intentic-prompt.ts). The default.
@@ -337,15 +334,14 @@ export const SandboxSettingsSchema = z.object({
      *
      * The first two are peers: both get the harness's own guidance appended (the AskUserQuestion/plan blocks
      * the chat's cards need, the checklist guidance behind the todo panel, the browser-tool guidance), plus the
-     * delegation note and the terse steer. `custom` is the one that does not, by the owner's explicit choice,
-     * see the field below. */
+     * delegation note. `custom` is the one that does not, by the owner's explicit choice, see the field below. */
     systemPromptMode: SystemPromptModeSchema.default("intentic").describe(
         "Which instructions the agent starts from: intentic's own, the ones the installed Claude Code carries, or your own. The first two both get this product's own guidance added on top; your own gets nothing added, which is the point of it.",
     ),
     /* The owner's own prompt, used only when `systemPromptMode` is "custom". Then it is the ENTIRE system
-     * prompt: both built-in bases are gone and so is everything the daemon would otherwise append, the widget
-     * guidance the chat's cards are driven by, and the terse-output steer (whose toggle goes inert). That is
-     * the price of total control, and the UI states it at the moment of the edit rather than letting the
+     * prompt: both built-in bases are gone and so is everything the daemon would otherwise append, including
+     * the widget guidance the chat's cards are driven by. That is the price of total control, and the UI states
+     * it at the moment of the edit rather than letting the
      * widgets go quietly dark. Only the cross-provider delegation note survives, because it has a home outside
      * the system prompt already (the user-message preamble stableSystemPrompt puts it in).
      *
@@ -395,6 +391,21 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Open every conversation with a map of the project it starts in: what is in it, what each part is for, and where the agent is standing. Worked out fresh each time rather than written down anywhere, because a written layout is wrong within a fortnight. Off by default, since it spends tokens on the first message of every conversation.",
         ),
+    /* Measurement control for the map, at CONVERSATION level for the plainest of reasons: the note is sent on
+     * the opening message, so every later turn of a mapped conversation has a map in its transcript and a
+     * per-turn flip would call eleven treated turns controls.
+     *
+     * Judged on `UsageTurn.openingListings` and read on each conversation's opening turn (usage/turn-experiments.ts),
+     * because that is the turn the note was sent to and averaging it across a long conversation divides the
+     * effect by the conversation's length. 0 ⇒ no measurement and every conversation receives the map. */
+    workspaceMapHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0)
+        .describe(
+            "What share of conversations to open without the map, so the two can be compared. Whole conversations rather than individual turns, because the map is sent once and stays in the conversation's history afterwards.",
+        ),
     /* THE MARKDOWN SHADOWS OF BINARY FILES, the eager half of fileq (_sandbox/fileq). The lazy half — the
      * `fileq` CLI an agent runs mid-task — is always on PATH and gated only by its skill; this switch is
      * about the BACKGROUND pass: the daemon watching /work and converging a sidecar under
@@ -448,26 +459,39 @@ export const SandboxSettingsSchema = z.object({
         .max(1)
         .default(0)
         .describe("What share of commands to leave untrimmed, so the saving can be measured against a real comparison rather than estimated."),
-    /* The models behind the small automatic jobs that are not a conversation, today the commit message
-     * written when an agent's work lands. An ORDERED list of `${provider}:${modelId}`, tried top to bottom, or
-     * EMPTY for Auto.
-     *
-     * A LIST rather than a pick, because the single interesting failure of this feature is a model that is
-     * connected and simply will not answer today: the account's allowance went on the chat, and one spent
-     * provider then takes the job down for hours while the others sit idle. Written in order, the daemon steps
-     * over the spent one and the message still gets written (agent/quick-model.ts walks it).
-     *
-     * Empty is the default and still the interesting case: Auto is resolved from whatever accounts are
-     * connected at the moment it is read (resolveQuickModels), so it can never name a provider this sandbox has
-     * no credential for, it improves by itself when one is added, and it is a ladder too, the cheapest rung of
-     * every connected provider, best first. Storing resolved ids here instead would go stale exactly like a
-     * pinned model does. */
-    quickModel: z
-        .array(z.string())
-        .max(10)
-        .default([])
+    /* WHICH MODEL DOES WHICH JOB, one ordered list per ROLE (model-roles.ts declares them all).
+     *
+     * ONE KEY RATHER THAN SEVENTEEN, and the record is keyed by the role catalog rather than by free strings: a
+     * job that starts choosing a model tomorrow becomes configurable by adding a row to that table, and the
+     * settings page, the resolver and the daemon's lookup all follow without a schema change. Seventeen named
+     * fields here would be the same table written a fourth time, in the one place where getting it out of step
+     * spends somebody's money.
+     *
+     * IT REPLACED THREE BUNDLED KEYS — `quickModel`, `agentRunModels` and `commandJudgeModels` — and the reason
+     * is worth keeping: the first two were grouped by assumed INTENSITY, not by job. "Quick" covered commit
+     * messages, session titles and loop verdicts at once, so an owner who wanted better commit subjects could
+     * not ask for them without also moving every session title onto the same model; "agent runs" covered a
+     * production incident and a documentation sweep with one tier. An intensity is a guess about work its owner
+     * knows better, and neither the configuration nor the UI was actually saving anyone anything by making it.
+     *
+     * EACH LIST IS AN ORDERED LADDER of pins, tried top to bottom, because the interesting failure is a model
+     * that is connected and will not answer today: the account's allowance went on the chat, and one spent
+     * provider takes that job down for hours while the others sit idle.
+     *
+     * AN ABSENT OR EMPTY LIST IS THE INTERESTING CASE and means the role's declared floor (resolveRoleModels): a
+     * one-shot helper derives an Auto ladder from whatever is connected right now — so it can never name a
+     * provider this sandbox has no credential for, and it improves by itself as accounts are added — while a
+     * whole session falls to the model the owner picked for their own chat, because nothing here can judge what
+     * a session is worth and a wrong guess is billed whole. Storing resolved ids instead would go stale exactly
+     * as a pinned model does. */
+    // `partialRecord`, not `record`: an exhaustive one would make every role a required key, so a settings file
+    // that has never been touched would have to spell out seventeen empty arrays to be valid, and adding a role
+    // would invalidate every settings file in existence. An absent key IS the answer "this role has no list".
+    modelRoles: z
+        .partialRecord(ModelRoleSchema, z.array(ModelPinSchema).max(10))
+        .default({})
         .describe(
-            "Which models do the small automatic jobs that are not a conversation, such as writing a commit message. A list rather than one pick, tried in order, because the interesting failure is a model that is connected and simply will not answer today. Empty means work it out from whatever is connected, which improves by itself as accounts are added.",
+            "Which models do which job, one ordered list per job: commit messages, session titles, the safety judge, pipeline fixes, and every other place this sandbox picks a model for you. Tried in order, so one spent account does not take a job down. A job with no list falls back to its own default: cheapest connected for the one-shot helpers, your own chat model for whole sessions.",
         ),
     /* WHICH REPOS KEEP A CHANGELOG, the repos whose commits carry a `Release-Note:` trailer, written by the
      * same quick model that drafts the subject (git/commit-message.ts) and harvested at release time.
@@ -489,40 +513,6 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Which repositories keep a changelog, and so get a user-facing note written alongside each merge. A list rather than a switch, and empty by default, because the commit writer's standing rule is to copy the house style rather than impose one, and a repository that has never written such a note gives it nothing to copy.",
         ),
-    /* WHAT AN AGENT RUN OPENS ON, the tier above quickModel, and the answer for every turn a SURFACE starts
-     * rather than a person at a composer: Fix with agent on a pipeline or a deployment, a Maintenance chore, a
-     * Documentation or Acceptance run, the fix a failed pre-push check proposes. An ORDERED list of PINS, each
-     * naming a provider and model AND how that one is to be run (AgentRunPinSchema); EMPTY ⇒ whatever the chat
-     * composer would have started with, which is the honest floor because it is the model the user already
-     * chose to work with.
-     *
-     * EACH ENTRY CARRIES ITS OWN REASONING AND COST KNOBS, which is why these are objects rather than the
-     * `${provider}:${model}` keys the two lists around them still hold. The effort used to be one field beside
-     * the list, answering for every model in it, and the entries of this list are the least interchangeable
-     * things on the page: the head is the tier the owner wants the work done at and what follows it is the
-     * account that catches it when the first is spent. AgentRunPinSchema has the rest of the argument.
-     *
-     * A LIST, for the reason quickModel is one: the account at the head runs out, and every surface-started run
-     * in the sandbox then fails on a credential the user cannot see from the row they pressed. Written in order,
-     * the next one down catches it (turn-resume.ts walks it).
-     *
-     * PINNED, NOT DERIVED, the deliberate difference from quickModel one line above, and the reason these are
-     * two settings rather than one. A quick helper exists to stay OFF the frontier tier, so cheapest-connected
-     * is the right automatic answer and an empty list resolves to Auto. An agent run has to read a failing
-     * suite, or a container log, or a story, and repair the thing: the tier is a judgement about how much the
-     * job is worth, nothing here can make it, and a wrong guess is billed in whole sessions rather than in
-     * tokens. So an empty list here resolves to NOTHING and the composer's own pick answers instead.
-     *
-     * The daemon applies this to any turn flagged `unattended` that names no model of its own, one rule, so a
-     * surface added tomorrow inherits it by saying what it is instead of re-deriving where models come from. A
-     * surface MAY still name one (the shared run button's caret, Acceptance's per-run pick), and that wins. */
-    agentRunModels: z
-        .array(AgentRunPinSchema)
-        .max(10)
-        .default([])
-        .describe(
-            "Which models run the work a screen starts rather than a person: fixing a red pipeline, a maintenance chore, an acceptance run. Tried in order, so one spent account does not take every such run down, and each entry says how hard that model should think as well as which one it is. Empty falls back to whatever the chat would have used, which is the honest floor because it is the model you already chose to work with.",
-        ),
     /* AUTOMATIC TIER SELECTION: may the daemon run an easy-looking turn on a cheaper rung of the provider the
      * user is already on, instead of on the model they picked?
      *
@@ -565,9 +555,9 @@ export const SandboxSettingsSchema = z.object({
             "How readily a turn counts as simple enough for the cheaper model. It moves only the cutoff: at every setting a turn still has to say something positively easy, so nothing here can downgrade a short vague request.",
         ),
     /* WHICH CHEAP MODEL A DOWNGRADED TURN LANDS ON, an ordered list of `${provider}:${model}` keys
-     * (quickModelKey), or EMPTY for Auto.
+     * (modelPinKey), or EMPTY for Auto.
      *
-     * Empty is the default and the interesting case, exactly as quickModel's is: Auto is the cheapest row the
+     * Empty is the default and the interesting case, exactly as a one-shot role's is: Auto is the cheapest row the
      * turn's own provider publishes, read through the same cheap-end order (compareCheapestFirst), so the two
      * features can never disagree about which rung is the cheap one, and connecting an account tomorrow
      * improves the answer by itself.
@@ -731,35 +721,13 @@ export const SandboxSettingsSchema = z.object({
      * entitled to say so, and before this they could not: the old rulebook could be set to allow everything, and
      * the redesign quietly made itself the one part of the sandbox you could only opt further into.
      *
-     * Judged commands are also the one automatic job whose model choice genuinely differs from the rest of
-     * `quickModel`'s work, which is why the list below exists rather than a line in the comment above it: a
-     * commit message written by a model that misread the diff is a sentence somebody edits, and a verdict
-     * written by a model that misread a command is a card that should not have been raised or, worse, one that
-     * should have been. */
+     * WHICH MODEL judges is not answered here: it is the `safety-judge` role in `modelRoles`, like every other
+     * job in this sandbox that picks one. It used to need its own key, on the argument that a verdict is worth a
+     * different model than a commit message — true, and the fact that it had to be argued for one job at a time
+     * is exactly what the role catalog replaced. */
     commandJudge: CommandJudgeModeSchema.default("on").describe(
         "Whether a model reads your safety policy before a flagged command runs. Off judges nothing and asks about nothing; Watch judges everything and records it without ever interrupting you, which is how you find out what your policy actually does before you let it stop anything; On lets the verdict decide. Wiping a disk or deleting under /history asks at every setting — that rule is typed rather than judged, and cannot be turned off.",
     ),
-    /* WHICH MODEL READS THE POLICY, an ordered list of `${provider}:${modelId}` keys (quickModelKey) walked top
-     * to bottom, or EMPTY for whatever the quick model would be.
-     *
-     * A LIST, for the reason every other model setting here is one: the head runs out and the whole feature goes
-     * with it. Falling back to the quick chain rather than to Auto is deliberate — it is what this did before the
-     * setting existed, so an owner who never opens the row keeps exactly the behaviour they had, and one who
-     * writes an entry is saying that command verdicts are worth a different model than commit messages.
-     *
-     * THE ARGUMENT FOR SETTING IT AT ALL, since the cheapest connected rung is the default: this prompt is the
-     * one quick job that is genuinely adversarial. Its input includes text the agent is about to run, which may
-     * have arrived from a stranger's web page, and a small model can be talked round by it (command-judge.ts is
-     * candid about that). It is also the job where being WRONG is expensive in both directions — a needless card
-     * teaches the owner to click through the next one. Neither is a reason for us to spend somebody's frontier
-     * allowance by default; both are reasons for them to be able to. */
-    commandJudgeModels: z
-        .array(z.string())
-        .max(10)
-        .default([])
-        .describe(
-            "Which models decide whether a flagged command should run, tried in order so one spent account does not take the gate down. Empty uses whatever the quick model is, which is what this did before the setting existed.",
-        ),
     /* HOW MUCH AN AGENT MAY DELEGATE, the three ceilings the Claude Code harness enforces on its own Agent
      * tool, surfaced here because their defaults are tuned for a laptop and this is a container the owner sized.
      *
@@ -777,7 +745,7 @@ export const SandboxSettingsSchema = z.object({
      * The refusal an agent sees names the env var (`ask them to raise CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`),
      * which is why these three exist as settings at all: without them the only answer to that ask is editing
      * the container's environment and restarting the daemon. */
-    subagentsAtOnce: z.number().min(1).max(200).default(20).describe("How many helper agents may work at the same time."),
+    subagentsAtOnce: z.number().min(1).max(200).default(20).describe("How many subagents may work at the same time."),
     subagentsPerTurn: z.number().min(1).max(2000).default(200).describe("How many a single turn may start in total."),
     // Depth 1 = an agent may delegate, but its children may not. The CLI's own default is 3, and it is the one
     // of the three whose runaway case is unbounded rather than merely wide, each level multiplies the last.
@@ -786,7 +754,7 @@ export const SandboxSettingsSchema = z.object({
         .min(1)
         .max(10)
         .default(3)
-        .describe("How many levels deep the delegation may go, since a helper can start helpers of its own."),
+        .describe("How many levels deep the delegation may go, since a subagent can start subagents of its own."),
 });
 export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
 // One of the two built-in bases, as text: Intentic's own prompt, or Claude Code's preset read out of the CLI
@@ -800,19 +768,9 @@ export const BuiltinPromptTextSchema = z.object({ text: z.string(), version: z.s
 export type BuiltinPromptText = z.infer<typeof BuiltinPromptTextSchema>;
 /* ---- savings report: what each token-reduction mechanism actually saved ----
  *
- * TWO FAMILIES, deliberately never one list of bars. They are measured differently, and a chart that ranks
- * them side by side claims a confidence and a denominator that only one of them has:
- *
- *   input , shell output the cleaners trimmed before the model ever saw it. Both sides of the comparison come
- *            off the SAME command (raw in, emitted out), so the counterfactual is observed rather than
- *            estimated: exact, per command, no sample size to argue about.
- *   output, the model's own tokens under the terse steer. There is no second run of the same turn to compare
- *            against, so the only honest number is an experiment: a turn-level holdout, an n per arm, and a
- *            margin. It is absent entirely until both arms are large enough for the delta to mean anything.
- *
- * The two are also in different units of value, a saved tool-output token is saved again on every later
- * request of that conversation, an output token is saved once but costs several times as much, which is the
- * other reason they are separate sections with separate totals rather than one number.
+ * Input-side savings: shell output the cleaners trimmed before the model ever saw it. Both sides of the
+ * comparison come off the SAME command (raw in, emitted out), so the counterfactual is observed rather than
+ * estimated: exact, per command, no sample size to argue about.
  */
 
 // One mechanism's realized saving, biggest first. `savedTokens` is what THIS stage removed from what reached
@@ -851,15 +809,17 @@ export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() }
  * stand behind. An experiment can carry several, see TurnExperimentSchema.
  *
  * `metric` says what `mean` counts and what `deltaPct` is a delta in, and choosing it is most of the work.
- *   proseChars     , the terse steer: the thing it steers, and the only part of the model's output that
- *                     responds to being asked to be brief (UsageTurn.proseChars has why output tokens cannot).
  *   searchCalls    , the search teaching: the searches a turn ran, which the teaching directly changes.
  *   openingSearches, the same, narrower: the searches before the turn first touched a file.
- * Search mechanisms must not be judged on COST. Cost is a whole turn's work, a search mechanism moves one part
- * of it, and the part sits inside the noise of the rest exactly as the steer's effect once sat inside its
- * tool-call arguments. */
+ *   openingListings   , the project map: the directory listings a turn ran to work out where it was, which is
+ *                      what the map hands over and what its note tells the turn not to go and fetch.
+ *   callsBeforeTarget, the map again, on value rather than compliance: how far the turn walked before
+ *                      touching a file it went on to edit.
+ * Neither mechanism may be judged on COST. Cost is a whole turn's work, both of these move one part of it, and
+ * the part sits inside the noise of the rest. The map's whole payload is about 200 tokens, so a cost reading
+ * would be measuring a quantity two orders of magnitude under its own error bar. */
 export const TurnMetricReadingSchema = z.object({
-    metric: z.enum(["proseChars", "searchCalls", "openingSearches"]),
+    metric: z.enum(["searchCalls", "openingSearches", "openingListings", "callsBeforeTarget"]),
     on: SavingsArmSchema,
     off: SavingsArmSchema,
     /* HOW MUCH LONGER, when the margin spans zero and the honest answer is "keep collecting": the additional
@@ -886,23 +846,20 @@ export const TurnMetricReadingSchema = z.object({
     /* THE CLAIM, present only once there is one. Both together, and only when the margin does NOT span zero.
      *
      * A schema that can't express a half-measured experiment is how a 34%-that-becomes-8%-tomorrow never
-     * reaches the screen, and clearing `minTurns` turned out not to be enough to buy that. The terse steer
-     * crossed its thirtieth control turn and immediately reported +31.2% ± 35.1pp: a confidence interval
+     * reaches the screen, and clearing `minTurns` turned out not to be enough to buy that. An early search
+     * teaching run crossed its thirtieth control turn and immediately reported +31.2% ± 35.1pp: a confidence interval
      * running from −3.4% to +66.7%, which is to say no effect was measured at all, rendered as an alarming
      * number pointing the wrong way. Thirty turns is where the normal approximation starts to hold, not where
      * this much per-turn spread resolves an effect; requiring the interval to exclude zero is the same
      * withhold-until-it-means-something rule applied to the thing that actually decides whether it does.
      *   deltaPct, change in the metric's mean per turn under the mechanism; negative is a saving.
      *   saved   , what the delta is worth over the turns that actually ran with it, in this window, in the
-     *              metric's own unit (characters, or searches). */
+     *              metric's own unit (searches). */
     deltaPct: z.number().optional(),
     saved: z.number().optional(),
 });
 export type TurnMetricReading = z.infer<typeof TurnMetricReadingSchema>;
-/* A turn-level A/B, the one shape both of this sandbox's turn experiments report in, because they differ in
- * nothing but which flag flips and what the turns are judged on. Only turns the mechanism was ELIGIBLE for are
- * counted: a turn under a custom system prompt drops the terse steer along with everything else the daemon
- * appends, so it belongs to neither arm.
+/* A turn-level A/B, the shape the iq search teaching experiment reports in.
  *
  * ONE COIN FLIP, SEVERAL READINGS. `metrics` is a list because the search teaching is judged on two, the
  * searches a turn ran, and the ones it ran before touching a file, and they are two readings of the SAME
@@ -919,17 +876,22 @@ export const TurnExperimentSchema = z.object({
     // counts toward the daemon's real threshold instead of a number the browser guessed. Shared by every
     // reading: they are the same turns counted differently, so they clear it together.
     minTurns: z.number(),
-    // The randomized unit behind the arm counts. Turn mechanisms default to turns; teaching loaded into a
-    // provider session randomizes and analyzes whole conversations so repeated turns are not false replicas.
-    sampleUnit: z.enum(["turns", "conversations"]).optional(),
+    /* The randomized unit behind the arm counts. Turn mechanisms default to turns. Teaching loaded into a
+     * provider session randomizes and analyzes whole conversations, so repeated turns are not false replicas.
+     *
+     * "opening turns" is the third case and belongs to a treatment sent ONCE: the project map rides the first
+     * message and nothing after it, so the sample is one turn per conversation rather than an average over
+     * the conversation's turns. The distinction is not cosmetic. Averaging a first-turn treatment across a
+     * twelve-turn conversation divides its effect by twelve and reports the remainder as noise. */
+    sampleUnit: z.enum(["turns", "conversations", "opening turns"]).optional(),
     // Content-addressed treatment version. Present where mixing rows from two instruction revisions would turn
     // one experiment into two unnamed ones; the reader filters to this (latest) cohort.
     cohort: z.string().optional(),
 });
 export type TurnExperiment = z.infer<typeof TurnExperimentSchema>;
-// `output`/`search` are absent when that experiment isn't running at all (its flag off, or no holdout set), a
-// section that isn't there reads as "not measured", which is the truth, while zeros would read as "measured,
-// worth nothing".
+// `search` is absent when that experiment isn't running at all (its flag off, or no holdout set), a section
+// that isn't there reads as "not measured", which is the truth, while zeros would read as "measured, worth
+// nothing".
 /* WHAT THE COMPLEXITY JUDGE HAS BEEN SAYING, read back off the spend ledger's tier fields (UsageTurn.tierScore
  * and friends) over the requested window. The three numbers docs/model-routing-design.md §4 says the feature
  * cannot be defended without, plus the veto count, and nothing else: no counterfactual "you would have saved
@@ -964,8 +926,11 @@ export const TierReportSchema = z.object({
 export type TierReport = z.infer<typeof TierReportSchema>;
 export const SavingsReportSchema = z.object({
     input: InputSavingsSchema,
-    output: TurnExperimentSchema.optional(),
     search: TurnExperimentSchema.optional(),
+    /* The project map's arms, read on opening turns (see TurnExperimentSchema.sampleUnit). Absent under the
+     * same rule as `search`: the switch is off, or no holdout is set, and a section that is not there reads as
+     * "not measured", which is the truth, where zeros would read as "measured, worth nothing". */
+    map: TurnExperimentSchema.optional(),
     // Automatic tier selection's readout, see TierReportSchema. Absent ⇒ nothing was judged in the window.
     tier: TierReportSchema.optional(),
 });