@intentic/sandbox-contract 1.302.0 → 1.304.0

package/src/policy/persona-home.ts

@@ -0,0 +1,39 @@
+import { type Fence, fenceCovers } from "./fence-paths.js";
+
+// Where a persona card LIVES, and therefore who may act through it. A card is not granted per person any more: a
+// person holds areas, an area is folders, and a card whose home those folders cover is one that person may wear.
+// Pure and shared, because the daemon refuses on this answer and the Access tab draws the consequence from it, and
+// two implementations would disagree at exactly the boundary that matters.
+
+// The two fields a card names a place with; structural rather than the Persona type, so this stays free of the
+// schema layer that imports it.
+export interface PersonaPlace {
+    readonly workspace?:
+        | {
+              readonly startIn?: string | undefined;
+              readonly folders?: readonly string[] | undefined;
+          }
+        | undefined;
+}
+
+/**
+ * The card's home as a fence: the folder it opens in, else the folders it may touch, else undefined — the workspace
+ * root, which only somebody holding the whole workspace covers.
+ * `startIn` wins over `folders` because where a conversation OPENS is the one place the card certainly works; the
+ * folders it may touch are a ceiling, usually the whole tree, and reading that as the home would make nearly every
+ * card owner-only.
+ */
+export const personaHome = (card: PersonaPlace): Fence => {
+    const startIn = card.workspace?.startIn;
+    if (startIn !== undefined && startIn !== "") {
+        return [startIn];
+    }
+    const folders = card.workspace?.folders;
+    return folders === undefined || folders.length === 0 ? undefined : folders;
+};
+
+/**
+ * Whether a person fenced to these folders may act through this card. An unfenced holder reaches every card; a fenced
+ * one reaches those homed inside its folders, and never a card that lives at the workspace root.
+ */
+export const fenceHoldsPersona = (fence: Fence, card: PersonaPlace): boolean => fenceCovers(fence, personaHome(card));

package/src/schemas/agents.ts

@@ -2,6 +2,7 @@
 import { z } from "zod";
 import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ForkedFromSchema } from "./agent.js";
 import { LoopStateSchema } from "./loops.js";
+import { LimitPolicySchema, RetryPolicySchema, TurnBreakPolicySchema, TurnBreakSchema } from "./turn-break.js";
 import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
 // A fleet agent is any conversation with a registry entry, keyed by conversationId. Isolated ones own a git worktree
 // (branch agent/<id>); workspace conversations have none, but both share one status/activity/cost lifecycle.
@@ -252,15 +253,11 @@ export const AgentSummarySchema = z.object({
         .describe(
             "This conversation's own answer to whether its work merges automatically. Absent means it follows the sandbox-wide setting, which is the common case.",
         ),
-    // Per-conversation override, written by the in-chat retry press (not the settings toggle) so one late-night click
-    // can't arm every agent; absent inherits the sandbox setting.
-    resumeAfterOutage: z.boolean().optional(),
-    // Off by default, unlike its neighbors: firing the moment a spent allowance reopens spends a window the user may be
-    // saving.
-    resumeAfterLimit: z.boolean().optional(),
-    // Per-conversation override for moving a held turn to another account with room the moment it's refused; absent
-    // inherits.
-    moveAfterLimit: z.boolean().optional(),
+    // This conversation's own answer to each ending's one question, written by the in-chat control (not the settings
+    // row) so one late-night click can't arm every agent; absent inherits the sandbox-wide policy.
+    limitPolicy: LimitPolicySchema.optional(),
+    outagePolicy: RetryPolicySchema.optional(),
+    stopPolicy: RetryPolicySchema.optional(),
     // A collaborator's ask to land (collaborators can't merge themselves); cleared by whichever merge or discard
     // answers it.
     landRequested: z
@@ -294,6 +291,14 @@ export const AgentSummarySchema = z.object({
         .describe(
             "Who asked for the first turn, as the sandbox verified it: a member's email, token:<label> for a program's control token, or agent:<conversation id> for a child another conversation spawned. Absent when nothing was verified (a wake, a loopback caller).",
         ),
+    // The fence it was born with. Rides the summary because it is what decides who may see the row at all
+    // (auth/fleet-scope.ts visibleTo); without it here a fenced reader's board would be empty of even their own work.
+    areas: z
+        .array(z.string())
+        .optional()
+        .describe(
+            "Which named areas of the workspace this conversation was started within, latched from whoever asked for the first turn. Absent means its starter held the whole workspace, which is why a fenced member is not shown it.",
+        ),
     // Responsibility, beside provenance: the starter says who asked, this says who answers for it now. Absent means
     // nobody has claimed it, which is what a program's or an automation's conversation is until somebody does.
     owner: SessionOwnerSchema.optional().describe(
@@ -619,33 +624,15 @@ export const AgentAutoLandSchema = z.object({
             "Whether its work merges automatically when a turn finishes. Null clears the override and goes back to following the sandbox-wide setting, so a conversation does not sit holding a frozen copy of a default it has quietly stopped following.",
         ),
 });
-// Same `null`-clears-the-override shape as autoLand, for this conversation's own outage-resume posture.
-export const AgentResumeAfterOutageSchema = z.object({
-    id: z.string().min(1).describe("Which conversation."),
-    resumeAfterOutage: z
-        .boolean()
-        .nullable()
-        .describe("Whether it retries by itself when the model provider was what failed. Null clears the override back to the sandbox-wide setting."),
-});
-// Same three-state override, for the limit blocker; written by the card's own offer when a limit strands a turn.
-export const AgentResumeAfterLimitSchema = z.object({
+// Same `null`-clears-the-override shape as autoLand, for this conversation's own answer to one ending's question.
+// One route rather than one per ending: they are the same decision asked about different walls, and three near-identical
+// verbs is how the surfaces drifted apart in the first place.
+export const AgentBreakPolicySchema = z.object({
     id: z.string().min(1).describe("Which conversation."),
-    resumeAfterLimit: z
-        .boolean()
-        .nullable()
-        .describe(
-            "Whether the turn a spent allowance refused is sent again by itself once the window reopens. Null clears the override back to the sandbox-wide setting.",
-        ),
-});
-// Same three-state override, for moving a held turn to another account with room.
-export const AgentMoveAfterLimitSchema = z.object({
-    id: z.string().min(1).describe("Which conversation."),
-    moveAfterLimit: z
-        .boolean()
-        .nullable()
-        .describe(
-            "Whether the turn a spent allowance refused is moved to another connected account of the same provider that has room, as soon as the refusal lands. Null clears the override back to the sandbox-wide setting.",
-        ),
+    ending: TurnBreakSchema.describe("Which wall this answers for: a spent usage limit, a provider outage, or a turn that stopped short."),
+    policy: TurnBreakPolicySchema.nullable().describe(
+        "What happens next for that ending. `wait` holds the turn for a press; `retry` re-runs it on a bounded ladder (outage, stop); `resend` sends it again at the published reset and `move` also tries another account with room (limit only). An answer the ending does not allow is refused. Null clears the override and goes back to following the sandbox-wide policy, so a conversation does not sit holding a frozen copy of a default it has quietly stopped following.",
+    ),
 });
 export const AgentFileDiffQuerySchema = z.object({
     id: z.string().min(1).describe("Which conversation."),

package/src/schemas/areas.test.ts

@@ -0,0 +1,40 @@
+import { PUBLIC_DIR, STATE_DIR } from "@intentic/constants";
+import { describe, expect, test } from "vitest";
+import { AreaFolderSchema } from "./areas.js";
+
+// What an area may name. These refusals are load-bearing rather than cosmetic: an area's folders become the fence
+// every file route refuses on, so they are the whole of what keeps a grant below maintainer out of the config that
+// decides what agents may do.
+describe("AreaFolderSchema", () => {
+    test("an ordinary folder, at any depth, is an area", () => {
+        expect(AreaFolderSchema.safeParse("support").success).toBe(true);
+        expect(AreaFolderSchema.safeParse("finance/reports").success).toBe(true);
+    });
+
+    test("the workspace root is not an area: naming no area at all is what granting everything means", () => {
+        expect(AreaFolderSchema.safeParse(".").success).toBe(false);
+        expect(AreaFolderSchema.safeParse("/").success).toBe(false);
+    });
+
+    test("a folder that climbs out of the workspace is refused however it is spelled", () => {
+        expect(AreaFolderSchema.safeParse("../etc").success).toBe(false);
+        expect(AreaFolderSchema.safeParse("support/../..").success).toBe(false);
+    });
+
+    test("the sandbox's own configuration and its outbox can never be named", () => {
+        for (const folder of [
+            STATE_DIR,
+            `${STATE_DIR}/config`,
+            `${STATE_DIR}/config/hooks`,
+            PUBLIC_DIR,
+            `${PUBLIC_DIR}/site`,
+        ]) {
+            expect(AreaFolderSchema.safeParse(folder).success, folder).toBe(false);
+        }
+    });
+
+    test("a folder that merely starts with one of those names is ordinary", () => {
+        expect(AreaFolderSchema.safeParse("publications").success).toBe(true);
+        expect(AreaFolderSchema.safeParse("support/public-notes").success).toBe(true);
+    });
+});

package/src/schemas/areas.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { foldPath, isSandboxPath } from "../policy/fence-paths.js";
+import { entryId } from "./internal.js";
+
+// A named part of the workspace: the unit a person's reach is granted in. Named rather than listed per member because
+// a folder list on every row makes each new folder an edit per member, and two rows meant to see the same thing drift
+// apart the first time one is updated and the other isn't.
+// An area is not a credential and holds none; what it holds is a decision about who sees which folders, which is why
+// the file is tracked and a change to it shows up in review.
+
+// Workspace-relative, forward-slash, no climb. Checked rather than rewritten: a transform here would make the route's
+// wire shape inexpressible, and two builds compare surfaces by that shape. The route folds what it writes instead, so
+// two spellings of one folder still cannot make two entries.
+export const AreaFolderSchema = z
+    .string()
+    .min(1)
+    .max(200)
+    .refine((raw) => (foldPath(raw) ?? "") !== "", {
+        message: "a folder is workspace-relative and inside the workspace; the workspace root is what naming no area already means",
+    })
+    // A fence is what a writer's every file route refuses on, so an area naming the control plane would be the one way
+    // a grant below maintainer could reach the config that decides what agents may do, or publish to the internet.
+    .refine((raw) => !isSandboxPath(raw), {
+        message: "an area cannot name the sandbox's own configuration or its public outbox",
+    });
+
+export const AreaSchema = z.object({
+    id: entryId.describe("The area's id, the name a member row points at."),
+    label: z.string().max(60).optional().describe("What to call it on screen. Absent falls back to the id, which somebody chose anyway."),
+    brief: z
+        .string()
+        .max(200)
+        .optional()
+        .describe("What this part of the workspace is, in one line, so whoever grants it can tell what they are handing over."),
+    folders: z
+        .array(AreaFolderSchema)
+        .min(1)
+        .max(50)
+        .describe(
+            "The folders it admits, workspace-relative. At least one: an area naming nothing would be a grant with no reader, and the way to grant everything is to name no area at all.",
+        ),
+});
+export type Area = z.infer<typeof AreaSchema>;
+
+export const AreasListSchema = z.object({
+    areas: z.array(AreaSchema).describe("Every named part of the workspace this sandbox grants access in."),
+});
+
+export const AreaIdParamSchema = z.object({ id: entryId.describe("Which area.") });

package/src/schemas/automations.ts

@@ -4,6 +4,7 @@ import { AgentOriginSchema, ModelPinSchema } from "./agent.js";
 import { AgentSummarySchema } from "./agents.js";
 import { entryId } from "./internal.js";
 import { IssuesConfigSchema } from "./issues.js";
+import { ZoneSchema } from "../time/zone.js";
 // An automation wakes the agent: the daemon fires each enabled one on its trigger, runs the optional guard command
 // (non-zero exit skips the wake), then runs one turn with the prompt. The manifest is user config; run history is
 // daemon-recorded.
@@ -60,6 +61,13 @@ export const TriggerSchema = z.discriminatedUnion("kind", [
     z.object({
         kind: z.literal("schedule").describe("On a clock."),
         cron: z.string().min(1).describe("When, in cron notation."),
+        // A cron is a WALL-CLOCK RULE: "43 20 * * *" is not a moment, it is 20:43 on some clock, and which clock is
+        // not written in it. The composer sends the reader's own zone here; absent, the sandbox's `timezone` setting
+        // answers, and absent that, UTC. Stored per automation rather than only globally so one chore can keep a
+        // colleague's hours, or a market's, without moving everything else.
+        tz: ZoneSchema.optional().describe(
+            "Which clock the times in the cron mean, as a zone name like Europe/Warsaw. Leave it out to use the sandbox's own setting, which is what you want unless this one chore belongs to a different place.",
+        ),
         // Fires only once at least this many other sessions have started since this automation's last wake; a due run
         // short of that is recorded as skipped.
         afterSessions: z

package/src/schemas/capabilities.ts

@@ -3,7 +3,6 @@
 import { z } from "zod";
 import { ExitConfigSchema } from "./exit.js";
 import { entryId } from "./internal.js";
-import { ServiceKindSchema } from "./inventory.js";
 import { NetdiskConfigSchema } from "./netdisk.js";
 import { VpnConfigSchema } from "./vpn.js";
 // One-way: the browser extension bundles webext.js alone, so nothing there may reach back into this file.
@@ -15,8 +14,6 @@ export const CapabilityKindSchema = z.enum([
     "devops",
     "monorepo",
     "mcp",
-    "service",
-    "integration",
     "cli",
     "plugin",
     "extension",
@@ -42,18 +39,6 @@ export const McpConfigSchema = z.object({
     url: z.url().describe("Where the tool server answers."),
     token: z.string().optional().describe("The credential it needs, if any. Stored, never echoed back."),
 });
-export const ServiceConfigSchema = z.object({
-    service: ServiceKindSchema.describe("Which service to provision."),
-    domain: z.string().min(1).describe("The address it should answer on."),
-    on: z.string().min(1).describe("Which machine to put it on."),
-    expose: z.string().min(1).describe("How it should be reachable."),
-});
-// External-app credential injected into deployed apps (i.have.stripe → STRIPE_API_KEY), not agent-facing like `cli`.
-// Closed, unlike `cli`: it becomes an `i.have.<provider>` deploy.config.ts entry, so the vocabulary belongs to the
-// deploy engine, not an extension.
-export const IntegrationConfigSchema = z.object({
-    provider: z.literal("stripe").describe("Which outside service's credential to make available to deployed apps."),
-});
 // Gives the agent an authenticated CLI tool: credential plus any non-secret URL, injected into the agent's env each
 // turn, taught via an .agents/skills/<id> cheatsheet. Provider fields are data in an extension's
 // `contributes.capabilities`, validated at add-time, not by this schema.
@@ -234,6 +219,43 @@ export const LOCAL_MODEL_WINDOW_DEFAULT: LocalModelWindow = "65536";
 // ceiling no shipped GGUF was trained for it.
 export const LOCAL_MODEL_WINDOW_MIN = 2048;
 export const LOCAL_MODEL_WINDOW_MAX = 1_048_576;
+// q8_0 KV cost per token, the rate every window price derives from: 64 KiB, so the rungs come out at exactly 1, 2, 4
+// and 8 GiB. One rate rather than a per-model one, because the true cost varies ~2x across the list (50–60 KB/token
+// measured) and a per-row figure is arithmetic somebody redoes by hand on every model added. Rounded UP into that band
+// rather than down: over-reserving costs a rung, under-reserving costs an allocation failure a card had promised
+// against.
+export const LOCAL_MODEL_KV_BYTES_PER_TOKEN = 65_536;
+// What a rung honestly serves. `instant` is the one the connect view prefetches — it downloads in under a minute and
+// cannot drive a full agent turn, so no surface may sell it as one; `work` is what that view recommends for real use.
+export type LocalModelTier = "instant" | "work";
+export interface LocalModelChoice {
+    // Hugging Face owner/repo/file.gguf, exactly as LocalModelConfig.model carries it.
+    readonly id: string;
+    readonly label: string;
+    // The published file's own size, not a rounded guess: the card's label, the fit arithmetic and the download
+    // estimate all read this, so a model cannot be priced two ways.
+    readonly weightsBytes: number;
+    readonly tier: LocalModelTier;
+}
+// The curated list, smallest first. ponytail: these bytes are the Hugging Face tree API's answer for each file — the
+// hand-written labels that predated them overstated gemma-4 12B by 2x and Qwen3.8 27B by a third, which is the class of
+// drift a machine-readable size exists to end.
+export const LOCAL_MODELS: readonly LocalModelChoice[] = [
+    { id: "unsloth/Qwen3.5-2B-GGUF/Qwen3.5-2B-Q4_K_M.gguf", label: "Qwen3.5 2B", weightsBytes: 1_280_835_840, tier: "instant" },
+    {
+        id: "unsloth/Phi-4-mini-instruct-GGUF/Phi-4-mini-instruct-Q4_K_M.gguf",
+        label: "Phi-4-mini 3.8B",
+        weightsBytes: 2_491_874_272,
+        tier: "work",
+    },
+    { id: "unsloth/Qwen3.5-9B-GGUF/Qwen3.5-9B-Q4_K_M.gguf", label: "Qwen3.5 9B", weightsBytes: 5_680_522_464, tier: "work" },
+    { id: "unsloth/gemma-4-12b-it-GGUF/gemma-4-12b-it-Q4_K_M.gguf", label: "Gemma 4 12B", weightsBytes: 7_121_861_440, tier: "work" },
+    { id: "unsloth/Qwen3.8-27B-GGUF/Qwen3.8-27B-UD-Q4_K_M.gguf", label: "Qwen3.8 27B", weightsBytes: 16_464_440_224, tier: "work" },
+];
+export const localModelChoice = (id: string): LocalModelChoice | undefined => LOCAL_MODELS.find((choice) => choice.id === id);
+// Exactly one row carries the instant tier; the fit module and the prefetch route take it from here rather than
+// repeating its id, so the prefetched bytes and the offered option cannot name different files.
+export const LOCAL_MODEL_INSTANT: LocalModelChoice = LOCAL_MODELS.find((choice) => choice.tier === "instant")!;
 export const LocalModelConfigSchema = z.object({
     model: z.string().min(1),
     gpu: z.enum(["on", "off"]).default("off"),
@@ -266,8 +288,6 @@ export const WalletConfigSchema = z.object({
 });
 export type WalletConfig = z.infer<typeof WalletConfigSchema>;
 export type McpConfig = z.infer<typeof McpConfigSchema>;
-export type ServiceConfig = z.infer<typeof ServiceConfigSchema>;
-export type IntegrationConfig = z.infer<typeof IntegrationConfigSchema>;
 export type CliConfig = z.infer<typeof CliConfigSchema>;
 export type PluginConfig = z.infer<typeof PluginConfigSchema>;
 export type ExtensionConfig = z.infer<typeof ExtensionConfigSchema>;
@@ -283,8 +303,6 @@ export const CapabilitySchema = z.discriminatedUnion("kind", [
     // operator panel.
     z.object({ id: entryId, kind: z.literal("monorepo"), config: z.object({}) }),
     z.object({ id: entryId, kind: z.literal("mcp"), config: McpConfigSchema }),
-    z.object({ id: entryId, kind: z.literal("service"), config: ServiceConfigSchema }),
-    z.object({ id: entryId, kind: z.literal("integration"), config: IntegrationConfigSchema }),
     z.object({ id: entryId, kind: z.literal("cli"), config: CliConfigSchema }),
     z.object({ id: entryId, kind: z.literal("plugin"), config: PluginConfigSchema }),
     z.object({ id: entryId, kind: z.literal("extension"), config: ExtensionConfigSchema }),

package/src/schemas/personas.ts

@@ -45,7 +45,11 @@ export const PersonaPowersSchema = z.object({
 });
 export type PersonaPowers = z.infer<typeof PersonaPowersSchema>;
 // `folders` only refuses file-tool calls outside it; it stops a misread instruction, not a shell. The container is the
-// real workspace-wide fence.
+// real workspace-wide fence, and a conversation started by a fenced person is narrower still — the turn works inside
+// this persona's folders AND that person's areas, never the wider of the two.
+// A plain folder list rather than a named area (schemas/areas.ts), because the two answer different questions: a
+// persona's fence is written once for that persona, while an area is a grant several people hold and one edit has to
+// move all of them.
 // No placement field, by decision: every session already opens in its own private copy, never the shared tree.
 export const PersonaWorkspaceSchema = z.object({
     // Absent means the workspace root.
@@ -192,7 +196,9 @@ export const PersonaSchema = z.object({
         .string()
         .max(200)
         .optional()
-        .describe("What this persona is for, in one line. A new chat is routed onto a persona by this sentence, and the Personas page shows it under the name."),
+        .describe(
+            "What this persona is for, in one line. A new chat is routed onto a persona by this sentence, and the Personas page shows it under the name.",
+        ),
     powers: PersonaPowersSchema.optional().describe(
         "What a conversation wearing it may do. Absent means the full toolbox, so a card written before this existed behaves exactly as it did.",
     ),
@@ -221,13 +227,18 @@ export const PersonaSchema = z.object({
 export type Persona = z.infer<typeof PersonaSchema>;
 // Ladder filtered to connected providers, deduplicated. Empty (absent, or every provider disconnected) means the card
 // has no opinion — the caller decides, not "run nothing".
-export const personaModels = (card: Pick<Persona, "models">, sources: readonly ModelSource[]): readonly ModelPin[] => readyChain(sources, card.models ?? []);
+export const personaModels = (card: Pick<Persona, "models">, sources: readonly ModelSource[]): readonly ModelPin[] =>
+    readyChain(sources, card.models ?? []);
 // Asked once per chat, on the message it was sent with; answers with the one card the message belongs to, or none.
 // `folder`/`paths` are the facts a card's `context`/`startIn` can be matched against that words alone can't supply.
 export const PersonaRouteAskSchema = z.object({
     prompt: z.string().min(1).max(20000).describe("The message a new chat is about to open with."),
     folder: z.string().max(200).optional().describe("The workspace folder the chat was opened in, when it was opened in one."),
-    paths: z.array(z.string().min(1).max(500)).max(50).default([]).describe("Workspace paths the message names: uploads, @-mentions, the editor's own file."),
+    paths: z
+        .array(z.string().min(1).max(500))
+        .max(50)
+        .default([])
+        .describe("Workspace paths the message names: uploads, @-mentions, the editor's own file."),
 });
 export type PersonaRouteAsk = z.infer<typeof PersonaRouteAskSchema>;
 export const PersonaRouteSchema = z.object({

package/src/schemas/providers/usage.ts

@@ -60,9 +60,18 @@ export const UsageTurnSchema = z.object({
     openingListings: z.number().optional(),
     // Tool calls before the turn first touched a file it later edited; absent (not zero) if it edited nothing.
     callsBeforeTarget: z.number().optional(),
+    // Calls that ended in error, counted once each however many updates reported it; absent means unmeasured, not a
+    // clean turn.
+    failedCalls: z.number().optional(),
     // Arm of the project-map experiment, stable per conversation; mapChars is the note's length when sent.
     mapArm: z.boolean().optional(),
     mapChars: z.number().optional(),
+    // Arm of the field-notes experiment, stable per conversation; notesChars is what the budget let through.
+    notesArm: z.boolean().optional(),
+    notesChars: z.number().optional(),
+    // Hash of the brief that was sent, recorded on control turns too. Load-bearing rather than decorative: the file is
+    // rewritten monthly, so a 30-day window holds two different treatments and pooling them would measure neither.
+    notesCohort: z.string().optional(),
     // What became of pre-turn retrieval on this turn, and how long it took. Assignment and DELIVERY are different
     // facts: the first version of this mechanism was assigned to every eligible turn and reached four in five of them,
     // which is the difference between a null result and a mechanism that never ran. Absent means the flag was off, so

package/src/schemas/settings.ts

@@ -5,6 +5,8 @@ import { z } from "zod";
 import { CommandJudgeModeSchema } from "../policy/safety-policy.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
 import { AdmissionPolicySchema, AdmissionRuleSchema, ModelPinSchema } from "./agent.js";
+import { LimitPolicySchema, RetryPolicySchema } from "./turn-break.js";
+import { ZoneSchema } from "../time/zone.js";
 // Which prompt base the agent runs before this turn composes anything on top: Intentic's own (default), Claude Code's
 // preset, or the owner's text. Declared out here since both the daemon and the browser branch on it.
 export const SystemPromptModeSchema = z.enum(["intentic", "claude", "custom"]);
@@ -202,6 +204,20 @@ export type SkillSwitch = z.infer<typeof SkillSwitchSchema>;
 // picks rather than failing whole.
 
 export const SandboxSettingsSchema = z.object({
+    // The zone every WALL-CLOCK RULE in this sandbox is meant in — an automation's cron, and anything else that says
+    // "at 09:00" instead of naming an instant. It is not a display preference: nothing formats through it, and an
+    // instant on screen is still drawn in the reader's own clock.
+    // Empty means nobody has said, and the container's clock (UTC) answers. That is harmless for a sandbox where
+    // nothing is scheduled and wrong the moment something is, which is why the editor offers its own zone on first
+    // load and the automations screen names this one beside every schedule.
+    // An IANA id rather than an offset, because an offset cannot express the summer-time rule that moves "09:00" twice
+    // a year, and a chore set in March should still be right in November.
+    timezone: z
+        .union([z.literal(""), ZoneSchema])
+        .default("")
+        .describe(
+            "Which clock this sandbox's schedules are set by, as a zone name like Europe/Warsaw. Automations that repeat on a clock fire by this, not by the machine's own time. Leave it empty and they fire by UTC, which is almost certainly not what you meant when you typed a time.",
+        ),
     stableSystemPrompt: z
         .boolean()
         .default(false)
@@ -270,6 +286,34 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "What share of conversations to open without the map, so the two can be compared. Whole conversations rather than individual turns, because the map is sent once and stays in the conversation's history afterwards.",
         ),
+    // The one composed piece that is WRITTEN rather than derived: a monthly automation rewrites it off the session
+    // corpus, so it carries what no scan of the tree can (which commands really work here, what the box can take, how
+    // the owner asks for things) and the map keeps carrying what a scan can.
+    fieldNotes: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Open every turn with a brief on how work actually goes in this sandbox: the traps that cost past sessions calls, the commands that really verify, what the machine can take. Written once a month by an automation that reads back the sessions run here, rather than worked out per turn, because it is drawn from history rather than from the tree. Off by default, since it rides every turn of every conversation.",
+        ),
+    // Characters, not sections: the file's own ranking decides WHICH sections, this decides HOW MANY fit. Same unit as
+    // the project map's ceiling so the two costs read on one scale.
+    fieldNotesBudget: z
+        .number()
+        .int()
+        .min(500)
+        .max(20000)
+        .default(4000)
+        .describe(
+            "How much of that brief to send. Its sections are ranked, most costly-to-not-know first, and they are taken whole in that order until this runs out — so raising it buys more of the tail, never a fuller version of the same thing.",
+        ),
+    fieldNotesHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0)
+        .describe(
+            "What share of conversations to run without the brief, so the two can be compared. Whole conversations rather than individual turns, because the brief sits in the prompt for the whole session and withholding it from one turn would not take it back.",
+        ),
     // Only the eager background pass; the `fileq` CLI itself is always on PATH regardless, gated only by its own skill.
     sidecars: z
         .boolean()
@@ -331,30 +375,20 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "How many days a finished conversation stays on the board before being put away. Zero means never. The one setting here that defaults on, because each card left behind is a real working copy on disk, not just a row.",
         ),
-    // Off still records the failure, so the per-conversation resume offer arms normally; nothing is lost, just not
-    // automatic.
-    resumeAfterOutage: z
-        .boolean()
-        .default(false)
-        .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 one resume that waits for a published instant rather than guessing; a limit with no published reset (Grok,
-    // Cursor) never fires this way at all.
-    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.",
-        ),
-    // Same provider only; a different provider would retire the session for a saving that isn't one. Composes with
-    // `resumeAfterLimit` into four postures: hold, wait for reset, move-or-hold, move-or-wait.
-    moveAfterLimit: z
-        .boolean()
-        .default(false)
-        .describe(
-            "Whether a turn a spent usage limit refused is moved to another connected account of the same provider that still has room, as soon as the refusal lands. The sandbox-wide default; any one conversation can say otherwise. Off to begin with, because it spends a second account on your behalf. With no account that has room the turn waits as the setting above says.",
-        ),
+    // One answer per ending, never a set of switches over the same event: the chat's own question and these rows are
+    // the same question at two scopes. Every ending defaults to `wait`, because a re-run spends the reader's allowance
+    // on a turn they sent once.
+    limitPolicy: LimitPolicySchema.default("wait").describe(
+        "What happens to a turn a spent usage limit refused. `wait` holds it for a press. `resend` sends it again by itself once the allowance reopens, which needs a provider that publishes a reset (Grok and Cursor publish none). `move` also tries another connected account of the same provider that still has room, as soon as the refusal lands, and keeps the reset as its fallback. The sandbox-wide default; any one conversation can say otherwise.",
+    ),
+    // Off still records the failure, so the per-conversation offer arms normally; nothing is lost, just not automatic.
+    outagePolicy: RetryPolicySchema.default("wait").describe(
+        "What happens to a turn the model provider's own failure killed. `wait` holds it for a press. `retry` re-runs it on the shared per-provider breaker, backing off between attempts. The sandbox-wide default; any one conversation can say otherwise. Worth `retry` for a sandbox whose work mostly happens with nobody in the room.",
+    ),
+    // The posture that used to live only in a browser tab; moving it here is what lets it fire with nothing open.
+    stopPolicy: RetryPolicySchema.default("wait").describe(
+        "What happens to a turn that stopped short with nothing to repair — a hung runtime, a crashed harness. `wait` holds it for a press. `retry` re-runs the held turn on a short ladder, standing down after three tries that got nowhere rather than looping forever.",
+    ),
     limitMoveCarryUnder: z
         .number()
         .int()
@@ -369,7 +403,7 @@ export const SandboxSettingsSchema = z.object({
         .boolean()
         .default(false)
         .describe(
-            "Whether a turn killed by the sandbox restarting is re-run once it comes back. Off to begin with, for the same reason: it would spend your allowance on work you are not watching and edit files while you are still waiting for the sandbox to return. Either way the interruption is recorded rather than silently lost.",
+            "Whether a turn killed by the sandbox restarting is re-run once it comes back. A switch rather than one of the policies above, because a restart is the one ending with nobody watching it, so there is no in-chat question to answer. Off to begin with: it would spend your allowance on work you are not watching and edit files while you are still waiting for the sandbox to return. Either way the interruption is recorded rather than silently lost.",
         ),
     // Which repositories' own declarations (`<repo>/.intentic/checks.json`) the owner has switched on, each against the
     // fingerprint of what was declared when they did. A declaration that has since changed no longer matches its
@@ -430,6 +464,20 @@ export const SandboxSettingsSchema = z.object({
         .describe("How many levels deep the delegation may go, since a subagent can start subagents of its own."),
 });
 export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
+
+// A browser telling the sandbox which clock IT is on. An offer, not an instruction: see `adoptTimezone`.
+export const TimezoneOfferSchema = z.object({
+    timezone: ZoneSchema.describe("The zone the offering machine is in, as an IANA name like Europe/Warsaw."),
+});
+export type TimezoneOffer = z.infer<typeof TimezoneOfferSchema>;
+
+// What the sandbox's clock is after the offer, and whether the offer is what set it. `adopted: false` with a zone
+// back means somebody had already chosen, which is the normal answer for every browser after the first.
+export const TimezoneStateSchema = z.object({
+    timezone: z.string().describe("The zone this sandbox's schedules are now read in. Empty only if none could be resolved."),
+    adopted: z.boolean().describe("Whether this call is what set it. False means it was already answered and the stored zone stands."),
+});
+export type TimezoneState = z.infer<typeof TimezoneStateSchema>;
 // Read live from the installed CLI (preset-prompt.ts), not a stored transcription. `version` is the CLI build it came
 // from, so a fork from an older build reads as a snapshot; empty for Intentic's own prompt.
 export const BuiltinPromptTextSchema = z.object({ text: z.string(), version: z.string() });
@@ -465,9 +513,10 @@ export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() }
 // openingSearches: same, narrowed to before the turn first touched a file.
 // openingListings: directory listings a turn ran to orient itself (the project map).
 // callsBeforeTarget: how far a turn walked before touching a file it went on to edit.
+// failedCalls: tool calls that ended in error (the field notes, whose largest section is a failure taxonomy).
 // Never cost: each mechanism moves one small part of a turn's work, inside the noise of the rest.
 export const TurnMetricReadingSchema = z.object({
-    metric: z.enum(["searchCalls", "openingSearches", "openingListings", "callsBeforeTarget"]),
+    metric: z.enum(["searchCalls", "openingSearches", "openingListings", "callsBeforeTarget", "failedCalls"]),
     on: SavingsArmSchema,
     off: SavingsArmSchema,
     // Additional control turns to reach a fixed target resolution, not today's delta (which inherits noise and always
@@ -518,11 +567,34 @@ export const DependencySavingsSchema = z.object({
     updatedAt: z.number().optional(),
 });
 export type DependencySavings = z.infer<typeof DependencySavingsSchema>;
+// What the settings row can say about the brief without opening it: whether there is one, how much of it this budget
+// reaches, and whether anything is scheduled to rewrite it. Read off the file and the automation store, never stored.
+export const FieldNotesStatusSchema = z.object({
+    // False means the automation has never run (or was never set up) — the ordinary state before the first month.
+    present: z.boolean(),
+    // Epoch ms the file was last written. Absent when there is no file.
+    writtenAt: z.number().optional(),
+    // How many ranked sections the current budget reaches, out of how many the file holds. The pair is the point: "5"
+    // alone cannot tell a generous budget from a short file.
+    ranksSent: z.number().optional(),
+    ranksTotal: z.number().optional(),
+    // What the brief costs the prompt, in characters, at the current budget.
+    chars: z.number().optional(),
+    // The monthly rewrite: absent until the owner creates it from the offered template, since an automation names the
+    // models it spends and nothing chooses those for them.
+    automation: z.enum(["missing", "enabled", "disabled"]),
+    // When it next runs, epoch ms; absent when there is nothing scheduled.
+    nextRunAt: z.number().optional(),
+    // Said out loud rather than shown as "no file": a brief that exists and cannot be read is a broken automation.
+    unreadable: z.string().optional(),
+});
+export type FieldNotesStatus = z.infer<typeof FieldNotesStatusSchema>;
 export const SavingsReportSchema = z.object({
     input: InputSavingsSchema,
     search: TurnExperimentSchema.optional(),
     // Same absence rule as `search`: not measured, never zero.
     map: TurnExperimentSchema.optional(),
+    notes: TurnExperimentSchema.optional(),
     dependencies: DependencySavingsSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;

package/src/schemas/shared.ts

@@ -9,16 +9,17 @@ export const OkSchema = object({
         .describe("Always true. A route that answers this either did the thing or refused with a status; there is no third outcome to report."),
 });
 // Trust tiers, ordered low to high: desk talks to the persona cards it was handed and sees nothing else, viewer
-// watches, collaborator's outward actions become requests, maintainer holds the owner's authority but is revocable,
-// owner is the one bound identity and not a grant.
-export const MemberRoleSchema = zEnum(["desk", "viewer", "collaborator", "maintainer", "owner"]);
+// watches, collaborator's outward actions become requests, writer changes files inside the areas it holds and ships
+// none of them, maintainer holds the owner's authority but is revocable, owner is the one bound identity and not a
+// grant.
+export const MemberRoleSchema = zEnum(["desk", "viewer", "collaborator", "writer", "maintainer", "owner"]);
 export type MemberRole = z.infer<typeof MemberRoleSchema>;
 // Roles an invite can grant: everything but owner, which binds at first sign-in and is never granted.
-export const GrantedRoleSchema = zEnum(["desk", "viewer", "collaborator", "maintainer"]);
+export const GrantedRoleSchema = zEnum(["desk", "viewer", "collaborator", "writer", "maintainer"]);
 export type GrantedRole = z.infer<typeof GrantedRoleSchema>;
 // Single source for role order; every surface that gates on a role reads this ranking. A desk is below every
 // floor: its routes are an allowlist of its own (auth/role-floor.ts deskReach), never a floor it can clear.
-const MEMBER_ROLE_RANK: Record<MemberRole, number> = { desk: 0, viewer: 1, collaborator: 2, maintainer: 3, owner: 4 };
+const MEMBER_ROLE_RANK: Record<MemberRole, number> = { desk: 0, viewer: 1, collaborator: 2, writer: 3, maintainer: 4, owner: 5 };
 export const roleAtLeast = (role: MemberRole, floor: MemberRole): boolean => MEMBER_ROLE_RANK[role] >= MEMBER_ROLE_RANK[floor];
 // Rotating a door credential (event webhook, release gate, bug intake): the old value stops working immediately; the
 // new one is shown once to be saved.