@intentic/sandbox-contract 1.239.0 → 1.242.0

package/src/schemas/git.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { AgentProviderSchema } from "./agent.js";
 import { LandConflictSchema, LandedMessageSchema } from "./agents.js";
+import { CommandRunSchema } from "./ci.js";
 import { RefNameSchema } from "./internal.js";
 import { RepoParamSchema } from "./shared.js";
 // What a commit records, three shapes, each a real git spelling. The last two are for the case where nothing
@@ -48,6 +49,34 @@ export const PushSchema = RepoParamSchema.extend({
         .optional()
         .describe("Which branch to push. Leave it out for the checked-out one. A branch with no upstream yet gets one set on this push."),
 });
+/* WHO SAID NO to a push, read off git's final words (git/git.ts pushRefusal), because the three answers ask
+ * three different things of the owner and only one of them is an agent's to fix:
+ *   hook      , this repository's own pre-push hook refused it: the code is known to be wrong, the hook's
+ *               output says how, and a fix is worth proposing.
+ *   remote    , the server rejected the refs: a non-fast-forward, a protected branch. Pull first, or push
+ *               somewhere else; nothing about the code has been judged.
+ *   transport , it never got there: credentials, a host that does not answer, a remote that is not a
+ *               repository. The same again, and a retry is the only sensible button. */
+export const PushRefusalSchema = z.enum(["hook", "remote", "transport"]);
+export type PushRefusal = z.infer<typeof PushRefusalSchema>;
+/* THE PUSH AS A RUN: the pre-push check's shape (CommandRunSchema) with the three things a push adds. A push is
+ * a command that runs this repository's pre-push hook, which for a workspace with a real gate is the whole
+ * suite, minutes of output; it is a terminal to watch and a verdict to poll for exactly as the check is, and
+ * NOT a request held open for its duration (the browser's header deadline is seconds, and a push that ran a
+ * suite inside its own request reported "failed" over a push that had gone). One shape for both halves of
+ * the push flow is what lets the browser render a refused push with the card, the terminal link and the
+ * proposed fix it already has for a red check. */
+export const PushRunSchema = CommandRunSchema.extend({
+    repo: z.string().describe("The repository this run is about, the same id the routes take."),
+    reason: z
+        .string()
+        .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.",
+    ),
+});
+export type PushRun = z.infer<typeof PushRunSchema>;
 export const GitFileQuerySchema = RepoParamSchema.extend({ path: z.string().min(1).describe("The file to read, relative to the repository root.") });
 export const GitFileWriteSchema = RepoParamSchema.extend({
     path: z.string().min(1).describe("Where to write, relative to the repository root. Missing folders are created."),
@@ -107,6 +136,22 @@ export const GitChangeSchema = z.object({
         .optional()
         .describe("Lines added. Absent for a binary file, and for an untracked one, which has nothing to compare against."),
     deletions: z.number().optional().describe("Lines removed. Absent for the same reasons additions is."),
+    /* THE SAME CHANGE WITH THE COMMENTS TAKEN OUT, computed here rather than by whoever renders the row, and
+     * that is the whole point of it being on the wire. A review's diffs open on code alone, so the numbers beside
+     * them are the code's; working those out needs both whole sides of the file and a TextMate walk over each,
+     * which the app used to do per file, as the files were read — so a row arrived showing git's count and
+     * changed to this one the moment anything read it, which moved the row under the reader when the list was
+     * sorted by size. Shipped with the list, the number a reader sees first is the number it stays.
+     *
+     * Absent, not zero, when there is nothing to say: a binary file, one side too large to read, a path whose
+     * grammar this build does not ship, or a list too long to count whole (see git/code-counts.ts). The caller
+     * then shows git's own counts, which for such a file are the only honest reading anyway. */
+    code: z
+        .object({ additions: z.number(), deletions: z.number() })
+        .optional()
+        .describe(
+            "The same +/− with every comment stripped from both sides, which is what a review shows beside a diff that opens on code alone. Absent when the file cannot be read that way (binary, too large, or a language this build ships no grammar for): git's own counts above are then the reading.",
+        ),
 });
 export type GitChange = z.infer<typeof GitChangeSchema>;
 // Where a repo's checked-out branch stands against its remote. Every field is optional-or-zero because every
@@ -375,16 +420,25 @@ export const RepoModulesSchema = z.object({
 export type RepoModules = z.infer<typeof RepoModulesSchema>;
 export const WorkspaceModulesSchema = z.object({ repos: z.array(RepoModulesSchema).describe("Every repository with the packages inside it.") });
 export type WorkspaceModules = z.infer<typeof WorkspaceModulesSchema>;
-// One file an agent touched, plus whether that change is ALREADY in the main tree. The review lists the
-// agent's CUMULATIVE output (base → worktree), not just the not-yet-landed remainder, because landing is not
-// the end of the review: a clean turn auto-lands within milliseconds, and a list scoped to the remainder shows
-// the user an empty panel for work they never got to look at. `landed` is what still separates the two, the
-// remainder is what "Land now" would apply, and the panel filters on exactly this flag.
+/* One file an agent touched AND STILL DIFFERS FROM MAIN ON, plus whether the main working tree is already
+ * holding it. The list is what the conversation wrote measured against the main line as it stands right now,
+ * which takes three states to say and each one decides a different next move for the reader:
+ *
+ *   · main's history has this content: the user accepted it, it is their commit, and it is no longer a
+ *     difference against main. There is no row (see `absorbed` on the response).
+ *   · the main working tree has it, uncommitted: the steady state seconds after a land, waiting in the Changes
+ *     panel. A row, `landed: true`.
+ *   · neither: never landed, or landed and then discarded. A row, `landed: false`, and this is exactly what
+ *     "Land now" would apply.
+ *
+ * Landed work keeps its row on purpose: a clean turn auto-lands within milliseconds, so a list scoped to the
+ * outstanding remainder would show an empty panel for work nobody had looked at yet. What retires a row is the
+ * user committing it, which is the one act that says they are done reviewing it. */
 export const AgentChangeSchema = GitChangeSchema.extend({
     landed: z
         .boolean()
         .describe(
-            "Whether this change is already in the shared tree. The list is everything the conversation wrote, not just what is left over, because a clean turn merges in milliseconds and a list of leftovers would show an empty panel for work nobody had looked at yet.",
+            "Whether your workspace already holds this content. Read from the tree at request time, not from what a land recorded: discard a landed file in the Changes panel and this goes back to false, which is what puts it back under Land now.",
         ),
 });
 export type AgentChange = z.infer<typeof AgentChangeSchema>;
@@ -420,6 +474,16 @@ export type AgentRepoChanges = z.infer<typeof AgentRepoChangesSchema>;
  * than the last attempt. */
 export const AgentChangesSchema = z.object({
     repos: z.array(AgentRepoChangesSchema).describe("One entry per repository the conversation touched."),
+    /* HOW MUCH OF THE WORK IS NO LONGER A DIFFERENCE, so an empty list can say WHICH kind of empty it is. An
+     * agent that has written nothing and an agent whose every file the user committed both answer with no rows,
+     * and they are opposite facts: one is "ask it for something", the other is "it is all in your history". A
+     * count rather than the rows themselves, because that is the whole of what the surface needs to pick a
+     * sentence, and carrying the rows would put the list back where it started. */
+    absorbed: z
+        .number()
+        .describe(
+            "How many of this conversation's files your own history already carries, and which are therefore not listed as differences any more.",
+        ),
     conflicts: z
         .array(LandConflictSchema)
         .optional()
@@ -428,3 +492,54 @@ export const AgentChangesSchema = z.object({
         ),
 });
 export type AgentChanges = z.infer<typeof AgentChangesSchema>;
+
+/* WHERE THE WORK WENT once it stopped being a difference, the other half of the sentence `absorbed` above can
+ * only start. The review is what still differs from main, so a reader who committed an agent's every file
+ * arrives at an empty panel; the count lets it say WHICH kind of empty, and this says where to go and shows
+ * the work, which is what the reader actually came for.
+ *
+ * Deliberately its OWN read rather than more fields on the review. The review is on the panel's hot path and
+ * this is a `git log` per repo that only matters once history has taken something, so it is asked for exactly
+ * when there is an answer to have. That also keeps the review's shape honest: its rows are differences against
+ * main, and these are not.
+ *
+ * A COMMIT CARRIES the work, it did not necessarily author it: a path is attributed to the newest commit that
+ * left the agent's content there, which is where a reader should be sent to read it now. See the daemon's
+ * agents/landed-history.ts for the span this is measured over and for why an unattributable path is counted
+ * rather than assigned to a plausible commit. */
+export const AgentHistoryCommitSchema = z.object({
+    sha: z.string().describe("The commit."),
+    short: z.string().describe("Its abbreviated hash, which is what a reader recognises it by."),
+    subject: z.string().describe("Its first line."),
+    author: z.string().describe("Who committed it."),
+    at: z.number().describe("When it was authored, in milliseconds."),
+    changes: z
+        .array(GitChangeSchema)
+        .describe(
+            "The conversation's files that this commit is the newest carrier of, as the conversation changed them. Every file appears under exactly one commit, so these counts add up to the work rather than over-counting a file that history touched twice.",
+        ),
+});
+export type AgentHistoryCommit = z.infer<typeof AgentHistoryCommitSchema>;
+export const AgentRepoHistorySchema = z.object({
+    repo: z.string().describe("Which repository."),
+    commits: z.array(AgentHistoryCommitSchema).describe("The commits carrying this conversation's work there, newest first."),
+    /* Carried for the same reason the review's rows carry it, and read from the same tree at the same instant:
+     * a package the conversation created lives only in its own copy, so the shared tree cannot name it, and
+     * without this every file of a brand-new package groups under no package at all. */
+    modules: z.array(WorkspaceModuleSchema).describe("The packages of the tree these files came from, so a review can group them by package."),
+});
+export type AgentRepoHistory = z.infer<typeof AgentRepoHistorySchema>;
+export const AgentHistorySchema = z.object({
+    repos: z.array(AgentRepoHistorySchema).describe("One entry per repository holding committed work of this conversation."),
+    /* FILES HISTORY HOLDS THAT NO COMMIT HERE ACCOUNTS FOR, reported rather than hidden. Content reaches the
+     * main line by roads that do not pass through a commit since the land: a cherry-pick from elsewhere,
+     * another conversation landing the same lines, the user typing them by hand before this one landed. Those
+     * files are absorbed and unattributable at once, and a surface that quietly dropped them would be claiming
+     * the commits it names are the whole story. */
+    unaccounted: z
+        .number()
+        .describe(
+            "How many of the conversation's absorbed files none of these commits carries. Above zero means its content reached your main line by some other road, so the commits listed are not the whole story.",
+        ),
+});
+export type AgentHistory = z.infer<typeof AgentHistorySchema>;

package/src/schemas/issues.ts

@@ -150,7 +150,7 @@ export type Issue = z.infer<typeof IssueSchema>;
 export const IssueSummarySchema = IssueSchema.extend({ id: entryId.describe("The issue's id, which is its fingerprint.") });
 export type IssueSummary = z.infer<typeof IssueSummarySchema>;
 
-// `invalid` is the same trust-boundary confession the drafts list makes, for the opposite reason: nothing but
+// `invalid` is the same trust-boundary confession the approvals list makes, for the opposite reason: nothing but
 // the daemon writes these, so a file in here that will not parse is a BUG in this daemon or a half-written
 // volume, and either is worth seeing rather than silently skipping.
 export const IssuesListSchema = z.object({

package/src/schemas/panels.ts

@@ -5,12 +5,32 @@ import { z } from "zod";
 // preview-<panelKey>-<sandboxId>.<zone> to it) PLUS content facts, evidence the web app's extensions run their
 // detect() over, computed daemon-side in one pass so the browser never scans /work file-by-file.
 
+/* WHERE A START THE SANDBOX IS RUNNING HAS GOT TO, between the click and the first byte served. The process
+ * manager watches the pane's foreground command every couple of seconds (processes/managed-processes.ts), and
+ * these four words are what that sampling can honestly say: the shell is still coming up; the install that
+ * runs first when node_modules is missing is still going; the dev command is running but nothing listens yet;
+ * or the command has already exited back to a prompt, which is the one a person needs told at once, because
+ * the "Preparing the preview…" it would otherwise sit behind never ends. Absent once the preview proxy has
+ * something to serve, and absent for anything the sandbox is not starting. */
+export const PanelLaunchSchema = z.enum(["launching", "installing", "starting", "exited"]);
+export type PanelLaunch = z.infer<typeof PanelLaunchSchema>;
+
 export const PanelSummarySchema = z.object({
     // The repo id: its root-relative dir under /work (slashes become `--` in the preview subdomain label).
     repo: z.string().describe("Which repository."),
     // Whether the repo ships a runnable dev server (a package.json `dev` script at operator/ or the root).
     hasPanel: z.boolean().describe("Whether it has anything runnable at all."),
     running: z.boolean().describe("Whether the sandbox has it running."),
+    /* Whether its dependencies are on disk, a node_modules at the directory Start runs in. What decides what a
+     * Start COSTS: seconds when true, an install first when false, and the Start screen's copy says which
+     * instead of promising "a few minutes" over a tree that is already installed (the starter site's is: the
+     * image bakes it). True for a repo with nothing runnable, which has nothing to install for. */
+    installed: z
+        .boolean()
+        .describe("Whether its dependencies are installed, which is what decides whether a start takes seconds or an install first."),
+    launch: PanelLaunchSchema.optional().describe(
+        "Where a start the sandbox is running has got to: its shell coming up, installing, its dev command running with nothing listening yet, or exited back to a prompt. Absent when nothing is starting and once it serves.",
+    ),
     // Whether anything this repo owns is answering, see `servers`. Not the same question as `running`: a panel
     // whose install is still going is running and not yet healthy, and a dev server someone started in their own
     // terminal is healthy without the daemon running it.

package/src/schemas/plan-limits.ts

@@ -1,21 +1,47 @@
 import { z } from "zod";
+import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../provider-specs.js";
 import { AgentHarnessSchema, AgentProviderSchema, EditorContextSchema } from "./agent.js";
 // Declared ABOVE both account shapes because both carry it: headroom is one idea in this product, not a Claude
 // idea that other providers imitate. A native account (OauthAccount) and a routed subscription
 // (TranslatorAccount) differ in who holds the credential and how the reading is taken, never in what a
 // reading IS, so every surface that draws a percentage reads this one type and no other.
 
+/* WHICH MODELS A POOL GATES, said by the reader that parsed it and carried on the wire, so every surface and
+ * every picker answers "does this pool stand between me and THIS model" from one fact instead of six rules.
+ *
+ * A plan is not one allowance. Google meters Gemini separately from the Claude and GPT models it serves off the
+ * same sign-in; a Claude plan carries a per-model weekly slice ("Opus", "Fable") beside its all-models pools;
+ * ChatGPT publishes a code-review limit that no chat turn spends. Before this field the relation lived in six
+ * places that disagreed (a static Google table, a Claude kind list, a max-over-everything ranking, a fullest-
+ * window reset, and two client-side matchers), so a Google account with its Gemini pool spent drew a red ring
+ * over Claude Opus, and a Claude account with its Opus slice spent was ranked "spent" for a Haiku call.
+ *
+ *   "all"      every model on this plan spends it: the 5-hour and weekly pools, Kimi's throttles.
+ *   "none"     nothing a turn here runs spends it: a code-review limit, a surface-scoped pool for another
+ *              product. Still shown, never binding.
+ *   { models } a slice scoped to the models the names match. Names are matched as runs of whole words against
+ *              the model id AND its label ("opus" is in "claude-opus-4-6" and in "Claude Opus 4.6"; "gemini"
+ *              is in "gemini-3-pro"), see plan-pools.ts, because the plan names a pool by the vendor's word for
+ *              the tier and nothing else connects the two.
+ *
+ * Decided by the READER, never inferred later: the payload is the only place the grouping is known, and it is
+ * the plan's to change, so the fact travels with the reading it describes. */
+export const WindowGatesSchema = z.union([z.literal("all"), z.literal("none"), z.object({ models: z.array(z.string().min(1)).min(1) })]);
+export type WindowGates = z.infer<typeof WindowGatesSchema>;
+
 // One plan-limit pool. `kind` is the provider's own key ('five_hour' | 'seven_day' | 'seven_day_opus' |
 // 'seven_day_sonnet' | 'model:Fable' | …) rather than an enum we'd have to keep in step with the provider: an
 // unrecognised pool is shown under its raw key, which is far better than being silently folded into a
 // neighbour. `label` is the provider's OWN display name where it supplies one (the per-model buckets do), it
 // wins over anything we'd infer, because the model names in a plan's limits are the provider's to rename.
-// `resetsAt` is epoch SECONDS (matching the SDK's frame).
+// `resetsAt` is epoch SECONDS (matching the SDK's frame). `gates` says which models the pool stands in the way
+// of, see WindowGatesSchema.
 export const UsageWindowSchema = z.object({
     kind: z.string(),
     label: z.string().optional(),
     utilization: z.number(), // 0-100
     resetsAt: z.number().optional(),
+    gates: WindowGatesSchema,
 });
 export type UsageWindow = z.infer<typeof UsageWindowSchema>;
 // An account's headroom: EVERY window the provider reports, read together, plus when the reading was taken.
@@ -69,6 +95,10 @@ export const ProviderRefusalSchema = z.object({
     message: z.string().describe("The provider's own words, verbatim. The only part that says which limit or which credential."),
     // The account that was serving, when the daemon knows it (native turns only, see above).
     account: z.string().optional().describe("Which account was serving, where that is known."),
+    // The model the refused turn ran, so a `limit` refusal can be read against the POOL that model spends
+    // (UsageWindow.gates) rather than against the account's fullest pool, which on a plan that meters models
+    // separately is routinely a different allowance from the one that said no.
+    model: z.string().optional().describe("Which model the refused turn was on, where that is known."),
 });
 export type ProviderRefusal = z.infer<typeof ProviderRefusalSchema>;
 export const ProviderRefusalsSchema = z.object({
@@ -89,18 +119,35 @@ export const TranslatorAccountSchema = z.object({
     // or one that did not answer, must still render as the connected account it is, with a dot instead of a
     // ring.
     usage: AccountUsageSchema.optional(),
+    /* THE TRANSLATOR'S OWN VERDICT ON THE CREDENTIAL, the one live fact no quota read can produce. CLIProxyAPI
+     * benches an auth file the moment upstream refuses it (a quota 429, an expired token) and routes around it
+     * until `until`; a reading taken five minutes ago cannot know that, and a green ring over a benched file is
+     * exactly the gap a refusal used to be the only way to see. Absent ⇒ the proxy is routing to it. */
+    cooling: z
+        .object({
+            // Epoch SECONDS, like every reset on this wire. Absent when the proxy named no retry instant.
+            until: z.number().optional(),
+            // The proxy's own sentence, when it gave one.
+            reason: z.string().optional(),
+        })
+        .optional(),
 });
 export type TranslatorAccount = z.infer<typeof TranslatorAccountSchema>;
-// Which routed-provider subscriptions are connected in the translator, per provider, a LIST per provider, not
-// a flag: CLIProxyAPI holds any number of auth files per provider side by side and balances requests across
-// them, so connecting a second ChatGPT or Google account is more headroom, and each is disconnectable on its
-// own. Drives the account rows in Sandbox ▸ Agent.
-export const TranslatorAccountsSchema = z.object({
-    codex: z.array(TranslatorAccountSchema),
-    grok: z.array(TranslatorAccountSchema),
-    kimi: z.array(TranslatorAccountSchema),
-    gemini: z.array(TranslatorAccountSchema),
-});
+/* Which routed-provider subscriptions are connected in the translator, per provider, a LIST per provider, not
+ * a flag: CLIProxyAPI holds any number of auth files per provider side by side and balances requests across
+ * them, so connecting a second ChatGPT or Google account is more headroom, and each is disconnectable on its
+ * own. Drives the account rows in Sandbox ▸ Agent.
+ *
+ * ONE KEY PER TRANSLATOR PROVIDER, built over the derived list rather than typed out, because this object and
+ * the enum beside it (KeyedProviderSchema) are the same fact twice and the browser reads a provider's slot
+ * without checking it exists: a provider present in the enum and missing here is `undefined.length`, at the
+ * exact moment somebody is asking whether they can send. */
+export const TranslatorAccountsSchema = z.object(
+    Object.fromEntries(TRANSLATOR_PROVIDERS.map((provider) => [provider, z.array(TranslatorAccountSchema)] as const)) as Record<
+        TranslatorProvider,
+        z.ZodArray<typeof TranslatorAccountSchema>
+    >,
+);
 export type TranslatorAccounts = z.infer<typeof TranslatorAccountsSchema>;
 // The side-channel body that un-parks a turn waiting on the user. Every interactive card, plan approval,
 // clarifying questions, a per-tool permission prompt, parks on the SAME registry keyed by `requestId`, so

package/src/schemas/provider-subscriptions.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../provider-specs.js";
 // The providers whose model can run UNDER the Claude Code harness through the bundled translator (CLIProxyAPI),
 // which holds their SUBSCRIPTION OAuth and re-serves it behind an Anthropic endpoint. The `claude` provider is
 // absent, native Anthropic OAuth serves it directly, without the translator. Codex, Grok and Gemini also have a
@@ -7,5 +8,9 @@ import { z } from "zod";
 // Gemini is in BOTH camps and that is not a contradiction: its native runtime (OpenCode) reaches Google through
 // this same translator and these same auth files. The harness axis picks the loop; the translator is the road
 // under either.
-export const KeyedProviderSchema = z.enum(["codex", "grok", "kimi", "gemini"]);
-export type KeyedProvider = z.infer<typeof KeyedProviderSchema>;
+//
+// DERIVED from the provider table's `auth.kind`, never listed here: this enum and the accounts schema built on
+// it (TranslatorAccountsSchema) and the daemon's CLIProxyAPI id map are three readings of one fact, and they
+// used to be three hand-kept lists that had to agree.
+export const KeyedProviderSchema = z.enum(TRANSLATOR_PROVIDERS);
+export type KeyedProvider = TranslatorProvider;

package/src/schemas/settings.ts

@@ -1,6 +1,6 @@
 // settings: per-sandbox agent settings (.intentic/config/settings.json)
 import { z } from "zod";
-import { AdmissionPolicySchema, AdmissionRuleSchema, CommandClassSchema } from "./agent.js";
+import { AdmissionPolicySchema, AdmissionRuleSchema, AgentRunPinSchema } from "./agent.js";
 // Which prompt the agent is, before this turn composes anything on top. Two built-in bases and an escape
 // hatch: Intentic's own (the default), Claude Code's preset, or the owner's text. Declared out here rather
 // than inline in the settings object because both sides of the wire branch on it, the daemon to build the
@@ -27,9 +27,14 @@ export type DependencyFreshness = z.infer<typeof DependencyFreshnessSchema>;
  * chores already wake on those and folding them into this table later must not mean renaming what users wrote.
  */
 
-// WHERE a rule can stand. Three, and each is a place the daemon already stopped to make a decision, this
+// WHERE a rule can stand. Four, and each is a place the daemon already stopped to make a decision, this
 // names those decisions rather than inventing new ones.
 export const RuleMomentSchema = z.enum([
+    // The assistant has just written a file, with an edit tool or with a shell command; the tree says which. A
+    // command here runs on that one file (`{file}` in the command is its path) and what it prints on a non-zero
+    // exit rides back with the edit's own result, while the file is still in mind. The cheapest moment a defect
+    // can be caught at, and the one the per-edit linter and byte scan stand at.
+    "file.edited",
     // The assistant is about to stop. A rule here can send it back to work, which is the only moment that can.
     "turn.ending",
     // Code is about to leave the machine. A rule here gates the push on its own exit code.
@@ -56,8 +61,10 @@ export type RuleMoment = z.infer<typeof RuleMomentSchema>;
  * `verify-removals` weighs what a turn DELETED against what the repository's history says about those lines,
  * which is a question `git log` answers and no shell one-liner an owner could type would, and
  * `verify-ui-edits` weighs the rendered surfaces a turn changed against whether it ever looked at one, the one
- * question a passing suite is structurally unable to answer. */
-export const RuleBuiltinSchema = z.enum(["verify-edits", "verify-removals", "verify-ui-edits"]);
+ * question a passing suite is structurally unable to answer, and `verify-tests` weighs the test files a turn
+ * touched against two things a green suite cannot say: whether their assertions got weaker than the same files
+ * at HEAD, and whether a test the turn wrote would have passed before the change it covers. */
+export const RuleBuiltinSchema = z.enum(["verify-edits", "verify-removals", "verify-ui-edits", "verify-tests"]);
 export type RuleBuiltin = z.infer<typeof RuleBuiltinSchema>;
 export const RuleActionSchema = z.discriminatedUnion("kind", [
     z.object({
@@ -73,6 +80,13 @@ export const RuleActionSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("builtin"), name: RuleBuiltinSchema }),
 ]);
 export type RuleAction = z.infer<typeof RuleActionSchema>;
+/* HOW A TURN ENDED, as the `agent.finished` moment sees it. `clean`, `error` and `conflict` are the turn's own
+ * fate. `checks-failed` is a clean turn whose `turn.ending` command check went red on the tree it is about to
+ * land: the model was told, answered, and the last run still failed. It is named separately because a landing
+ * rule has to be able to speak about it, and because its default is not the others': work in that state is HELD
+ * unless a rule names `checks-failed` and says allow (rules/rules.ts landingVerdict). */
+export const RuleOutcomeSchema = z.enum(["clean", "error", "conflict", "checks-failed"]);
+export type RuleOutcome = z.infer<typeof RuleOutcomeSchema>;
 // WHEN a rule narrows. Three keys, chosen because they cover the two things people reach for on day one,
 // "only this repo" and "don't bother for a docs-only change", without opening a query language. Every key
 // absent ⇒ the rule always matches at its moment, which is what the three replaced settings each did.
@@ -81,8 +95,8 @@ export const RuleConditionSchema = z.object({
     repo: z.string().min(1).optional(),
     // Globs the change has to touch for the rule to fire. Absent/empty ⇒ any.
     paths: z.array(z.string().min(1)).max(20).optional(),
-    // How the turn ended. Absent/empty ⇒ any.
-    outcome: z.array(z.enum(["clean", "error", "conflict"])).optional(),
+    // How the turn ended. Absent/empty ⇒ any, except that `checks-failed` never lands by omission.
+    outcome: z.array(RuleOutcomeSchema).optional(),
 });
 export type RuleCondition = z.infer<typeof RuleConditionSchema>;
 /* ONE RULE. `id` is stable and owner-visible: it is what the activity feed names when the rule fires and what
@@ -91,8 +105,10 @@ export type RuleCondition = z.infer<typeof RuleConditionSchema>;
  * WHICH ACTIONS FIT WHICH MOMENT is checked here rather than left to the consumer, because the alternative is
  * a rule that saves cleanly and then quietly does nothing, the failure mode a settings screen can least
  * afford. A verdict at `turn.ending` has nothing to decide; a command at `agent.finished` has no defined place
- * in the landing pass and would be a promise this stage cannot keep. */
+ * in the landing pass and would be a promise this stage cannot keep; an instruction at `file.edited` would be
+ * repeated on every save, which is noise by the third one. */
 const MOMENT_ACTIONS: Record<RuleMoment, readonly RuleAction["kind"][]> = {
+    "file.edited": ["command"],
     "turn.ending": ["builtin", "instruct", "command"],
     "push.starting": ["command"],
     "agent.finished": ["verdict"],
@@ -418,42 +434,9 @@ export const SandboxSettingsSchema = z.object({
      *
      * Off by default like every other flag here, and off means genuinely nothing: no hook is wired, and the
      * sandbox makes no network call it would not otherwise have made. */
-    dependencyFreshness: DependencyFreshnessSchema.default("off")
-        .describe(
-            "Whether a version the agent is about to pin is checked against the package's own registry first. Facts only, or facts plus the name of a maintained replacement where the registry agrees the current choice has been abandoned. It tells the agent and lets it decide rather than refusing, because matching a version your project already uses is usually the right answer and a gate would fight it.",
-        ),
-    /* DOES THE TEST IT JUST WROTE ACTUALLY TEST THE CHANGE?
-     *
-     * A model writes a test that passes, and a passing test is the thing it was asked for, so nothing in the loop
-     * objects. The failure this catches is the one where the test would have passed BEFORE the change too: it
-     * exercises the code without depending on the behaviour that was added, and it will keep passing when that
-     * behaviour is broken later. It type-checks, it lints, `pnpm verify` is green, and the suite has grown a test
-     * that can never fail.
-     *
-     * The check is a differential, and it is cheap for one specific reason: in an agent turn we already know
-     * exactly which source files changed. So the test is re-run with those files' HEAD contents served in place
-     * of the working copies, and the answer is one bit — did it still pass? A test that passes against the old
-     * code did not test the new code. This is one-mutant mutation testing where the mutant is "your change,
-     * reverted", which is the cheapest useful mutant there is and the only one already known for free.
-     *
-     * NOTHING IS WRITTEN TO THE TREE. The HEAD copies are served through a vite `load` hook in a generated config,
-     * never checked out over the working files — a hook that could leave a half-reverted tree behind on a crash
-     * would be trading a whole turn's work for a lint-grade signal.
-     *
-     * IT REPORTS AND GETS OUT OF THE WAY, for the same reason the freshness check above does. Two legitimate
-     * cases pass on HEAD and must not be fought: a test written BEFORE its implementation (it fails now, which
-     * the agent can see without help), and a pure refactor, where a test that keeps passing is the entire point.
-     * Distinguishing those from a weak test needs intent, so the fact rides back as context and the model decides.
-     *
-     * Scoped to source changed in the SAME package as the test, because that is what a package's own vitest run
-     * loads from source; a cross-package import resolves to the other package's built output, where there is
-     * nothing to swap. Off by default like every flag here, and off wires no hook at all. */
-    testFaultDetection: z
-        .boolean()
-        .default(false)
-        .describe(
-            "After the agent writes a test, re-run it against the code as it was before this turn's changes. A test that still passes did not test the change — it will pass just as happily when that behaviour breaks. Reports what it finds and lets the agent decide, because a test written before its implementation and a pure refactor both pass this honestly.",
-        ),
+    dependencyFreshness: DependencyFreshnessSchema.default("off").describe(
+        "Whether a version the agent is about to pin is checked against the package's own registry first. Facts only, or facts plus the name of a maintained replacement where the registry agrees the current choice has been abandoned. It tells the agent and lets it decide rather than refusing, because matching a version your project already uses is usually the right answer and a gate would fight it.",
+    ),
     outputCleaners: z
         .string()
         .default("")
@@ -507,11 +490,17 @@ export const SandboxSettingsSchema = z.object({
         ),
     /* WHAT AN AGENT RUN OPENS ON, the tier above quickModel, and the answer for every turn a SURFACE starts
      * rather than a person at a composer: Fix with agent on a pipeline or a deployment, a Maintenance chore, a
-     * Documentation or Acceptance run, the fix a failed pre-push check proposes. An ORDERED list of
-     * `${provider}:${model}` (quickModelKey) plus the reasoning effort beside it; EMPTY ⇒ whatever the chat
+     * Documentation or Acceptance run, the fix a failed pre-push check proposes. An ORDERED list of PINS, each
+     * naming a provider and model AND how that one is to be run (AgentRunPinSchema); EMPTY ⇒ whatever the chat
      * composer would have started with, which is the honest floor because it is the model the user already
      * chose to work with.
      *
+     * EACH ENTRY CARRIES ITS OWN REASONING AND COST KNOBS, which is why these are objects rather than the
+     * `${provider}:${model}` keys the two lists around them still hold. The effort used to be one field beside
+     * the list, answering for every model in it, and the entries of this list are the least interchangeable
+     * things on the page: the head is the tier the owner wants the work done at and what follows it is the
+     * account that catches it when the first is spent. AgentRunPinSchema has the rest of the argument.
+     *
      * A LIST, for the reason quickModel is one: the account at the head runs out, and every surface-started run
      * in the sandbox then fails on a credential the user cannot see from the row they pressed. Written in order,
      * the next one down catches it (turn-resume.ts walks it).
@@ -527,13 +516,12 @@ export const SandboxSettingsSchema = z.object({
      * surface added tomorrow inherits it by saying what it is instead of re-deriving where models come from. A
      * surface MAY still name one (the shared run button's caret, Acceptance's per-run pick), and that wins. */
     agentRunModels: z
-        .array(z.string())
+        .array(AgentRunPinSchema)
         .max(10)
         .default([])
         .describe(
-            "Which models run the work a screen starts rather than a person: fixing a red pipeline, a maintenance chore, an acceptance run. Tried in order, so one spent account does not take every such run down. Empty falls back to whatever the chat would have used, which is the honest floor because it is the model you already chose to work with.",
+            "Which models run the work a screen starts rather than a person: fixing a red pipeline, a maintenance chore, an acceptance run. Tried in order, so one spent account does not take every such run down, and each entry says how hard that model should think as well as which one it is. Empty falls back to whatever the chat would have used, which is the honest floor because it is the model you already chose to work with.",
         ),
-    agentRunEffort: z.string().default("").describe("How hard those runs should think."),
     /* AUTOMATIC TIER SELECTION: may the daemon run an easy-looking turn on a cheaper rung of the provider the
      * user is already on, instead of on the model they picked?
      *
@@ -630,6 +618,25 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Whether a turn killed by the model provider failing is re-run automatically, backing off between attempts. The sandbox-wide default; any one conversation can say otherwise. Off to begin with, because a retry spends your allowance on a turn you sent once and only you can say whether it was worth paying for twice. Worth turning on for a sandbox whose work mostly happens with nobody in the room.",
         ),
+    /* THE SANDBOX-WIDE DEFAULT for the blocker that is not a failure: "when a spent usage limit refuses a turn,
+     * send that turn again the moment the allowance comes back".
+     *
+     * The one automatic resume here that WAITS FOR A PUBLISHED INSTANT rather than guessing. Its neighbour above
+     * escalates a backoff at a provider nobody can predict; this one sleeps until the hour the provider itself
+     * named and fires once, at it. A limit that publishes no instant (Grok, Cursor) is never fired for at all,
+     * because there is nothing to wait for and a guess would be spending the user's money on arithmetic.
+     *
+     * OFF by default, and this is the setting the default matters most for. Every other blocker in this pair
+     * clears at nobody's expense, while this one clears into an allowance the user may have been holding back
+     * deliberately, so the shipped behaviour is to say when it reopens and let them decide. What arming it buys
+     * is the case a press cannot reach: the 2am wall on a board nobody is watching, where the alternative is a
+     * card that sat waiting eight hours for a press that was always going to come. */
+    resumeAfterLimit: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Whether a turn a spent usage limit refused is sent again by itself once the allowance reopens. The sandbox-wide default; any one conversation can say otherwise. Off to begin with, because the allowance is your budget and a turn that spends it the second it comes back is not a decision to make for you. Worth turning on for a sandbox whose work mostly happens with nobody in the room.",
+        ),
     /* When the daemon dies under a running turn, re-run that turn once it is back (agent/turn-journal.ts records
      * every in-flight turn; the boot pass in agent/turn-resume.ts re-runs what survived). OFF by default, like
      * the outage resume above and for the same reason: a boot that re-runs turns spends the user's allowance on
@@ -697,7 +704,7 @@ export const SandboxSettingsSchema = z.object({
      * `<provider>.<type>` ("discord.message.send") with `<provider>.*` as the per-provider wildcard; exact key
      * wins. An action with no rule is allowed, the empty default wires no hook at all, so an unconfigured
      * workspace pays nothing. "hold" cannot park a running turn (nobody may be there to answer); it refuses the
-     * live call and points the agent at the drafts outbox, which IS the held form of a send.
+     * live call and points the agent at the approvals queue, which IS the held form of a send.
      *
      * The CHILD-AGENT surface reads the same book: `agents.spawn` covers starting, steering and answering
      * child agents on every provider, `agents.spawn.<provider>` singles one out (the specific key wins), and
@@ -708,50 +715,17 @@ export const SandboxSettingsSchema = z.object({
         .record(z.string(), AdmissionRuleSchema)
         .default({})
         .describe("What an agent may do out in the world, per kind of action: go ahead, ask first, or never."),
-    /* THE COMMAND GATE'S RULEBOOK, a verdict per CommandClass, for shell commands the agent runs itself. This
-     * is the layer that still applies once a session is already running: the admission floor above decides who
-     * may wake the agent, and after that every command it types is inside one already-admitted session.
-     *
-     * "hold" means what it says here, unlike in actionRules: the gate raises a permission card and the command
-     * waits for a real answer, in EVERY posture, hooks fire under bypassPermissions, where the card machinery
-     * on its own never would. An UNATTENDED turn has nobody to answer, so a hold there refuses instead and says
-     * why; that is the honest form of "ask me" when there is no me.
-     *
-     * An unlisted class is allowed, WITH ONE FLOOR UNDER IT: the classes nothing brings back (FLOOR_CLASSES in
-     * command-classes.ts, `system.destructive` today) are held where the owner wrote nothing, so a workspace
-     * that has never opened this page is not one mistyped path away from a formatted disk. An explicit `allow`
-     * still wins, it is a decision about that exact class and the floor must not override the person who made
-     * it. Everything else stays as it was: unlisted is allowed and ordinary work is never asked about.
-     *
-     * Keys are the CommandClass enum, so a typo is a settings error rather than a rule that silently never
-     * matches. */
-    commandRules: z
-        .partialRecord(CommandClassSchema, AdmissionRuleSchema)
-        .default({})
-        .describe(
-            "What an agent may run inside the sandbox, for the six kinds of command that are hard to take back: rewriting git history, deleting recursively, wiping a disk or a container volume, reading credential files, publishing a package, reaching out to the network. Everything else is recoverable in a container that is itself disposable, and gating it would be friction bought with nothing. Leaving a kind unset is not the same as allowing it: wiping a disk is held for your approval until you say otherwise, because nothing here brings that back.",
-        ),
-    /* WHETHER A HELD COMMAND IS TRANSLATED BEFORE YOU ANSWER FOR IT. Off by default, and the default is the
-     * argument: the card is already complete without this, and switching it on spends one quick-model call per
-     * card raised, on the owner's own connected account.
-     *
-     * It buys the case the card is worst at. A held command is regularly a hundred-plus characters of pipeline
-     * the agent assembled, and the question the card actually asks, "do you want this to happen", is not
-     * answerable by reading shell quickly. The classifier already marks WHICH fragment held it (the card paints
-     * those); a sentence is what says what the rest of it does and why the agent wanted it.
-     *
-     * NEVER THE AGENT'S OWN WORDS. The sentence comes from the quick model reading the command text, not from
-     * the model being gated: a card that let the asking agent write its own justification would be a safety
-     * prompt whose persuasive half is authored by the thing it is meant to gate.
-     *
-     * The command itself is never replaced by it, only folded behind a disclosure the sentence sits above, and
-     * the marked fragments stay on the card either way, see ChatMessageView's permission card. */
-    explainCommands: z
-        .boolean()
-        .default(false)
-        .describe(
-            "Have the quick model describe each held command in one plain sentence, above the command itself. Costs one quick-model call per card raised, on your own connected account. The command is always still there to read.",
-        ),
+    /* THE COMMAND GATE IS NOT CONFIGURED HERE. It used to be: `commandRules` was a verdict per CommandClass and
+     * `explainCommands` decided whether a card carried a sentence. Both are gone, and the reason is the whole
+     * safety redesign (safety-policy.ts argues it): a regex verdict per class asked about `echo "rm -rf /"` and
+     * an actual delete in the same words, and no setting of six switches fixes that, because telling the two
+     * apart is an act of understanding rather than a threshold. What replaced them is the owner's written
+     * policy at .intentic/config/safety.md, read by a judge that also sees what the daemon knows about the turn,
+     * plus one typed hard rule the judge cannot waive. The Safety page edits that document; nothing about the
+     * command gate belongs in this object.
+     *
+     * The sentence on a card is no longer optional either: it is the judge's own reason for the verdict, so a
+     * card without one would be a card that could not say why it exists. */
     /* HOW MUCH AN AGENT MAY DELEGATE, the three ceilings the Claude Code harness enforces on its own Agent
      * tool, surfaced here because their defaults are tuned for a laptop and this is a container the owner sized.
      *