@intentic/sandbox-contract 1.164.0 → 1.166.0

package/src/hostnames.ts

@@ -14,6 +14,22 @@ export const sandboxHostname = (id: string, zone: string): string => `${sandboxS
 // The container sshd hostname the desktop-sync (Mutagen) reaches over the sandbox tunnel: `ssh-<id>.<zone>`.
 export const sshHostname = (id: string, zone: string): string => `ssh-${id}.${zone}`;
 
+/* The LOOPBACK name: `local-<id>.<zone>`, an A record pointing at 127.0.0.1.
+ *
+ * A public DNS name for a private address looks odd until you ask what the alternative is. A browser on the
+ * same machine as the sandbox can reach its daemon in microseconds instead of crossing to a Cloudflare edge
+ * and back — but only over HTTPS, because Safari refuses http://127.0.0.1 from an HTTPS page as mixed content
+ * (WebKit 171934, open since 2017), and HTTPS needs a name a public CA will certify. An IP literal cannot have
+ * one; this can. The daemon holds the key and gets the certificate by proving control of the zone over
+ * DNS-01 (there is nothing on the public internet for a CA to connect to).
+ *
+ * It discloses nothing: the id is already the leading label of the sandbox's public hostname, and the address
+ * it resolves to is every machine's own loopback. */
+export const localHostname = (id: string, zone: string): string => `local-${id}.${zone}`;
+
+// What that record points at, and the reason it is safe to publish: every resolver on earth gets 127.0.0.1.
+export const LOCAL_ADDRESS = "127.0.0.1";
+
 // A per-host SSH tunnel's Cloudflare tunnel NAME (its hostname reuses sshHostname with the host-ssh id).
 export const hostSshTunnelName = (id: string): string => `host-ssh-${id}`;
 

package/src/index.ts

@@ -10,6 +10,7 @@ import { claudeContract } from "./contracts/claude.contract.js";
 import { codexContract } from "./contracts/codex.contract.js";
 import { draftsContract } from "./contracts/drafts.contract.js";
 import { extensionsContract } from "./contracts/extensions.contract.js";
+import { gateContract } from "./contracts/gate.contract.js";
 import { geminiContract } from "./contracts/gemini.contract.js";
 import { gitContract } from "./contracts/git.contract.js";
 import { grokContract } from "./contracts/grok.contract.js";
@@ -41,6 +42,7 @@ export { claudeContract } from "./contracts/claude.contract.js";
 export { codexContract } from "./contracts/codex.contract.js";
 export { draftsContract } from "./contracts/drafts.contract.js";
 export { extensionsContract } from "./contracts/extensions.contract.js";
+export { gateContract } from "./contracts/gate.contract.js";
 export { geminiContract } from "./contracts/gemini.contract.js";
 export { gitContract } from "./contracts/git.contract.js";
 export { grokContract } from "./contracts/grok.contract.js";
@@ -92,6 +94,7 @@ export const sandboxContract = {
     settings: settingsContract,
     intentic: intenticContract,
     gemini: geminiContract,
+    gate: gateContract,
     git: gitContract,
     grok: grokContract,
     kimi: kimiContract,

package/src/model-order.test.ts

@@ -7,37 +7,42 @@ import { compareCheapestFirst, compareModelIds, compareUnrankedModelIds, familyO
  * conversations on whichever id sorted first. */
 
 // A Codex catalog exactly as an OpenAI-compatible /v1/models hands it over: alphabetical, i.e. meaningless.
-const CODEX = ["gpt-5.1-codex", "gpt-5.4-mini", "gpt-5.5", "gpt-5.6-sol", "gpt-5.6-terra"];
+const CODEX = ["gpt-5.1-codex", "gpt-5.4-mini", "gpt-5.5", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra"];
 
 test("ranks the frontier line above the cheap one and the newest release above its predecessors", () => {
     // The base line (no tier word) leads, newest first; the mini rung sinks under all of it regardless of how
     // recently it shipped — which is the whole decision a user makes in this list.
-    expect(CODEX.toSorted(compareModelIds)).toEqual(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.5", "gpt-5.1-codex", "gpt-5.4-mini"]);
+    expect(CODEX.toSorted(compareModelIds)).toEqual(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.1-codex", "gpt-5.4-mini"]);
 });
 
-test("lands the same models at the head and the tail whichever order the endpoint listed them in", () => {
-    // Arrival order survives only as the tiebreak between two ids the rule ranks equally (the 5.6 siblings), so
-    // an alphabetical registry and a reversed one can no longer disagree about which model the group opens on.
+test("orders a release's named tiers strongest-first whichever order the endpoint listed them in", () => {
     for (const arrival of [CODEX.toSorted(), CODEX.toReversed()]) {
         const ordered = arrival.toSorted(compareModelIds);
 
-        expect(ordered.slice(0, 2).toSorted()).toEqual(["gpt-5.6-sol", "gpt-5.6-terra"]);
+        expect(ordered.slice(0, 3)).toEqual(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]);
         expect(ordered.at(-1)).toBe("gpt-5.4-mini");
     }
 });
 
-test("an unranked catalog settles its own ties, so the SAME sibling opens the group on every refresh", () => {
-    // The measured failure: the translator's /v1/models hands sol/terra/luna back in a different order per
-    // request, and the rule above ranks all three equally — same tier, same 5.6 release. Under plain stability
-    // the catalog's head (i.e. the model a fresh conversation starts on) followed that reshuffling.
+test("keeps release-local tiers below the next generation and above the previous one", () => {
+    expect(["gpt-5.6-luna", "gpt-5.5", "gpt-5.7", "gpt-5.6-sol"].toSorted(compareModelIds)).toEqual([
+        "gpt-5.7",
+        "gpt-5.6-sol",
+        "gpt-5.6-luna",
+        "gpt-5.5",
+    ]);
+});
+
+test("the Codex release-tier order is stable across catalog refreshes", () => {
     const arrivals = [
         ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"],
         ["gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.6-sol"],
         ["gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra"],
     ];
-    const heads = arrivals.map((arrival) => arrival.toSorted(compareUnrankedModelIds)[0]);
 
-    expect(new Set(heads).size).toBe(1);
+    for (const arrival of arrivals) {
+        expect(arrival.toSorted(compareUnrankedModelIds)).toEqual(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]);
+    }
     // Same rule, so ranking still outranks the tiebreak: the mini rung stays at the tail, under every sibling.
     expect(["gpt-5.4-mini", ...arrivals[0]!].toSorted(compareUnrankedModelIds).at(-1)).toBe("gpt-5.4-mini");
 });
@@ -68,6 +73,14 @@ test("reads each vendor's tier vocabulary, not just Claude's", () => {
     ]);
 });
 
+test("reads Kimi's k-prefixed generation so K3 leads the K2.x catalog", () => {
+    const catalog = ["kimi-k2.6", "kimi-k2.7-code-highspeed", "kimi-k3", "kimi-k2.7-code"];
+
+    expect(releaseOf("kimi-k3")).toEqual({ version: [3], date: 0 });
+    expect(familyOf("kimi-k3")).toBe(familyOf("kimi-k2.6"));
+    expect(catalog.toSorted(compareUnrankedModelIds)).toEqual(["kimi-k3", "kimi-k2.7-code", "kimi-k2.7-code-highspeed", "kimi-k2.6"]);
+});
+
 test("the rightmost tier word wins, because tier words compose", () => {
     // flash-lite is the cheap end of Flash, codex-max the frontier end of Codex — reading the leftmost word
     // instead would file both under the tier they modify.
@@ -169,6 +182,10 @@ test("finds each vendor's own cheap rung, including a re-served open-weights row
     expect(["grok-4", "grok-4-fast"].toSorted(compareCheapestFirst)[0]).toBe("grok-4-fast");
 });
 
+test("reads a release-local tier ladder from the cheap end too", () => {
+    expect(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"].toSorted(compareCheapestFirst)[0]).toBe("gpt-5.6-luna");
+});
+
 test("falls back on the newest release for a catalog that publishes no cheap tier at all", () => {
     // Kimi names no tier word anywhere, so every row is UNRANKED and the tier term cancels. Serving the newest
     // of what it does publish is the honest answer — there is no cheaper rung to find.

package/src/model-order.ts

@@ -14,9 +14,11 @@
  * every vendor names its models the same way — which is what lets the daemon's four catalog services and the
  * web's picker share one rule instead of each inventing a local one. */
 
-// A version-ish segment: digits and dots, optionally v-prefixed (`4`, `5.1`, `v2`, `20251001`). Everything else
-// is a NAME segment and belongs to the family — which is what makes the split below exhaustive.
-const VERSION_SEGMENT = /^v?[\d.]+$/;
+// A version-ish segment: digits and dots, optionally prefixed by the vendor's version marker (`4`, `5.1`, `v2`,
+// `k3`, `k2.7`, `20251001`). Kimi is the one provider that fuses the marker with the generation; treating `k3`
+// as a name made the current flagship look unversioned, so K2.x sorted above it. Everything else is a NAME
+// segment and belongs to the family — which is what makes the split below exhaustive.
+const VERSION_SEGMENT = /^(?:v|k)?[\d.]+$/i;
 
 // A date stamp rather than a version component: six digits or more (20251001, 250514). The distinction is not
 // cosmetic — claude-opus-4-1-20250805 (Opus 4.1) and claude-opus-4-20250514 (Opus 4.0) compare as (4,1) vs (4)
@@ -48,7 +50,7 @@ export interface ModelRelease {
 export const releaseOf = (id: string): ModelRelease => {
     const numeric = segmentsOf(id)
         .filter((segment) => VERSION_SEGMENT.test(segment))
-        .map((segment) => segment.replace(/^v/, ""));
+        .map((segment) => segment.replace(/^[vk]/i, ""));
     const stamps = numeric.filter((segment) => DATE_SEGMENT.test(segment)).map(Number);
     return {
         version: numeric
@@ -109,12 +111,21 @@ const TIER_RANK: Readonly<Record<string, number>> = {
 
 const UNRANKED = -1;
 
-// The LAST recognized word wins, because tier words compose and the rightmost is the most specific one:
-// gemini-flash-lite is the cheap end of Flash, gpt-codex-max the frontier end of Codex.
-export const tierRankOf = (family: string): number => {
+/* Some providers name a capability ladder INSIDE one release instead of using the cross-release adjectives
+ * above. Codex 5.6's Sol/Terra/Luna rows are that shape: they must remain together ahead of the older 5.5 line,
+ * but their order is not an arbitrary id tiebreak — Sol is the strongest, followed by Terra, then Luna. Keeping
+ * this as a separate rank lets release recency still win across generations (a future GPT 5.7 base model must
+ * not be buried under a recognized 5.6 suffix), while the three siblings sort by their real tier. */
+const RELEASE_TIER_RANK: Readonly<Record<string, number>> = {
+    sol: 0,
+    terra: 1,
+    luna: 2,
+};
+
+const lastRankOf = (family: string, ranks: Readonly<Record<string, number>>): number => {
     let rank = UNRANKED;
     for (const segment of family.split("-")) {
-        const found = TIER_RANK[segment];
+        const found = ranks[segment];
         if (found !== undefined) {
             rank = found;
         }
@@ -122,18 +133,32 @@ export const tierRankOf = (family: string): number => {
     return rank;
 };
 
-// The canonical order of two model ids: tier first, then release. Hand it straight to Array#toSorted — that sort
-// is stable, so two ids this rule cannot separate keep the order they arrived in (for Claude, the provider's own).
-export const compareModelIds = (left: string, right: string): number =>
-    tierRankOf(familyOf(left)) - tierRankOf(familyOf(right)) || compareRelease(releaseOf(left), releaseOf(right));
+const releaseTierRankOf = (family: string): number => lastRankOf(family, RELEASE_TIER_RANK);
+
+// The LAST recognized word wins, because tier words compose and the rightmost is the most specific one:
+// gemini-flash-lite is the cheap end of Flash, gpt-codex-max the frontier end of Codex.
+export const tierRankOf = (family: string): number => lastRankOf(family, TIER_RANK);
+
+// The canonical order of two model ids: broad tier first, then release, then a tier declared within that release.
+// Hand it straight to Array#toSorted — that sort is stable, so two ids this rule cannot separate keep the order
+// they arrived in (for Claude, the provider's own).
+export const compareModelIds = (left: string, right: string): number => {
+    const leftFamily = familyOf(left);
+    const rightFamily = familyOf(right);
+    return (
+        tierRankOf(leftFamily) - tierRankOf(rightFamily) ||
+        compareRelease(releaseOf(left), releaseOf(right)) ||
+        releaseTierRankOf(leftFamily) - releaseTierRankOf(rightFamily)
+    );
+};
 
 /* The order for a catalog its endpoint published as a SET — Codex, Gemini, Kimi and Grok, i.e. everything but
  * Anthropic's ranked list. Falling back on arrival order is what the rule above does with a tie, and for a RANKED
  * catalog that is exactly right: the tie is the provider's own opinion, so claude-opus-5 stays ahead of
  * claude-fable-5. For a set there is no opinion to keep, and the header of this file assumed the leftover order
- * was at least alphabetical — it is not. A subscription vending sol/terra/luna (same tier, same 5.6 release, three
- * ids this rule cannot separate) hands its rows back in whatever order its registry iterated THIS request, so the
- * tie decided which model a fresh conversation opened on AND flipped between catalog refreshes.
+ * was at least alphabetical — it is not. A subscription can hand tied rows back in whatever order its registry
+ * iterated THIS request, so the tie decides which model a fresh conversation opens on and can flip between
+ * catalog refreshes.
  *
  * So a set breaks its own ties on the id. Which sibling that seats first is arbitrary — but it is the same
  * arbitrary answer every refresh, which is the property `default` actually needs. */
@@ -151,5 +176,12 @@ export const compareUnrankedModelIds = (left: string, right: string): number =>
  * not the efficient rung — and the cheap end is only ever a family whose tier word is actually recognized.
  * Falling off the end of a catalog with no efficient tier at all (Kimi publishes none) is then honest: the
  * newest of what it does publish, chosen by the release tiebreak below. */
-export const compareCheapestFirst = (left: string, right: string): number =>
-    tierRankOf(familyOf(right)) - tierRankOf(familyOf(left)) || compareRelease(releaseOf(left), releaseOf(right));
+export const compareCheapestFirst = (left: string, right: string): number => {
+    const leftFamily = familyOf(left);
+    const rightFamily = familyOf(right);
+    return (
+        tierRankOf(rightFamily) - tierRankOf(leftFamily) ||
+        compareRelease(releaseOf(left), releaseOf(right)) ||
+        releaseTierRankOf(rightFamily) - releaseTierRankOf(leftFamily)
+    );
+};

package/src/quick-model.test.ts

@@ -9,7 +9,7 @@ import { type QuickModelSource, quickModelKey, resolveQuickModel } from "./quick
 const CLAUDE: QuickModelSource = { provider: `claude`, ready: true, models: [`claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5-20251001`] };
 const GOOGLE: QuickModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-flash`, `gemini-3-flash-lite`, `gemini-3-pro`] };
 const CODEX: QuickModelSource = { provider: `codex`, ready: true, models: [`gpt-5.4-mini`, `gpt-5.6`] };
-const KIMI: QuickModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2-0711-preview`, `kimi-k2-0905-preview`] };
+const KIMI: QuickModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2.6`, `kimi-k2.7-code`, `kimi-k3`] };
 
 const offline = (source: QuickModelSource): QuickModelSource => ({ ...source, ready: false });
 
@@ -72,7 +72,7 @@ test("ignores a malformed pin instead of running an empty model id", () => {
 
 test("serves the newest of a catalog that publishes no cheap tier at all", () => {
     // Kimi names no tier word anywhere. There is no cheaper rung to find, so the newest row is the honest answer.
-    expect(resolveQuickModel([KIMI], ``)).toEqual({ provider: `kimi`, model: `kimi-k2-0905-preview` });
+    expect(resolveQuickModel([KIMI], ``)).toEqual({ provider: `kimi`, model: `kimi-k3` });
 });
 
 test("reports nothing when no account is connected, so the button can say so instead of failing on click", () => {

package/src/schemas.test.ts

@@ -29,6 +29,11 @@ test("a payload from a build that predates a toggle parses, with the new toggle
         autoLand: true,
         autoResumeOnLimit: false,
         resumeAfterOutage: true,
+        autoResumeOnRestart: true,
+        gateCommand: "",
+        gateQuietMs: 20_000,
+        gateTimeoutMs: 900_000,
+        gateAutoFix: true,
     });
 });
 
@@ -61,6 +66,15 @@ test("an empty object is the full default settings object", () => {
         // On, unlike the limit resume beside it: an outage resume spends nothing the dead turn hadn't already
         // committed, and the turns it saves are the unattended ones nobody is watching to restart by hand.
         resumeAfterOutage: true,
+        // On: a daemon restart is usually intentic's own doing (an image update, an approved environment
+        // change), not the user's decision, so the turn it interrupted resumes rather than staying stuck.
+        autoResumeOnRestart: true,
+        // Empty disables the landing gate until the owner supplies this workspace's verification command.
+        gateCommand: "",
+        gateQuietMs: 20_000,
+        gateTimeoutMs: 900_000,
+        // Once a gate is configured, a red verdict wakes one fixer by default.
+        gateAutoFix: true,
     });
 });
 

package/src/schemas.ts

@@ -715,6 +715,45 @@ export const SandboxSettingsSchema = z.object({
      * (automation wakes, Discord, webhooks), which no browser-held preference could ever rescue. It is the same
      * reasoning that leaves the auth resume ungated: this is the provider's failure, not the user's decision. */
     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,
+     * 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.
+     *
+     * 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.
+     * 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>;
 
@@ -1204,8 +1243,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(),
@@ -1233,6 +1273,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({
@@ -1244,8 +1287,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(),
 });
@@ -1999,9 +2046,15 @@ export const AutomationApprovalIdParamSchema = z.object({ id: z.string() });
 
 export const AutomationRunSchema = z.object({
     at: z.number(),
-    // skipped = the guard said no; error = the guard passed but the agent turn surfaced an error.
-    outcome: z.enum(["completed", "skipped", "error"]),
+    // skipped = the guard said no; error = the guard passed but the agent turn surfaced an error; interrupted =
+    // the daemon died mid-wake, so the run reached no outcome of its own (see agent/turn-journal.ts). Without
+    // that last one an interrupted fire records NOTHING and simply vanishes from the row's history, which reads
+    // 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(),
 });
 export type AutomationRun = z.infer<typeof AutomationRunSchema>;
 
@@ -2038,8 +2091,18 @@ export const PipelineRunSchema = z.object({
     project: z.string(),
     // The vendor's numeric run/pipeline id — what rerun/cancel address.
     runId: z.number(),
-    // github's display_title (the commit/PR line); gitlab's pipeline name when set. Absent ⇒ the view shows ref@sha.
+    // The run's headline: github's display_title (the commit subject, or the PR title when a PR triggered it),
+    // gitlab's pipeline name or the head commit's subject. Absent ⇒ the view falls back to ref@sha.
     title: z.string().optional(),
+    // Who the vendor credits for the run — the actor who set it off, matching what both vendors' own UIs
+    // show. The avatar is a vendor-hosted URL; absent ⇒ the view draws the author's initials instead.
+    authorName: z.string().optional(),
+    authorAvatarUrl: z.string().optional(),
+    // What set the run off, in the vendor's own vocabulary: gitlab's pipeline `source` (push, schedule,
+    // merge_request_event, web, api, trigger…) or github's `event` (push, pull_request, schedule,
+    // workflow_dispatch…). Left raw rather than flattened into a shared enum — the vendor's word is the
+    // precise one, and the view only calls it out when it isn't the everyday push.
+    trigger: z.string().optional(),
     branch: z.string(),
     sha: z.string(),
     status: PipelineStatusSchema,
@@ -2052,6 +2115,28 @@ export const PipelineRunSchema = z.object({
 });
 export type PipelineRun = z.infer<typeof PipelineRunSchema>;
 
+// One job inside a pipeline run. The view fetches these lazily (one extra call per visible run) so the list
+// endpoint stays cheap. Both GitHub Actions jobs and GitLab CI jobs normalize onto these fields.
+// `stage` is GitLab's native sequential grouping and is absent on GitHub — the Actions jobs API exposes no
+// `stage` and no `needs`, so the view instead layers GitHub jobs into execution waves off the timestamps
+// below (overlapping runtimes ⇒ ran in parallel). Both are epoch ms; absent while a job is still queued.
+export const PipelineJobSchema = z.object({
+    name: z.string(),
+    status: PipelineStatusSchema,
+    stage: z.string().optional(),
+    startedAt: z.number().optional(),
+    finishedAt: z.number().optional(),
+    durationSeconds: z.number().optional(),
+    // The job's page on its host — the shortest path from "this step failed" to the log that says why.
+    webUrl: z.string().optional(),
+});
+export type PipelineJob = z.infer<typeof PipelineJobSchema>;
+
+export const CiJobsResponseSchema = z.object({
+    jobs: z.array(PipelineJobSchema),
+});
+export type CiJobsResponse = z.infer<typeof CiJobsResponseSchema>;
+
 // One mapped repo's CI wiring state. `hookWarning` is the manual-setup story when webhook registration was
 // refused (token scope, role) or impossible (no public URL): what happened plus the target URL + secret to
 // paste into the repo's webhook settings — the git-access sshRegistrationWarning pattern.
@@ -2069,9 +2154,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() });
@@ -2081,6 +2174,97 @@ 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. 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.
+export const GateFixSchema = z.object({
+    startedAt: z.number(),
+    sessionId: z.string().optional(),
+    // `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
@@ -2206,8 +2390,12 @@ export const PortForwardResultSchema = z.object({ previewUrl: z.string().optiona
 export type PortForwardResult = z.infer<typeof PortForwardResultSchema>;
 
 // ---- terminal ----
-// EVERY attachable tmux session in the sandbox — the web app's ONE global terminal panel (the interactive I/O
-// is the /system/terminal WebSocket, not oRPC): `shell` = a web-* session the user opened (numbered pill),
+// EVERY live surface in the sandbox the web app's ONE global panel can show. Mostly tmux sessions (the
+// interactive I/O is the /system/terminal WebSocket, not oRPC), plus the agent's browser, which is not a
+// terminal at all — no more than a `process` row is — but IS the same question: what is running right now,
+// and can I look at it? One list, because the panel that answers that question is one panel.
+//
+// `shell` = a web-* session the user opened (numbered pill),
 // `panel` = a panel-* dev-server session (labeled by its panel key, started via Start; running:false =
 // untracked, e.g. a finished one-shot job's lingering shell), `agent` = an agent-* session the Claude agent's
 // Bash commands run in (live-watchable, AI-marked in the UI; running:false once every window is a finished
@@ -2218,7 +2406,11 @@ 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.
+// 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.
 //
 // `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
@@ -2228,12 +2420,14 @@ 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"]),
+    kind: z.enum(["shell", "panel", "agent", "job", "process", "browser"]),
     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>;