@intentic/sandbox-contract 1.165.0 → 1.167.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({
@@ -355,9 +379,8 @@ 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>;
 
 // One connected subscription in the translator. `name` is CLIProxyAPI's auth-file name — the stable store key a
@@ -371,6 +394,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>;
@@ -525,11 +549,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 +558,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 +576,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 +584,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 +645,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 +669,12 @@ 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.
+// Build-wide kill switch for usage-limit auto-resume. Keep the setting and implementation in place while the
+// feature is disabled, but clamp every daemon response and settings write to OFF so a persisted `true` from an
+// older build cannot keep spending a newly reset allowance. The web also reads this constant to render the
+// control unavailable and to distrust a stale daemon that still reports a scheduled resume.
+export const USAGE_LIMIT_AUTO_RESUME_ENABLED: boolean = false;
+
 export const SandboxSettingsSchema = z.object({
     stableSystemPrompt: z.boolean().default(false),
     skills: z.array(z.string()).default([]),
@@ -678,6 +710,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,12 +746,13 @@ 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),
+    // Latent opt-in for re-running a turn after the Claude subscription's usage window resets. It defaults off
+    // because an unattended retry spends the fresh allowance without the user in the room, and the build-wide
+    // gate above currently clamps even an older saved opt-in off while the feature is unavailable.
+    autoResumeOnLimit: z
+        .boolean()
+        .default(false)
+        .overwrite((enabled) => USAGE_LIMIT_AUTO_RESUME_ENABLED && enabled),
     /* 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.
      *
@@ -726,6 +774,34 @@ 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 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.
+     *
+     * Configuring it is the opt-in, which is why there is no separate enable flag to disagree with it. The
+     * command runs in the workspace root through `sh -c`, exactly as a terminal would run it (see gate/gate.ts
+     * for why this is NOT an automation guard: a suite outlives GUARD_TIMEOUT_MS, and a timed-out guard reads
+     * as "skipped" — a silent green over a suite that never finished). */
+    gateCommand: z.string().max(500).default(""),
+    /* How long after a land the gate waits before running. A landing burst is the case this exists for: five
+     * agents finishing within a minute of each other are five lands, and a gate that ran per land would spend
+     * five suites to answer about four trees nobody will ever push. Every land re-arms the timer, so the run
+     * happens once, on the tree the user is about to review.
+     *
+     * It counts from the last LAND and nothing else — explicitly not "until the fleet is idle". Agents here run
+     * for hours, so a fleet of twenty with one long runner would never present a quiet moment, and a gate that
+     * waited for one would only ever fire when clicked (gate/gate.ts). */
+    gateQuietMs: z.number().min(0).max(600_000).default(20_000),
+    // Ceiling on one gate run, after which the child is killed and the verdict is `failed` with `timedOut`.
+    // Never a pass: a suite that did not finish has not said anything about the tree, and the one thing this
+    // 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
+     * 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). */
+    gateAutoFix: z.boolean().default(true),
 });
 export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
 
@@ -793,13 +869,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
@@ -807,18 +891,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 ----
@@ -971,9 +1061,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").
@@ -1215,8 +1305,9 @@ export type WorkspaceClassification = z.infer<typeof WorkspaceClassificationSche
 // within `text` so clients highlight without re-finding the needle.
 export const WorkspaceSearchQuerySchema = z.object({
     query: z.string().min(2).max(512),
-    // Search verbs only — anchor/git verbs (outline, context, log, who, …) are CLI-only surface.
-    mode: z.enum(["q", "find", "files", "def", "refs", "sym", "ast", "ask"]).optional(),
+    // Search verbs only — anchor/git verbs (outline, context, log, who, …) are CLI-only surface. Natural language
+    // has no verb of its own: `q` classifies the query and answers it semantically when the words call for it.
+    mode: z.enum(["q", "find", "files", "def", "refs", "sym", "ast"]).optional(),
     includeIgnored: z.stringbool().optional(),
     limit: z.coerce.number().int().positive().optional(),
     after: z.string().optional(),
@@ -1244,6 +1335,9 @@ export const WorkspaceSearchFreshnessSchema = z.object({
     state: z.enum(["fresh", "building", "stale"]),
     ageMs: z.number().optional(),
     progress: z.number().optional(),
+    // How many files the index has not caught up with, when it is stale. A count is reportable; "stale" alone
+    // reads as a warning about the answer, which it almost never is.
+    behind: z.number().optional(),
 });
 export type WorkspaceSearchFreshness = z.infer<typeof WorkspaceSearchFreshnessSchema>;
 export const WorkspaceSearchResultSchema = z.object({
@@ -1255,8 +1349,12 @@ export const WorkspaceSearchResultSchema = z.object({
     truncated: z.boolean(),
     cursor: z.string().optional(),
     hint: z.string().optional(),
-    // Code-graph neighbors of the top hits (definition anchors + ready-made follow-up commands).
+    // Code-graph neighbors of the top hits (definition anchors + the strongest caller of each).
     related: z.array(z.string()).optional(),
+    // Ranked `path:line` anchors that placed but were NOT shown, best first — the answer often sits at rank 5–13,
+    // behind groups the budget spent itself on. The text surface has always printed this map; a JSON caller could
+    // not see it, so it had to page through `cursor` to learn what the terminal was told up front.
+    candidates: z.array(z.string()).optional(),
     // Run provenance for benchmarking: retrieval stages DISABLED this invocation (absent = full pipeline).
     features: z.array(z.string()).optional(),
 });
@@ -2016,9 +2114,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>;
 
@@ -2118,9 +2216,17 @@ export const CiRunsResponseSchema = z.object({
     repos: z.array(CiRepoSchema),
     // Newest first, across all mapped repos.
     runs: z.array(PipelineRunSchema),
+    // When the owner last opened the pipelines view. Rides the runs response so the rail can decide what is
+    // NEW without a second call — a breakage older than this has already been seen and must not badge again.
+    // Absent ⇒ never opened, so everything counts as unseen.
+    seenAt: z.number().optional(),
 });
 export type CiRunsResponse = z.infer<typeof CiRunsResponseSchema>;
 
+// Stamping the view as read hands back the timestamp it wrote, so the client updates without a refetch.
+export const CiSeenResponseSchema = z.object({ seenAt: z.number() });
+export type CiSeenResponse = z.infer<typeof CiSeenResponseSchema>;
+
 // rerun/cancel/fix address a run by repo + vendor id; the daemon re-resolves repo → project + token per call,
 // so a stale card can't act on a project the workspace no longer maps to.
 export const CiRunParamSchema = z.object({ repo: z.string(), runId: z.number() });
@@ -2130,6 +2236,96 @@ export type CiRunParam = z.infer<typeof CiRunParamSchema>;
 export const CiFixResponseSchema = z.object({ conversationId: z.string() });
 export type CiFixResponse = z.infer<typeof CiFixResponseSchema>;
 
+/* ---- the landing gate: the workspace's own verdict on the composite of landed work ----
+ *
+ * WHERE THIS SITS, and why it is not one of the four other places it could:
+ *
+ * A fleet of 5-20 agents lands work into the main tree as UNCOMMITTED changes (agents/land.ts), the user
+ * reviews and commits it by parts, pushes, and CI answers minutes later. This gate front-runs that answer by
+ * asking the same question of the same artifact, before the push.
+ *
+ * NOT inside an agent's turn. An isolated worktree's `node_modules` reads as the MAIN checkout's, so a
+ * monorepo's workspace links resolve cross-package imports to /work's sources rather than the worktree's edited
+ * ones (agents/worktrees.ts). A suite run in a worktree therefore tests the agent's edits against everyone
+ * else's UNEDITED siblings: it invents failures that don't exist and passes changes that break on the
+ * composite, and two agents editing one contract each go green alone and red together. The composite is the
+ * only honest artifact, and it exists in exactly one place — the main working tree.
+ *
+ * NOT at commit. The user commits BY PARTS, and a suite reads the worktree, not the index — so a verdict taken
+ * at a partial commit describes a tree that never gets pushed as such. Commit is where a verdict is DISPLAYED
+ * (ReviewPanel's badge), computed earlier.
+ *
+ * NOT at push. By then HEAD has moved, per-path attribution has expired (agents/origins.ts), and the agents may
+ * be archived with their worktrees reclaimed — so the fix starts cold, in the same position `/ci/fix` is in.
+ * That saves the CI round-trip and none of the context switch.
+ *
+ * So: after the land, before the staging — the one window where the artifact is what CI will see, attribution
+ * is still live, and nobody is waiting on it. */
+
+/* What the gate has to say about the tree right now.
+ *
+ *   idle      — no command configured, or nothing has run yet.
+ *   armed     — work landed; the quiet period is counting down (see gateQuietMs).
+ *   running   — the check is live. `output` grows as it streams.
+ *   passed    — exited 0 over `fingerprint`.
+ *   failed    — exited non-zero, or was killed by gateTimeoutMs (`timedOut`). The state a fix answers.
+ *   error     — the gate itself could not run: the command was not spawnable. NOT a fix-able failure, because
+ *               there is nothing wrong with the code — the gate is misconfigured, and saying "tests failed"
+ *               would send an agent hunting a bug that isn't there.
+ *   cancelled — the user stopped the run, or the tree moved under it.
+ */
+export const GateStatusSchema = z.enum(["idle", "armed", "running", "passed", "failed", "error", "cancelled"]);
+export type GateStatus = z.infer<typeof GateStatusSchema>;
+
+// An agent whose landed work the failure implicates. `paths` are its attributed files that the check's own
+// output NAMED — empty when the output named none of them, which is the honest shape for a failure that could
+// not be pinpointed (an integration break between two deltas, a suite that prints no paths at all): the agent
+// is listed because its work is in the tree under test, not because anything accused it.
+export const GateAgentSchema = z.object({
+    agentId: z.string(),
+    title: z.string().optional(),
+    provider: AgentProviderSchema.optional(),
+    paths: z.array(z.string()),
+});
+export type GateAgent = z.infer<typeof GateAgentSchema>;
+
+// 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(),
+    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.
+    outcome: z.enum(["running", "done", "error"]),
+    detail: z.string().optional(),
+});
+export type GateFix = z.infer<typeof GateFixSchema>;
+
+export const GateVerdictSchema = z.object({
+    status: GateStatusSchema,
+    // The command this verdict ran, echoed rather than read back from settings: a verdict read after the
+    // setting changed still has to say what produced it.
+    command: z.string(),
+    startedAt: z.number().optional(),
+    finishedAt: z.number().optional(),
+    exitCode: z.number().optional(),
+    timedOut: z.boolean().optional(),
+    // The check's own output, tail-capped (GATE_OUTPUT_BYTES). The tail, not the head: a suite's verdict and
+    // its failure summary are at the end, and a head-capped buffer of a chatty build is all progress lines.
+    output: z.string(),
+    /* WHICH TREE this verdict is about — HEAD plus the shape of every repo's uncommitted content. Recomputed
+     * on read: when it no longer matches, the verdict is `stale` and the badge says so instead of asserting a
+     * green light over a tree that has since moved. This is what keeps a passed verdict from outliving its
+     * subject when the user edits, discards, or commits half of it. */
+    fingerprint: z.string(),
+    stale: z.boolean(),
+    implicated: z.array(GateAgentSchema),
+    fix: GateFixSchema.optional(),
+});
+export type GateVerdict = z.infer<typeof GateVerdictSchema>;
+
 // ---- drafts: agent-proposed posts awaiting owner approval (.intentic/drafts/<id>.json) ----
 // One JSON file per draft. The AGENT creates drafts with its normal file tools — it can't call daemon routes,
 // the same split as the environment proposal — while the daemon edits/deletes them on the owner's behalf, so
@@ -2271,11 +2467,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
@@ -2285,19 +2479,56 @@ 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. Exactly one page per running session 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(),
+    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() });
+
 // ---- 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)
@@ -2463,7 +2694,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.
@@ -2482,6 +2714,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>;