@intentic/sandbox-contract 1.317.0 → 1.318.0

package/src/schemas/context-trim.ts

@@ -1,5 +1,6 @@
 // context-trim: what a window too small for a full turn made the sandbox leave out
 import { z } from "zod";
+import type { SandboxNotice } from "../events/sandbox-notice.js";
 
 // The only disclosure of a note that never rode; without it a turn runs thinner and nothing on screen says why.
 export const ContextTrimSchema = z.object({
@@ -18,12 +19,16 @@ export type ContextTrim = z.infer<typeof ContextTrimSchema>;
 // 16k, 32k; a server's own odd number spelled out in full.
 const windowLabel = (tokens: number): string => (tokens % 1024 === 0 ? `${tokens / 1024}k` : tokens.toLocaleString("en-US"));
 
+/** The trim's notice by code and facts, for a reader that words it in its own language. */
+export const contextTrimNotice = ({ window, omitted, base }: ContextTrim): Extract<SandboxNotice, { code: "contextTrim" }> => ({
+    code: "contextTrim",
+    params: { window: windowLabel(window), ...(omitted.length === 0 ? {} : { omitted: omitted.join(`, `) }), base },
+});
+
 // The closing clause is load-bearing: without it the row reads as "my AGENTS.md may not have arrived".
-export const contextTrimLine = ({ window, omitted, base }: ContextTrim): string => {
+export const contextTrimLine = (trim: ContextTrim): string => {
+    const { window, omitted, base } = contextTrimNotice(trim).params;
     const swapped = base ? ` The agent's own base instructions were swapped for a short paragraph, too.` : ``;
-    const left = omitted.length === 0 ? `` : ` — left out: ${omitted.join(`, `)}`;
-    return (
-        `Sent thin for this model's ${windowLabel(window)} window${left}.${swapped}` +
-        ` Your workspace rules, this turn's persona and where its files live still rode.`
-    );
+    const left = omitted === undefined ? `` : ` — left out: ${omitted}`;
+    return `Sent thin for this model's ${window} window${left}.${swapped}` + ` Your workspace rules, this turn's persona and where its files live still rode.`;
 };

package/src/schemas/devices.ts

@@ -178,8 +178,10 @@ export const icShapeArgs = (slug: string, fields: SandboxShapeFields, when: Sand
 export const icForgetShapeArgs = (slug: string): string[] => ["sandbox", "shape", slug, "--forget"];
 // Power goes through ic too, so a Start or Restart from any door applies the shape saved for the next restart.
 export const icPowerArgs = (op: "start" | "stop" | "restart", slug: string): string[] => ["sandbox", op, slug];
-// Adds the device id to the flow input; the daemon looks up machines by id.
-export const DeviceSandboxFlowInputSchema = DeviceSandboxFlowSchema.extend({ id: z.string().min(1) });
+// Adds the device id to the flow input; the daemon looks up machines by id. `resumeTurns` is the owner saying, as they
+// restart the sandbox relaying this, that the turns it cuts should run again once it is back; the daemon keeps it for
+// its next boot and never forwards it to the machine. A sandbox older than it ignores it, and the cut turns wait.
+export const DeviceSandboxFlowInputSchema = DeviceSandboxFlowSchema.extend({ id: z.string().min(1), resumeTurns: z.boolean().optional() });
 export type DeviceSandboxFlowInput = z.infer<typeof DeviceSandboxFlowInputSchema>;
 // Streamed operation output, matching `IntenticLineSchema`: `line` frames as printed, then one terminal frame, `result`
 // or `error`, carrying the machine's own message rather than a code.
@@ -374,6 +376,9 @@ export const DevicePairingSchema = z.object({
     mode: z.enum(["sync", "mirror"]),
     // Set only for mode "sync", and only for the sandbox being reported to.
     localDir: z.string().optional(),
+    // Which sandbox folder `localDir` holds when it is not /work itself: a project pairing's `/work/<name>`, the
+    // owner's own folder, which carries no state backup and no git bridge. Absent means /work.
+    remoteDir: z.string().optional(),
     // Machine-owned switch (agent's own `sync mirror off`); absent reads as "on", not merely unknown.
     mirroring: z.enum(["on", "off"]).optional(),
     // Mutagen's own status word, kept verbatim rather than reduced to a traffic light.
@@ -512,6 +517,37 @@ export const DeviceSyncSchema = z.object({
     environment: z.string().optional(),
 });
 export type DeviceSync = z.infer<typeof DeviceSyncSchema>;
+
+// A public host key as a machine pins it in known_hosts: its type and base64 body, no comment and nothing after.
+export const SshHostKeySchema = z
+    .string()
+    .regex(/^(?:ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(?:256|384|521)|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com) [A-Za-z0-9+/]+={0,2}$/);
+
+// POST /system/authorized-key: a machine's agent enrolling its SSH key for desktop sync, redeeming a pairing token.
+// Every field past `key` is optional: an older agent sends none of them and is still enrolled.
+export const SyncEnrollmentRequestSchema = z.object({
+    // One authorized_keys line; its comment is the name the enrollment goes by (`DeviceSync.machine`).
+    key: z.string(),
+    // The computer and the environment on it that are enrolling, so the enrollment joins that machine's card.
+    machineId: MachineIdSchema.optional(),
+    environment: z.string().min(1).optional(),
+});
+export type SyncEnrollmentRequest = z.infer<typeof SyncEnrollmentRequestSchema>;
+
+// The daemon's answer to an enrollment. Every field is optional for the agent reading it, since each arrived in a later
+// daemon than the route: without `syncToken` the agent refuses the enrollment, without `mode` it reads "sync", and
+// without `hostKey` it falls back to recording whatever key the sandbox presents first.
+export const SyncEnrollmentAnswerSchema = z.object({
+    ok: z.literal(true).optional(),
+    // Authorizes the ports poll, the machine report and the SSH transport, sent as `x-intentic-sync`.
+    syncToken: z.string().optional(),
+    // What the pairing granted: a member's pairing only ever enrolls "mirror".
+    mode: z.enum(["sync", "mirror"]).optional(),
+    // The public key the sandbox's sshd presents (an SshHostKeySchema line), for the agent to pin under the pairing's
+    // alias. Checked by the agent on its own, so a key it cannot read costs the pin, never the enrollment.
+    hostKey: z.string().optional(),
+});
+export type SyncEnrollmentAnswer = z.infer<typeof SyncEnrollmentAnswerSchema>;
 export const DeviceSchema = z.object({
     // Stable row key: the reported hostname when either door produced one, else the name that door knows it by.
     key: z.string(),

package/src/schemas/environment.ts

@@ -40,10 +40,17 @@ export const RuntimeInstallSchema = z.object({
     declinedAt: z.number().optional(),
 });
 export type RuntimeInstall = z.infer<typeof RuntimeInstallSchema>;
+// A draft the owner already answered (approved, removed or declined), by its tool and the hash of its steps: the same
+// file coming back with an agent's land, which still carries it on its branch, proposes nothing. An agent asking again
+// (`environment propose`) clears its tool's entries.
+export const SettledDraftSchema = z.object({ tool: z.string(), hash: z.string(), at: z.number() });
+export type SettledDraft = z.infer<typeof SettledDraftSchema>;
 export const RuntimeInstallsFileSchema = z.object({
     installs: z.array(RuntimeInstallSchema),
     // The last drift snapshot, persisted so a daemon restart does not blank the card until the next sweep.
     drift: EnvironmentDriftSchema.optional(),
+    // Drafts already answered, newest last and capped; absent on a ledger written before removal existed.
+    settled: z.array(SettledDraftSchema).optional(),
 });
 export type RuntimeInstallsFile = z.infer<typeof RuntimeInstallsFileSchema>;
 // Ledger entry as the Environment card shows it: recurrence joined with whether it's present in the live container
@@ -74,6 +81,26 @@ export type EnvironmentRuntimeDecision = z.infer<typeof EnvironmentRuntimeDecisi
 // there (SANDBOX_DEV_ROOT), absent on a sandbox that was handed a local image without one.
 export const EnvironmentLocalImageSchema = z.object({ base: z.string(), root: z.string().optional() });
 export type EnvironmentLocalImage = z.infer<typeof EnvironmentLocalImageSchema>;
+// A rebuild the owner asked to start by itself once no agent is mid-turn, kept by the sandbox rather than the page that
+// asked, so a page closed or a phone locked meanwhile does not lose it. Held in the sandbox's memory: a restart of the
+// sandbox for any other reason drops it, and the card offers the rebuild again.
+export const EnvironmentRebuildWaitSchema = z.object({
+    // The approved overlay it builds, and the connected device that runs it.
+    hash: z.string(),
+    host: z.string(),
+    requestedAt: z.number(),
+    // waiting: until no agent is mid-turn. rebuilding: handed to the device, which restarts this sandbox at the end.
+    // failed: the device refused or could not be reached; said until the owner dismisses it or asks again.
+    phase: z.enum(["waiting", "rebuilding", "failed"]),
+    // Who it waits on, by the title the board shows them under; empty once it is no longer waiting.
+    waitingOn: z.array(z.string()),
+    // The device's own words for a failed one.
+    message: z.string().optional(),
+});
+export type EnvironmentRebuildWait = z.infer<typeof EnvironmentRebuildWaitSchema>;
+// Asks for that rebuild: the approved overlay's hash and the device that rebuilds this sandbox.
+export const EnvironmentRebuildWhenIdleSchema = z.object({ host: z.string().min(1), hash: z.string().min(1) });
+export type EnvironmentRebuildWhenIdle = z.infer<typeof EnvironmentRebuildWhenIdleSchema>;
 export const EnvironmentSchema = z.object({
     proposal: environmentFileSchema.optional(),
     // The owner-approved agent-written custom section (.intentic/config/environment.custom.Dockerfile).
@@ -89,6 +116,12 @@ export const EnvironmentSchema = z.object({
     recurring: z.array(EnvironmentRecurringSchema).optional(),
     // Absent on a sandbox running a published image, which is every sandbox but a dogfooding one.
     localImage: EnvironmentLocalImageSchema.optional(),
+    // A rebuild waiting for the agents to be idle, or started or refused once they were; absent when none is asked.
+    rebuildWhenIdle: EnvironmentRebuildWaitSchema.optional(),
+    // This sandbox can hold a rebuild until no agent is mid-turn (POST /environment/rebuild-when-idle), and resume the
+    // turns a restart the owner starts cuts when asked (a device swap's `resumeTurns`). Absent from one too old to,
+    // where the rebuild dialog offers only "Rebuild now" and the cut turns wait to be continued, as before.
+    waitsForAgents: z.literal(true).optional(),
 });
 export type Environment = z.infer<typeof EnvironmentSchema>;
 export const EnvironmentApproveSchema = z.object({ hash: z.string().min(1) });
@@ -127,8 +160,14 @@ export const EnvironmentItemSchema = z.object({
     detail: z.string().optional(),
     // The block's own instruction lines, for the reader who wants to see exactly what runs.
     commands: z.string().optional(),
+    // The custom-section block this row is, which the owner may take out (POST /environment/remove names it). Absent
+    // on capability and base rows, and from a sandbox that cannot remove one, so no Remove is offered there.
+    block: z.string().optional(),
 });
 export type EnvironmentItem = z.infer<typeof EnvironmentItemSchema>;
+// Takes one tool out of the environment: its approved block, its pending draft, or both.
+export const EnvironmentRemoveSchema = z.object({ block: z.string() });
+export type EnvironmentRemove = z.infer<typeof EnvironmentRemoveSchema>;
 export const EnvironmentContentsSchema = z.object({ items: z.array(EnvironmentItemSchema) });
 export type EnvironmentContents = z.infer<typeof EnvironmentContentsSchema>;
 // A sandbox is four stores: /work, /history, the container, and the AI-provider credential root. A bundle carries only

package/src/schemas/git/git.ts

@@ -86,7 +86,7 @@ export const PushSchema = RepoParamSchema.extend({
 });
 // Who said no to a push, read off git's own words (`pushRefusal`); the three answers ask three different things of the
 // owner.
-// hook: this repo's own pre-push hook refused it; the code is known wrong, worth a fix.
+// hook: this repo's own pre-push hook refused it; what it printed is about the code, and the terminal holds all of it.
 // remote: the server rejected the refs (non-fast-forward, protected branch); pull first or push elsewhere.
 // transport: it never got there (credentials, unreachable host); a retry is the only useful button.
 export const PushRefusalSchema = z.enum(["hook", "remote", "transport"]);
@@ -100,7 +100,7 @@ export const PushRunSchema = CommandRunSchema.extend({
         .optional()
         .describe("Why not, in git's own words: the last verdict line, for a row that has room for one line. The whole tail is `output`."),
     refusedBy: PushRefusalSchema.optional().describe(
-        "Who refused a failed push: this repository's pre-push hook (the code is wrong, a fix is worth proposing), the remote (pull first), or the transport (credentials, network: retry). Absent while it runs and for a push that went.",
+        "Who refused a failed push: this repository's own pre-push hook (what it printed is about the code), the remote (pull first), or the transport (credentials, network: retry). Absent while it runs and for a push that went.",
     ),
 });
 export type PushRun = z.infer<typeof PushRunSchema>;
@@ -389,6 +389,17 @@ export const AgentChangeSchema = GitChangeSchema.extend({
         ),
 });
 export type AgentChange = z.infer<typeof AgentChangeSchema>;
+// One manifest's new dependency names: the file at the delta's anchor against the file as it stands now, so a review
+// can say what the project takes on before it lands.
+export const AddedDependenciesSchema = z.object({
+    path: z.string().describe("The manifest, relative to the repository root, such as video/package.json."),
+    added: z
+        .array(z.string())
+        .describe(
+            "The names it declares now and did not declare before, sorted. Only new names: a version bump of a dependency already there is not listed.",
+        ),
+});
+export type AddedDependencies = z.infer<typeof AddedDependenciesSchema>;
 // An agent worktree's delta vs its base, deliberately not RepoChanges: no index here, so sharing that shape would force
 // an empty `staged` and a staging affordance that cannot work on a worktree nobody checks out.
 export const AgentRepoChangesSchema = z.object({
@@ -401,6 +412,13 @@ export const AgentRepoChangesSchema = z.object({
         .describe(
             "The packages of the tree these changes came from, so a review can group by package. Carried with the changes rather than looked up separately, because a package the conversation has just created exists only in its own copy and the shared tree has never heard of it.",
         ),
+    // Absent rather than empty when nothing was added, the common case.
+    addedDependencies: z
+        .array(AddedDependenciesSchema)
+        .optional()
+        .describe(
+            "Dependencies the changed manifests here declare that they did not before (package.json, pyproject.toml, requirements.txt), one entry per manifest that gained any. The review is where a new dependency is approved: a conversation installs freely in its own copy, and this is what the project takes on if the work lands. Absent when none was added.",
+        ),
 });
 export type AgentRepoChanges = z.infer<typeof AgentRepoChangesSchema>;
 // The review, plus why the last land refused: a conflict is found when the turn ends but resolved later on this

package/src/schemas/hosts.ts

@@ -70,11 +70,14 @@ export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 //   Both features ride that verb, so an agent advertises both or neither.
 // - `rollback-to`: the `rollback` op's `to`, going back to an older version kept on the machine rather than the
 //   previous one; advertised only when the agent's `ic sandbox rollback` takes `--to`.
-export const DeviceFeatureSchema = z.enum(["reshape-later", "set-shape", "rollback-to"]);
+// - `loopback-catch`: the `catchLoopback` procedure, a sign-in's loopback redirect caught on this machine
+//   (loopback-catch.ts); an agent without it rejects the call as an unknown procedure.
+export const DeviceFeatureSchema = z.enum(["reshape-later", "set-shape", "rollback-to", "loopback-catch"]);
 export type DeviceFeature = z.infer<typeof DeviceFeatureSchema>;
 export const DEVICE_FEATURE_RESHAPE_LATER: DeviceFeature = "reshape-later";
 export const DEVICE_FEATURE_SET_SHAPE: DeviceFeature = "set-shape";
 export const DEVICE_FEATURE_ROLLBACK_TO: DeviceFeature = "rollback-to";
+export const DEVICE_FEATURE_LOOPBACK_CATCH: DeviceFeature = "loopback-catch";
 // The features an agent advertised that this build knows; an unknown one is a newer agent's and means nothing here.
 export const deviceFeatures = (facts: Pick<DeviceFacts, "features"> | undefined): DeviceFeature[] =>
     (facts?.features ?? []).flatMap((feature) => {

package/src/schemas/keep-warm.ts

@@ -2,6 +2,7 @@
 // clock lives here; how many refreshes a hold may spend is priced by the provider that serves it (runtimes/claude).
 
 import { z } from "zod";
+import type { SandboxNotice } from "../events/sandbox-notice.js";
 
 // A cache clock as the daemon publishes it: the last request that touched the entry, and the entry's lifetime.
 export interface CacheClock {
@@ -95,16 +96,28 @@ const spanLabel = (ms: number): string => {
     return hours === 0 ? `${minutes}m` : `${hours}h ${minutes % 60}m`;
 };
 
-/** The transcript's line for a turn that picked up a conversation kept warm for it; undefined for any other turn. */
-export const keptWarmLine = (opening: PromptCacheOpening): string | undefined => {
+/** The notice for a turn that picked up a conversation kept warm for it, by code and facts; undefined for any other turn. */
+export const keptWarmNotice = (opening: PromptCacheOpening): Extract<SandboxNotice, { code: "keptWarm" | "keptCold" }> | undefined => {
     const { kept } = opening;
     if (kept === undefined) {
         return undefined;
     }
-    const held = `kept warm for ${spanLabel(kept.forMs)} with ${kept.refreshes} ${kept.refreshes === 1 ? "refresh" : "refreshes"}`;
-    return opening.readTokens >= opening.writtenTokens
-        ? `Picked up warm: ${tokensLabel(opening.readTokens)} tokens read from the cache, ${held}.`
-        : `Picked up cold despite being ${held}: ${tokensLabel(opening.writtenTokens)} tokens sent again, because this turn's prompt no longer matched the cache.`;
+    const warm = opening.readTokens >= opening.writtenTokens;
+    const params = { tokens: tokensLabel(warm ? opening.readTokens : opening.writtenTokens), span: spanLabel(kept.forMs), refreshes: kept.refreshes };
+    return warm ? { code: "keptWarm", params } : { code: "keptCold", params };
+};
+
+/** The transcript's line for a turn that picked up a conversation kept warm for it; undefined for any other turn. */
+export const keptWarmLine = (opening: PromptCacheOpening): string | undefined => {
+    const notice = keptWarmNotice(opening);
+    if (notice === undefined) {
+        return undefined;
+    }
+    const { tokens, span, refreshes } = notice.params;
+    const held = `kept warm for ${span} with ${refreshes} ${refreshes === 1 ? "refresh" : "refreshes"}`;
+    return notice.code === "keptWarm"
+        ? `Picked up warm: ${tokens} tokens read from the cache, ${held}.`
+        : `Picked up cold despite being ${held}: ${tokens} tokens sent again, because this turn's prompt no longer matched the cache.`;
 };
 
 // A turn's prefix, part by part, so two turns that should share a cache can say which part stopped matching.

package/src/schemas/loopback-catch.ts

@@ -0,0 +1,45 @@
+// Loopback catch: how a sign-in whose redirect lands on http://localhost:<port>/… finishes without a paste. The daemon
+// is not on the machine the browser is on, so something that is (a device agent, the browser extension) watches that
+// one address for the attempt's lifetime and hands back where the browser landed. Both peers answer the same
+// procedure (`catchLoopback`) with the same frames, so the daemon drives them identically.
+// Named imports rather than the `z` namespace: the extension bundles this module (see webext.ts).
+import { discriminatedUnion, enum as zEnum, literal, number, object, string } from "zod";
+import type * as z from "zod";
+
+// What one catcher is asked to watch. The state is deliberately absent: the daemon checks it on what comes back, so a
+// catcher can hold nothing that tells a real landing from a forged one, and needs nothing to.
+export const LoopbackCatchSchema = object({
+    // The attempt's own id, for logs on both ends; not redeemable.
+    id: string().min(1),
+    // The host the provider redirects to, spelled as its registration spells it: some are registered as
+    // `localhost`, some as `127.0.0.1`, and a browser treats the two as different origins.
+    host: zEnum(["localhost", "127.0.0.1"]),
+    port: number().int().min(1).max(65535),
+    // The path only, leading slash included; the query is the grant and is never matched.
+    path: string().startsWith("/"),
+    // Epoch ms; a catcher stops watching by itself here even if nobody aborts the stream.
+    expiresAt: number(),
+    // Who the page thanks once the browser lands ("Claude"), so the tab says what just happened.
+    title: string().min(1),
+}).strict();
+export type LoopbackCatch = z.infer<typeof LoopbackCatchSchema>;
+
+// What a catcher streams back. `busy` ends its part (the port is taken on that machine, or it cannot watch at all);
+// `landed` may come more than once, since anything on the machine can hit a loopback port and only the daemon can
+// tell which hit is the sign-in.
+export const LoopbackCatchEventSchema = discriminatedUnion("type", [
+    object({ type: literal("listening") }),
+    object({ type: literal("busy"), reason: string() }),
+    object({ type: literal("landed"), url: string().min(1) }),
+]);
+export type LoopbackCatchEvent = z.infer<typeof LoopbackCatchEventSchema>;
+
+// Advertised in a device's `features` and a browser's facts; only a peer that says it is asked.
+export const LOOPBACK_CATCH_FEATURE = "loopback-catch";
+
+// Who is watching for this attempt's landing, for the card to say "finishes by itself on rog".
+export const SignInCatcherSchema = object({
+    kind: zEnum(["device", "browser"]),
+    label: string().min(1),
+});
+export type SignInCatcher = z.infer<typeof SignInCatcherSchema>;

package/src/schemas/maintenance.ts

@@ -137,7 +137,7 @@ export const MutationScoreSchema = z.object({
         .number()
         .describe("The share of injected faults the suite caught. Not a coverage figure: coverage says a line ran, this says an assertion depended on it."),
     killed: z.number().int().nonnegative().describe("Faults the suite caught."),
-    survived: z.number().int().nonnegative().describe("Faults it did not: code that can be broken with every test still green."),
+    survived: z.number().int().nonnegative().describe("Faults it did not: code that can be broken with every test still passing."),
     // A timeout counts as detected here (Stryker's own convention), not as inconclusive.
     inconclusive: z
         .number()

package/src/schemas/needs.ts

@@ -256,6 +256,12 @@ export const ConversationGrantSchema = z.object({
     capabilities: z.array(z.string()).default([]).describe("Connected capabilities it may use although its persona leaves them out."),
     folders: z.array(z.string()).default([]).describe("Workspace folders its file tools may touch beyond its fence."),
     shelves: z.array(GrantShelfSchema).default([]).describe("Shelves of tools opened for it."),
+    // Answered on an install card's "Allow installs for this conversation", read live by the command gate, so it holds
+    // from the install that asked onward, this turn included, and across restarts.
+    installs: z
+        .boolean()
+        .default(false)
+        .describe("Whether its own dependency installs run without asking, where the owner's setting would otherwise ask first."),
     updatedAt: z.number().describe("When it last changed, in milliseconds."),
     by: z.string().optional().describe("Who last allowed something here."),
 });
@@ -270,11 +276,12 @@ export const StandingGrantsSchema = z.object({
             capabilities: z.array(z.string()).describe("Connected capabilities allowed although its persona leaves them out."),
             folders: z.array(z.string()).describe("Workspace folders its file tools may touch beyond its fence."),
             shelves: z.array(GrantShelfSchema).describe("Shelves of tools opened for it."),
+            installs: z.boolean().default(false).describe("Whether its own dependency installs run without asking."),
             by: z.string().optional().describe("Who last allowed one of those."),
             updatedAt: z.number().optional().describe("When one of those last changed, in milliseconds."),
             releases: z
                 .array(z.object({ subject: z.string(), approvedBy: z.string(), at: z.number() }))
-                .describe("Gated credentials released to it, until the daemon restarts or somebody takes one back."),
+                .describe("Gated credentials released to it, until somebody takes one back."),
         }),
     ),
 });
@@ -282,8 +289,10 @@ export type StandingGrants = z.infer<typeof StandingGrantsSchema>;
 
 export const GrantRevokeSchema = z.object({
     conversationId: z.string(),
-    kind: z.enum(["capability", "folder", "shelf", "release"]).describe("Which kind of yes: a grant past the persona or area, or a credential's release."),
-    what: z.string().describe("The capability id, folder, shelf or released credential it named."),
+    kind: z
+        .enum(["capability", "folder", "shelf", "release", "install"])
+        .describe("Which kind of yes: a grant past the persona or area, a credential's release, or letting its installs run unasked."),
+    what: z.string().describe("The capability id, folder, shelf or released credential it named; empty for installs."),
 });
 export type GrantRevoke = z.infer<typeof GrantRevokeSchema>;
 

package/src/schemas/personas.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { type ModelSource, readyChain } from "../models/model-pins.js";
 import { type ModelPin, ModelPinSchema } from "./agent.js";
 import { entryId } from "./internal.js";
-import { SkillDraftSchema, SkillNameSchema, SystemPromptModeSchema } from "./settings.js";
+import { SkillDraftSchema, SkillNameSchema, SYSTEM_PROMPT_MAX, SystemPromptModeSchema } from "./settings.js";
 // A named face the sandbox shows outward: who it speaks as, what it may do, where it works, what it's told, what it
 // runs on. No credential lives on the card; accounts stay private, per-sandbox. Not a security boundary for a watched
 // chat — a real fence only for an unattended turn, whose resolver defaults to nothing.
@@ -176,7 +176,12 @@ export interface TurnBriefingFixture {
 export const TURN_BRIEFING_FIXTURES: readonly TurnBriefingFixture[] = [
     { label: "Where this turn's files live", why: "Without it a runtime that is only cwd'd into its branch writes into the shared checkout." },
     { label: "Who this turn is acting as", why: "The card's own identity, on the runtimes that have nowhere else to put it." },
-    { label: "Standing instructions for this workspace", why: "Your own AGENTS.md rules. Replace them by giving this card its own system prompt." },
+    // Kept under a card's own system prompt too (system-prompt.ts `ownPrompt`): writing a prompt withdraws this product's
+    // guidance, never the owner's own rules.
+    {
+        label: "Standing instructions for this workspace",
+        why: "Your own AGENTS.md rules, sent even when this card has its own system prompt. Change them in AGENTS.md.",
+    },
     {
         label: "Some connected accounts need a person's approval",
         why: "Names who to ask; without it a withheld account reads as simply not connected.",
@@ -307,7 +312,7 @@ export type PersonaKit = z.infer<typeof PersonaKitSchema>;
 export const PersonaPromptSchema = PersonaIdParamSchema.extend({
     prompt: z
         .string()
-        .max(20000)
+        .max(SYSTEM_PROMPT_MAX)
         .describe(
             "What to tell this persona. Sending an empty one removes it entirely rather than storing a blank, so the persona falls back to the sandbox's own instructions.",
         ),

package/src/schemas/providers/provider-oauth.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { AccountStateSchema, AccountUsageSchema } from "./plan-limits.js";
+import { SignInCatcherSchema } from "../loopback-catch.js";
 import { KeyedProviderSchema } from "./provider-subscriptions.js";
 // Claude uses PKCE paste-back (start → exchange); Codex uses OpenAI's device-code flow (start → poll). A sandbox can
 // hold several accounts per provider; `id` is the store key, `label` the display name. Tokens never ride this shape —
@@ -91,6 +92,12 @@ export const LoginStartSchema = z.object({
             "This attempt's id, for finishing or abandoning it. Not a credential and not redeemable: the proof that completes the sign-in never leaves the sandbox.",
         ),
     expiresAt: z.number().describe("When this attempt stops being answerable, in milliseconds, so a card can stop waiting instead of spinning."),
+    catchers: z
+        .array(SignInCatcherSchema)
+        .optional()
+        .describe(
+            "Who is watching for where the browser lands, on the machine it is on: a device or a browser of yours. Listed means the sign-in finishes by itself once the page is approved there; the paste stays open for a browser anywhere else. Empty or absent means nothing is watching.",
+        ),
 });
 export type LoginStart = z.infer<typeof LoginStartSchema>;
 // e.g. Z.ai's international vs. mainland plans.
@@ -111,6 +118,18 @@ export const LoginCompletedSchema = z.object({
         "The account it connected, where the sign-in ends here. Absent means keep watching the account list.",
     ),
 });
+// One attempt's standing, for a card to watch the attempt itself rather than the account list: a list that already
+// held an account says nothing about whether this sign-in, adding another, has landed.
+export const LoginStatusSchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("wait") }),
+    z.object({
+        status: z.literal("ok"),
+        account: OauthAccountSchema.optional().describe("The account it connected. Absent where the row lands in the account list a little later."),
+    }),
+    z.object({ status: z.literal("error"), error: z.string().min(1).describe("Why it failed, to show as it is.") }),
+]);
+export type LoginStatus = z.infer<typeof LoginStatusSchema>;
+export const LoginStatusQuerySchema = z.object({ handshake: z.string().min(1).describe("Which attempt.") });
 // Tidiness, not a security boundary: an unanswered attempt also times out on its own (`expiresAt`).
 export const LoginCancelSchema = z.object({ handshake: z.string().min(1).describe("Which attempt to stop waiting on.") });
 // codex/grok/kimi/gemini via CLIProxyAPI; `flow` is explicit even when a provider's URL already embeds an optional
@@ -124,6 +143,12 @@ export const TranslatorStartSchema = z.object({
         .describe(
             "Which shape this is. A device sign-in finishes by itself and you poll the attempt; a redirect needs the address it landed on handed back. Said outright rather than guessed at from whether a code happens to exist.",
         ),
+    catchers: z
+        .array(SignInCatcherSchema)
+        .optional()
+        .describe(
+            "Who is watching for where the browser lands, on the machine it is on: a device or a browser of yours. Listed means the sign-in finishes by itself once the page is approved there; the paste stays open for a browser anywhere else. Empty or absent means nothing is watching.",
+        ),
 });
 export const TranslatorStatusSchema = z.discriminatedUnion("status", [
     z.object({ status: z.literal("wait") }),
@@ -142,6 +167,13 @@ export const TranslatorCompleteSchema = z.object({
 // Order is meaningful: the provider's own preference order, never re-ranked.
 export const ModelBadgeSchema = z.enum(["reasoning", "fast"]);
 export type ModelBadge = z.infer<typeof ModelBadgeSchema>;
+// Why a model may run one-shot helper jobs (a commit message, a title) and never an agent turn. Only a positive answer
+// sets it, so a server that says nothing leaves a model usable:
+// no-tool-calls: its server reports a chat template that cannot call tools (llama.cpp's /props `chat_template_caps`),
+//   and llama.cpp drops a turn's tools without a word, so the turn would run and do nothing useful
+// instant-tier: the curated local model sold as too small to drive a turn (LOCAL_MODELS' `instant` rung)
+export const HelperOnlySchema = z.enum(["no-tool-calls", "instant-tier"]);
+export type HelperOnly = z.infer<typeof HelperOnlySchema>;
 export const ModelSchema = z.object({
     id: z.string().describe("What to name when asking for this model."),
     label: z.string().describe("What to call it on screen."),
@@ -156,6 +188,9 @@ export const ModelSchema = z.object({
     // The served window, not the training length — memory can clamp it lower. Turns are refused against this. Absent
     // means unknown, never unlimited.
     contextWindow: z.number().optional().describe("How many tokens this model will accept in one request, where the server publishes it."),
+    helperOnly: HelperOnlySchema.optional().describe(
+        "Set where this model may write commit messages, titles and other one-shot jobs but never run a chat turn, and why: its server says it cannot call tools, or it is the small local model kept for quick jobs. Absent means nothing has said it cannot.",
+    ),
     // Epoch seconds. A fact about the MODEL, not about any one account: a routed provider balances across credentials,
     // so a model every one of them is benched on is unrunnable however much headroom their rings show. Absent is the
     // ordinary case and means runnable, never "unknown".

package/src/schemas/secrets.ts

@@ -1,5 +1,6 @@
 // secrets: user-supplied env-var secrets the daemon writes to desired-state/.env
 import { z } from "zod";
+import { SECRET_HOST_MAX, SECRET_HOST_PATTERN_RE, SECRET_HOSTS_MAX } from "../policy/secret-hosts.js";
 // Straight to the sandbox daemon, never through the platform; `apply` reloads .env with no restart. `list` returns keys
 // only; `reveal` is the one owner-only exception that returns a value.
 // An env var name, as a shell exports it. Exported so the browser validates against this rather than restating it:
@@ -104,6 +105,66 @@ export const CredentialGrantSchema = z.object({
     message: z.string().describe("What the grant means in practice, and what to do next."),
 });
 
+// The host guard: the second way a secret can need a person, beside a named approver. On, a use goes unasked only when
+// every host its text names is on the secret's list; one aimed anywhere else, or anywhere its text does not show, waits
+// for a person's click, whatever the safety judge says and whether or not it could be asked. Off, the guard never asks.
+// Keyed like a gate: a secret by its name, a connected capability by its id, covering every field of it.
+export const SecretHostSchema = z
+    .string()
+    .max(SECRET_HOST_MAX)
+    .regex(SECRET_HOST_PATTERN_RE)
+    .describe(
+        "One host, `api.github.com`, or every host under a domain, `*.github.com` (which does not include github.com itself). Lowercase, no scheme or port.",
+    );
+
+export const SecretHostSourceSchema = z
+    .enum(["owner", "connector"])
+    .describe(
+        "Who set it: the owner, or the connector the credential belongs to, whose guard is on with its own service's hosts until the owner changes it.",
+    );
+export type SecretHostSource = z.infer<typeof SecretHostSourceSchema>;
+
+export const SecretHostGuardSchema = z.object({
+    subject: z.string().min(1).describe("Which secret, by the name its reference carries, or which connected capability, by its id."),
+    kind: CredentialGateKindSchema,
+    guard: z.boolean().describe("On: a use off the list, or whose destination cannot be read, asks a person first. Off: it never asks."),
+    hosts: z
+        .array(SecretHostSchema)
+        .max(SECRET_HOSTS_MAX)
+        .describe("Where it goes without asking while the guard is on. Empty with the guard on: every use asks. Kept while it is off, for turning it back on."),
+    source: SecretHostSourceSchema,
+});
+export type SecretHostGuard = z.infer<typeof SecretHostGuardSchema>;
+
+export const SecretHostGuardsSchema = z.object({
+    guards: z
+        .array(SecretHostGuardSchema)
+        .describe("Every secret whose host guard has been set, or that a connector guards by default. One not listed has its guard off. Names and hosts only, never a value."),
+});
+
+export const SecretHostGuardSetSchema = z.object({
+    subject: z.string().min(1).describe("Which secret, by name, or which connected capability, by id."),
+    kind: CredentialGateKindSchema.optional().describe("Whether the subject is a secret or a capability. Worked out from the name when absent."),
+    guard: z.boolean().describe("Whether a use off the list, or whose destination cannot be read, must ask a person first."),
+    hosts: z
+        .array(SecretHostSchema)
+        .max(SECRET_HOSTS_MAX)
+        .describe(
+            "The whole new list. Turning the guard on or taking hosts away is open to anybody who may use secrets; turning it off or adding a host is the owner's to approve.",
+        ),
+    // Filled by the CLI itself, so the model cannot aim the owner's card at somebody else's conversation.
+    conversationId: z
+        .string()
+        .optional()
+        .describe("Which conversation to ask the owner in, when the change needs them. The CLI fills this from the running turn."),
+});
+
+export const SecretHostGuardSetResultSchema = z.object({
+    guard: z.boolean().describe("Whether the guard is on now."),
+    hosts: z.array(z.string()).describe("Where it goes without asking while the guard is on."),
+    approvedBy: z.string().optional().describe("Who approved the change, when it needed the owner's click. Absent when nobody had to."),
+});
+
 // Across every store: env/generated secrets, capability credentials, AI-provider accounts. Values never ride this
 // shape; `revealable` says whether `reveal` can return one (everything but provider accounts).
 export const SecretInventoryEntrySchema = z.object({
@@ -151,6 +212,15 @@ export const SecretInventoryEntrySchema = z.object({
         })
         .optional()
         .describe("Who has to release this before the agent can use it, and for how long one release lasts. Absent when it is not gated."),
+    // Joined from the host guards, the owner's and a connector's own, so the row can say where it may go.
+    hosts: z
+        .object({
+            guard: z.boolean().describe("Whether a use off the list, or whose destination cannot be read, asks a person first."),
+            list: z.array(z.string()).describe("The hosts it goes to unasked while the guard is on, each exact or `*.domain`."),
+            source: SecretHostSourceSchema,
+        })
+        .optional()
+        .describe("Its host guard. Absent when none was ever set and no connector sets one: the guard is off."),
 });
 export type SecretInventoryEntry = z.infer<typeof SecretInventoryEntrySchema>;
 export const SecretInventorySchema = z.object({

package/src/schemas/settings-history.ts

@@ -107,4 +107,6 @@ export const SETTINGS_HISTORY = [
     keepWarmObject,
     // Where the check after landing ran (2026-09-27): nothing checks work after it lands any more, CI does.
     at("offload", drop("landCheck")),
+    // The model list for the fix a refused push offered (2026-09-28): a refused push now says why and offers nothing.
+    at("modelRoles", drop("pre-push-fix")),
 ] as const;

package/src/schemas/settings.test.ts

@@ -23,7 +23,7 @@ describe(`which built-in stands at which moment`, () => {
         expect(rule(`agent.landed`, { kind: `command`, command: `pnpm test` }).success).toBe(false);
     });
 
-    test(`there is no push moment: the repository's own pre-push hook gates a push`, () => {
+    test(`there is no push moment: nothing runs on the way to a push, CI checks what was pushed`, () => {
         expect(rule(`push.starting`, { kind: `command`, command: `pnpm test` }).success).toBe(false);
     });
 });
@@ -111,3 +111,21 @@ describe(`the folded keep-warm settings`, () => {
         expect(convertDocument(SETTINGS_HISTORY, `object`, current, true).changes).toEqual([]);
     });
 });
+
+// The pre-push fix's model list went with the fix a refused push used to offer (2026-09-28). A settings file that still
+// names it must read, since an unknown role refuses the whole file, and every other job's list stays as its owner set it.
+describe(`the retired pre-push fix role`, () => {
+    const pin = { provider: `claude`, model: `claude-opus-5-5` };
+
+    test(`is dropped from a stored file, leaving every other job's list, and the file reads`, () => {
+        const stored = { modelRoles: { "pipeline-fix": [pin], "pre-push-fix": [pin] } };
+        expect(SandboxSettingsSchema.safeParse(stored).success).toBe(false);
+        const converted = convertDocument(SETTINGS_HISTORY, `object`, stored, true);
+        expect(converted.value).toEqual({ modelRoles: { "pipeline-fix": [pin] } });
+        expect(SandboxSettingsSchema.parse(converted.value).modelRoles).toEqual({ "pipeline-fix": [pin] });
+    });
+
+    test(`leaves a file without it alone`, () => {
+        expect(convertDocument(SETTINGS_HISTORY, `object`, { modelRoles: { "pipeline-fix": [pin] } }, true).changes).toEqual([]);
+    });
+});