@intentic/sandbox-contract 1.166.0 → 1.168.0

package/src/schemas.ts

@@ -50,8 +50,8 @@ export const EditorContextSchema = z.object({
 });
 export type EditorContext = z.infer<typeof EditorContextSchema>;
 
-// The client-minted stable conversation identity. Constrained because it lands in branch names (agent/<id>)
-// and filesystem paths — the regex is the injection guard. Shared by the turn input and the attach input.
+// The client-minted stable conversation identity. Constrained because isolated conversations also use it in
+// branch names (agent/<id>) and filesystem paths — the regex is the injection guard. Shared by turn + attach.
 const ConversationIdSchema = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/);
 
 // Where a conversation came from when nobody typed it into the browser: an automation wake carrying a message
@@ -102,7 +102,7 @@ export const AgentTurnSchema = z
         account: z.string().optional(),
         sessionId: z.string().optional(),
         // The client-minted stable conversation identity (survives provider/account/harness switches, which
-        // retire sessions). Keys the fleet registry entry, the conversation's worktree, and the turn run.
+        // retire sessions). Keys the fleet registry entry and turn run, plus the worktree when isolated.
         conversationId: ConversationIdSchema.optional(),
         // When true, the turn runs in the conversation's isolated git worktree (created lazily on first use)
         // instead of the shared /work tree — the parallel-agents mode. Requires conversationId.
@@ -157,10 +157,10 @@ export const AttachTurnSchema = z.object({
 });
 export type AttachTurn = z.infer<typeof AttachTurnSchema>;
 
-// ---- agents: the parallel-conversation fleet ----
-// A "fleet agent" is a conversation with a registry entry — every isolated conversation, keyed by its
-// conversationId. Isolated ones own a git worktree (branch agent/<id> in every workspace repo); the fleet
-// surface shows all of them with live status/activity/cost so the user can drive N agents in parallel.
+// ---- agents: the conversation fleet ----
+// A "fleet agent" is any conversation with a registry entry, keyed by its conversationId. Isolated ones own a
+// git worktree (branch agent/<id> in every workspace repo); workspace conversations have no branch. The fleet
+// surface shows both through the same status/activity/cost lifecycle.
 
 // idle/running/awaiting are the turn lifecycle (awaiting = paused on a plan approval or question); ready /
 // landed / conflict are outcomes of the land flow — `ready` is a clean completion whose delta stayed on the
@@ -173,7 +173,31 @@ export type AttachTurn = z.infer<typeof AttachTurnSchema>;
 // unlabelled: without it such a turn rehydrates as `idle`, which is the resting status of a turn that finished
 // CLEANLY, so the board files a killed agent under Finished and the question it was holding disappears with the
 // process that asked it. See agents-store.ts — this is the status a live turn leaves on disk.
-export const AgentStatusSchema = z.enum(["idle", "running", "awaiting", "ready", "landed", "conflict", "error", "interrupted"]);
+//
+/* `stopping` and `stopped` are the two halves of a user's Stop, and they exist because a hard-cancel is NOT
+ * instant: /agent/stop aborts the provider and then waits for the turn's generator to unwind (worktree and
+ * registry cleanup), which is seconds of real time. For that whole window the runtime half still said
+ * `running`, so every surface kept its spinner turning on a turn the user had already killed — and then the
+ * card jumped to a settled state out of nowhere. `stopping` is what the daemon knows the instant the abort
+ * lands, published immediately so the press has a visible result; `stopped` is where the turn comes to rest.
+ *
+ * `stopped` is deliberately its own value rather than `interrupted` or `error`. Not `error`, which is what a
+ * stopped turn used to report (every provider adapter surfaces the abort's unwind as an error frame) — a card
+ * accusing the user's own deliberate press of being a failure. Not `interrupted` either: that one means the
+ * daemon died under the turn, and a boot pass may re-run it, which is precisely what must never happen to a
+ * turn a person chose to end. */
+export const AgentStatusSchema = z.enum([
+    "idle",
+    "running",
+    "awaiting",
+    "stopping",
+    "stopped",
+    "ready",
+    "landed",
+    "conflict",
+    "error",
+    "interrupted",
+]);
 export type AgentStatus = z.infer<typeof AgentStatusSchema>;
 // The card's live activity snippet: the last tool the agent used (with its target) and the in-progress todo.
 export const AgentActivitySchema = z.object({
@@ -238,6 +262,14 @@ export const AgentSummarySchema = z.object({
     // Completed turns and lifetime tool calls — the card's msgs/tools counters.
     turns: z.number().optional(),
     toolUses: z.number().optional(),
+    /* The agents THIS agent started (SubagentSessionSchema), live and lifetime. Absent ⇒ it has never delegated,
+     * which is most agents — so the card's chip appears on content rather than reading "0" down the board.
+     *
+     * It earns a place on a card because a fleet card is the answer to "what is this agent up to", and an agent
+     * running five children looked exactly like an agent running none: the work was real, the spend was real, and
+     * the board said nothing. The tokens are NOT folded into the parent's cost — a child's spend is its own, and
+     * the Subagents area is where it is attributed. */
+    subagents: z.object({ running: z.number(), total: z.number() }).optional(),
     // The agent's cumulative output (base → branch tip across every repo), refreshed on each land —
     // the card's "12 files · +412 −96" readout. Independent of what has landed.
     diff: z.object({ files: z.number(), insertions: z.number(), deletions: z.number() }).optional(),
@@ -355,14 +387,56 @@ export const AgentLandSchema = z.object({ id: z.string().min(1), mode: LandModeS
 // The providers whose model can run UNDER the Claude Code harness through the bundled translator (CLIProxyAPI),
 // which holds their SUBSCRIPTION OAuth and re-serves it behind an Anthropic endpoint. The `claude` provider is
 // absent — native Anthropic OAuth serves it directly, without the translator. Codex and Grok also have a native
-// runtime and so carry the harness axis; `gemini` is routed-only (Google publishes no Anthropic-protocol
-// endpoint and this sandbox bakes no Gemini runtime), so a Gemini turn is always a Claude Code turn.
-export const KeyedProviderSchema = z.enum(["codex", "grok", "gemini"]);
+// runtime and so carry the harness axis; Kimi and Gemini are routed-only, so their turns always use Claude Code.
+export const KeyedProviderSchema = z.enum(["codex", "grok", "kimi", "gemini"]);
 export type KeyedProvider = z.infer<typeof KeyedProviderSchema>;
 
+// ---- plan-limit usage ----
+// Declared ABOVE both account shapes because both carry it: headroom is one idea in this product, not a Claude
+// idea that other providers imitate. A native account (OauthAccount) and a routed subscription
+// (TranslatorAccount) differ in who holds the credential and how the reading is taken — never in what a
+// reading IS — so every surface that draws a percentage reads this one type and no other.
+
+// One plan-limit pool. `kind` is the provider's own key ('five_hour' | 'seven_day' | 'seven_day_opus' |
+// 'seven_day_sonnet' | 'model:Fable' | …) rather than an enum we'd have to keep in step with the provider: an
+// unrecognised pool is shown under its raw key, which is far better than being silently folded into a
+// neighbour. `label` is the provider's OWN display name where it supplies one (the per-model buckets do) — it
+// wins over anything we'd infer, because the model names in a plan's limits are the provider's to rename.
+// `resetsAt` is epoch SECONDS (matching the SDK's frame).
+export const UsageWindowSchema = z.object({
+    kind: z.string(),
+    label: z.string().optional(),
+    utilization: z.number(), // 0-100
+    resetsAt: z.number().optional(),
+});
+export type UsageWindow = z.infer<typeof UsageWindowSchema>;
+
+// An account's headroom: EVERY window the provider reports, read together, plus when the reading was taken.
+// All of them, not the binding one, because "which pool is binding" changes between turns and a reader
+// comparing accounts needs the same pools on every row. How the reading is TAKEN is per provider and stops at
+// the daemon's readers: Claude's rides the turn's own stream, ChatGPT's and Google's are pulled through
+// CLIProxyAPI's credential-scoped management call. All of them are control requests, so none costs tokens.
+//
+// Within one window utilization only climbs, so an un-reset window stays a valid FLOOR however old it is; past
+// its `resetsAt` it describes a pool that no longer exists and the store drops it. `measuredAt` is epoch MS
+// (matching connectedAt) — deliberately a different unit from the windows' seconds.
+export const AccountUsageSchema = z.object({
+    windows: z.array(UsageWindowSchema),
+    measuredAt: z.number(),
+});
+export type AccountUsage = z.infer<typeof AccountUsageSchema>;
+
 // One connected subscription in the translator. `name` is CLIProxyAPI's auth-file name — the stable store key a
 // disconnect addresses — and `label` the sign-in identity it reported (the account email, else the file name).
-export const TranslatorAccountSchema = z.object({ name: z.string(), label: z.string() });
+export const TranslatorAccountSchema = z.object({
+    name: z.string(),
+    label: z.string(),
+    // The same headroom an OauthAccount carries, on the same field, for the same reason: the account rows are
+    // one list to the reader. Optional because a provider whose quota this sandbox cannot read (Grok, Kimi) —
+    // or one that did not answer — must still render as the connected account it is, with a dot instead of a
+    // ring.
+    usage: AccountUsageSchema.optional(),
+});
 export type TranslatorAccount = z.infer<typeof TranslatorAccountSchema>;
 // Which routed-provider subscriptions are connected in the translator, per provider — a LIST per provider, not
 // a flag: CLIProxyAPI holds any number of auth files per provider side by side and balances requests across
@@ -371,6 +445,7 @@ export type TranslatorAccount = z.infer<typeof TranslatorAccountSchema>;
 export const TranslatorAccountsSchema = z.object({
     codex: z.array(TranslatorAccountSchema),
     grok: z.array(TranslatorAccountSchema),
+    kimi: z.array(TranslatorAccountSchema),
     gemini: z.array(TranslatorAccountSchema),
 });
 export type TranslatorAccounts = z.infer<typeof TranslatorAccountsSchema>;
@@ -429,14 +504,8 @@ export const SteerSchema = z
 // True cancel for the conversation's in-flight turn — aborts the agent daemon-side, unlike closing the
 // /agent fetch (which sends no cancel frame).
 export const StopTurnSchema = z.object({ conversationId: z.string().min(1) });
-// Fire the conversation's remembered usage-limit resume NOW instead of waiting out the reset. `account`
-// points the re-run at a different connected account of the same provider — the "resume on another account"
-// action a spent allowance offers when the sandbox holds more than one; omitted, the turn re-runs on
-// whatever served it (a plain "try again now"). NOT_FOUND when nothing is pending (the failure was already
-// superseded by a fresh turn, or the daemon restarted).
-export const ResumeLimitSchema = z.object({ conversationId: z.string().min(1), account: z.string().min(1).optional() });
-
-// ---- claude subscription usage ----
+
+// ---- claude rate-limit gate ----
 // The GATE signal: whether the provider is letting turns through right now, and — when it is refusing — which
 // window is binding and when it lifts. This is the SDK's rate_limit_event, mapped one-to-one, and it is only
 // ever about the CURRENT moment. It is deliberately NOT the thing the headroom displays read: the event names a
@@ -450,34 +519,6 @@ export const RateLimitInfoSchema = z.object({
 });
 export type RateLimitInfo = z.infer<typeof RateLimitInfoSchema>;
 
-// One plan-limit pool. `kind` is the provider's own key ('five_hour' | 'seven_day' | 'seven_day_opus' |
-// 'seven_day_sonnet' | 'model:Fable' | …) rather than an enum we'd have to keep in step with the provider: an
-// unrecognised pool is shown under its raw key, which is far better than being silently folded into a
-// neighbour. `label` is the provider's OWN display name where it supplies one (the per-model buckets do) — it
-// wins over anything we'd infer, because the model names in a plan's limits are the provider's to rename.
-// `resetsAt` is epoch SECONDS (matching the SDK's frame).
-export const UsageWindowSchema = z.object({
-    kind: z.string(),
-    label: z.string().optional(),
-    utilization: z.number(), // 0-100
-    resetsAt: z.number().optional(),
-});
-export type UsageWindow = z.infer<typeof UsageWindowSchema>;
-
-// An account's headroom: EVERY window the provider reports, read together, plus when the reading was taken.
-// All of them, not the binding one, because "which pool is binding" changes between turns and a reader
-// comparing accounts needs the same pools on every row. Sourced from the CLI's own usage endpoint at turn end
-// (see claudeUsageWindows) — a control request, so it costs no tokens.
-//
-// Within one window utilization only climbs, so an un-reset window stays a valid FLOOR however old it is; past
-// its `resetsAt` it describes a pool that no longer exists and the store drops it. `measuredAt` is epoch MS
-// (matching connectedAt) — deliberately a different unit from the windows' seconds.
-export const AccountUsageSchema = z.object({
-    windows: z.array(UsageWindowSchema),
-    measuredAt: z.number(),
-});
-export type AccountUsage = z.infer<typeof AccountUsageSchema>;
-
 // ---- provider oauth ----
 // Claude uses the PKCE authorize-URL + paste-back handshake (start → exchange). Codex uses OpenAI's device-code
 // flow (start → poll): the browser signs in at verificationUri and enters userCode; the daemon polls until done.
@@ -504,8 +545,9 @@ export const OauthAccountSchema = z.object({
     needsReauth: z.boolean().optional(),
     detail: z.string().optional(),
     // The account's last known subscription-usage snapshot, so the picker can show what's left on each account
-    // before the user commits a turn to one. Claude-only (it is the sole provider whose stream reports a usage
-    // window) and absent until that account has run a turn — an unmeasured account reads as unknown, never 0%.
+    // before the user commits a turn to one. Absent until a reading exists for it — an unmeasured account reads
+    // as unknown, never 0%. Claude is the provider that fills it here, because its stream reports the windows;
+    // the routed subscriptions carry the identical field on TranslatorAccount, filled by a pulled reading.
     usage: AccountUsageSchema.optional(),
 });
 export type OauthAccount = z.infer<typeof OauthAccountSchema>;
@@ -525,11 +567,6 @@ export const OauthExchangeSchema = z.object({
     label: z.string().optional(),
 });
 export const AuthorizeChallengeSchema = z.object({ authorizeUrl: z.string(), verifier: z.string(), state: z.string() });
-// Kimi (Moonshot) authenticates with an API key, not OAuth: the user pastes a key from their Moonshot account
-// and the sandbox stores it as an account (one key per account, several accounts side by side). `label` is the
-// user's display name (blank ⇒ the daemon derives a default). The key never rides back out — connection status
-// is existence in `/kimi/accounts`.
-export const KimiConnectSchema = z.object({ apiKey: z.string().min(1), label: z.string().optional() });
 // 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
@@ -539,13 +576,15 @@ export const KimiConnectSchema = z.object({ apiKey: z.string().min(1), label: z.
 // 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(), code: z.string() });
-// A routed-provider subscription login start (codex/grok/gemini via CLIProxyAPI). Codex and Grok mint a
-// one-time device `code` the user enters at the provider's site, and CLIProxyAPI polls to completion on its
-// own — the card only waits. Google publishes no device flow: the user approves in a browser and is redirected
-// to a loopback URL this sandbox never receives, so `code` is empty and the card asks them to paste that URL
-// back (see TranslatorCompleteSchema). Which half a provider uses is READ from the response rather than
-// hardcoded per provider, so the card needs no provider table.
-export const TranslatorStartSchema = z.object({ url: z.string(), code: z.string(), state: z.string() });
+// 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.
+export const TranslatorStartSchema = z.object({
+    url: z.string(),
+    code: z.string(),
+    state: z.string(),
+    flow: z.enum(["device", "redirect"]),
+});
 // The paste-back half of a redirect login: the URL the provider sent the browser to, carrying the grant as
 // ?code=&state=. `state` ties it to the handshake that issued it — the translator rejects a mismatch.
 export const TranslatorCompleteSchema = z.object({
@@ -555,7 +594,7 @@ export const TranslatorCompleteSchema = z.object({
 });
 // A provider's model catalog, resolved daemon-side from live discovery with a persisted last-known-good list and
 // a seed floor (Grok via opencode.ts xaiModels, Codex via codex-models.ts, Claude via the Agent SDK's
-// supportedModels) — never empty, so the picker is never blank. `label` is the humanized display name; `default`
+// supportedModels) — never empty, so the picker is never blank. `label` is the provider's display name; `default`
 // is the model a fresh chat on that provider seeds (always present). Shared by /grok/models, /codex/models,
 // /claude/models. `efforts` is the reasoning-effort tiers the model accepts (Claude reports them per model);
 // empty ⇒ the client's default tiers.
@@ -563,8 +602,8 @@ export const TranslatorCompleteSchema = z.object({
 // EVERY field here is provider-reported — nothing about a model is curated in this repo, so a new release or a
 // renamed family flows to the UI with no code change. Providers differ in how much they publish: the Claude
 // Agent SDK reports a display name, a capability description, effort tiers, and capability flags, while the
-// OpenAI-compatible /v1/models endpoints (codex/grok/kimi) report ids only — those rows render label-only, and
-// that absence is the honest answer rather than something to paper over with a hand-written table.
+// Some OpenAI-compatible /v1/models endpoints report ids only — those rows render label-only, and that absence
+// is the honest answer rather than something to paper over with a hand-written table.
 //
 // ORDER IS MEANINGFUL: `models` arrives in the provider's own preference order, which is what the picker sorts
 // by, and `default` is the provider's own default. Neither is re-ranked locally.
@@ -624,6 +663,11 @@ export const BuiltinPromptSchema = z.object({ base: z.enum(["intentic", "claude"
 //   iqSearch          — loads the image-baked iq Claude Code plugin (skill + SessionStart nudge) so the agent
 //                        prefers the iq CLI over grep/find/Glob; off ⇒ plugin not loaded, native search tools
 //                        only. Opt-in (default off); the browser Search box uses iq regardless.
+//   iqContext         — retrieves for the user's message BEFORE the turn starts and prepends the ranked answer
+//                        to it, so the model opens with the anchors instead of paying a search round-trip to
+//                        find them. Independent of iqSearch: that one teaches the agent to search, this one
+//                        answers ahead of it.
+//   iqContextHoldout  — measurement control for iqContext, same shape as terseHoldout (UsageTurn.iqContext).
 //   outputCleaners    — the Bash output-cleaner spec (agent-output-filter): "off" = filter disabled (default),
 //                        "" = all cleaners on, else an iq-style allow-list / default-minus
 //                        spec ("git,pnpm" = only those; "-cap" = all except). Threaded to the filter via env.
@@ -643,6 +687,7 @@ export const BuiltinPromptSchema = z.object({ base: z.enum(["intentic", "claude"
 // surface fail to parse the moment a toggle is added — which reaches the user as a page of switches that are
 // silently dead, not as an error. It also means an older on-disk manifest keeps the owner's other picks rather
 // than being discarded whole.
+
 export const SandboxSettingsSchema = z.object({
     stableSystemPrompt: z.boolean().default(false),
     skills: z.array(z.string()).default([]),
@@ -678,6 +723,21 @@ export const SandboxSettingsSchema = z.object({
      * Cap is roomy — the bases it stands in for are ~6.8k characters — but finite, because every turn pays it. */
     systemPrompt: z.string().max(20000).default(""),
     iqSearch: z.boolean().default(false),
+    /* RETRIEVE BEFORE THE TURN, don't wait to be asked. The daemon runs the user's message through the resident
+     * iq engine and prepends the ranked answer to it, so a turn that would have opened with two or three search
+     * calls opens with the anchors already in hand. Independent of `iqSearch`, which only teaches the agent to
+     * reach for the CLI once it decides to search — this one answers ahead of that decision, and the two
+     * compose: the injected capsule names the anchors, the CLI is there for what it missed.
+     *
+     * It rides the USER message (turn-context.ts), never the system prompt, for the same reason the setup
+     * notice does: it changes every turn, and the system prefix is kept byte-stable for the prompt cache.
+     * Off by default — it spends input tokens on every eligible turn, and whether that trade pays is exactly
+     * what the holdout below is for. */
+    iqContext: z.boolean().default(false),
+    // Measurement control for the pre-injection, identical in shape to `terseHoldout`: a fraction [0,1] of
+    // otherwise-eligible turns run WITHOUT the retrieved context and stamp their arm onto the ledger
+    // (UsageTurn.iqContext), so the report compares two real populations of turns instead of asserting a saving.
+    iqContextHoldout: z.number().min(0).max(1).default(0),
     outputCleaners: z.string().default("off"),
     outputHoldout: z.number().min(0).max(1).default(0),
     filterBackend: z.enum(["native", "rtk"]).default("native"),
@@ -699,17 +759,12 @@ export const SandboxSettingsSchema = z.object({
      * automation-opened agents (Discord, webhooks, email) finish turns with no browser in the room — a
      * browser-held preference could not govern them. Per-agent override: AgentSummarySchema.autoLand. */
     autoLand: z.boolean().default(true),
-    // When a turn dies on the Claude subscription's usage limit, re-run it automatically once the limit
-    // window resets (a minute after, so a skewed clock can't retry into the same closed window). Off by
-    // default: an unattended retry spends the fresh window without the user in the room, so the daemon
-    // records every limit-hit either way and the chat OFFERS the toggle at the moment it would have helped —
-    // enabling it then still resumes the turn that just bounced.
-    autoResumeOnLimit: z.boolean().default(false),
     /* When a turn dies because the MODEL PROVIDER was failing (500/502/503, a 529 at capacity, a dropped
      * socket), re-run it on an escalating backoff until it goes through or the attempts are spent.
      *
-     * Defaults ON, unlike autoResumeOnLimit, and the difference is not an inconsistency: a spent allowance is
-     * the user's own budget, and resuming into a fresh window spends something they may have been saving. An
+     * Defaults ON, and a spent Claude allowance is the counter-example that explains why: that one is the
+     * user's own budget, and resuming into a freshly reset window spends something they may have been saving —
+     * so a usage limit stops the turn and says when it resets, and nothing re-runs it. An
      * outage resume spends nothing the dead turn had not already committed, resolves in minutes rather than
      * hours, and — the deciding argument — the turns hurt worst by it are the ones with nobody in the room
      * (automation wakes, Discord, webhooks), which no browser-held preference could ever rescue. It is the same
@@ -717,8 +772,8 @@ export const SandboxSettingsSchema = z.object({
     resumeAfterOutage: z.boolean().default(true),
     /* When the daemon dies under a running turn, re-run that turn once it is back (agent/turn-journal.ts records
      * every in-flight turn; the boot pass in agent/turn-resume.ts re-runs what survived). ON by default, where
-     * autoResumeOnLimit is off, and the difference is who broke the turn: a spent allowance is the user's own
-     * budget, while a restart is usually intentic's OWN doing — the container is recreated on every update,
+     * a spent usage limit re-runs nothing, and the difference is who broke the turn: a spent allowance is the
+     * user's own budget, while a restart is usually intentic's OWN doing — the container is recreated on every update,
      * every environment approval and every dev-sandbox.sh swap. Approving the Dockerfile change an agent asked
      * for must not cost the run that asked for it, and a user who just clicked Approve is in the room expecting
      * the work to continue, not a second button.
@@ -726,7 +781,7 @@ export const SandboxSettingsSchema = z.object({
      * OFF still records the interruption: the fleet card reads `interrupted` (see AgentStatusSchema) and an
      * automation's row shows an `interrupted` run — nothing is re-run, but nothing is silently lost either. */
     autoResumeOnRestart: z.boolean().default(true),
-    /* THE LANDING GATE — the check command run over the COMPOSITE of landed work, once the fleet goes quiet.
+    /* THE LANDING GATE — the check command run over the COMPOSITE of landed work after a landing debounce.
      * Empty ⇒ no gate at all, which is the default: only the owner knows what verifies this workspace, and a
      * guessed command that fails on a fresh clone would read as the gate finding a bug on its first run.
      *
@@ -749,7 +804,7 @@ export const SandboxSettingsSchema = z.object({
     // gate exists to prevent is a green light nobody earned.
     gateTimeoutMs: z.number().min(60_000).max(3_600_000).default(900_000),
     /* Wake a fixer automatically when the gate goes red, instead of only lighting the badge. ON with a
-     * configured command, unlike the other unattended-spend toggles (autoResumeOnLimit), and the difference is
+     * configured command, and the difference from the unattended spend a usage limit refuses is
      * that the spend here is the POINT: a red gate whose fix waits for the user to notice has moved the CI
      * round-trip into the workspace without removing it from the user's day. One attempt per verdict, so a
      * command that fails for a reason no agent can fix costs one turn, not a loop (gate/gate.ts). */
@@ -821,13 +876,21 @@ export const InputSavingsSchema = z.object({
 });
 export type InputSavings = z.infer<typeof InputSavingsSchema>;
 
-// One arm of the turn-level experiment: the turns that ran with the steer, and the turns the holdout ran
-// without it. Mean output tokens PER TURN, because the arms never hold the same number of turns.
-export const SavingsArmSchema = z.object({ turns: z.number(), meanOutputTokens: z.number() });
+// One arm of a turn-level experiment: the turns that ran with the mechanism, and the turns the holdout ran
+// without it. A mean PER TURN, because the arms never hold the same number of turns.
+export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() });
 
-// The terse steer, as measured. Only turns where the steer was ELIGIBLE are counted — a turn under a custom
-// system prompt drops the steer along with everything else the daemon appends, so it belongs to neither arm.
-export const OutputSavingsSchema = z.object({
+/* 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.
+ *
+ * `metric` says what `mean` counts and what `deltaPct` is a delta in. The terse steer is judged on the model's
+ * OWN output tokens, which is the thing it steers. Pre-injection is judged on COST, because it spends input
+ * tokens deliberately to buy back search turns — scored on output tokens it would look like a pure expense,
+ * and scored on input tokens like a pure loss; the trade only nets out in money. */
+export const TurnExperimentSchema = z.object({
+    metric: z.enum(["outputTokens", "costUsd"]),
     on: SavingsArmSchema,
     off: SavingsArmSchema,
     // Turns per arm before a delta is reported at all. Carried on the wire so the screen's "measuring…" state
@@ -835,18 +898,24 @@ export const OutputSavingsSchema = z.object({
     minTurns: z.number(),
     /* The three below are present TOGETHER, and only once both arms clear `minTurns` — a schema that can't
      * express a half-measured experiment is how a 34%-that-becomes-8%-tomorrow never reaches the screen.
-     *   deltaPct   — change in mean output tokens per turn under the steer; negative is a saving.
-     *   marginPct  — ± percentage points, 95% (Welch, unequal variances and unequal arms).
-     *   savedTokens — what the delta is worth over the turns that actually ran with the steer, in this window. */
+     *   deltaPct  — change in the metric's mean per turn under the mechanism; negative is a saving.
+     *   marginPct — ± percentage points, 95% (Welch, unequal variances and unequal arms).
+     *   saved     — what the delta is worth over the turns that actually ran with it, in this window, in the
+     *               metric's own unit (tokens, or dollars). */
     deltaPct: z.number().optional(),
     marginPct: z.number().optional(),
-    savedTokens: z.number().optional(),
+    saved: z.number().optional(),
 });
-export type OutputSavings = z.infer<typeof OutputSavingsSchema>;
+export type TurnExperiment = z.infer<typeof TurnExperimentSchema>;
 
-// `output` is absent when the experiment isn't running at all (terse 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".
-export const SavingsReportSchema = z.object({ input: InputSavingsSchema, output: OutputSavingsSchema.optional() });
+// `output`/`context` 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".
+export const SavingsReportSchema = z.object({
+    input: InputSavingsSchema,
+    output: TurnExperimentSchema.optional(),
+    context: TurnExperimentSchema.optional(),
+});
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 
 // ---- intentic CLI ----
@@ -999,9 +1068,9 @@ export const RepoChangesSchema = z.object({
     remote: GitRemoteStateSchema.optional(),
     // WHICH AGENT PUT IT THERE: repo-relative path → the agent ids that landed it, newest land first. Keyed by
     // PATH rather than carried on each GitChange because a path can be listed on two sides at once (staged and
-    // edited again) and its origin is the same fact for both. Only agents can appear here — a main-tree turn,
-    // a terminal edit and your own typing never pass through land, so they are simply absent (see
-    // agents/origins.ts), which is why the panel badges an agent and says nothing at all for anyone else.
+    // edited again) and its origin is the same fact for both. Only branch-backed agents whose work passed
+    // through land can appear here; workspace conversations, terminal edits and the user's typing are absent
+    // (see agents/origins.ts), so the panel badges an attributable agent and says nothing for anyone else.
     // Ids, not titles: the identity for every id named here rides the response once, in `originAgents`.
     origins: z.record(z.string(), z.array(z.string())).optional(),
     // Why the repo could not be scanned at all, condensed to git's own one-line reason ("fatal: bad object HEAD").
@@ -2052,9 +2121,9 @@ export const AutomationRunSchema = z.object({
     // as "it never fired" — the one reading a 3 a.m. automation must not be given.
     outcome: z.enum(["completed", "skipped", "error", "interrupted"]),
     detail: z.string().optional(),
-    // The runtime session the wake ran in, so the row can open the transcript. Absent for a run that never
-    // reached a provider (skipped by its guard) or whose provider minted no session before it died.
-    sessionId: z.string().optional(),
+    // The stable conversation opened by the wake, so the row can open the provider-neutral agent transcript.
+    // Absent only for a run skipped before a conversation was needed.
+    conversationId: z.string().optional(),
 });
 export type AutomationRun = z.infer<typeof AutomationRunSchema>;
 
@@ -2227,13 +2296,12 @@ export const GateAgentSchema = z.object({
 });
 export type GateAgent = z.infer<typeof GateAgentSchema>;
 
-// The fix turn one red verdict got. A MAIN-TREE turn, not an isolated conversation, so there is no
-// conversationId and no fleet card to open — the composite it must reproduce lives in the main working tree and
-// a fresh worktree branches from HEAD without it. `sessionId` is what makes the run readable after the fact,
-// the same thing an automation's run record carries for the same reason.
+// The fix turn one red verdict got. It is a workspace conversation because the composite it must reproduce
+// lives as uncommitted content in the main working tree; it still has the same stable registry identity as any
+// other conversation.
 export const GateFixSchema = z.object({
     startedAt: z.number(),
-    sessionId: z.string().optional(),
+    conversationId: z.string(),
     // `running` while the turn streams; `done` when it ended cleanly, whatever the re-check then said;
     // `error` when the turn itself failed (a provider outage, no credential), which is worth distinguishing
     // because it is the one case where re-running the fix could still help.
@@ -2406,11 +2474,9 @@ export type PortForwardResult = z.infer<typeof PortForwardResultSchema>;
 // process (a lingering shell after a crash reads false). A process row that maps to an installed extension's
 // declared process carries extensionId+processName, the address for its /extensions start/stop routes. The
 // `{name}` kill-route param is a bare string validated in the handler (a bad name is a BAD_REQUEST) since the
-// same charset gates a `tmux kill-session -t` shell-out. `browser` = a `browser-<sdk session>` Chromium the
-// agent is driving through its @playwright/mcp tools (browser/browser-sessions.ts) — watchable live over the
-// /system/browser-view WebSocket, `running` while that Chromium is connected, and hidden from the strip by
-// the same rule as `agent`: it is a record of work, not a place. Its `label` is the page's own title and
-// `url` the page it is on, which is the one thing a browser pill has to say that a terminal pill does not.
+// same charset gates a `tmux kill-session -t` shell-out. The agent's BROWSER is deliberately NOT one of these
+// kinds: a Chromium with its own tab strip is a surface in its own right, not a pane in the terminal panel, so
+// it lists from /system/browsers with the pages it has open (BrowserSessionSchema below).
 //
 // `activityAt` (epoch ms of the session's last output) and `exitCode` (the LAST window's exit status, absent
 // while that pane still lives) are what let a finished session be READ rather than merely listed: the panel's
@@ -2420,19 +2486,128 @@ export type PortForwardResult = z.infer<typeof PortForwardResultSchema>;
 export const TerminalSessionSchema = z.object({
     name: z.string(),
     label: z.string().optional(),
-    kind: z.enum(["shell", "panel", "agent", "job", "process", "browser"]),
+    kind: z.enum(["shell", "panel", "agent", "job", "process"]),
     running: z.boolean(),
     activityAt: z.number(),
     exitCode: z.number().optional(),
     extensionId: z.string().optional(),
     processName: z.string().optional(),
-    // Browser sessions only: the page the agent is on right now.
-    url: z.string().optional(),
 });
 export const TerminalsListSchema = z.object({ sessions: z.array(TerminalSessionSchema) });
 export type TerminalsList = z.infer<typeof TerminalsListSchema>;
 export const TerminalNameParamSchema = z.object({ name: z.string() });
 
+/* ---- browsers: the Chromium the agent drives through its @playwright/mcp tools ----
+ *
+ * A `browser-<sdk session>` Chromium (browser/browser-sessions.ts), watchable live over the
+ * /system/browser-view WebSocket. It lists apart from the terminals because it is shaped differently in the one
+ * way that decides a UI: a terminal is ONE stream of bytes, while a browser holds SEVERAL pages at once and the
+ * question "what is the agent looking at?" only has an answer if the wire carries all of them. So `pages` is the
+ * point of this schema — the view renders them as a tab strip and binds the screencast to whichever the user
+ * picks, and `active` is the one the agent itself last touched (what the view follows until the user says
+ * otherwise).
+ *
+ * `id` is opaque and minted per session, and it is what makes a tab survive a relist: it is stable for the life
+ * of the page, unlike its url (the agent navigates away) or its position (a closed tab renumbers the rest). */
+export const BrowserPageSchema = z.object({
+    id: z.string(),
+    // The page's own title. Absent mid-navigation, which is exactly when a tab still needs to render.
+    title: z.string().optional(),
+    url: z.string(),
+    // The page the agent last drove — on a finished session, the one it ended on. Exactly one page has it.
+    active: z.boolean(),
+});
+export const BrowserSessionSchema = z.object({
+    name: z.string(),
+    // The pill's text: the active page's title, else its host, else which browser this is.
+    label: z.string(),
+    // Which MCP server drives it: `web` (the credential-free browser) or a logged-in capability's id — the
+    // difference between a throwaway page and one signed in as the user, which is worth saying out loud.
+    server: z.string(),
+    // False once that Chromium is gone (the turn ended, the agent closed it, it crashed). A finished session
+    // still lists for a while, with the pages it had — the record of where the agent went.
+    running: z.boolean(),
+    activityAt: z.number(),
+    // When that Chromium went away, for the "closed 20m ago" line a finished session leads with. Absent while
+    // running, which is the same fact as `running` — but the view needs the timestamp, not just the flag.
+    finishedAt: z.number().optional(),
+    pages: z.array(BrowserPageSchema),
+});
+export type BrowserPage = z.infer<typeof BrowserPageSchema>;
+export type BrowserSession = z.infer<typeof BrowserSessionSchema>;
+export const BrowsersListSchema = z.object({ sessions: z.array(BrowserSessionSchema) });
+export type BrowsersList = z.infer<typeof BrowsersListSchema>;
+export const BrowserNameParamSchema = z.object({ name: z.string() });
+
+/* ---- subagents: the agents an agent starts ----
+ *
+ * The third thing a turn spawns that the operator can be shown, after its shell and its browser — and the only
+ * one that is itself an agent. Two kinds land in this one list, because from outside they are the same fact
+ * (another agent, working, that you did not start):
+ *   • `subagent` — the SDK's Agent/Task tool. The daemon learns of it from the SubagentStart/SubagentStop hooks
+ *     and the task_* stream messages, joined on `toolUseId`.
+ *   • `codex` / `grok` — a CLI the agent drove from its own Bash (agent/delegation.ts). Detected in the Bash
+ *     PreToolUse hook, bound to its thread/session id from the command's output.
+ *
+ * `id` IS THE SPAWNING TOOL CALL'S id — the Agent card's, or the Bash card's for a delegation. It is the one key
+ * every source already carries (the SDK's subagent meta, its task_* messages, and the `parentToolUseId` the
+ * client nests inner frames under), so nothing has to be correlated: a card links to its subagent with the id it
+ * already has, and the subagent points back at the card the same way. The ids the transcripts are actually READ
+ * with — the SDK's agent id, a Codex thread, an OpenCode session — stay daemon-side, because no surface asks a
+ * question they answer.
+ *
+ * WHAT A KIND CHANGES, and it is only ever the live view: a subagent has no process of its own to look at, so
+ * watching it means reading its transcript. A delegation runs in a tmux window, so it has both — `terminal`
+ * names it, and the card keeps its existing "Watch in terminal" beside the transcript door. */
+export const SubagentKindSchema = z.enum(["subagent", "codex", "grok"]);
+export type SubagentKind = z.infer<typeof SubagentKindSchema>;
+
+// running/pending are live; the rest are terminal. Deliberately the SDK's own task vocabulary
+// (SDKTaskUpdatedMessage.patch.status) rather than AgentStatus: this is not a fleet card's lifecycle (no
+// draft/landed/conflict), and mapping the two would invent states neither side reports.
+export const SubagentStatusSchema = z.enum(["pending", "running", "completed", "failed", "killed", "paused"]);
+export type SubagentStatus = z.infer<typeof SubagentStatusSchema>;
+
+export const SubagentSessionSchema = z.object({
+    id: z.string(),
+    kind: SubagentKindSchema,
+    // The conversation whose turn spawned this — what the area groups its rows by, and the way back to the chat
+    // the card lives in.
+    conversationId: z.string(),
+    // What it is and what it was asked to do: the subagent type (`Explore`, `general-purpose`) or the delegated
+    // provider's model, and the caller's one-line description. The area's row and the card's title read as
+    // `Explore · Locate claimIndexer definition`.
+    agentType: z.string().optional(),
+    description: z.string().optional(),
+    model: z.string().optional(),
+    // How deep in the spawn tree (1 = spawned by the turn itself). From the SDK's meta.json; a subagent may
+    // itself delegate, and a flat list that cannot say so reads as though the turn started all of them.
+    spawnDepth: z.number().optional(),
+    // Backgrounded: the parent went on working instead of waiting for it. This is the whole reason the list
+    // exists — a backgrounded child used to be invisible until its result landed, sometimes minutes later.
+    background: z.boolean().optional(),
+    status: SubagentStatusSchema,
+    startedAt: z.number(),
+    endedAt: z.number().optional(),
+    activityAt: z.number(),
+    // What it has spent and done so far (task_progress). Tokens are the child's own, so a parent's cost line and
+    // the sum of its children's are two different true numbers.
+    tokens: z.number().optional(),
+    toolUses: z.number().optional(),
+    lastTool: z.string().optional(),
+    // Its report — the last assistant message (SubagentStop) or the task summary. The answer to "what did it
+    // conclude?" without opening the transcript, which is the question a finished child is read for.
+    summary: z.string().optional(),
+    error: z.string().optional(),
+    // A delegation's live view: the tmux session its command runs in. Absent for an SDK subagent, which has no
+    // process of its own to attach to.
+    terminal: z.string().optional(),
+});
+export type SubagentSession = z.infer<typeof SubagentSessionSchema>;
+export const SubagentsListSchema = z.object({ sessions: z.array(SubagentSessionSchema) });
+export type SubagentsList = z.infer<typeof SubagentsListSchema>;
+export const SubagentIdParamSchema = z.object({ id: z.string() });
+
 // ---- environment: the overlay Dockerfile extending the sandbox image ----
 // The approved file is DAEMON-COMPOSED: pinned FROM + capability fragments + the owner-approved custom section.
 // The agent writes the proposal file (.intentic/environment.Dockerfile — custom-section content only, no FROM)
@@ -2598,7 +2773,8 @@ export const UsageTurnSchema = z.object({
     // when the provider's own subscription default served it without the daemon naming one.
     model: z.string().optional(),
     harness: z.string(),
-    // The conversation this turn belonged to, so spend can join to a fleet agent. Absent on a main-tree turn.
+    // The conversation this turn belonged to, so spend can join to a fleet agent. Absent only for an internal
+    // one-shot turn that has no conversation identity.
     conversationId: z.string().optional(),
     // The provider's own turn count for the request (a Claude "turn" can be several under the hood), so turns
     // and cost stay comparable across providers. 1 when the provider reported none.
@@ -2617,6 +2793,15 @@ export const UsageTurnSchema = z.object({
      * no control to be compared against. Pooling those into the off-arm would compare steered turns against a
      * population selected by something other than the coin flip, which is not a control at all. */
     terse: z.boolean().optional(),
+    /* Which arm of the pre-injection experiment this turn ran on (settings.iqContextHoldout), on the same terms
+     * as `terse` above: absent ⇒ outside the experiment.
+     *
+     * TRUE means the turn was ASSIGNED the retrieved context, not that a note was necessarily prepended — a
+     * treatment turn whose retrieval came back empty or unconfident injects nothing. That is deliberate: the
+     * arms have to be the coin flip's populations, and re-labelling a turn by what retrieval happened to find
+     * would sort turns by how searchable their question was, which is a property of the question. The control
+     * arm contains the same unsearchable questions in the same proportion, so they cancel. */
+    iqContext: z.boolean().optional(),
 });
 export type UsageTurn = z.infer<typeof UsageTurnSchema>;