@intentic/sandbox-contract 1.165.0 → 1.166.0

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

@@ -30,6 +30,10 @@ test("a payload from a build that predates a toggle parses, with the new toggle
         autoResumeOnLimit: false,
         resumeAfterOutage: true,
         autoResumeOnRestart: true,
+        gateCommand: "",
+        gateQuietMs: 20_000,
+        gateTimeoutMs: 900_000,
+        gateAutoFix: true,
     });
 });
 
@@ -65,6 +69,12 @@ test("an empty object is the full default settings object", () => {
         // 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

@@ -726,6 +726,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, 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>;
 
@@ -1215,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(),
@@ -1244,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({
@@ -1255,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(),
 });
@@ -2118,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() });
@@ -2130,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

package/src/session-names.ts

@@ -0,0 +1,44 @@
+/* THE NAMES OF THE SESSIONS ONE TURN OPENS.
+ *
+ * A turn that runs Bash gets a tmux session; a turn that browses gets a Chromium the daemon watches over CDP.
+ * Both are named off the SDK session id by the same derivation, and both are listed together by
+ * GET /system/terminals — so the name is wire vocabulary, not an implementation detail of either half.
+ *
+ * It lives in the contract because three parties derive it and none of them may guess: the daemon NAMES the
+ * session, the web app OPENS it, and an extension that wants to point the user at a turn's live browser has only
+ * the fleet roster's `sessionId` to work from. A second copy of this string math anywhere is a drift waiting to
+ * happen — the copy would keep resolving to a plausible name that nothing has ever listed.
+ *
+ * Reached as `@intentic/sandbox-contract/session-names`, NOT through the barrel — the same shape tunnel-ids has,
+ * and for the same reason: this module has no dependencies, while the barrel pulls the whole contract (and
+ * @intentic/extension-api behind it). One subpath keeps a daemon unit test that only wants a session name from
+ * having to resolve the entire wire surface.
+ */
+
+export const WEB_SESSION_PREFIX = "web-";
+export const AGENT_SESSION_PREFIX = "agent-";
+export const JOB_SESSION_PREFIX = "job-";
+export const BROWSER_SESSION_PREFIX = "browser-";
+
+/* Eight characters of the SDK session UUID, sanitized to the session-name charset. Eight is what groups a whole
+ * turn's work — including its subagents' — under one name, and it clears the name guard
+ * (`^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$`) without further escaping. Undefined when the id sanitizes to empty, which
+ * is never a valid session name. */
+export const sessionSuffix = (sessionId: string): string | undefined => {
+    const id = sessionId.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 8);
+    return id === "" ? undefined : id;
+};
+
+// The tmux session one SDK session's Bash commands run in — the same derivation the Bash hook routes commands
+// through, so an emitted `terminal` frame and the live session can't drift.
+export const agentSessionName = (sessionId: string): string | undefined => {
+    const suffix = sessionSuffix(sessionId);
+    return suffix === undefined ? undefined : `${AGENT_SESSION_PREFIX}${suffix}`;
+};
+
+// The browser session one SDK session drives. Shares the suffix with agentSessionName on purpose: a
+// conversation's shell and its browser read as the pair they are.
+export const browserSessionName = (sessionId: string): string | undefined => {
+    const suffix = sessionSuffix(sessionId);
+    return suffix === undefined ? undefined : `${BROWSER_SESSION_PREFIX}${suffix}`;
+};