@intentic/sandbox-contract 1.315.0 → 1.317.0

package/src/schemas/devices.ts

@@ -1,6 +1,7 @@
 // What one of the user's own machines is running.
 import { z } from "zod";
 import { parseHostConnection, type DeviceFacts, DeviceFactsSchema, MachineIdSchema, userDistrosOf, WslEnvironmentSchema } from "./hosts.js";
+import { RollbackTargetSchema, UpdateOutcomeSchema } from "./updates.js";
 import { DEV_VERSION } from "../state/versions.js";
 // Desktop-sync report shape shared by the agent, daemon and browser, produced only by the agent's own `deviceReport`.
 // The agent never reports `sandboxes`; the docker half is filled in by whoever reads the report, scoped to the reader's
@@ -76,6 +77,19 @@ export const DeviceSandboxSchema = z.object({
     resources: SandboxResourcesSchema.optional(),
     // The update `ic sandbox prepare` built and left waiting for this sandbox; absent when nothing is staged.
     staged: z.object({ image: z.string(), version: z.string().optional(), channel: z.string().optional() }).optional(),
+    // Everything below is read off an `ic` new enough to know it; an older ic's listing simply lacks it.
+    // What the running image says it is.
+    version: z.string().optional(),
+    // An interrupted swap left the old container set aside with no replacement: the sandbox is down, and `start` (or
+    // any swap) puts it back. `running` is false while this is true.
+    parked: z.boolean().optional(),
+    // A swap has just happened and the previous version is still parked and ready: until this moment the host watches
+    // the new one and goes back by itself if it keeps crashing, never becomes ready, or loses its tunnel.
+    probationUntil: z.number().optional(),
+    // What the host last did about this sandbox's version (the same record the sandbox reads as `lastUpdate`).
+    lastUpdate: UpdateOutcomeSchema.optional(),
+    // Newest first: what `rollback` would return to, then the older versions kept on this machine for `rollback --to`.
+    rollbackTargets: z.array(RollbackTargetSchema).optional(),
 });
 export type DeviceSandbox = z.infer<typeof DeviceSandboxSchema>;
 // One operation on one sandbox, streamed as lines ending in a `result` or `error` frame. `prepare` builds the pending
@@ -118,6 +132,9 @@ export const DeviceSandboxFlowSchema = z.strictObject({
     slug: z.string().min(1),
     // Approved overlay's sha256, required only by `rebuild`; only content matching it is ever built.
     hash: z.string().optional(),
+    // `rollback` only: a version or pinned image from the sandbox's `rollbackTargets` to go back to instead of the
+    // previous one. Sent only to an agent that advertises `rollback-to`: an older one refuses the field.
+    to: z.string().min(1).optional(),
     // `set-shape` only, both required by it: the whole shape, and when it takes effect.
     // Strict too, unlike the same shape read off a report (where a newer ic's extra field must not fail an older
     // reader): an order carrying a field this agent does not know is refused rather than carried out without it.
@@ -505,7 +522,7 @@ export const DeviceSchema = z.object({
     // The host connection's key, when this machine is also a connected device. Absent otherwise.
     hostId: z.string().optional(),
     // The card that connection is of, beside the key rather than parsed out of it: the machine's name, a label. Absent
-    // with `hostId`, and from a daemon older than the field (`deviceCard` reads the key then).
+    // with `hostId`.
     card: z.string().optional(),
     // The computer this row is an environment of, from whichever door has said (MachineIdSchema): what `machinesOf`
     // groups by. Absent when no door has, which leaves the row a computer of its own.
@@ -563,20 +580,15 @@ export const deviceDistro = (device: Device): string | undefined => {
 const byEnvironment = (a: Device, b: Device): number =>
     Number(isWslDevice(a)) - Number(isWslDevice(b)) || (deviceDistro(a) ?? a.label).localeCompare(deviceDistro(b) ?? b.label);
 
-// The card a device's door hangs off: one card is one computer, so two doors naming the same card are one machine
-// whatever either has said about itself — which is the whole of what an environment that has never connected says.
-// The row's own label, else its key read by the one parser there is (a row from a daemon older than `card`).
-export const deviceCard = (device: Pick<Device, "card" | "hostId">): string | undefined =>
-    device.card ?? (device.hostId === undefined ? undefined : parseHostConnection(device.hostId).card);
-
 // The computer a device is on, by whichever door said: its row, its connect-time facts, its report, its sync enrollment.
 export const deviceMachineId = (device: Device): string | undefined =>
     device.machineId ?? device.facts?.machineId ?? device.report?.machineId ?? device.sync?.machineId;
 
-// What makes two devices one computer: a shared card, or a shared machine id. Nothing else: a hostname is shared by a
-// PC and its WSL distros and by two unrelated machines with the same name, so it joined things by accident.
+// What makes two devices one computer: a shared card (the row's own `card`, never parsed back out of its key: one card
+// is one computer, whatever either door has said about itself), or a shared machine id. Nothing else: a hostname is
+// shared by a PC and its WSL distros and by two unrelated machines with the same name, so it joined things by accident.
 const tokensOf = (device: Device): string[] => {
-    const card = deviceCard(device);
+    const { card } = device;
     const machine = deviceMachineId(device);
     return [...(card === undefined ? [] : [`card:${card.toLowerCase()}`]), ...(machine === undefined ? [] : [`machine:${machine}`])];
 };
@@ -621,8 +633,9 @@ const machineOf = (environments: readonly Device[]): Machine => {
     if (first === undefined) {
         return { key: "", label: "", environments };
     }
-    const named = environments.map(deviceCard).find((key) => key !== undefined) ?? (rest.length === 0 ? undefined : deviceMachineId(first));
-    const label = first.label === first.hostId ? (deviceCard(first) ?? first.label) : first.label;
+    const named =
+        environments.map((device) => device.card).find((key) => key !== undefined) ?? (rest.length === 0 ? undefined : deviceMachineId(first));
+    const label = first.label === first.hostId ? (first.card ?? first.label) : first.label;
     return { key: named ?? first.key, label, environments };
 };
 

package/src/schemas/hosts.ts

@@ -68,10 +68,13 @@ export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 // - `set-shape`: the `set-shape`/`forget-shape` ops, and `start`/`restart` applying a saved shape, all through an `ic`
 //   whose `ic sandbox shape` takes the contract's own shape (`--set`); advertised only when the agent's `ic` does.
 //   Both features ride that verb, so an agent advertises both or neither.
-export const DeviceFeatureSchema = z.enum(["reshape-later", "set-shape"]);
+// - `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"]);
 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";
 // 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/needs.ts

@@ -0,0 +1,292 @@
+import { z } from "zod";
+
+// A need: something an agent cannot finish its task without that only a person can provide (a connection, a secret's
+// value, wider reach, a tool in the image). Unlike a parked card it outlives the turn that raised it: the sandbox keeps
+// it until someone answers, draws it wherever it is waiting, and wakes the conversation when it is met
+// (docs/architecture/needs.md). Every word on a need is the daemon's except `why`, the agent's own case.
+
+export const NEED_KINDS = ["capability", "secret", "grant", "release", "environment"] as const;
+export const NeedKindSchema = z.enum(NEED_KINDS).describe("What is being asked for: a connection, a secret's value, wider reach, a gated credential, or a tool in the image.");
+export type NeedKind = z.infer<typeof NeedKindSchema>;
+
+// `working` is a yes still being carried out: a connection whose form is open, an overlay approved but not yet built.
+export const NeedStatusSchema = z
+    .enum(["open", "working", "met", "declined", "cancelled"])
+    .describe(
+        "Where it stands: open (waiting on a person), working (a person said yes and it is being set up), met, declined, or cancelled (the agent withdrew it, or its conversation went away).",
+    );
+export type NeedStatus = z.infer<typeof NeedStatusSchema>;
+
+export const OPEN_NEED_STATUSES: readonly NeedStatus[] = ["open", "working"];
+export const isOpenNeed = (need: { readonly status: NeedStatus }): boolean => OPEN_NEED_STATUSES.includes(need.status);
+
+// A setting value as a form holds it: every field of a catalog entry is a string on the way in.
+const FieldValuesSchema = z.record(z.string(), z.string());
+
+export const CapabilityNeedModeSchema = z
+    .enum(["connect", "reconnect", "change"])
+    .describe("Connect something new, give a connected one a credential that works again, or change a setting on a connected one.");
+export type CapabilityNeedMode = z.infer<typeof CapabilityNeedModeSchema>;
+
+export const CapabilityNeedSchema = z.object({
+    kind: z.literal("capability"),
+    entry: z.string().min(1).describe("The catalog entry, as the catalog names it."),
+    name: z.string().describe("What the catalog calls it, never the agent's spelling."),
+    mode: CapabilityNeedModeSchema,
+    instance: z.string().optional().describe("The connection a reconnect or a change is about."),
+    target: z.string().optional().describe("The site, host or address the connection is for, when the entry can hold several."),
+    prefill: FieldValuesSchema.optional().describe(
+        "Settings the agent could fill in for a new connection, never a credential: the daemon keeps only the entry's own non-secret fields.",
+    ),
+    changes: FieldValuesSchema.optional().describe("For a change: each setting and the value it would take. Never a credential."),
+    reason: z.string().optional().describe("The daemon's own sentence on why this is the ask, such as the refusal a connected credential keeps getting."),
+    reported: z
+        .boolean()
+        .optional()
+        .describe(
+            "The agent reported the credential refused while the connection still probes as working, so only a person's word that it is fixed meets it: the probe could not see the refusal in the first place.",
+        ),
+});
+export type CapabilityNeed = z.infer<typeof CapabilityNeedSchema>;
+
+// The alphabet a `{{secret:NAME}}` reference resolves; a pasted value is stored under exactly this name.
+export const SECRET_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+
+export const SecretNeedSchema = z.object({
+    kind: z.literal("secret"),
+    name: z.string().regex(SECRET_NAME).describe("The name it is stored under, and what `{{secret:NAME}}` will resolve."),
+    where: z.string().max(200).optional().describe("How it will be used: the header, the command, the site it goes to."),
+    link: z
+        .string()
+        .url()
+        .refine((url) => url.startsWith("https://"), "only an https link")
+        .optional()
+        .describe("Where a person gets one, shown as a link on the card."),
+    hint: z.string().max(120).optional().describe("What a valid one looks like, so a wrong paste is caught by eye."),
+    replace: z.boolean().optional().describe("One is stored under this name and is being refused: the ask is for a new value in its place."),
+});
+export type SecretNeed = z.infer<typeof SecretNeedSchema>;
+
+export const GrantSubjectSchema = z
+    .enum(["capability", "folder", "shelf", "site"])
+    .describe(
+        "A connected capability the persona leaves out, a folder outside the conversation's reach, a whole shelf of tools, or a site in the person's own browser, which only their browser extension can allow.",
+    );
+export type GrantSubject = z.infer<typeof GrantSubjectSchema>;
+
+// A site as a person's browser grants it: the host alone, whatever scheme, path or pattern it was written with
+// ("https://github.com/*" and "github.com" are one site). What a site grant need is keyed and met by.
+export const grantSite = (origin: string): string =>
+    origin
+        .trim()
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, "")
+        .replace(/[/?#].*$/, "")
+        .toLowerCase();
+
+export const GRANT_SHELVES = ["files", "shell", "code", "web", "browser", "delegate", "sandbox"] as const;
+export const GrantShelfSchema = z.enum(GRANT_SHELVES);
+export type GrantShelf = z.infer<typeof GrantShelfSchema>;
+
+export const GrantScopeSchema = z
+    .enum(["conversation", "persona"])
+    .describe("How far a yes goes: this conversation only, or the persona itself, for every conversation that wears it.");
+export type GrantScope = z.infer<typeof GrantScopeSchema>;
+
+export const GrantNeedSchema = z.object({
+    kind: z.literal("grant"),
+    subject: GrantSubjectSchema,
+    what: z.string().min(1).describe("The capability's id, the folder, or the shelf."),
+    label: z.string().describe("What it is, in the daemon's words: the account and its kind, the folder, the shelf's name."),
+    persona: z.string().optional().describe("The persona that withholds it, when one does."),
+    scope: GrantScopeSchema.optional().describe("How far the yes went, once there was one."),
+});
+export type GrantNeed = z.infer<typeof GrantNeedSchema>;
+
+export const ReleaseNeedSchema = z.object({
+    kind: z.literal("release"),
+    subject: z.string().min(1).describe("The gated account or connector."),
+    approvers: z.array(z.string()).describe("Who may release it. Anyone else's answer is refused and leaves it waiting."),
+});
+export type ReleaseNeed = z.infer<typeof ReleaseNeedSchema>;
+
+export const EnvironmentNeedSchema = z.object({
+    kind: z.literal("environment"),
+    tool: z.string().min(1).describe("What the steps install, the name the proposal is filed under."),
+    steps: z.string().min(1).describe("The Dockerfile steps proposed for the image's custom section: RUN and ENV lines only."),
+    approvedHash: z.string().optional().describe("The overlay these steps were approved into; met once the running container was built from it."),
+});
+export type EnvironmentNeed = z.infer<typeof EnvironmentNeedSchema>;
+
+export const NeedSubjectSchema = z
+    .discriminatedUnion("kind", [CapabilityNeedSchema, SecretNeedSchema, GrantNeedSchema, ReleaseNeedSchema, EnvironmentNeedSchema])
+    .describe("What exactly is asked for.");
+export type NeedSubject = z.infer<typeof NeedSubjectSchema>;
+
+// How the agent learned the outcome: the call it raised the need with, words into its live turn, a turn of its own, or
+// queued behind what the conversation was doing.
+export const NeedToldSchema = z.enum(["call", "turn", "queued"]);
+export type NeedTold = z.infer<typeof NeedToldSchema>;
+
+export const NeedSchema = z.object({
+    id: z.string().describe("The need's handle, the one `needs cancel` takes."),
+    conversationId: z.string().describe("The conversation that asked, and the one its answer wakes."),
+    subject: NeedSubjectSchema,
+    title: z.string().describe("The one line it leads with, in the daemon's words."),
+    why: z.string().max(280).optional().describe("The agent's case for it, and the only words on a need that are the agent's."),
+    status: NeedStatusSchema,
+    createdAt: z.number().describe("When it was raised, in milliseconds."),
+    updatedAt: z.number().describe("When it last moved, in milliseconds."),
+    answeredBy: z.string().optional().describe("Who answered it, as the sandbox verified them."),
+    outcome: z.string().optional().describe("How it ended, in the daemon's words, once it has."),
+    told: NeedToldSchema.optional().describe("How the agent heard the outcome, once it has."),
+    unattended: z.boolean().optional().describe("Raised by a turn nobody was watching, so the card waited for whoever came next."),
+});
+export type Need = z.infer<typeof NeedSchema>;
+
+// What an agent may send: the kind and what it can know about it. Names, titles and every other field the card shows are
+// the daemon's to fill in, from the catalog, the persona, the gate policy.
+export const NeedAskSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("capability"),
+        entry: z.string().min(1).describe("The catalog entry or a connected instance's id."),
+        target: z.string().max(200).optional().describe("The site, host or address it is for."),
+        set: FieldValuesSchema.optional().describe("Settings to fill in, or to change on a connected one. Credentials are refused."),
+        reconnect: z
+            .boolean()
+            .optional()
+            .describe("It is connected, but its credential is being refused: ask for a new one rather than being told to use it."),
+    }),
+    SecretNeedSchema,
+    z.object({
+        kind: z.literal("grant"),
+        subject: GrantSubjectSchema,
+        what: z.string().min(1).max(400),
+    }),
+    z.object({ kind: z.literal("release"), subject: z.string().min(1) }),
+    z.object({ kind: z.literal("environment"), tool: z.string().min(1).max(64), steps: z.string().min(1).max(20_000) }),
+]);
+export type NeedAsk = z.infer<typeof NeedAskSchema>;
+
+// The longest a raising call holds: under the agent shell's 110-second cutoff, so the answer returns on the call.
+export const NEED_WAIT_MAX_S = 100;
+export const NEED_WAIT_DEFAULT_S = 90;
+
+export const NeedRaiseSchema = z.object({
+    ask: NeedAskSchema,
+    why: z.string().max(280).optional(),
+    wait: z
+        .number()
+        .int()
+        .min(0)
+        .max(NEED_WAIT_MAX_S)
+        .optional()
+        .describe("Seconds to hold the call for an answer. Absent is 90 for a watched turn and 0 for an unattended one."),
+});
+export type NeedRaise = z.infer<typeof NeedRaiseSchema>;
+
+// How a raising call ended. `met`: usable now, exit 0. `open`: asked and still waiting, exit 3; the answer arrives in the
+// conversation by itself. `refused`: nothing was raised or it was declined, exit 1.
+export const NeedRaisedSchema = z.object({
+    state: z.enum(["met", "open", "refused"]),
+    message: z.string().describe("The sentence the CLI prints, written for the agent to act on."),
+    need: NeedSchema.optional(),
+    code: z.string().optional().describe("A refusal's type, for a script to branch on."),
+});
+export type NeedRaised = z.infer<typeof NeedRaisedSchema>;
+
+// A person's answer, by what the card offered. A secret's value travels on its own route (needs.contract.ts), never here.
+export const NeedAnswerSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("decline"), note: z.string().max(500).optional().describe("Why not, passed to the agent.") }),
+    // A connection's yes before its form is saved: moves the need to working, so the board keeps saying so.
+    z.object({ kind: z.literal("accept") }),
+    // A change to a connected capability's settings, applied as the card showed it.
+    z.object({ kind: z.literal("apply") }),
+    z.object({ kind: z.literal("grant"), scope: GrantScopeSchema }),
+    z.object({ kind: z.literal("release") }),
+    z.object({ kind: z.literal("approve") }),
+]);
+export type NeedAnswer = z.infer<typeof NeedAnswerSchema>;
+
+export const NeedIdParamSchema = z.object({ id: z.string().min(1).describe("Which need.") });
+export const NeedAnswerInputSchema = NeedIdParamSchema.extend({ answer: NeedAnswerSchema });
+export const NeedSecretInputSchema = NeedIdParamSchema.extend({
+    value: z.string().min(1).max(64_000).describe("The secret's value. Stored, never echoed, never written into a transcript."),
+});
+export const NeedsQuerySchema = z.object({
+    conversationId: z.string().optional().describe("One conversation's needs. Absent is every conversation's."),
+    open: z.boolean().optional().describe("Only the ones still waiting."),
+});
+export const NeedsListSchema = z.object({ needs: z.array(NeedSchema).describe("Newest first.") });
+
+// What `capabilities list` reads (GET /capabilities/connectable, a raw route): shared by the daemon's handler and the
+// CLI's suite, so the two cannot drift apart again the way a renamed field once left the command printing nothing.
+export const CapabilityConnectableSchema = z.object({
+    entries: z.array(
+        z.object({
+            entry: z.string().describe("The catalog entry's id, what `capabilities request` takes."),
+            name: z.string(),
+            description: z.string(),
+            connected: z.boolean().describe("Whether an instance of it is live, not merely added."),
+        }),
+    ),
+    suggested: z
+        .array(
+            z.object({
+                entry: z.string(),
+                claim: z.string().describe("What the workspace seems to want, in words."),
+                evidence: z.string().describe("What was read to say so, verbatim: a file, a remote."),
+            }),
+        )
+        .default([]),
+});
+export type CapabilityConnectable = z.infer<typeof CapabilityConnectableSchema>;
+
+// One open need as the conversation's card lists it: enough for the board to say what the agent waits on.
+export const AgentNeedSchema = z.object({
+    id: z.string(),
+    kind: NeedKindSchema,
+    title: z.string(),
+    status: NeedStatusSchema,
+});
+export type AgentNeed = z.infer<typeof AgentNeedSchema>;
+
+// What a person allowed one conversation beyond its persona and area, from a grant need's card
+// (personas/conversation-grants.ts). Honoured from that conversation's next turn on, and revocable on the Grants page.
+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."),
+    updatedAt: z.number().describe("When it last changed, in milliseconds."),
+    by: z.string().optional().describe("Who last allowed something here."),
+});
+export type ConversationGrant = z.infer<typeof ConversationGrantSchema>;
+
+// Every yes still standing, by conversation: what its grants widened past its persona or area, and which gated
+// credentials a named person released to it. Reviewed and taken back from Needs you.
+export const StandingGrantsSchema = z.object({
+    conversations: z.array(
+        z.object({
+            conversationId: z.string(),
+            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."),
+            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."),
+        }),
+    ),
+});
+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."),
+});
+export type GrantRevoke = z.infer<typeof GrantRevokeSchema>;
+
+// The file the needs store keeps: every open need and the recent closed ones, by id.
+export const NeedsFileSchema = z.record(z.string(), NeedSchema);
+export type NeedsFile = z.infer<typeof NeedsFileSchema>;

package/src/schemas/personas.ts

@@ -141,8 +141,8 @@ export const TURN_BRIEFING_NOTES: readonly TurnBriefingNote[] = [
     {
         id: "checks",
         label: "Checks after landing",
-        when: "First message and after a compaction, and again whenever the main tree's own check turns red or back to green: what runs after its work lands, and which failures the main tree already has.",
-        cost: "The agent does not know which failures are the main tree's own and not its doing, so it may spend a turn chasing one somebody else is already fixing.",
+        when: "First message and after a compaction: that nothing checks its work when it finishes or after it lands, which checks are its to run, and that CI checks what the owner pushes.",
+        cost: "The agent does not know what checks its work, so it may run the whole repository's suite on a shared machine, or chase a failure main already has.",
     },
     {
         id: "dependencies",

package/src/schemas/providers/plan-limits.ts

@@ -123,6 +123,14 @@ export const ProviderRefusalSchema = z.object({
     // Lets a `limit` refusal be read against the pool that model spends (`UsageWindow.gates`), not the account's
     // fullest pool.
     model: z.string().optional().describe("Which model the refused turn was on, where that is known."),
+    // The provider's own "try again at …", which a polled reading cannot contradict: a usage endpoint can keep showing
+    // room while the plan refuses every turn.
+    resetsAt: z
+        .number()
+        .optional()
+        .describe(
+            "When the provider said to try again, in epoch seconds, for a spent allowance where it named one. Until then the refusal stands whatever a reading says; after it, it is over.",
+        ),
 });
 export type ProviderRefusal = z.infer<typeof ProviderRefusalSchema>;
 export const ProviderRefusalsSchema = z.object({

package/src/schemas/secrets.ts

@@ -19,6 +19,29 @@ export const SecretKeysSchema = z.object({
 export const SecretKeyParamSchema = z.object({ key: secretKey.describe("Which secret, by name.") });
 export const SecretRevealSchema = z.object({ value: z.string().describe("The value itself. The only place in this API one is ever returned.") });
 
+// A secret nobody has to find or paste: a session key, a webhook signing secret, a database password the task sets up
+// itself. The sandbox makes it and keeps it; the caller gets its reference and length, never the value.
+export const SECRET_FORMATS = ["hex", "base64url", "alnum"] as const;
+export const SecretGenerateSchema = z.object({
+    key: secretKey.describe("The name to store it under: a name nothing here holds yet, since a new value would break whatever uses the old one."),
+    bytes: z
+        .number()
+        .int()
+        .min(16)
+        .max(128)
+        .default(32)
+        .describe("How much randomness, in bytes. 32 unless whatever reads it demands a particular length."),
+    format: z
+        .enum(SECRET_FORMATS)
+        .default("hex")
+        .describe("How it is spelled: `hex` (0-9, a-f), `base64url` (letters, digits, - and _), or `alnum` (letters and digits only, for readers that refuse symbols)."),
+});
+export const SecretGeneratedSchema = z.object({
+    key: z.string().describe("The name it is stored under."),
+    length: z.number().int().describe("How many characters it is, which a reader's validation may care about."),
+    stored: z.enum(["env", "sandbox"]).describe("Where it was kept: desired-state/.env once DevOps is active, the sandbox's own store before that."),
+});
+
 // A wall against the agent's own judgment, not a compromised container: a shell here can read the policy same as the
 // vault. Approvers are an exact list, never a role floor; the owner isn't on it unless added.
 export const CredentialGateScopeSchema = z

package/src/schemas/settings-history.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { dropAll, fold, isJsonObject, mapValue, retype } from "../documents/conversions.js";
+import { at, drop, dropAll, fold, isJsonObject, mapValue, retype } from "../documents/conversions.js";
 import type { KeepWarmSettings, RuleSchema } from "./settings.js";
 
 // The conversions the settings shape has had, oldest first: what brings any earlier release's settings to
@@ -105,4 +105,6 @@ export const SETTINGS_HISTORY = [
         "drops rules at the retired turn.ending moment (and the verify-ui-edits built-in), which run nothing",
     ),
     keepWarmObject,
+    // Where the check after landing ran (2026-09-27): nothing checks work after it lands any more, CI does.
+    at("offload", drop("landCheck")),
 ] as const;

package/src/schemas/settings.test.ts

@@ -48,15 +48,16 @@ describe(`where a command lives`, () => {
         expect(file([{ when: `push`, run: `pnpm verify:push` }])).toBe(false);
     });
 
-    test(`a land check is one per repository and narrows by no path`, () => {
+    // `land` is retired like `turn`: it runs nothing, so a file written while it ran reads however it spelled one.
+    test(`a retired land check still reads, however many a file names and whatever paths it gives`, () => {
         const file = (checks: unknown[]) => RepoChecksFileSchema.safeParse({ checks }).success;
         expect(
             file([
                 { when: `land`, run: `pnpm verify` },
                 { when: `land`, run: `pnpm test` },
             ]),
-        ).toBe(false);
-        expect(file([{ when: `land`, run: `pnpm verify`, paths: [`src/**`] }])).toBe(false);
+        ).toBe(true);
+        expect(file([{ when: `land`, run: `pnpm verify`, paths: [`src/**`] }])).toBe(true);
     });
 });
 

package/src/schemas/settings.ts

@@ -15,8 +15,8 @@ export type SystemPromptMode = z.infer<typeof SystemPromptModeSchema>;
 export const BuiltinPromptSchema = z.object({ base: z.enum(["intentic", "claude"]) });
 // Rules: "at this moment, if this is true, do this". The owner's rules decide (land, hold, version); every command a
 // moment runs is a repository's own check (`<repo>/.intentic/checks.json`), compiled into this same table by the daemon,
-// so no command lives in settings. Nothing verifies inside a turn: the whole-tree check runs after work lands and never
-// holds anything (schemas/workspace/mainline.ts).
+// so no command lives in settings. Nothing verifies inside a turn or after a land: CI checks what the owner pushes, and
+// nothing here holds anything (schemas/workspace/push-checks.ts).
 export const RuleMomentSchema = z.enum([
     // A command here runs on the just-written file (`{file}` is its path); the cheapest moment to catch a defect.
     "file.edited",
@@ -436,30 +436,34 @@ export const SandboxSettingsSchema = z.object({
     ),
     // Worth it since the container is recreated on every update or environment approval — otherwise approving a
     // Dockerfile change costs the run that asked for it.
-    // What happens to breakage found after the work that caused it has left the turn. A land that turns the main tree's own
-    // check red waits for the lands queued behind it to be checked too, then goes back to the conversation that landed it
-    // while that one still has it in mind, or to a fresh conversation when nobody can be named or the one named has gone
-    // cold; main's CI staying red on one failure gets a fix agent once pushes go quiet, with a fleet failure re-run instead.
-    // Off, all of it is only reported.
+    // What happens when main's CI goes red (ci/main-fixer.ts): its first failed job starts one fix agent, which is sent
+    // every later failure on main until main is green, within a few turns, and a failure on the CI fleet itself is re-run
+    // once instead. Off, it is only reported.
     autoRepair: z
         .boolean()
         .default(true)
         .describe(
-            "Whether breakage found after the work left its turn is repaired without asking. A land that turns the main tree's check red is repaired once the work queued behind it has been checked too: by the conversation that landed it while it still has the work in mind, otherwise by a fresh conversation handed the failures and the suspects' changes. Main's CI staying red on the same failure gets a fix agent once pushes go quiet, and a failure on the CI fleet itself is re-run once instead. Off, all of it is only reported.",
+            "Whether main's CI going red is repaired without asking. The first job that fails on main starts one fix agent, without waiting for the rest of the run, and every later failure on main goes to that same agent until a run passes. It gets a few turns; when they are spent, or it finishes without changing anything (a failure that is not in the code), the red waits for you. A failure on the CI fleet itself is re-run once instead. Off, all of it is only reported.",
         ),
     // Where heavy work runs: a runner (the same image, on one of the owner's machines) instead of this sandbox. Keyed by
-    // the heavy-command rule an agent's command matched (system/resources/heavy-commands.ts), and one entry for the
-    // check after landing, each naming a runner id. A runner that is offline, outdated or full hands the work back here,
-    // which the command's output says. Never pushed to a runner itself (portability/definition.ts), which must not pass
-    // work on again.
+    // the heavy-command rule an agent's command matched (system/resources/heavy-commands.ts), each naming a runner id. A
+    // runner that is offline, outdated or full hands the work back here, which the command's output says. Never pushed
+    // to a runner itself (portability/definition.ts), which must not pass work on again.
     offload: z
         .object({
             commands: z.record(z.string().min(1), z.string().min(1)).default({}),
-            landCheck: z.string().min(1).optional(),
         })
         .default({ commands: {} })
         .describe(
-            "Which heavy work runs on a runner on one of your machines instead of this sandbox: agents' commands by the kind the heavy-command rules sort them into (tests, typechecks, verify…), and the check after landing. The code travels as it stands, uncommitted work included; the output streams back, and any file the command changed comes back with it. A machine that is offline, outdated or busy hands the work back to this sandbox, and the output says so.",
+            "Which heavy work runs on a runner on one of your machines instead of this sandbox: agents' commands by the kind the heavy-command rules sort them into (tests, typechecks, verify…). The code travels as it stands, uncommitted work included; the output streams back, and any file the command changed comes back with it. A machine that is offline, outdated or busy hands the work back to this sandbox, and the output says so.",
+        ),
+    // A person answering a need is exactly the moment they want the work to go on (docs/architecture/needs.md), unlike a
+    // restart nobody watched, so this one is on to begin with.
+    continueWhenNeedMet: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Whether a conversation carries on by itself once something it asked a person for arrives: a connection made, a secret given, access allowed, a tool built into the image. Off leaves the answer on the conversation's card until someone sends a message.",
         ),
     autoResumeOnRestart: z
         .boolean()
@@ -665,9 +669,9 @@ export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 // spelling for the daemon that reads it, the screen that names it and the demo that mimics it.
 export const REPO_CHECKS_FILE = `${STATE_DIR}/checks.json`;
 
-// Named for the occasion as a repository would say it: `edit` is `file.edited`, and `land` is the daemon's run over the
-// main tree after every land (rules/repo-checks.ts maps them). `turn` is retired: nothing runs when a turn ends any more,
-// and a declaration naming it still reads but runs nothing. No check refuses a land, a commit or a push.
+// Named for the occasion as a repository would say it: `edit` is `file.edited` (rules/repo-checks.ts maps it). `turn`
+// and `land` are retired: nothing runs when a turn ends or after work lands any more (CI checks what the owner pushes),
+// and a declaration naming either still reads but runs nothing. No check refuses a land, a commit or a push.
 // `edit` runs on one file (`{file}`) and its output rides back in the edit's own response, so a command declared there is
 // paid per edit and has to take the file.
 export const RepoCheckMomentSchema = z.enum(["edit", "turn", "land"]);
@@ -675,7 +679,7 @@ export type RepoCheckMoment = z.infer<typeof RepoCheckMomentSchema>;
 
 export const RepoCheckSchema = z.object({
     when: RepoCheckMomentSchema.describe(
-        "When to run it: `edit` on each file as it is written (`{file}` is its path), `land` on the main tree after finished work lands (absent, the package's own verify or test script runs there). `turn` is retired and runs nothing: checks no longer run while a conversation works.",
+        "When to run it: `edit` on each file as it is written (`{file}` is its path). `turn` and `land` are retired and run nothing: checks no longer run while a conversation works or after its work lands, since CI checks what is pushed.",
     ),
     run: z.string().min(1).max(500).describe("The command, run in this repository's own directory, so it reads as it would in a terminal there."),
     label: z.string().min(1).max(80).optional().describe("What to call it on screen. Absent names it after the command."),
@@ -695,11 +699,7 @@ export const RepoChecksFileSchema = z.object({
     checks: z
         .array(RepoCheckSchema)
         .max(10)
-        .default([])
-        // One land check per repository: it is THE verdict on the main tree the push hook replays, not one of several.
-        .refine((checks) => checks.filter((check) => check.when === "land").length <= 1, { message: "a repository declares at most one land check" })
-        // A land checks the whole tree an install settled, not a change, so there is nothing for a glob to narrow.
-        .refine((checks) => checks.every((check) => check.when !== "land" || check.paths === undefined), { message: "a land check takes no paths" }),
+        .default([]),
 });
 export type RepoChecksFile = z.infer<typeof RepoChecksFileSchema>;
 
@@ -711,7 +711,7 @@ export const RepoChecksSummarySchema = z.object({
     fired: z
         .array(z.number().nullable())
         .describe(
-            "When each declared check last reported something, in the file's order, as epoch milliseconds; null for one that never has, or for the land check, whose verdict the activity feed records instead.",
+            "When each declared check last reported something, in the file's order, as epoch milliseconds; null for one that never has, or for a retired one, which runs nothing.",
         ),
     adopted: z
         .boolean()
@@ -722,16 +722,10 @@ export const RepoChecksSummarySchema = z.object({
             "Whether the declaration changed since it was adopted, which holds it until the owner looks again. True only for a repository that was adopted before.",
         ),
     error: z.string().optional().describe("Why the file could not be read, when it exists but does not parse. The checks list is empty in that case."),
-    landDefault: z
-        .string()
-        .optional()
-        .describe(
-            "What runs on the main tree after a land when the file declares no `land` check: the package's own verify or test script. Absent when the repository has neither.",
-        ),
 });
 export type RepoChecksSummary = z.infer<typeof RepoChecksSummarySchema>;
 export const RepoChecksListSchema = z.object({
-    repos: z.array(RepoChecksSummarySchema).describe("Every repository that declares checks or has a package check that runs after a land, in id order."),
+    repos: z.array(RepoChecksSummarySchema).describe("Every repository that declares checks, in id order."),
 });
 export type RepoChecksList = z.infer<typeof RepoChecksListSchema>;
 export const RepoChecksAdoptSchema = z.object({