@intentic/sandbox-contract 1.316.0 → 1.318.0

package/src/policy/secret-hosts.ts

@@ -0,0 +1,73 @@
+// Which hosts a stored secret may be sent to: an owner's list per secret, matched against the hosts one use would reach.
+// Shared by the daemon's check, its routes and the Secrets view, so the three cannot disagree on what a pattern means.
+// A list names hosts, never ports or paths: the question it answers is who receives the value, not which door.
+
+// One DNS label: letters, digits and inner hyphens, at most 63 characters.
+const LABEL = String.raw`[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?`;
+
+// An exact host (`api.github.com`, `localhost`, `10.0.0.2`) or every host under a domain (`*.github.com`). A wildcard
+// names at least two labels under it, so `*.com` cannot stand in for most of the internet.
+export const SECRET_HOST_PATTERN_RE = new RegExp(String.raw`^(?:\*\.${LABEL}(?:\.${LABEL})+|${LABEL}(?:\.${LABEL})*)$`);
+export const SECRET_HOST_MAX = 253;
+// Enough for a service's API, uploads and content hosts several times over; a list longer than this is no limit.
+export const SECRET_HOSTS_MAX = 64;
+
+const WILDCARD = "*.";
+
+// What a person types or pastes, as the pattern it means: lowercased, trimmed, a trailing dot and a port dropped, and a
+// whole URL reduced to its host. Undefined for anything that is not a host pattern, so a caller refuses it by name.
+export const normalizeHostPattern = (raw: string): string | undefined => {
+    let text = raw.trim().toLowerCase();
+    if (/^[a-z][a-z0-9+.-]*:\/\//.test(text)) {
+        try {
+            text = new URL(text).hostname;
+        } catch {
+            return undefined;
+        }
+    }
+    text = text.replace(/:\d+$/, "").replace(/\.$/, "");
+    return text.length <= SECRET_HOST_MAX && SECRET_HOST_PATTERN_RE.test(text) ? text : undefined;
+};
+
+// A host a use would reach, in the form patterns are written in: lowercased, one trailing dot dropped. Undefined when it
+// is not a plain host name or IPv4 address, which callers read as "cannot tell where this goes".
+export const normalizeHost = (raw: string): string | undefined => {
+    const host = raw.toLowerCase().replace(/\.$/, "");
+    return host.length <= SECRET_HOST_MAX && !host.startsWith(WILDCARD) && SECRET_HOST_PATTERN_RE.test(host) ? host : undefined;
+};
+
+// `*.github.com` matches every host under github.com at any depth, and not github.com itself; anything else matches only
+// itself. Both sides are expected normalized.
+export const hostMatches = (pattern: string, host: string): boolean =>
+    pattern.startsWith(WILDCARD) ? host.endsWith(pattern.slice(1)) : host === pattern;
+
+export const hostAllowed = (patterns: readonly string[], host: string): boolean => patterns.some((pattern) => hostMatches(pattern, host));
+
+// Whether every host `pattern` matches is already matched by `patterns`: an exact host by any pattern that matches it, a
+// wildcard only by itself or a wildcard over a domain above it.
+const covered = (patterns: readonly string[], pattern: string): boolean => {
+    if (!pattern.startsWith(WILDCARD)) {
+        return hostAllowed(patterns, pattern);
+    }
+    const suffix = pattern.slice(1);
+    return patterns.some((held) => held.startsWith(WILDCARD) && suffix.endsWith(held.slice(1)));
+};
+
+// One secret's host guard as a change reads it: whether it asks off the list, and the list. Absent reads as off.
+export interface HostGuardSetting {
+    readonly guard: boolean;
+    readonly hosts: readonly string[];
+}
+
+// Whether going from `current` to `next` only ever makes the agent ask more: turning the guard on, or taking hosts off a
+// guarded list (down to none, where every use asks). The one test for who may make a change: anybody who may use
+// secrets may tighten a guard, only the owner may loosen one, by adding a host or turning it off.
+export const tightensHostGuard = (current: HostGuardSetting | undefined, next: HostGuardSetting): boolean => {
+    if (!next.guard) {
+        return current === undefined || !current.guard;
+    }
+    if (current === undefined || !current.guard) {
+        return true;
+    }
+    return next.hosts.every((pattern) => covered(current.hosts, pattern));
+};

package/src/policy/turned-away.ts

@@ -10,6 +10,7 @@ const TURNED_AWAY: ReadonlySet<string> = new Set([
     "claude-not-entitled",
     "unknown-command",
     "context-window-too-small",
+    "model-helper-only",
     "sandbox-memory-low",
     "trial-unavailable",
     "trial-model-unavailable",

package/src/protocol/raw-routes.ts

@@ -61,6 +61,9 @@ export const RAW_ROUTES = {
     "POST /environment/approve": {},
     "POST /environment/reject": {},
     "POST /environment/runtime-install": {},
+    "POST /environment/remove": {},
+    "POST /environment/rebuild-when-idle": {},
+    "DELETE /environment/rebuild-when-idle": {},
     "GET /engines": {},
     "POST /engines/channel": {},
     "POST /engines/update": {},
@@ -83,9 +86,8 @@ export const RAW_ROUTES = {
     "GET /extensions/{id}/bundle": { lane: "bulk" },
     // An extension backend's own namespace, proxied verbatim.
     "ALL /x/*": {},
-    // The `capabilities` CLI: discovery by name, and the ask that parks on an owner-decided card.
+    // The `capabilities` CLI's discovery by name; its ask is the needs door (contracts/needs.contract.ts).
     "GET /capabilities/connectable": { floor: "maintainer", agent: true, control: "never" },
-    "POST /capabilities/ask": { floor: "maintainer", agent: true, control: "never" },
     // The `sandboxes` CLI; every create parks on a card in the owner's chat first.
     "GET /sandboxes": { agent: true },
     "POST /sandboxes": { agent: true },
@@ -93,13 +95,14 @@ export const RAW_ROUTES = {
     "GET /wallet/status": { agent: true, control: "never" },
     "POST /wallet/fetch": { agent: true, control: "never" },
     "GET /wallet/history": { agent: true, control: "never" },
-    // The `agents` CLI's children: start, follow up, answer (never a consent card), cancel, list.
+    // The `agents` CLI's children: start, follow up, answer (never a consent card), cancel, merge held work, list.
     "POST /children/spawn": { agent: true, control: "never" },
     "GET /children/providers": { agent: true, control: "never" },
     "POST /children/wait": { agent: true, control: "never" },
     "POST /children/send": { agent: true, control: "never" },
     "POST /children/answer": { agent: true, control: "never" },
     "POST /children/cancel": { agent: true, control: "never" },
+    "POST /children/merge": { agent: true, control: "never" },
     "GET /children": { agent: true, control: "never" },
     // The fleet reads, and the one write: words in front of another conversation, which a person can do by typing.
     "GET /fleet": { agent: true },

package/src/protocol/routes.test.ts

@@ -1,6 +1,6 @@
 import { eventIterator, oc } from "@orpc/contract";
 import { z } from "zod";
-import { SANDBOX_ROUTE_NAMES, SANDBOX_ROUTE_SHAPES, SANDBOX_ROUTES, sandboxRouteName } from "../index.js";
+import { SANDBOX_ROUTE_NAMES, SANDBOX_ROUTES, sandboxRouteName, sandboxRouteFingerprints } from "../index.js";
 import { procedure } from "./route-meta.js";
 import { contractRoutes, routeNameForRequest, routeShapes, servedRoute, streamOf } from "./routes.js";
 
@@ -231,7 +231,7 @@ describe(`the real sandbox contract`, () => {
     it(`fingerprints every route, streams included`, () => {
         // Nothing may opt out: a route with no fingerprint is a route the browser can never tell has drifted, and the
         // streaming ones (system.events, agent.attach, the exit dials) carry the frames a stale daemon breaks first.
-        expect(SANDBOX_ROUTE_NAMES.filter((name) => !(name in SANDBOX_ROUTE_SHAPES))).toEqual([]);
+        expect(SANDBOX_ROUTE_NAMES.filter((name) => !(name in sandboxRouteFingerprints()))).toEqual([]);
     });
 
     it(`fingerprints the streaming routes eventIterator used to hide`, () => {
@@ -250,7 +250,7 @@ describe(`the real sandbox contract`, () => {
                 `system.runDeviceAgentFlow`,
                 `vpn.connect`,
             ]
-                .filter((name) => name in SANDBOX_ROUTE_SHAPES)
+                .filter((name) => name in sandboxRouteFingerprints())
                 .toSorted(),
         ).toEqual([
             `agent.attach`,
@@ -269,8 +269,8 @@ describe(`the real sandbox contract`, () => {
     });
 
     it(`fingerprints every route exactly once`, () => {
-        expect(Object.keys(SANDBOX_ROUTE_SHAPES).every((name) => SANDBOX_ROUTE_NAMES.includes(name))).toBe(true);
-        expect(Object.keys(SANDBOX_ROUTE_SHAPES).length).toBe(SANDBOX_ROUTE_NAMES.length);
+        expect(Object.keys(sandboxRouteFingerprints()).every((name) => SANDBOX_ROUTE_NAMES.includes(name))).toBe(true);
+        expect(Object.keys(sandboxRouteFingerprints()).length).toBe(SANDBOX_ROUTE_NAMES.length);
     });
 
     it(`derives a route table with no duplicate names`, () => {
@@ -287,7 +287,7 @@ describe(`the real sandbox contract`, () => {
     // differently has to read as drift rather than as a machine that runs nothing.
     it(`fingerprints the fleet view the device buttons are gated on`, () => {
         expect(sandboxRouteName(`GET`, `/system/devices`)).toBe(`system.devices`);
-        expect(SANDBOX_ROUTE_SHAPES[`system.devices`]).toEqual(expect.any(String));
+        expect(sandboxRouteFingerprints()[`system.devices`]).toEqual(expect.any(String));
     });
 
     it(`resolves a known concrete request back to its contract name`, () => {

package/src/protocol/routes.ts

@@ -1,19 +1,12 @@
-import { eventIterator } from "@orpc/contract";
 import { z } from "zod";
 import type { RouteMeta } from "./route-meta.js";
+import { FRAME, streamOf } from "./stream-of.js";
 
 // Named route surface of the daemon's contract (`<group>.<route>`), derived automatically so nothing here is
 // hand-maintained. The daemon advertises which routes it implements (the /events hello frame); the browser diffs that
 // against its own contract so an old daemon's gap is a named feature check, not a silent 404.
 
-// Every streamed route declares its frames through this, never oRPC's `eventIterator` directly: that returns an opaque
-// standard-schema validator holding no reachable inner schema, so a stream's payload would be unfingerprintable and its
-// drift invisible. The frame schema rides along under a symbol, which oRPC never reads and JSON never serializes.
-// Typed as a plain `symbol`, not the inferred unique one: a unique symbol would ride into every contract's inferred
-// type and break declaration emit on a local name nothing outside can refer to.
-const FRAME: symbol = Symbol.for("intentic.contract.frame");
-
-export const streamOf = <T extends z.ZodType>(frame: T) => Object.assign(eventIterator(frame), { [FRAME]: frame });
+export { streamOf };
 
 // The frame schema behind a streamed route's validator, or undefined for an ordinary request/response schema.
 const frameOf = (schema: unknown): z.ZodType | undefined =>

package/src/protocol/stream-of.ts

@@ -0,0 +1,13 @@
+import { eventIterator } from "@orpc/contract";
+import type * as z from "zod";
+
+// Every streamed route declares its frames through this, never oRPC's `eventIterator` directly: that returns an opaque
+// standard-schema validator holding no reachable inner schema, so a stream's payload would be unfingerprintable and its
+// drift invisible. The frame schema rides along under a symbol, which oRPC never reads and JSON never serializes.
+// Typed as a plain `symbol`, not the inferred unique one: a unique symbol would ride into every contract's inferred
+// type and break declaration emit on a local name nothing outside can refer to.
+// Its own module, apart from routes.ts, because the browser extension's contract streams too and routes.ts reaches
+// zod's namespace at runtime, which the extension's bundle budget cannot carry.
+export const FRAME: symbol = Symbol.for("intentic.contract.frame");
+
+export const streamOf = <T extends z.ZodType>(frame: T) => Object.assign(eventIterator(frame), { [FRAME]: frame });

package/src/schemas/activity.ts

@@ -26,7 +26,7 @@ export const ActivityEventSchema = z.object({
     type: z
         .string()
         .describe(
-            "Exactly what happened: a message received or sent, a reaction, a turn starting or ending, a rule doing something. A rule that ran and passed says nothing here, because a feed of green ticks is one the eye learns to skip.",
+            "Exactly what happened: a message received or sent, a reaction, a turn starting or ending, a rule doing something. A rule that ran and passed says nothing here, because a feed of passes is one the eye learns to skip.",
         ),
     channelId: z.string().optional().describe("Which channel or thread it happened in."),
     // Inbound author display name.

package/src/schemas/agent.ts

@@ -131,7 +131,7 @@ export type ForkedFrom = z.infer<typeof ForkedFromSchema>;
 const AgentTurnFieldsSchema = z.object({
     prompt: z.string().describe("What to say to the agent. May be empty if you are only attaching files."),
     errand: TurnErrandSchema.optional().describe(
-        "What the words are for, when the app or the sandbox composed them rather than a person typing them: a land conflict to resolve, a red CI run to fix. Shown as the sandbox's words, not yours. Leave it out for your own words.",
+        "What the words are for, when the app or the sandbox composed them rather than a person typing them: a land conflict to resolve, a failed CI run to fix. Shown as the sandbox's words, not yours. Leave it out for your own words.",
     ),
     // Minted by the sender so a send whose answer was lost can be sent again without being delivered twice.
     messageId: z
@@ -488,6 +488,9 @@ export type ConversationQueue = z.infer<typeof ConversationQueueSchema>;
 // What resuming a queue did: started a turn with what waited, when nothing else ran.
 export const QueueResumedSchema = z.object({
     run: z.string().optional().describe("The turn the waiting messages started. Absent when a turn was already running, and they go after it."),
+    queue: ConversationQueueSchema.optional().describe(
+        "The queue the release left: what still waits once the turn took what it could. Absent from sandboxes older than the field.",
+    ),
 });
 export type QueueResumed = z.infer<typeof QueueResumedSchema>;
 // Attaches to a conversation's newest run (live, or finished within retention); no cursor to resume from, the head

package/src/schemas/agents.ts

@@ -4,6 +4,7 @@ import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, Conversatio
 import { LoopStateSchema } from "./loops.js";
 import { LimitPolicySchema, RetryPolicySchema, TurnBreakPolicySchema, TurnBreakSchema } from "./turn-break.js";
 import { KeepWarmSchema } from "./keep-warm.js";
+import { AgentNeedSchema } from "./needs.js";
 import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
 // A fleet agent is any conversation with a registry entry, keyed by conversationId. Isolated ones own a git worktree
 // (branch agent/<id>); workspace conversations have none, but both share one status/activity/cost lifecycle.
@@ -56,7 +57,7 @@ export const AgentAttentionSchema = z.object({
     plan: z.boolean().describe("It has proposed a plan and is waiting for a yes."),
     question: z.boolean().describe("It has asked you something."),
     permission: z.boolean().describe("It wants to use a tool it needs permission for."),
-    // A missing capability (capabilities/offers/capability-offer.ts); lets the lane say "setup needed" rather than a generic
+    // A missing capability on a card from before needs (docs/architecture/needs.md); lets the lane say "setup needed" rather than a generic
     // pause.
     capability: z.boolean().describe("It needs something connected that is not connected yet."),
     // A gated credential parked on a named person's click; the one pause the board's reader may not be able to clear
@@ -65,6 +66,11 @@ export const AgentAttentionSchema = z.object({
         .boolean()
         .describe("It is waiting for a named person to release a credential. The one pause that may not be yours to clear, whatever your role."),
     conflict: z.boolean().describe("Its work cannot be merged without somebody resolving a clash."),
+    // A need outlives its turn (docs/architecture/needs.md), so this can stand on a card that is not running at all.
+    need: z
+        .boolean()
+        .optional()
+        .describe("It asked a person for something it still needs: a connection, a secret, wider reach, a tool. Absent from a daemon older than needs."),
 });
 export type AgentAttention = z.infer<typeof AgentAttentionSchema>;
 // What the last turn left open, measured at the moment it ended, unlike AgentAttentionSchema's live parked waits.
@@ -83,7 +89,7 @@ export const UnfinishedWorkSchema = z.object({
         })
         .optional()
         .describe("The agent's own checklist where that turn left it. Absent for a conversation that kept no list."),
-    // Name of the `turn.ending` check still red when the turn ended. Retired with that check: nothing writes it now, and
+    // Name of the `turn.ending` check still failing when the turn ended. Retired with that check: nothing writes it now, and
     // it stays so entries written before still read.
     check: z
         .string()
@@ -92,7 +98,7 @@ export const UnfinishedWorkSchema = z.object({
 });
 export type UnfinishedWork = z.infer<typeof UnfinishedWorkSchema>;
 // What the last turn showed of its own work, read off its tool calls and never asked of the model: the record a card
-// badges instead of sending the turn back to prove anything. CI checks what the owner pushes (push-checks.ts).
+// badges instead of sending the turn back to prove anything. CI checks what the owner pushes (schemas/ci.ts).
 export const TurnProofSchema = z.object({
     at: z.number().describe("When the turn that left this ended, in milliseconds."),
     verification: z
@@ -426,6 +432,32 @@ export const AgentSummarySchema = z.object({
             "Since when somebody's composer has held a message for it that they have not sent yet, in milliseconds. While set, the sandbox never archives it on its own for being idle.",
         ),
     attention: AgentAttentionSchema.describe("Which kinds of waiting-for-you it is doing."),
+    // Beside `attention.permission`, which says only that one waits: the id an answer names and what it asks, so a card
+    // can offer the answer itself instead of a trip to the chat. The oldest one, while its turn runs.
+    permissionAsk: z
+        .object({
+            requestId: z.string().describe("Which request this is: the id an answer to it names."),
+            ask: z.string().describe("What it asks to do, on one line: the runtime's own sentence, else the tool's short name."),
+        })
+        .optional()
+        .describe(
+            "The oldest permission its running turn is waiting on, so it can be answered where the conversation is listed. Absent when none waits, and from a sandbox older than it.",
+        ),
+    // Kept on the record until a land goes through, unlike `failure`, which the next turn clears: a land that broke
+    // leaves the work stuck on its branch however many turns run after it.
+    landFailure: z
+        .object({
+            reason: z.string().describe("Why it failed, in the words it failed with."),
+            code: z
+                .string()
+                .optional()
+                .describe("Which kind of failure it was, when the sandbox could tell: unlinked when its copy lost its link to the workspace. Absent otherwise."),
+            at: z.number().describe("When it failed, in milliseconds."),
+        })
+        .optional()
+        .describe(
+            "The last attempt to bring its work into the workspace failed, and why. Cleared by the next land that goes through. Absent when nothing failed, and from a sandbox older than it.",
+        ),
     // Only the causes that still hold, re-read live (conversations/land/standing.ts), never the stored report's own list: a
     // blocker the user has since cleared is not something to offer them an action about.
     conflictCauses: z
@@ -446,8 +478,8 @@ export const AgentSummarySchema = z.object({
     // Completed turns and lifetime tool calls, the card's msgs/tools counters.
     turns: z.number().optional().describe("Turns it has finished."),
     toolUses: z.number().optional().describe("Tools it has used, over its whole life."),
-    // `running` reads the live subagent registry (swept after five minutes), `total` counts on the agent's own entry; a
-    // child's spend is its own, never folded into the parent's cost.
+    // `running` reads the live subagent roster, `total` counts on the agent's own entry; a child's spend is its own,
+    // never folded into the parent's cost.
     subagents: z
         .object({
             running: z.number().describe("Subagents working right now."),
@@ -473,6 +505,25 @@ export const AgentSummarySchema = z.object({
         .object({
             landed: z.number().describe("Paths this conversation merged in."),
             present: z.number().describe("How many of them are still there, either pending or committed."),
+            // Read off who acted on the tree between the land and the moment it was found missing; only a sole candidate
+            // is named, so an unattributed removal says nothing rather than guessing.
+            removedBy: z
+                .discriminatedUnion("kind", [
+                    z.object({
+                        kind: z.literal("agent"),
+                        id: z.string().describe("The conversation that took them out."),
+                        title: z.string().optional().describe("What that conversation is called."),
+                    }),
+                    z.object({
+                        kind: z.literal("person"),
+                        email: z.string().optional().describe("Who it was, as the sandbox verified them. Absent when the request carried no identity."),
+                        name: z.string().optional().describe("What to call them, when their sign-in carried a name."),
+                    }),
+                ])
+                .optional()
+                .describe(
+                    "Who took them out, when the sandbox could tell: an agent working in the workspace, or a person throwing the changes away. Absent when it could not tell, and from a sandbox older than it.",
+                ),
         })
         .optional()
         .describe(
@@ -527,6 +578,13 @@ export const AgentSummarySchema = z.object({
         .describe(
             "Outside conditions this conversation is parked on, each of which will wake it. Absent means none, which is nearly every conversation: an armed watch is why a finished-looking agent starts working by itself, and why a hosted machine will not go idle.",
         ),
+    // Kept in the needs store, so unlike `jobs` this survives a restart and stands while the conversation is idle.
+    needs: z
+        .array(AgentNeedSchema)
+        .optional()
+        .describe(
+            "What it is waiting on people for and has not got yet, oldest first. Absent means nothing: an open need is why an idle-looking agent still needs you.",
+        ),
     // In memory only: a daemon restart leaves transcript rows naming jobs this list no longer carries.
     jobs: z
         .array(
@@ -580,6 +638,12 @@ export const awaitsWake = (agent: { readonly awaitingWake?: boolean | undefined
 export type AgentWatch = NonNullable<AgentSummary["watches"]>[number];
 // One background job as a card carries it.
 export type AgentJob = NonNullable<AgentSummary["jobs"]>[number];
+// Who took landed work out of the workspace, as the card names them.
+export type LandedRemover = NonNullable<NonNullable<AgentSummary["landedPresence"]>["removedBy"]>;
+// A land that broke, kept on the card until one goes through.
+export type LandFailure = NonNullable<AgentSummary["landFailure"]>;
+// The permission a running turn waits on, as a card can answer it.
+export type WaitingPermission = NonNullable<AgentSummary["permissionAsk"]>;
 // AgentsListSchema is declared later, after AutomationApprovalSchema, since the fleet list carries held wakes and zod
 // needs that type declared first.
 export const AgentIdSchema = z.object({ id: z.string().min(1).describe("Which conversation.") });
@@ -610,6 +674,9 @@ export const AgentTranscriptQuerySchema = AgentIdSchema.extend({
 export const AgentToolChildrenQuerySchema = AgentIdSchema.extend({
     toolId: z.string().min(1).describe("Which tool call, by the id its card carries."),
 });
+export const AgentSubagentQuerySchema = AgentIdSchema.extend({
+    subagentId: z.string().min(1).describe("Which subagent this conversation's runtime ran in-process, by the id of the call that started it."),
+});
 // Absent `ids` archives every archivable finished agent (the lane's "Clear"); unarchive always names its own ids.
 export const AgentIdsSchema = z.object({ ids: z.array(z.string().min(1)).min(1).max(500).describe("Which conversations.") });
 // What actually moved, not the roster afterward: two archives finishing at once would otherwise let a slower snapshot

package/src/schemas/automations.ts

@@ -29,7 +29,7 @@ import { ZoneSchema } from "../time/zone.js";
 // turn.settled: fires once per isolated turn regardless of outcome, while the diff is still on screen
 // agent.landed: fires only once work reaches the main tree, including a later manual Land
 // deps.broken/deps.fixed: retired with the check that ran after every land (2026-09-27). Nothing emits them any more;
-// they stay so an automation written for them still reads, and it never fires. Main's red CI is the `ci` listener's.
+// they stay so an automation written for them still reads, and it never fires. Main's failing CI is the `ci` listener's.
 export const WorkspaceEventKindSchema = z.enum(["turn.settled", "agent.landed", "deps.broken", "deps.fixed"]);
 export type WorkspaceEventKind = z.infer<typeof WorkspaceEventKindSchema>;
 // Payload of a workspace-triggered wake, delivered as JSON in $AUTOMATION_PAYLOAD and appended to the prompt.
@@ -45,7 +45,7 @@ export const WorkspaceEventSchema = z.object({
     outcome: z.enum(["landed", "conflict", "ready", "idle", "error"]),
     repos: z.array(z.object({ repo: z.string(), from: z.string(), dir: z.string() })),
     // Present only for `deps.*` events: which project broke, the command and exit code, a bounded log tail, and
-    // `attempt` counting consecutive reds since the last green.
+    // `attempt` counting consecutive failures since the last pass.
     deps: z
         .object({
             project: z.string(),

package/src/schemas/capabilities.ts

@@ -104,6 +104,15 @@ export const SshConfigSchema = z.discriminatedUnion("auth", [
         user: z.string().min(1).describe("Which user to connect as."),
         privateKey: z.string().min(1).describe("The private key, whole. Stored with tight permissions and never echoed back."),
     }),
+    // The sandbox made this key itself (capabilities.sshKey), so its private half never crossed the wire; stored and
+    // written exactly like a pasted one.
+    z.object({
+        auth: z.literal("generated").describe("Sign in with a key the sandbox generated. Its private half never left the sandbox."),
+        host: z.string().min(1).describe("The machine's address."),
+        port: z.coerce.number().default(22).describe("Which port it listens on."),
+        user: z.string().min(1).describe("Which user to connect as."),
+        privateKey: z.string().min(1).describe("The private half of the generated key. Stored with tight permissions and never echoed back."),
+    }),
     z.object({
         auth: z.literal("password").describe("Sign in with a password."),
         host: z.string().min(1).describe("The machine's address."),
@@ -112,6 +121,14 @@ export const SshConfigSchema = z.discriminatedUnion("auth", [
         password: z.string().min(1).describe("The password. Stored, never echoed back."),
     }),
 ]);
+// What a form sends where a generated key's private half goes: the token capabilities.sshKey answered with, which the
+// add swaps for the key the daemon kept. VAULTED's sibling (policy/capability-secrets.ts) for a value not stored yet; a
+// marker with nothing held behind it is refused, never written.
+const STASHED_PREFIX = "__intentic_stashed__:";
+export const stashedMarker = (token: string): string => `${STASHED_PREFIX}${token}`;
+// The token a marker names; undefined for anything else (a real key, VAULTED, a blank).
+export const stashedToken = (value: unknown): string | undefined =>
+    typeof value === "string" && value.startsWith(STASHED_PREFIX) && value.length > STASHED_PREFIX.length ? value.slice(STASHED_PREFIX.length) : undefined;
 // What is optional about the in-sandbox Docker Engine: `gpu` is an IMAGE option (rides the Dockerfile overlay, needs a
 // rebuild), everything else is an ENGINE option (rewrites daemon.json, restarts dockerd, no rebuild but stops running
 // containers). Flat strings, not nested booleans, to match the manifest's own two-state convention.
@@ -227,7 +244,8 @@ export const LOCAL_MODEL_WINDOW_MAX = 1_048_576;
 // against.
 export const LOCAL_MODEL_KV_BYTES_PER_TOKEN = 65_536;
 // What a rung honestly serves. `instant` is the one the connect view prefetches — it downloads in under a minute and
-// cannot drive a full agent turn, so no surface may sell it as one; `work` is what that view recommends for real use.
+// cannot drive a full agent turn, so its catalog row is helper-only (Model.helperOnly): the chat picker does not offer
+// it and the daemon refuses a turn on it. `work` is what that view recommends for real use.
 export type LocalModelTier = "instant" | "work";
 export interface LocalModelChoice {
     // Hugging Face owner/repo/file.gguf, exactly as LocalModelConfig.model carries it.
@@ -237,21 +255,57 @@ export interface LocalModelChoice {
     // estimate all read this, so a model cannot be priced two ways.
     readonly weightsBytes: number;
     readonly tier: LocalModelTier;
+    // The repository commit the file is fetched at, a sha and never a branch: `main` moves, and a re-upload under the
+    // same name would change what a card promised without the card changing.
+    readonly revision: string;
+    // The file's own sha256 at that commit (its LFS oid). A download that does not hash to it is deleted, not served.
+    readonly sha256: string;
 }
-// The curated list, smallest first. ponytail: these bytes are the Hugging Face tree API's answer for each file — the
+// The curated list, smallest first. ponytail: sizes, revisions and digests are the Hugging Face API's answer for each
+// file (`/api/models/<repo>/revision/main` for the sha, `/tree/<sha>` for the size and LFS oid), read 2026-09-29 — the
 // hand-written labels that predated them overstated gemma-4 12B by 2x and Qwen3.8 27B by a third, which is the class of
-// drift a machine-readable size exists to end.
+// drift a machine-readable size exists to end. Bump a row's three together: each belongs to its revision.
 export const LOCAL_MODELS: readonly LocalModelChoice[] = [
-    { id: "unsloth/Qwen3.5-2B-GGUF/Qwen3.5-2B-Q4_K_M.gguf", label: "Qwen3.5 2B", weightsBytes: 1_280_835_840, tier: "instant" },
+    {
+        id: "unsloth/Qwen3.5-2B-GGUF/Qwen3.5-2B-Q4_K_M.gguf",
+        label: "Qwen3.5 2B",
+        weightsBytes: 1_280_835_840,
+        tier: "instant",
+        revision: "f6d5376be1edb4d416d56da11e5397a961aca8ae",
+        sha256: "aaf42c8b7c3cab2bf3d69c355048d4a0ee9973d48f16c731c0520ee914699223",
+    },
     {
         id: "unsloth/Phi-4-mini-instruct-GGUF/Phi-4-mini-instruct-Q4_K_M.gguf",
         label: "Phi-4-mini 3.8B",
         weightsBytes: 2_491_874_272,
         tier: "work",
+        revision: "78eb92a46fc37e6b524df991ed9aca9bc6aa7b80",
+        sha256: "88c00229914083cd112853aab84ed51b87bdf6b9ce42f532d8c85c7c63b1730a",
+    },
+    {
+        id: "unsloth/Qwen3.5-9B-GGUF/Qwen3.5-9B-Q4_K_M.gguf",
+        label: "Qwen3.5 9B",
+        weightsBytes: 5_680_522_464,
+        tier: "work",
+        revision: "3885219b6810b007914f3a7950a8d1b469d598a5",
+        sha256: "03b74727a860a56338e042c4420bb3f04b2fec5734175f4cb9fa853daf52b7e8",
+    },
+    {
+        id: "unsloth/gemma-4-12b-it-GGUF/gemma-4-12b-it-Q4_K_M.gguf",
+        label: "Gemma 4 12B",
+        weightsBytes: 7_121_861_440,
+        tier: "work",
+        revision: "fc034cfff751157913579611efad8462ac1be606",
+        sha256: "0a270ec9fe6b34f4a0d33992b6135117b484ebc4766ab76b51d4ae8c457e4c42",
+    },
+    {
+        id: "unsloth/Qwen3.8-27B-GGUF/Qwen3.8-27B-UD-Q4_K_M.gguf",
+        label: "Qwen3.8 27B",
+        weightsBytes: 16_464_440_224,
+        tier: "work",
+        revision: "4ca720788d1e01f1bff70c033e0d0028fd02e502",
+        sha256: "322e194ff79741c7baa497c240f677f54b201b0efab44ca8e50f122b39123482",
     },
-    { id: "unsloth/Qwen3.5-9B-GGUF/Qwen3.5-9B-Q4_K_M.gguf", label: "Qwen3.5 9B", weightsBytes: 5_680_522_464, tier: "work" },
-    { id: "unsloth/gemma-4-12b-it-GGUF/gemma-4-12b-it-Q4_K_M.gguf", label: "Gemma 4 12B", weightsBytes: 7_121_861_440, tier: "work" },
-    { id: "unsloth/Qwen3.8-27B-GGUF/Qwen3.8-27B-UD-Q4_K_M.gguf", label: "Qwen3.8 27B", weightsBytes: 16_464_440_224, tier: "work" },
 ];
 export const localModelChoice = (id: string): LocalModelChoice | undefined => LOCAL_MODELS.find((choice) => choice.id === id);
 // Exactly one row carries the instant tier; the fit module and the prefetch route take it from here rather than
@@ -460,3 +514,14 @@ export const CapabilityProbeSchema = z.object({
     who: z.string().optional().describe("Who the service said the credential belongs to, when it said."),
 });
 export type CapabilityProbe = z.infer<typeof CapabilityProbeSchema>;
+// POST /capabilities/ssh-key: a key pair made inside the sandbox for a connection being set up. The public half is the
+// whole answer; the private half stays in the daemon until an add sends `stashedMarker(token)` where it goes.
+export const SshKeySchema = z.object({
+    publicKey: z.string().describe("The public half, as the one line a server's authorized_keys holds: `ssh-ed25519 AAAA… intentic-<sandbox>`."),
+    token: z
+        .string()
+        .describe(
+            "Stands for the private half, which never leaves the sandbox. Sent wrapped as a marker in the private key's place, it installs that key once, and it lapses after thirty minutes.",
+        ),
+});
+export type SshKey = z.infer<typeof SshKeySchema>;

package/src/schemas/ci.ts

@@ -1,7 +1,6 @@
 // ci: pipeline runs on the workspace repos' github/gitlab remotes
 import { z } from "zod";
 import { AgentRunPickSchema } from "./agent.js";
-import { RedDecisionSchema } from "./workspace/push-checks.js";
 // The daemon maps each workspace repo to its CI project via a connected github/gitlab capability, registers a webhook
 // to fire `ci` listener automations instantly, and serves the Pipelines rail from a webhook-freshened, poll-backfilled
 // cache. `host` names which provider API serves a repo; the listener provider is always `ci`, since a trigger narrows
@@ -112,31 +111,72 @@ export type CiRepo = z.infer<typeof CiRepoSchema>;
 // Fallback poll interval when a repo's webhook couldn't register; lives here since both the poller and the automation
 // editor need it to tell the owner what a `hookWarning` actually costs (minutes' delay, not the feature).
 export const CI_POLL_INTERVAL_MS = 2 * 60_000;
-// Main's CI while it is red, as the daemon's one fix agent on it sees it (ci/main-fixer.ts): from the first job that
-// failed until a later run of every workflow that failed on it passes, whatever else failed along the way.
-export const CiMainRedSchema = z.object({
+// What was decided about a main-line branch while its CI fails, in the order it was decided (ci/main-fixer.ts).
+export const MainFailureDecisionKindSchema = z.enum([
+    // Its one fix agent was put on it: by the sandbox at the first job that failed, or by a person's Fix press, which
+    // gives the agent its turns back.
+    "fix-up",
+    // Nobody was sent: repairs are switched off, or nothing could take it.
+    "reported",
+    // The fix agent had its turns, or stopped without a fix: it waits for a person.
+    "spent",
+]);
+export type MainFailureDecisionKind = z.infer<typeof MainFailureDecisionKindSchema>;
+
+// Why the fix agent handed the failure back (a `spent` decision), as a closed set the editor words for itself, so what a
+// reader sees stays a few words in every language rather than whatever the turn's error happened to say.
+export const MainFailureHandBackSchema = z.enum([
+    // It had every turn the sandbox gives one failure, and main still fails.
+    "turns",
+    // Its turn ended without changing anything, so the failure is likely not in the code.
+    "no-change",
+    // A person stopped it.
+    "stopped",
+    // Its turn was cut off.
+    "interrupted",
+    // Its turn failed.
+    "turn-failed",
+    // Its conversation is gone or archived.
+    "gone",
+    // It could not be told about the newest failure.
+    "refused",
+]);
+export type MainFailureHandBack = z.infer<typeof MainFailureHandBackSchema>;
+
+export const MainFailureDecisionSchema = z.object({
+    kind: MainFailureDecisionKindSchema.describe("What was decided."),
+    reason: MainFailureHandBackSchema.optional().describe("Why the fix agent handed it back, on a `spent` decision."),
+    conversationId: z.string().optional().describe("The conversation working on it, when one is."),
+    at: z.number().describe("When that was decided, in milliseconds."),
+    detail: z.string().optional().describe("One short sentence on why, in the sandbox's words."),
+});
+export type MainFailureDecision = z.infer<typeof MainFailureDecisionSchema>;
+
+// A main-line branch while its CI fails, as the daemon's one fix agent on it sees it (ci/main-fixer.ts): from the first
+// job that failed until a later run of every workflow that failed on it passes, whatever else failed along the way.
+export const CiMainFailureSchema = z.object({
     repo: z.string().describe("Which workspace repository."),
     branch: z.string().describe("Which main-line branch."),
     since: z.number().describe("When its first job failed, in milliseconds."),
     runId: z.number().describe("The newest run that failed on it."),
-    jobs: z.array(z.string()).describe("The jobs failing on it now, by name: the newest red run's failures, and any that failed since."),
+    jobs: z.array(z.string()).describe("The jobs failing on it now, by name: the newest failed run's failures, and any that failed since."),
     fixer: z
         .string()
         .optional()
-        .describe("The one conversation working on it, which every failure goes to until the branch is green. Absent while nobody is on it."),
-    decision: RedDecisionSchema.optional().describe(
+        .describe("The one conversation working on it, which every failure goes to until the branch passes. Absent while nobody is on it."),
+    decision: MainFailureDecisionSchema.optional().describe(
         "The latest thing decided about it: `fix-up` while the fix agent has it, `spent` once it waits for you (its turns are used up, or it stopped without a fix), `reported` when repairs are off.",
     ),
 });
-export type CiMainRed = z.infer<typeof CiMainRedSchema>;
+export type CiMainFailure = z.infer<typeof CiMainFailureSchema>;
 export const CiRunsResponseSchema = z.object({
     repos: z.array(CiRepoSchema).describe("Which workspace repositories are wired to a forge, and how each one's notifications are set up."),
     // Newest first, across all mapped repos.
     runs: z.array(PipelineRunSchema).describe("Runs across all of them, newest first."),
-    reds: z
-        .array(CiMainRedSchema)
+    failures: z
+        .array(CiMainFailureSchema)
         .optional()
-        .describe("Every main-line branch red right now, with the fix agent on it. Absent from a daemon that keeps none."),
+        .describe("Every main-line branch failing right now, with the fix agent on it. Absent from a daemon that keeps none."),
 });
 export type CiRunsResponse = z.infer<typeof CiRunsResponseSchema>;
 // Re-resolves repo → project + token on every call, so a stale card can't act on a mapping the workspace no longer has.
@@ -155,6 +195,11 @@ export const CiFixParamSchema = CiRunParamSchema.extend({
     pick: AgentRunPickSchema.describe(
         "Which model to open the conversation on, when somebody chose one. Leave it out for the sandbox's own choice, which is the ordinary path.",
     ),
+    // The browser's own chat pick, which the daemon never holds: without it an unpinned fix opened on a provider the
+    // owner never chose. Absent (an older app, or nobody pressed) keeps the sandbox's own fallback.
+    fallback: AgentRunPickSchema.describe(
+        "The model a new chat opens on for whoever pressed, for when nobody chose one and no model set for fixing pipelines can run. Used while this sandbox can serve its provider; left out, or not servable, the sandbox takes its default provider when connected, else the first one connected.",
+    ),
     // The verb the picker's bar was ended with, when an attempt already exists (state/fix-attempt-plan.ts). Left out,
     // an ended attempt is continued and a fresh press opens attempt 1; one still in play answers CONFLICT.
     mode: z